달빛약속 / core/mod / YaksokSession
Class: YaksokSession
달빛 약속 코드의 실행 생명주기를 총괄하는 핵심 클래스입니다. 코드 모듈을 등록하고, 실행 파이프라인(토크나이징, 파싱, 실행)을 조율하며, 외부 환경(입출력, FFI)과의 상호작용을 관리합니다.
이 클래스는 달빛 약속 인터프리터의 공개 API(Public API)이자 퍼사드(Facade) 역할을 수행합니다. 모든 코드 실행은 이 세션을 통해 시작되고 관리됩니다.
Example
let output = '';
const session = new YaksokSession({
stdout: (message) => {
output += message;
}
});
session.addModule('main', '"안녕" 보여주기');
await session.runModule('main');
// output: "안녕"Constructors
YaksokSession()
YaksokSession(
config):YaksokSession
새로운 달빛 약속 실행 세션을 생성합니다.
Parameters
• config: Partial<SessionConfig> = {}
세션의 동작(stdout, stderr, 이벤트 핸들러, 기능 플래그 등)을 사용자화하는 설정 객체입니다.
Returns
See
SessionConfig
Defined in
Properties
baseContext?
optionalbaseContext:CodeFile
모든 모듈이 공유하는 기본 컨텍스트를 나타내는 CodeFile입니다. setBaseContext를 통해 설정됩니다.
Defined in
entrypoint
entrypoint:
CodeFile=null
현재 실행의 시작점(entrypoint)이 된 CodeFile 인스턴스입니다.
Defined in
extensions
extensions:
Extension[] =[]
세션에 등록된 FFI(Foreign Function Interface) 확장 목록입니다.
See
Extension
Defined in
files
files:
Record<string|symbol,CodeFile> ={}
세션에 등록된 모든 코드 모듈을 저장하는 객체입니다. 키는 모듈 이름, 값은 CodeFile 인스턴스입니다.
Defined in
flags
flags:
Partial<Partial<Record<FEATURE_FLAG,boolean>>> ={}
언어의 실험적인 기능을 켜거나 끌 수 있는 플래그입니다.
See
FEATURE_FLAG
Defined in
paused
paused:
boolean=false
코드 실행이 일시 중지되었는지 여부를 나타냅니다. pause()와 resume() 메서드로 제어됩니다.
Defined in
pubsub
pubsub:
PubSub<Events>
세션 내부의 이벤트를 발행하고 구독하는 Pub/Sub 시스템입니다. (예: runningCode, pause, resume)
See
Events
Defined in
runningPromise
runningPromise:
Promise<Scope> =null
현재 실행 중인 코드의 Promise입니다. 코드가 실행 중이 아닐 때는 null입니다.
Defined in
signal
signal:
AbortSignal=null
외부에서 코드 실행을 중단시키기 위한 AbortSignal입니다.
See
https://developer.mozilla.org/ko/docs/Web/API/AbortSignal
Defined in
stderr()
stderr: (
message) =>void
오류 발생 시 호출되는 함수입니다.
Parameters
• message: string
Returns
void
Defined in
stdout()
stdout: (
message) =>void
보여주기 명령어로 출력된 결과를 처리하는 함수입니다.
Parameters
• message: string
Returns
void
Defined in
stepByStep
stepByStep:
boolean=false
Defined in
Accessors
BASE_CONTEXT_SYMBOL
Get Signature
get BASE_CONTEXT_SYMBOL():
symbol
Returns
symbol
Defined in
Methods
addModule()
addModule(
moduleName,code,codeFileConfig):CodeFile
세션에 코드 모듈을 추가합니다.
추가된 코드는 즉시 실행되지 않고, runModule이 호출될 때 참조됩니다. 각 코드는 CodeFile 인스턴스로 변환되어 관리됩니다.
Parameters
• moduleName: string | symbol
모듈을 식별하는 고유한 이름 또는 심볼입니다.
• code: string
실행할 달빛 약속 소스코드 문자열입니다.
• codeFileConfig: Partial<CodeFileConfig> = {}
CodeFile에 대한 추가 설정입니다. (예: executionDelay)
Returns
생성된 CodeFile 인스턴스를 반환합니다.
Example
session.addModule('utils', '약속, 더하기 (A) (B): A + B');
session.addModule('main', '(@utils 더하기 1 2) 보여주기');Defined in
addModules()
addModules(
modules):void
여러 개의 코드 모듈을 한 번에 추가합니다. addModule을 각 모듈에 대해 호출하는 것과 동일합니다.
Parameters
• modules: Record<string, string>
모듈 이름을 키로, 소스코드를 값으로 하는 객체입니다.
Returns
void
Example
session.addModules({
math: '약속, 제곱 (수): 수 * 수',
main: '(@math 제곱 5) 보여주기',
});Defined in
extend()
extend(
extension):Promise<void>
세션에 FFI(Foreign Function Interface)를 위한 확장을 추가합니다. 확장을 통해 달빛 약속은 JavaScript, Python 등 외부 런타임과 상호작용할 수 있습니다.
Parameters
• extension: Extension
FFI 런타임을 제공하는 확장 객체입니다.
Returns
Promise<void>
See
Extension
Example
// QuickJS 런타임 확장 추가
await session.extend(new QuickJS());Defined in
getCodeFile()
getCodeFile(
fileName):CodeFile
세션에 등록된 CodeFile 인스턴스를 가져옵니다.
Parameters
• fileName: string | symbol
가져올 모듈의 이름입니다.
Returns
CodeFile 인스턴스를 반환합니다.
Throws
FileForRunNotExistError - 해당 이름의 모듈이 존재하지 않을 경우 발생합니다.
Defined in
pause()
pause():
void
현재 진행 중인 코드 실행을 일시 중지합니다. executionDelay가 설정된 경우에만 의미가 있으며, 다음 실행 단위(statement)로 넘어가기 전에 실행을 멈춥니다.
Returns
void
Defined in
resume()
resume():
Promise<void>
pause()로 일시 중지된 코드 실행을 재개합니다.
Returns
Promise<void>
실행이 완료되면 resolve되는 Promise를 반환합니다.
Defined in
runFFI()
runFFI(
runtime,code,args):Promise<ValueType>
등록된 FFI 확장을 통해 외부 코드를 실행합니다.
Parameters
• runtime: string
사용할 FFI 런타임의 이름입니다 (예: 'QuickJS').
• code: string
FFI 런타임에서 실행할 코드입니다.
• args: Record<string, any>
코드를 실행할 때 전달할 인자(값)들입니다.
Returns
Promise<ValueType>
실행 결과를 달빛 약속의 ValueType으로 변환하여 반환합니다.
Throws
FFIRuntimeNotFound - 해당 runtime을 처리할 확장이 없을 때 발생합니다.
Throws
MultipleFFIRuntimeError - 해당 runtime을 처리할 확장이 여러 개일 때 발생합니다.
Throws
ErrorInFFIExecution - FFI 실행 중 오류가 발생했을 때 발생합니다.
Defined in
runModule()
runModule(
moduleName):Promise<RunModuleResult>
지정된 모듈을 엔트리포인트로 하여 코드를 실행합니다.
이 메서드는 달빛 약속 코드 실행의 전체 과정을 조율합니다.
- 동시 실행 처리: 만약 다른 코드가 이미 실행 중(
runningPromise가 존재)이라면, 해당 실행이 끝날 때까지 기다립니다. 이를 통해 동일 세션 내에서의 실행 순서를 보장합니다. - 유효성 검사: 실행 전
validate()를 호출하여 코드의 정적 오류를 미리 확인합니다. - 실행:
CodeFile.run()을 호출하여 실제 코드 실행을 시작하고runningPromise에 할당합니다. - 오류 처리: 실행 중 발생하는 모든 종류의 오류를
catch하여 적절한RunModuleResult로 변환합니다. - 상태 해제:
finally블록에서runningPromise를null로 설정하여 세션이 다시 실행 가능한 상태임을 보장합니다.
Parameters
• moduleName: string | symbol
실행을 시작할 모듈(엔트리포인트)의 이름입니다.
Returns
Promise<RunModuleResult>
코드 실행 결과를 담은 RunModuleResult 객체의 Promise를 반환합니다.
See
RunModuleResult
Defined in
setBaseContext()
setBaseContext(
code):Promise<RunModuleResult>
모든 모듈이 공유하는 기본 컨텍스트(Base Context)를 설정합니다. 여기에 정의된 변수나 함수는 모든 모듈의 최상위 스코프에서 접근 가능합니다. 내장 함수 라이브러리 등을 구현할 때 유용합니다.
Parameters
• code: string
기본 컨텍스트로 사용할 달빛 약속 코드입니다.
Returns
Promise<RunModuleResult>
기본 컨텍스트 설정 결과를 담은 RunModuleResult의 Promise를 반환합니다.
Example
const prelude = `
약속, 절대값 (수):
만약 수가 0보다 작으면:
-수 반환하기
아니면:
수 반환하기
`;
await session.setBaseContext(prelude);
// 이제 모든 모듈에서 '절대값' 함수를 사용할 수 있습니다.
session.addModule('main', '절대값(-5) 보여주기');
await session.runModule('main'); // "5"가 출력됩니다.Defined in
validate()
validate(
entrypoint?):ErrorGroups
지정된 엔트리포인트부터 시작하여 모든 참조된 코드의 유효성을 검사합니다. 토크나이징과 파싱 과정에서 발생하는 정적 오류를 미리 확인할 수 있습니다.
Parameters
• entrypoint?: string | symbol
유효성 검사를 시작할 모듈의 이름입니다. 지정하지 않으면 모든 모듈을 검사합니다.
Returns
ErrorGroups
모듈별 오류 목록을 담은 Map 객체를 반환합니다.
See
ErrorGroups