@mojir/lits 2.2.3 → 2.3.0

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

@@ -5,6 +5,7 @@ import type { TokenStream } from '../tokenizer/tokenize';
 import { AutoCompleter } from '../AutoCompleter/AutoCompleter';
 import type { Arity } from '../builtin/interface';
 import type { LitsModule } from '../builtin/modules/interface';
+import type { MaybePromise } from '../utils/maybePromise';
 import { Cache } from './Cache';
 export interface LitsRuntimeInfo {
     astCache: Cache | null;
@@ -42,15 +43,20 @@ export declare class Lits {
     private modules;
     constructor(config?: LitsConfig);
     getRuntimeInfo(): LitsRuntimeInfo;
+    readonly async: {
+        run: (program: string, params?: ContextParams & FilePathParams) => Promise<unknown>;
+        context: (programOrAst: string | Ast, params?: ContextParams & FilePathParams) => Promise<Context>;
+        apply: (fn: LitsFunction, fnParams: unknown[], params?: ContextParams) => Promise<unknown>;
+    };
     run(program: string, params?: ContextParams & FilePathParams): unknown;
     context(programOrAst: string | Ast, params?: ContextParams & FilePathParams): Context;
     getUndefinedSymbols(programOrAst: string | Ast, params?: ContextParams): Set<string>;
     tokenize(program: string, tokenizeParams?: FilePathParams & MinifyParams): TokenStream;
     parse(tokenStream: TokenStream): Ast;
-    evaluate(ast: Ast, params: ContextParams): Any;
+    evaluate(ast: Ast, params: ContextParams): MaybePromise<Any>;
     transformSymbols(tokenStream: TokenStream, transformer: (symbol: string) => string): TokenStream;
     untokenize(tokenStream: TokenStream): string;
-    apply(fn: LitsFunction, fnParams: unknown[], params?: ContextParams): Any;
+    apply(fn: LitsFunction, fnParams: unknown[], params?: ContextParams): MaybePromise<Any>;
     private generateApplyFunctionCall;
     private generateAst;
     getAutoCompleter(program: string, position: number, params?: ContextParams): AutoCompleter;

package/dist/cli/src/builtin/bindingNode.d.ts

@@ -1,5 +1,6 @@
 import type { Any } from '../interface';
 import { type AstNode, type BindingTarget } from '../parser/types';
+import type { MaybePromise } from '../utils/maybePromise';
 export declare function walkDefaults(bindingTarget: BindingTarget, onDefault: (Node: AstNode) => void): void;
-export declare function evaluateBindingNodeValues(target: BindingTarget, value: Any, evaluate: (Node: AstNode) => Any): Record<string, Any>;
+export declare function evaluateBindingNodeValues(target: BindingTarget, value: Any, evaluate: (Node: AstNode) => MaybePromise<Any>): MaybePromise<Record<string, Any>>;
 export declare function getAllBindingTargetNames(bindingTarget: BindingTarget): Record<string, true>;

package/dist/cli/src/builtin/interface.d.ts

@@ -4,6 +4,7 @@ import type { GetUndefinedSymbols, UndefinedSymbols } from '../getUndefinedSymbo
 import type { Any, Arr } from '../interface';
 import type { SpecialExpressionNode } from '../parser/types';
 import type { SourceCodeInfo } from '../tokenizer/token';
+import type { MaybePromise } from '../utils/maybePromise';
 import type { SpecialExpressions } from '.';
 export type Arity = {
     min?: number;
@@ -76,7 +77,7 @@ export type SpecialExpressionDocs = FunctionDocs | CustomDocs;
 export declare function isFunctionDocs(docs: SpecialExpressionDocs): docs is FunctionDocs;
 type NormalExpressionEvaluator<T> = (params: Arr, sourceCodeInfo: SourceCodeInfo | undefined, contextStack: ContextStack, { executeFunction }: {
     executeFunction: ExecuteFunction;
-}) => T;
+}) => MaybePromise<T>;
 export interface BuiltinNormalExpression<T> {
     evaluate: NormalExpressionEvaluator<T>;
     name?: string;
@@ -91,7 +92,7 @@ interface EvaluateHelpers {
     getUndefinedSymbols: GetUndefinedSymbols;
 }
 export interface BuiltinSpecialExpression<T, N extends SpecialExpressionNode> {
-    evaluate: (node: N, contextStack: ContextStack, helpers: EvaluateHelpers) => T;
+    evaluate: (node: N, contextStack: ContextStack, helpers: EvaluateHelpers) => MaybePromise<T>;
     evaluateAsNormalExpression?: NormalExpressionEvaluator<T>;
     arity: Arity;
     docs?: SpecialExpressionDocs;

package/dist/cli/src/builtin/modules/number-theory/sequences/index.d.ts

@@ -1,11 +1,12 @@
 import type { SourceCodeInfo } from '../../../../tokenizer/token';
+import type { MaybePromise } from '../../../../utils/maybePromise';
 import type { BuiltinNormalExpression, BuiltinNormalExpressions } from '../../../../builtin/interface';
 type SeqKey<T extends string> = `${T}-seq`;
 type TakeWhileKey<T extends string> = `${T}-take-while`;
 type NthKey<T extends string> = `${T}-nth`;
 type PredKey<T extends string> = `${T}?`;
 type SeqFunction<Type extends number | string> = (length: number, sourceCodeInfo: SourceCodeInfo | undefined) => Type[];
-type TakeWhileFunction<Type extends number | string> = (pred: (value: Type, index: number) => boolean, sourceCodeInfo: SourceCodeInfo | undefined) => Type[];
+type TakeWhileFunction<Type extends number | string> = (pred: (value: Type, index: number) => MaybePromise<boolean>, sourceCodeInfo: SourceCodeInfo | undefined) => MaybePromise<Type[]>;
 type PredFunction<Type extends number | string> = (n: Type, sourceCodeInfo: SourceCodeInfo | undefined) => boolean;
 export type SequenceKeys<T extends string> = SeqKey<T> | TakeWhileKey<T> | NthKey<T> | PredKey<T>;
 export type SequenceDefinition<T extends string, Type extends number | string = number> = {

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

@@ -1,11 +1,12 @@
 import type { Any, Arr } from '../interface';
 import type { LitsFunctionType } from '../parser/types';
 import type { SourceCodeInfo } from '../tokenizer/token';
+import type { MaybePromise } from '../utils/maybePromise';
 import type { ContextStack } from './ContextStack';
 import type { EvaluateNode, ExecuteFunction } from './interface';
 type FunctionExecutors = Record<LitsFunctionType, (fn: any, params: Arr, sourceCodeInfo: SourceCodeInfo | undefined, contextStack: ContextStack, helpers: {
     evaluateNode: EvaluateNode;
     executeFunction: ExecuteFunction;
-}) => Any>;
+}) => MaybePromise<Any>>;
 export declare const functionExecutors: FunctionExecutors;
 export {};

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

@@ -1,5 +1,6 @@
 import type { Any } from '../interface';
 import type { Ast, AstNode } from '../parser/types';
+import type { MaybePromise } from '../utils/maybePromise';
 import type { ContextStack } from './ContextStack';
-export declare function evaluate(ast: Ast, contextStack: ContextStack): Any;
-export declare function evaluateNode(node: AstNode, contextStack: ContextStack): Any;
+export declare function evaluate(ast: Ast, contextStack: ContextStack): MaybePromise<Any>;
+export declare function evaluateNode(node: AstNode, contextStack: ContextStack): MaybePromise<Any>;

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

@@ -1,13 +1,14 @@
 import type { Any, Arr } from '../interface';
 import type { AstNode, FunctionLike } from '../parser/types';
 import type { SourceCodeInfo } from '../tokenizer/token';
+import type { MaybePromise } from '../utils/maybePromise';
 import type { ContextStack } from './ContextStack';
 interface ContextEntry {
     value: Any;
 }
 export type Context = Record<string, ContextEntry>;
-export type EvaluateNode = (node: AstNode, contextStack: ContextStack) => Any;
-export type ExecuteFunction = (fn: FunctionLike, params: Arr, contextStack: ContextStack, sourceCodeInfo?: SourceCodeInfo) => Any;
+export type EvaluateNode = (node: AstNode, contextStack: ContextStack) => MaybePromise<Any>;
+export type ExecuteFunction = (fn: FunctionLike, params: Arr, contextStack: ContextStack, sourceCodeInfo?: SourceCodeInfo) => MaybePromise<Any>;
 export type LookUpResult = ContextEntry | null;
 export declare function isContextEntry(value: unknown): value is ContextEntry;
 export {};

package/dist/cli/src/utils/maybePromise.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MaybePromise utilities for transparent async support.
+ *
+ * The sync path stays zero-overhead — when no async JS functions are involved,
+ * everything runs synchronously with only `instanceof Promise` checks as overhead.
+ * When an async value is detected, the evaluation chain switches to Promise-based
+ * execution for the remainder.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Chain a value that might be a Promise. If the value is sync, calls fn synchronously.
+ * If it's a Promise, chains with .then().
+ */
+export declare function chain<T, U>(value: MaybePromise<T>, fn: (v: T) => MaybePromise<U>): MaybePromise<U>;
+/**
+ * Like Array.map but handles MaybePromise callbacks sequentially.
+ * In the sync case, runs as a simple loop. Switches to async only when needed.
+ */
+export declare function mapSequential<T, U>(arr: readonly T[], fn: (elem: T, index: number) => MaybePromise<U>): MaybePromise<U[]>;
+/**
+ * Like Array.reduce but handles MaybePromise callbacks sequentially.
+ * In the sync case, runs as a simple loop. Switches to async only when needed.
+ */
+export declare function reduceSequential<T, U>(arr: readonly T[], fn: (acc: U, elem: T, index: number) => MaybePromise<U>, initial: U): MaybePromise<U>;
+/**
+ * Like Array.forEach but handles MaybePromise callbacks sequentially.
+ * In the sync case, runs as a simple loop. Switches to async only when needed.
+ */
+export declare function forEachSequential<T>(arr: readonly T[], fn: (elem: T, index: number) => MaybePromise<void>): MaybePromise<void>;
+/**
+ * Try/catch that handles MaybePromise values correctly.
+ * If tryFn returns a Promise, catches both sync throws and Promise rejections.
+ */
+export declare function tryCatch<T>(tryFn: () => MaybePromise<T>, catchFn: (error: unknown) => MaybePromise<T>): MaybePromise<T>;
+/**
+ * Like Array.some but handles MaybePromise callbacks sequentially.
+ * Returns the first truthy MaybePromise result, or false.
+ */
+export declare function someSequential<T>(arr: readonly T[], fn: (elem: T, index: number) => MaybePromise<unknown>): MaybePromise<boolean>;
+/**
+ * Like Array.every but handles MaybePromise callbacks sequentially.
+ * Returns false as soon as a falsy result is found.
+ */
+export declare function everySequential<T>(arr: readonly T[], fn: (elem: T, index: number) => MaybePromise<unknown>): MaybePromise<boolean>;
+/**
+ * Like Array.filter but handles MaybePromise callbacks sequentially.
+ * Returns the filtered array.
+ */
+export declare function filterSequential<T>(arr: readonly T[], fn: (elem: T, index: number) => MaybePromise<unknown>): MaybePromise<T[]>;
+/**
+ * Like Array.findIndex but handles MaybePromise callbacks sequentially.
+ * Returns -1 if no element matches.
+ */
+export declare function findIndexSequential<T>(arr: readonly T[], fn: (elem: T, index: number) => MaybePromise<unknown>): MaybePromise<number>;