@mojir/dvala 0.0.7 → 0.0.9

package/dist/cli/reference/examples.d.ts

@@ -5,7 +5,7 @@ export interface Example {
     code: string;
     context?: {
         bindings?: Record<string, unknown>;
-        handlers?: Record<string, string>;
+        effectHandlers?: Record<string, string>;
     };
 }
 export declare const examples: Example[];

package/dist/cli/src/AutoCompleter/AutoCompleter.d.ts

@@ -1,4 +1,6 @@
-import type { ContextParams, Dvala } from '../Dvala/Dvala';
+export interface AutoCompleterParams {
+    bindings?: Record<string, unknown>;
+}
 type AutoCompleteSuggestion = {
     program: string;
     position: number;
@@ -11,7 +13,7 @@ export declare class AutoCompleter {
     private searchString;
     private suggestions;
     private suggestionIndex;
-    constructor(originalProgram: string, originalPosition: number, dvala: Dvala, params: ContextParams);
+    constructor(originalProgram: string, originalPosition: number, params?: AutoCompleterParams);
     getNextSuggestion(): AutoCompleteSuggestion | null;
     getPreviousSuggestion(): AutoCompleteSuggestion | null;
     private getAutoCompleteSuggestionResult;

package/dist/cli/src/{Dvala/Cache.d.ts → Cache.d.ts}

@@ -1,4 +1,4 @@
-import type { Ast } from '../parser/types';
+import type { Ast } from './parser/types';
 export declare class Cache {
     private cache;
     private firstEntry;

package/dist/cli/src/builtin/specialExpressions/functions.d.ts

@@ -2,5 +2,5 @@ import type { DvalaFunction, SpecialExpressionNode } from '../../parser/types';
 import type { BuiltinSpecialExpression } from '../interface';
 import type { Function } from '../utils';
 import type { specialExpressionTypes } from '../specialExpressionTypes';
-export type LambdaNode = SpecialExpressionNode<[typeof specialExpressionTypes['0_lambda'], Function, string]>;
+export type LambdaNode = SpecialExpressionNode<[typeof specialExpressionTypes['0_lambda'], Function]>;
 export declare const lambdaSpecialExpression: BuiltinSpecialExpression<DvalaFunction, LambdaNode>;

package/dist/cli/src/createDvala.d.ts

@@ -0,0 +1,47 @@
+import { AutoCompleter } from './AutoCompleter/AutoCompleter';
+import type { DvalaModule } from './builtin/modules/interface';
+import type { DvalaBundle } from './bundler/interface';
+import type { Handlers, RunResult } from './evaluator/effectTypes';
+export interface CreateDvalaOptions {
+    modules?: DvalaModule[];
+    bindings?: Record<string, unknown>;
+    effectHandlers?: Handlers;
+    cache?: number;
+    /** Enable debug tokenization: captures source positions for better error messages. */
+    debug?: boolean;
+}
+/**
+ * Options for `run()`. When `pure` is `true`, `effectHandlers` cannot be provided.
+ */
+export type DvalaRunOptions = {
+    bindings?: Record<string, unknown>;
+    pure: true;
+    effectHandlers?: never;
+    filePath?: string;
+} | {
+    bindings?: Record<string, unknown>;
+    pure?: false;
+    effectHandlers?: Handlers;
+    filePath?: string;
+};
+/**
+ * Options for `runAsync()`. When `pure` is `true`, `effectHandlers` cannot be provided.
+ */
+export type DvalaRunAsyncOptions = {
+    bindings?: Record<string, unknown>;
+    pure: true;
+    effectHandlers?: never;
+    maxSnapshots?: number;
+} | {
+    bindings?: Record<string, unknown>;
+    pure?: false;
+    effectHandlers?: Handlers;
+    maxSnapshots?: number;
+};
+export interface DvalaRunner {
+    run: (source: string | DvalaBundle, options?: DvalaRunOptions) => unknown;
+    runAsync: (source: string | DvalaBundle, options?: DvalaRunAsyncOptions) => Promise<RunResult>;
+    getUndefinedSymbols: (source: string) => Set<string>;
+    getAutoCompleter: (program: string, position: number) => AutoCompleter;
+}
+export declare function createDvala(options?: CreateDvalaOptions): DvalaRunner;

package/dist/cli/src/evaluator/ContextStack.d.ts

@@ -1,9 +1,14 @@
 import type { Any } from '../interface';
-import type { ContextParams } from '../Dvala/Dvala';
 import type { DvalaModule } from '../builtin/modules/interface';
 import type { SymbolNode, UserDefinedSymbolNode } from '../parser/types';
 import type { SourceCodeInfo } from '../tokenizer/token';
 import type { Context, LookUpResult } from './interface';
+interface CreateContextStackParams {
+    globalContext?: Context;
+    contexts?: Context[];
+    bindings?: Record<string, unknown>;
+    globalModuleScope?: boolean;
+}
 export type ContextStack = ContextStackImpl;
 export declare class ContextStackImpl {
     private _contexts;
@@ -23,6 +28,8 @@ export declare class ContextStackImpl {
     getContextsRaw(): Context[];
     /** Get host values (plain bindings passed at creation). */
     getHostValues(): Record<string, unknown> | undefined;
+    /** Get the top-level module scope as plain key→value bindings. */
+    getModuleScopeBindings(): Record<string, unknown>;
     /**
      * Find the index of globalContext in the _contexts array.
      * Returns -1 if not found (should not happen in valid state).
@@ -59,4 +66,5 @@ export declare class ContextStackImpl {
     lookUp(node: UserDefinedSymbolNode): LookUpResult;
     evaluateSymbol(node: SymbolNode): Any;
 }
-export declare function createContextStack(params?: ContextParams, modules?: Map<string, DvalaModule>, pure?: boolean): ContextStack;
+export declare function createContextStack(params?: CreateContextStackParams, modules?: Map<string, DvalaModule>, pure?: boolean): ContextStack;
+export {};

package/dist/cli/src/evaluator/effectTypes.d.ts

@@ -97,8 +97,8 @@ export interface EffectContext {
      */
     resumeFrom: (snapshot: Snapshot, value: Any) => void;
 }
-/** An async function that handles an effect by calling `resume`, `suspend`, `fail`, or `next`. */
-export type EffectHandler = (ctx: EffectContext) => Promise<void>;
+/** A function that handles an effect by calling `resume`, `suspend`, `fail`, or `next`. */
+export type EffectHandler = (ctx: EffectContext) => void | Promise<void>;
 /** Map from effect pattern (e.g. `'llm.complete'`, `'dvala.*'`, `'*'`) to its handler. */
 export type Handlers = Record<string, EffectHandler>;
 /**
@@ -112,9 +112,8 @@ export type Handlers = Record<string, EffectHandler>;
  */
 export declare function effectNameMatchesPattern(effectName: string, pattern: string): boolean;
 /**
- * Find all matching handlers for an effect name, in registration order.
- * Returns an array of `[pattern, handler]` pairs — the first entry is
- * the "most specific" by registration order, not by pattern specificity.
+ * Find all matching async handlers for an effect name, in registration order.
+ * Returns an array of `[pattern, handler]` pairs.
  */
 export declare function findMatchingHandlers(effectName: string, handlers: Handlers | undefined): Array<[string, EffectHandler]>;
 /**
@@ -124,6 +123,7 @@ export declare function findMatchingHandlers(effectName: string, handlers: Handl
 export type RunResult = {
     type: 'completed';
     value: Any;
+    definedBindings?: Record<string, unknown>;
 } | {
     type: 'suspended';
     snapshot: Snapshot;

package/dist/cli/src/evaluator/trampoline.d.ts

@@ -70,7 +70,7 @@ export declare function tick(step: Step, handlers?: Handlers, signal?: AbortSign
  * Throws if any step produces a Promise (i.e., an async operation was
  * encountered in a synchronous context).
  */
-export declare function runSyncTrampoline(initial: Step): Any;
+export declare function runSyncTrampoline(initial: Step, effectHandlers?: Handlers): Any;
 /**
  * Run the trampoline asynchronously to completion.
  * Awaits any Promise<Step> that surfaces from async operations.
@@ -110,6 +110,15 @@ export declare function evaluateNode(node: AstNode, contextStack: ContextStack):
  * and host-side timeouts.
  */
 export declare function evaluateWithEffects(ast: Ast, contextStack: ContextStack, handlers?: Handlers, maxSnapshots?: number, deserializeOptions?: DeserializeOptions): Promise<RunResult>;
+/**
+ * Evaluate an AST synchronously with effect handler support.
+ *
+ * Uses the sync trampoline with `effectHandlers` threaded through `tick`.
+ * Throws if an async operation is encountered (e.g., an async handler
+ * is used). Handlers may call `resume(value)`, `fail(msg?)`, or `next()`.
+ * Calling `suspend()` will throw a runtime error.
+ */
+export declare function evaluateWithSyncEffects(ast: Ast, contextStack: ContextStack, effectHandlers?: Handlers): Any;
 /**
  * Resume a suspended continuation with a value.
  *

package/dist/cli/src/parser/subParsers/parseDo.d.ts

@@ -1,3 +1,3 @@
 import type { DoNode } from '../../builtin/specialExpressions/block';
 import type { ParserContext } from '../ParserContext';
-export declare function parseDo(ctx: ParserContext, allowDocString?: boolean): [DoNode, string];
+export declare function parseDo(ctx: ParserContext): DoNode;

package/dist/cli/src/tokenizer/token.d.ts

@@ -1,6 +1,6 @@
 import type { ReservedSymbol } from './reservedNames';
 import { type SymbolicBinaryOperator, type SymbolicOperator } from './operators';
-export declare const tokenTypes: readonly ["LBrace", "LBracket", "RBrace", "RBracket", "LParen", "RParen", "BasePrefixedNumber", "DocString", "Error", "MultiLineComment", "Number", "Operator", "RegexpShorthand", "ReservedSymbol", "SingleLineComment", "Shebang", "string", "Symbol", "Whitespace"];
+export declare const tokenTypes: readonly ["LBrace", "LBracket", "RBrace", "RBracket", "LParen", "RParen", "BasePrefixedNumber", "Error", "MultiLineComment", "Number", "Operator", "RegexpShorthand", "ReservedSymbol", "SingleLineComment", "Shebang", "string", "Symbol", "Whitespace"];
 export type TokenType = typeof tokenTypes[number];
 type GenericToken<T extends TokenType, V extends string = string> = [T, V] | [T, V, SourceCodeInfo];
 export type ErrorToken = ['Error', string, SourceCodeInfo | undefined, string];
@@ -19,10 +19,9 @@ export type ReservedSymbolToken<T extends ReservedSymbol = ReservedSymbol> = Gen
 export type SingleLineCommentToken = GenericToken<'SingleLineComment'>;
 export type ShebangToken = GenericToken<'Shebang'>;
 export type StringToken = GenericToken<'string'>;
-export type DocStringToken = GenericToken<'DocString'>;
 export type SymbolToken<T extends string = string> = GenericToken<'Symbol', T>;
 export type WhitespaceToken = GenericToken<'Whitespace'>;
-export type Token = LBraceToken | LBracketToken | LParenToken | RBraceToken | RBracketToken | RParenToken | BasePrefixedNumberToken | DocStringToken | ErrorToken | MultiLineCommentToken | NumberToken | OperatorToken | RegexpShorthandToken | ReservedSymbolToken | SingleLineCommentToken | ShebangToken | StringToken | SymbolToken | WhitespaceToken;
+export type Token = LBraceToken | LBracketToken | LParenToken | RBraceToken | RBracketToken | RParenToken | BasePrefixedNumberToken | ErrorToken | MultiLineCommentToken | NumberToken | OperatorToken | RegexpShorthandToken | ReservedSymbolToken | SingleLineCommentToken | ShebangToken | StringToken | SymbolToken | WhitespaceToken;
 export type TokenDescriptor<T extends Token> = [length: number, token?: T];
 export interface SourceCodeInfo {
     position: {
@@ -74,7 +73,6 @@ export declare function asRBraceToken(token: Token | undefined): RBraceToken;
 export declare function isStringToken(token: Token | undefined): token is StringToken;
 export declare function assertStringToken(token: Token | undefined): asserts token is StringToken;
 export declare function asStringToken(token: Token | undefined): StringToken;
-export declare function isDocStringToken(token: Token | undefined): token is DocStringToken;
 export declare function isRegexpShorthandToken(token: Token | undefined): token is RegexpShorthandToken;
 export declare function assertRegexpShorthandToken(token: Token | undefined): asserts token is RegexpShorthandToken;
 export declare function asRegexpShorthandToken(token: Token | undefined): RegexpShorthandToken;

package/dist/cli/src/tokenizer/tokenize.d.ts

@@ -1,8 +1,7 @@
-import type { FilePathParams } from '../Dvala/Dvala';
 import type { Token } from './token';
 export interface TokenStream {
     tokens: Token[];
     hasDebugData: boolean;
     filePath?: string;
 }
-export declare function tokenize(input: string, debug: boolean, filePath: FilePathParams['filePath']): TokenStream;
+export declare function tokenize(input: string, debug: boolean, filePath: string | undefined): TokenStream;

package/dist/cli/src/tokenizer/tokenizers.d.ts

@@ -1,7 +1,6 @@
-import type { BasePrefixedNumberToken, DocStringToken, ErrorToken, LBraceToken, LBracketToken, LParenToken, MultiLineCommentToken, NumberToken, OperatorToken, RBraceToken, RBracketToken, RParenToken, RegexpShorthandToken, ReservedSymbolToken, SingleLineCommentToken, StringToken, SymbolToken, Token, TokenDescriptor, WhitespaceToken } from './token';
+import type { BasePrefixedNumberToken, ErrorToken, LBraceToken, LBracketToken, LParenToken, MultiLineCommentToken, NumberToken, OperatorToken, RBraceToken, RBracketToken, RParenToken, RegexpShorthandToken, ReservedSymbolToken, SingleLineCommentToken, StringToken, SymbolToken, Token, TokenDescriptor, WhitespaceToken } from './token';
 type Tokenizer<T extends Token> = (input: string, position: number) => TokenDescriptor<T | ErrorToken>;
 export declare const NO_MATCH: TokenDescriptor<never>;
-export declare const tokenizeDocString: Tokenizer<DocStringToken>;
 export declare const tokenizeNumber: Tokenizer<NumberToken>;
 export declare const tokenizeBasePrefixedNumber: Tokenizer<BasePrefixedNumberToken>;
 export declare const tokenizeSymbol: Tokenizer<SymbolToken>;
@@ -10,5 +9,5 @@ export declare const tokenizeOperator: Tokenizer<OperatorToken>;
 export declare const tokenizeMultiLineComment: Tokenizer<MultiLineCommentToken>;
 export declare const tokenizeShebang: Tokenizer<SingleLineCommentToken>;
 export declare const tokenizeSingleLineComment: Tokenizer<SingleLineCommentToken>;
-export declare const tokenizers: [Tokenizer<WhitespaceToken>, Tokenizer<MultiLineCommentToken>, Tokenizer<SingleLineCommentToken>, Tokenizer<ReservedSymbolToken>, Tokenizer<LParenToken>, Tokenizer<RParenToken>, Tokenizer<LBracketToken>, Tokenizer<RBracketToken>, Tokenizer<LBraceToken>, Tokenizer<RBraceToken>, Tokenizer<DocStringToken>, Tokenizer<StringToken>, Tokenizer<RegexpShorthandToken>, Tokenizer<BasePrefixedNumberToken>, Tokenizer<NumberToken>, Tokenizer<OperatorToken>, Tokenizer<SymbolToken>];
+export declare const tokenizers: [Tokenizer<WhitespaceToken>, Tokenizer<MultiLineCommentToken>, Tokenizer<SingleLineCommentToken>, Tokenizer<ReservedSymbolToken>, Tokenizer<LParenToken>, Tokenizer<RParenToken>, Tokenizer<LBracketToken>, Tokenizer<RBracketToken>, Tokenizer<LBraceToken>, Tokenizer<RBraceToken>, Tokenizer<StringToken>, Tokenizer<RegexpShorthandToken>, Tokenizer<BasePrefixedNumberToken>, Tokenizer<NumberToken>, Tokenizer<OperatorToken>, Tokenizer<SymbolToken>];
 export {};

package/dist/cli/src/tooling.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Standalone tooling functions for tokenizing, parsing, and analysis.
+ *
+ * These are thin wrappers around internal utilities that do not require
+ * a Dvala instance.
+ */
+import { AutoCompleter } from './AutoCompleter/AutoCompleter';
+import type { AutoCompleterParams } from './AutoCompleter/AutoCompleter';
+import type { DvalaModule } from './builtin/modules/interface';
+import type { TokenStream } from './tokenizer/tokenize';
+import type { Ast } from './parser/types';
+import { untokenize } from './untokenizer';
+export type { TokenStream };
+/**
+ * Tokenize a Dvala source string into a token stream.
+ * Pass `debug: true` to capture source positions (needed for the debugger).
+ */
+export declare function tokenizeSource(source: string, debug?: boolean, filePath?: string): TokenStream;
+/**
+ * Parse a token stream into an AST.
+ * The stream is automatically minified (whitespace removed) before parsing.
+ */
+export declare function parseTokenStream(tokenStream: TokenStream): Ast;
+/**
+ * Convert a token stream back to source code.
+ */
+export { untokenize };
+/**
+ * Transform all symbol tokens in a token stream using the provided function.
+ */
+export declare function transformSymbols(tokenStream: TokenStream, transformer: (symbol: string) => string): TokenStream;
+/**
+ * Get all undefined symbols in a Dvala program.
+ *
+ * @param source - Dvala source code
+ * @param options - optional context to treat as defined
+ * @param options.bindings - host bindings to treat as defined
+ * @param options.modules - modules to treat as available
+ */
+export declare function getUndefinedSymbols(source: string, options?: {
+    bindings?: Record<string, unknown>;
+    modules?: DvalaModule[];
+}): Set<string>;
+/**
+ * Create an auto-completer for the given program at the given cursor position.
+ *
+ * @param program - Full Dvala source code
+ * @param position - Cursor position (character offset)
+ * @param params - Optional params (bindings to include as suggestions)
+ */
+export declare function getAutoCompleter(program: string, position: number, params?: AutoCompleterParams): AutoCompleter;