@mojir/lits 2.4.1 → 2.5.0

package/README.md

@@ -48,10 +48,10 @@ $ lits eval "[1, 2, 3, 4] filter odd? map inc"
 $ lits run script.lits
 
 # Bundle a multi-file project into a single .json file
-$ lits bundle main.lits -o bundle.json
+$ lits bundle main.lits -o bundle.lits.json
 
 # Run a bundle
-$ lits run-bundle bundle.json
+$ lits run-bundle bundle.lits.json
 
 # Run tests
 $ lits test tests.test.lits

package/dist/cli/cli.js

@@ -7,7 +7,7 @@ var readline = require('node:readline');
 var os = require('node:os');
 var process$1 = require('node:process');
 
-var version = "2.4.1";
+var version = "2.5.0";
 
 function getCodeMarker(sourceCodeInfo) {
     if (!sourceCodeInfo.position || !sourceCodeInfo.code)
@@ -3677,6 +3677,7 @@ const miscNormalExpression = {
                 return asAny(params[params.length - 1], sourceCodeInfo);
             return null;
         },
+        pure: false,
         arity: {},
         docs: {
             category: 'misc',
@@ -6757,7 +6758,10 @@ function isNumberReservedSymbol(symbol) {
 }
 
 const functionExecutors = {
-    NativeJsFunction: (fn, params, sourceCodeInfo) => {
+    NativeJsFunction: (fn, params, sourceCodeInfo, contextStack) => {
+        if (contextStack.pure && !fn.nativeFn.pure) {
+            throw new LitsError(`Cannot call impure native function '${fn.name}' in pure mode`, sourceCodeInfo);
+        }
         try {
             const result = fn.nativeFn.fn(...params);
             // If the native function returns a Promise, await it transparently
@@ -6938,6 +6942,9 @@ const functionExecutors = {
     },
     Builtin: (fn, params, sourceCodeInfo, contextStack, { executeFunction }) => {
         const normalExpression = asNonUndefined(allNormalExpressions[fn.normalBuiltinSymbolType], sourceCodeInfo);
+        if (contextStack.pure && normalExpression.pure === false) {
+            throw new LitsError(`Cannot call impure function '${fn.name}' in pure mode`, sourceCodeInfo);
+        }
         return normalExpression.evaluate(params, sourceCodeInfo, contextStack, { executeFunction });
     },
     SpecialBuiltin: (fn, params, sourceCodeInfo, contextStack, { executeFunction }) => {
@@ -6958,6 +6965,9 @@ const functionExecutors = {
         if (!expression) {
             throw new LitsError(`Function '${fn.functionName}' not found in module '${fn.moduleName}'.`, sourceCodeInfo);
         }
+        if (contextStack.pure && expression.pure === false) {
+            throw new LitsError(`Cannot call impure function '${fn.functionName}' in pure mode`, sourceCodeInfo);
+        }
         assertNumberOfParams(expression.arity, params.length, sourceCodeInfo);
         return expression.evaluate(params, sourceCodeInfo, contextStack, { executeFunction });
     },
@@ -7056,6 +7066,9 @@ function evaluateNormalExpression(node, contextStack) {
             if (isNormalBuiltinSymbolNode(nameSymbol)) {
                 const type = nameSymbol[1];
                 const normalExpression = builtin.allNormalExpressions[type];
+                if (contextStack.pure && normalExpression.pure === false) {
+                    throw new LitsError(`Cannot call impure function '${normalExpression.name}' in pure mode`, node[2]);
+                }
                 return normalExpression.evaluate(params, node[2], contextStack, { executeFunction });
             }
             else {
@@ -7152,13 +7165,15 @@ class ContextStackImpl {
     nativeJsFunctions;
     modules;
     valueModules;
-    constructor({ contexts, values: hostValues, nativeJsFunctions, modules, valueModules, }) {
+    pure;
+    constructor({ contexts, values: hostValues, nativeJsFunctions, modules, valueModules, pure, }) {
         this.globalContext = asNonUndefined(contexts[0]);
         this.contexts = contexts;
         this.values = hostValues;
         this.nativeJsFunctions = nativeJsFunctions;
         this.modules = modules ?? new Map();
         this.valueModules = valueModules ?? new Map();
+        this.pure = pure ?? false;
     }
     getModule(name) {
         return this.modules.get(name);
@@ -7180,13 +7195,14 @@ class ContextStackImpl {
             nativeJsFunctions: this.nativeJsFunctions,
             modules: this.modules,
             valueModules: this.valueModules,
+            pure: this.pure,
         });
         contextStack.globalContext = globalContext;
         return contextStack;
     }
     new(context) {
         const contexts = [{}, context];
-        return new ContextStackImpl({ contexts, modules: this.modules, valueModules: this.valueModules });
+        return new ContextStackImpl({ contexts, modules: this.modules, valueModules: this.valueModules, pure: this.pure });
     }
     addValues(values, sourceCodeInfo) {
         const currentContext = this.contexts[0];
@@ -7292,7 +7308,7 @@ function assertNotShadowingBuiltin(name) {
         throw new LitsError(`Cannot shadow ${shadowedName}`, undefined);
     }
 }
-function createContextStack(params = {}, modules) {
+function createContextStack(params = {}, modules, pure) {
     const globalContext = params.globalContext ?? {};
     // Contexts are checked from left to right
     const contexts = params.contexts ? [globalContext, ...params.contexts] : [globalContext];
@@ -7336,6 +7352,7 @@ function createContextStack(params = {}, modules) {
         values: hostValues,
         modules,
         nativeJsFunctions,
+        pure,
     });
     return params.globalModuleScope ? contextStack : contextStack.create({});
 }
@@ -9443,9 +9460,13 @@ class Lits {
         return result;
     }
     runBundle(bundle, params = {}) {
-        const contextStack = createContextStack(params, this.modules);
+        const contextStack = createContextStack(params, this.modules, params.pure);
         // Evaluate file modules in dependency order and register as value modules.
         // Each file module is evaluated in its own scope so local bindings don't leak.
+        // File modules are always evaluated in pure mode to ensure deterministic,
+        // side-effect-free initialization regardless of the caller's pure setting.
+        const savedPure = contextStack.pure;
+        contextStack.pure = true;
         for (const [name, source] of bundle.fileModules) {
             const ast = this.generateAst(source, params);
             const moduleContextStack = contextStack.create({});
@@ -9455,6 +9476,7 @@ class Lits {
             }
             contextStack.registerValueModule(name, result);
         }
+        contextStack.pure = savedPure;
         // Parse and evaluate the main program
         const ast = this.generateAst(bundle.program, params);
         const result = evaluate(ast, contextStack);
@@ -9482,7 +9504,7 @@ class Lits {
         return ast;
     }
     evaluate(ast, params) {
-        const contextStack = createContextStack(params, this.modules);
+        const contextStack = createContextStack(params, this.modules, params.pure);
         return evaluate(ast, contextStack);
     }
     transformSymbols(tokenStream, transformer) {
@@ -13256,6 +13278,7 @@ const randomFunctions = {
         evaluate: () => {
             return Math.random();
         },
+        pure: false,
         arity: toFixedArity(0),
     },
     'random-int!': {
@@ -13264,6 +13287,7 @@ const randomFunctions = {
             assertNumber(max, sourceCodeInfo, { integer: true, gt: min });
             return Math.floor(Math.random() * (max - min)) + min;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-int-inclusive!': {
@@ -13272,6 +13296,7 @@ const randomFunctions = {
             assertNumber(max, sourceCodeInfo, { integer: true, gte: min });
             return Math.floor(Math.random() * (max - min + 1)) + min;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-float!': {
@@ -13280,6 +13305,7 @@ const randomFunctions = {
             assertNumber(max, sourceCodeInfo, { gt: min });
             return Math.random() * (max - min) + min;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-boolean!': {
@@ -13288,6 +13314,7 @@ const randomFunctions = {
             assertNumber(probability, sourceCodeInfo, { gte: 0, lte: 1 });
             return Math.random() < probability;
         },
+        pure: false,
         arity: { min: 0, max: 1 },
     },
     'random-item!': {
@@ -13296,6 +13323,7 @@ const randomFunctions = {
             const index = Math.floor(Math.random() * array.length);
             return asAny(array[index]);
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'random-sample!': {
@@ -13314,6 +13342,7 @@ const randomFunctions = {
             }
             return result;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-sample-unique!': {
@@ -13335,6 +13364,7 @@ const randomFunctions = {
             }
             return result;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'shuffle!': {
@@ -13347,6 +13377,7 @@ const randomFunctions = {
             }
             return shuffledArray;
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'random-normal!': {
@@ -13358,6 +13389,7 @@ const randomFunctions = {
             const z0 = Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math.PI * u2);
             return z0 * stdDev + mean;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-exponential!': {
@@ -13366,6 +13398,7 @@ const randomFunctions = {
             const u = Math.random();
             return -Math.log(u) / lambda;
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'random-binomial!': {
@@ -13380,6 +13413,7 @@ const randomFunctions = {
             }
             return k;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-poisson!': {
@@ -13394,6 +13428,7 @@ const randomFunctions = {
             } while (p > L);
             return k - 1;
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'random-gamma!': {
@@ -13402,6 +13437,7 @@ const randomFunctions = {
             assertNumber(scale, sourceCodeInfo, { gt: 0 });
             return randomGamma(shape, scale);
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-pareto!': {
@@ -13410,6 +13446,7 @@ const randomFunctions = {
             const u = Math.random();
             return (1 / u) ** (1 / alpha);
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'uuid!': {
@@ -13420,6 +13457,7 @@ const randomFunctions = {
                 return value.toString(16);
             });
         },
+        pure: false,
         arity: toFixedArity(0),
     },
     'random-char!': {
@@ -13431,6 +13469,7 @@ const randomFunctions = {
             const randomIndex = Math.floor(Math.random() * charSet.length);
             return charSet[randomIndex];
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'random-string!': {
@@ -13447,6 +13486,7 @@ const randomFunctions = {
             }
             return result;
         },
+        pure: false,
         arity: toFixedArity(2),
     },
     'random-id!': {
@@ -13460,6 +13500,7 @@ const randomFunctions = {
             }
             return result;
         },
+        pure: false,
         arity: toFixedArity(1),
     },
     'random-color!': {
@@ -13467,6 +13508,7 @@ const randomFunctions = {
             const randomColor = Math.floor(Math.random() * 0x1000000).toString(16);
             return `#${randomColor.padStart(6, '0')}`;
         },
+        pure: false,
         arity: toFixedArity(0),
     },
 };
@@ -34633,18 +34675,19 @@ const helpRegExp = new RegExp(`^\`help\\s+(${polishSymbolFirstCharacterClass}${p
 const expressions = [...normalExpressionKeys, ...specialExpressionKeys];
 const config = processArguments(process.argv.slice(2));
 const cliModules = getCliModules();
-function createLits(context) {
+function createLits(context, pure) {
     const _lits = new Lits({ debug: true, modules: [...allBuiltinModules, ...cliModules] });
     return {
         run: (program) => _lits.run(program, {
             globalContext: context,
             globalModuleScope: true,
+            pure,
         }),
     };
 }
 switch (config.subcommand) {
     case 'run': {
-        const lits = createLits(config.context);
+        const lits = createLits(config.context, config.pure);
         try {
             const content = fs.readFileSync(config.filename, { encoding: 'utf-8' });
             const result = lits.run(content);
@@ -34660,7 +34703,7 @@ switch (config.subcommand) {
         break;
     }
     case 'run-bundle': {
-        const lits = createLits(config.context);
+        const lits = createLits(config.context, config.pure);
         try {
             const content = fs.readFileSync(config.filename, { encoding: 'utf-8' });
             let parsed;
@@ -34688,7 +34731,7 @@ switch (config.subcommand) {
         break;
     }
     case 'eval': {
-        const lits = createLits(config.context);
+        const lits = createLits(config.context, config.pure);
         try {
             const result = lits.run(config.expression);
             if (config.printResult) {
@@ -34728,7 +34771,7 @@ switch (config.subcommand) {
     }
     case 'repl': {
         if (config.loadFilename) {
-            const lits = createLits(config.context);
+            const lits = createLits(config.context, false);
             const content = fs.readFileSync(config.loadFilename, { encoding: 'utf-8' });
             const result = lits.run(content);
             if (result !== null && typeof result === 'object' && !Array.isArray(result)) {
@@ -34765,7 +34808,7 @@ function runLitsTest(testPath, testNamePattern) {
         process.exit(1);
 }
 function execute(expression, context) {
-    const lits = createLits(context);
+    const lits = createLits(context, false);
     try {
         const result = lits.run(expression);
         historyResults.unshift(result);
@@ -34884,6 +34927,7 @@ function parsePrintOptions(args, startIndex) {
 function parseRunEvalOptions(args, startIndex) {
     let context = {};
     let printResult = true;
+    let pure = false;
     let i = startIndex;
     while (i < args.length) {
         const parsed = parseOption(args, i);
@@ -34906,6 +34950,10 @@ function parseRunEvalOptions(args, startIndex) {
                 i = result.nextIndex;
                 break;
             }
+            case '--pure':
+                pure = true;
+                i += parsed.count;
+                break;
             default:
                 printErrorMessage(`Unknown option "${parsed.option}"`);
                 process.exit(1);
@@ -34915,7 +34963,7 @@ function parseRunEvalOptions(args, startIndex) {
         printErrorMessage(`Unknown argument "${args[i]}"`);
         process.exit(1);
     }
-    return { context, printResult, nextIndex: i };
+    return { context, printResult, pure, nextIndex: i };
 }
 function processArguments(args) {
     // Global flags (no subcommand)
@@ -34936,8 +34984,8 @@ function processArguments(args) {
                 printErrorMessage('Missing filename after "run"');
                 process.exit(1);
             }
-            const { context, printResult } = parseRunEvalOptions(args, 2);
-            return { subcommand: 'run', filename, context, printResult };
+            const { context, printResult, pure } = parseRunEvalOptions(args, 2);
+            return { subcommand: 'run', filename, context, printResult, pure };
         }
         case 'run-bundle': {
             const filename = args[1];
@@ -34945,8 +34993,8 @@ function processArguments(args) {
                 printErrorMessage('Missing filename after "run-bundle"');
                 process.exit(1);
             }
-            const { context, printResult } = parseRunEvalOptions(args, 2);
-            return { subcommand: 'run-bundle', filename, context, printResult };
+            const { context, printResult, pure } = parseRunEvalOptions(args, 2);
+            return { subcommand: 'run-bundle', filename, context, printResult, pure };
         }
         case 'eval': {
             const expression = args[1];
@@ -34954,8 +35002,8 @@ function processArguments(args) {
                 printErrorMessage('Missing expression after "eval"');
                 process.exit(1);
             }
-            const { context, printResult } = parseRunEvalOptions(args, 2);
-            return { subcommand: 'eval', expression, context, printResult };
+            const { context, printResult, pure } = parseRunEvalOptions(args, 2);
+            return { subcommand: 'eval', expression, context, printResult, pure };
         }
         case 'bundle': {
             const filename = args[1];
@@ -35147,6 +35195,7 @@ Run/Run-bundle/Eval options:
   -c, --context=<json>            Context as a JSON string
   -C, --context-file=<file>       Context from a .json file
   -s, --silent                    Suppress printing the result
+  --pure                          Enforce pure mode (no side effects or non-determinism)
 
 Bundle options:
   -o, --output=<file>             Write bundle to file (default: stdout)

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

@@ -16,6 +16,7 @@ export interface LitsRuntimeInfo {
 export interface JsFunction {
     fn: (...args: any[]) => unknown;
     arity?: Arity;
+    pure?: boolean;
     docString?: string;
 }
 export interface ContextParams {
@@ -30,6 +31,9 @@ export interface MinifyParams {
 export interface FilePathParams {
     filePath?: string;
 }
+export interface PureParams {
+    pure?: boolean;
+}
 interface LitsConfig {
     initialCache?: Record<string, Ast>;
     astCacheSize?: number | null;
@@ -44,10 +48,10 @@ export declare class Lits {
     constructor(config?: LitsConfig);
     getRuntimeInfo(): LitsRuntimeInfo;
     readonly async: {
-        run: (programOrBundle: string | LitsBundle, params?: ContextParams & FilePathParams) => Promise<unknown>;
-        apply: (fn: LitsFunction, fnParams: unknown[], params?: ContextParams) => Promise<unknown>;
+        run: (programOrBundle: string | LitsBundle, params?: ContextParams & FilePathParams & PureParams) => Promise<unknown>;
+        apply: (fn: LitsFunction, fnParams: unknown[], params?: ContextParams & PureParams) => Promise<unknown>;
     };
-    run(programOrBundle: string | LitsBundle, params?: ContextParams & FilePathParams): unknown;
+    run(programOrBundle: string | LitsBundle, params?: ContextParams & FilePathParams & PureParams): unknown;
     private runBundle;
     getUndefinedSymbols(programOrAst: string | Ast, params?: ContextParams): Set<string>;
     tokenize(program: string, tokenizeParams?: FilePathParams & MinifyParams): TokenStream;
@@ -55,7 +59,7 @@ export declare class Lits {
     private evaluate;
     transformSymbols(tokenStream: TokenStream, transformer: (symbol: string) => string): TokenStream;
     untokenize(tokenStream: TokenStream): string;
-    apply(fn: LitsFunction, fnParams: unknown[], params?: ContextParams): MaybePromise<Any>;
+    apply(fn: LitsFunction, fnParams: unknown[], params?: ContextParams & PureParams): MaybePromise<Any>;
     private generateApplyFunctionCall;
     private generateAst;
     getAutoCompleter(program: string, position: number, params?: ContextParams): AutoCompleter;

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

@@ -80,6 +80,7 @@ type NormalExpressionEvaluator<T> = (params: Arr, sourceCodeInfo: SourceCodeInfo
 }) => MaybePromise<T>;
 export interface BuiltinNormalExpression<T> {
     evaluate: NormalExpressionEvaluator<T>;
+    pure?: boolean;
     name?: string;
     arity: Arity;
     docs?: FunctionDocs;

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

@@ -12,12 +12,14 @@ export declare class ContextStackImpl {
     private nativeJsFunctions?;
     private modules;
     private valueModules;
-    constructor({ contexts, values: hostValues, nativeJsFunctions, modules, valueModules, }: {
+    pure: boolean;
+    constructor({ contexts, values: hostValues, nativeJsFunctions, modules, valueModules, pure, }: {
         contexts: Context[];
         values?: Record<string, unknown>;
         nativeJsFunctions?: Record<string, NativeJsFunction>;
         modules?: Map<string, LitsModule>;
         valueModules?: Map<string, unknown>;
+        pure?: boolean;
     });
     getModule(name: string): LitsModule | undefined;
     getValueModule(name: string): {
@@ -32,4 +34,4 @@ export declare class ContextStackImpl {
     lookUp(node: UserDefinedSymbolNode): LookUpResult;
     evaluateSymbol(node: SymbolNode): Any;
 }
-export declare function createContextStack(params?: ContextParams, modules?: Map<string, LitsModule>): ContextStack;
+export declare function createContextStack(params?: ContextParams, modules?: Map<string, LitsModule>, pure?: boolean): ContextStack;

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

@@ -11,6 +11,6 @@ export type { LitsModule } from './builtin/modules/interface';
 export type { LitsBundle } from './bundler/interface';
 export { isLitsBundle } from './bundler/interface';
 export { type LitsError, isLitsError } from './errors';
-export type { ContextParams, FilePathParams, MinifyParams, LitsRuntimeInfo, JsFunction } from './Lits/Lits';
+export type { ContextParams, FilePathParams, MinifyParams, PureParams, LitsRuntimeInfo, JsFunction } from './Lits/Lits';
 export { isGrid, isMatrix, isVector } from './typeGuards/annotatedArrays';
 export type { AutoCompleter } from './AutoCompleter/AutoCompleter';