@dallaylaen/ski-interpreter 2.6.2 → 2.7.0

package/lib/types/extras.d.ts

@@ -1,11 +1,11 @@
 import { Expr, Named, FormatOptions, TermInfo } from './expr';
 import { toposort } from './toposort';
 /**
- * @desc  Extra utilities that do not belong in the core.
+ *   Extra utilities that do not belong in the core.
  */
 /**
  * @experimental
- * @desc  Look for an expression that matches the predicate,
+ *   Look for an expression that matches the predicate,
  *        starting with the seed and applying the terms to one another.
  *
  *        A predicate returning 0 (or nothing) means "keep looking",
@@ -28,7 +28,7 @@ import { toposort } from './toposort';
  * @param {(e: Expr, props: {}) => number?} predicate
  * @return {{expr?: Expr, total: number, probed: number, gen: number, cache?: Expr[][]}}
  */
-type SearchOptions = {
+export type SearchOptions = {
     depth?: number;
     tries?: number;
     infer?: boolean;
@@ -44,8 +44,8 @@ type SearchOptions = {
     }) => void;
     progressInterval?: number;
 };
-type SearchCallback = (e: Expr, props: TermInfo) => (number | undefined);
-type SearchResult = {
+export type SearchCallback = (e: Expr, props: TermInfo) => (number | undefined);
+export type SearchResult = {
     expr?: Expr;
     total: number;
     probed: number;
@@ -54,7 +54,7 @@ type SearchResult = {
 };
 declare function search(seed: Expr[], options: SearchOptions, predicate: SearchCallback): SearchResult;
 /**
- * @desc Recursively replace all instances of Expr in a data structure with
+ *  Recursively replace all instances of Expr in a data structure with
  *       respective string representation using the format() options.
  *       Objects of other types and primitive values are eft as is.
  *
@@ -64,7 +64,7 @@ declare function search(seed: Expr[], options: SearchOptions, predicate: SearchC
  */
 declare function deepFormat(obj: any, options?: FormatOptions): any;
 /**
- * @desc  Given an expression and a hash of named terms,
+ *   Given an expression and a hash of named terms,
  *        return a semicolon-separated string that declares said expression
  *        unambiguously.
  *
@@ -80,10 +80,20 @@ declare function deepFormat(obj: any, options?: FormatOptions): any;
 declare function declare(expr: Expr, env?: {
     [s: string]: Named;
 }): string;
+/**
+ *   Converts an unknown object into a FormatOptions, or returns an error it it is not valid.
+ *   A null/undefined counts as an empty options object (and is thus valid).
+ */
+declare function checkFormatOptions(raw: unknown): {
+    value: FormatOptions;
+} | {
+    error: Record<string, string>;
+};
 export declare const extras: {
     search: typeof search;
     deepFormat: typeof deepFormat;
     declare: typeof declare;
     toposort: typeof toposort;
+    checkFormatOptions: typeof checkFormatOptions;
 };
 export {};

package/lib/types/index.d.ts

@@ -20,19 +20,6 @@ export declare class SKI extends Parser {
         Church: typeof Church;
         Alias: typeof import("./expr").Alias;
     };
-    static schemas: {
-        FormatOptions: import("zod").ZodObject<{
-            terse: import("zod").ZodOptional<import("zod").ZodBoolean>;
-            html: import("zod").ZodOptional<import("zod").ZodBoolean>;
-            brackets: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
-            space: import("zod").ZodOptional<import("zod").ZodString>;
-            var: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
-            lambda: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString, import("zod").ZodString], null>>;
-            around: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
-            redex: import("zod").ZodOptional<import("zod").ZodTuple<[import("zod").ZodString, import("zod").ZodString], null>>;
-            inventory: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodCustom<import("./expr").Expr, import("./expr").Expr>>>;
-        }, import("zod/v4/core").$strip>;
-    };
     static B: import("./expr").Native;
     static C: import("./expr").Native;
     static I: import("./expr").Native;
@@ -40,7 +27,7 @@ export declare class SKI extends Parser {
     static S: import("./expr").Native;
     static W: import("./expr").Native;
     /**
-   * @desc Create a proxy object that generates variables on demand,
+   *  Create a proxy object that generates variables on demand,
    *       with names corresponding to the property accessed.
    *       Different invocations will return distinct variables,
    *       even if with the same name.
@@ -55,33 +42,17 @@ export declare class SKI extends Parser {
     };
     static church(n: number): Church;
     static extras: {
-        search: (seed: import("./expr").Expr[], options: {
-            depth?: number;
-            tries?: number;
-            infer?: boolean;
-            maxArgs?: number;
-            max?: number;
-            noskip?: boolean;
-            retain?: boolean;
-            progress?: (info: {
-                gen: number;
-                total: number;
-                probed: number;
-                step: boolean;
-            }) => void;
-            progressInterval?: number;
-        }, predicate: (e: import("./expr").Expr, props: import("./expr").TermInfo) => (number | undefined)) => {
-            expr?: import("./expr").Expr;
-            total: number;
-            probed: number;
-            gen: number;
-            cache?: import("./expr").Expr[][];
-        };
+        search: (seed: import("./expr").Expr[], options: import("./extras").SearchOptions, predicate: import("./extras").SearchCallback) => import("./extras").SearchResult;
         deepFormat: (obj: any, options?: import("./expr").FormatOptions) => any;
         declare: (expr: import("./expr").Expr, env?: {
             [s: string]: import("./expr").Named;
         }) => string;
         toposort: typeof toposort;
+        checkFormatOptions: (raw: unknown) => {
+            value: import("./expr").FormatOptions;
+        } | {
+            error: Record<string, string>;
+        };
     };
     static Quest: typeof Quest;
 }

package/lib/types/internal.d.ts

@@ -1,6 +1,6 @@
 export declare class Tokenizer {
     /**
-     * @desc Create a tokenizer that splits strings into tokens according to the given terms.
+     *  Create a tokenizer that splits strings into tokens according to the given terms.
      * The terms are interpreted as regular expressions, and are sorted by length
      * to ensure that longer matches are preferred over shorter ones.
      * @param {...string|RegExp} terms
@@ -8,14 +8,14 @@ export declare class Tokenizer {
     rex: RegExp;
     constructor(...terms: (string | RegExp)[]);
     /**
-     * @desc Split the given string into tokens according to the terms specified in the constructor.
+     *  Split the given string into tokens according to the terms specified in the constructor.
      * @param {string} str
      * @return {string[]}
      */
     split(str: string): string[];
 }
 /**
- * @desc Add ot remove tokens from a set according to a spec string.
+ *  Add ot remove tokens from a set according to a spec string.
  * The spec string is a sequence of tokens, with each group optionally prefixed
  * by one of the operators '=', '+', or '-'.
  * The '=' operator resets the set to contain only the following token(s).
@@ -28,7 +28,7 @@ export type TraverseDecorator = <T>(value?: T) => TraverseControl<T>;
 export type TraverseValue<T> = TraverseControl<T | null | undefined | void> | T | null | undefined | void;
 export declare class TraverseControl<T> {
     /**
-     * @desc A wrapper for values returned by fold/traverse callbacks
+     *  A wrapper for values returned by fold/traverse callbacks
      *       which instructs the traversal to alter its behavior while
      *       retaining the value in question.
      *
@@ -51,7 +51,7 @@ export declare class TraverseControl<T> {
  */
 export declare function unwrap<T>(value: TraverseValue<T>): [T?, TraverseDecorator?];
 /**
- * @desc Prepare a self-referencing wrapper function for use as a fold/traverse control decorator.
+ *  Prepare a self-referencing wrapper function for use as a fold/traverse control decorator.
  *
  *       If `fun` is created by `prepareWrapper`, then
  *       unwrap(fun(x)) will always return exactly [x, fun], and the second value can be checked with ===.

package/lib/types/parser.d.ts

@@ -45,7 +45,7 @@ export declare class Parser {
     hasLambdas: boolean;
     constructor(options?: ParserOptions);
     /**
-     * @desc Declare a new term
+     *  Declare a new term
      * If the first argument is an Alias, it is added as is.
      * Otherwise, a new Alias or Native term (depending on impl type) is created.
      * If note is not provided and this.annotate is true, an automatic note is generated.
@@ -69,7 +69,7 @@ export declare class Parser {
      */
     add(term: Alias | string, impl?: Expr | string | ((arg: Expr) => Invocation), options?: AddOptions | string): this;
     /**
-     * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
+     *  Internal helper for add() that creates an Alias or Native term from the given arguments.
      * @param {Alias|string} term
      * @param {string|Expr|function(Expr):Partial} impl
      * @returns {Native|Alias}
@@ -77,7 +77,7 @@ export declare class Parser {
      */
     _named(term: Alias | string, impl?: Expr | string | ((arg: Expr) => Invocation)): Native | Alias;
     /**
-     * @desc Declare a new term if it is not known, otherwise just allow it.
+     *  Declare a new term if it is not known, otherwise just allow it.
      *       Currently only used by quests.
      *       Use with caution, this function may change its signature, behavior, or even be removed in the future.
      *
@@ -88,7 +88,7 @@ export declare class Parser {
      */
     maybeAdd(name: string, impl: Expr | string | ((arg: Expr) => Invocation)): this;
     /**
-     * @desc Declare and remove multiple terms at once
+     *  Declare and remove multiple terms at once
      *       term=impl adds term
      *       term= removes term
      * @param {string[]} list
@@ -126,7 +126,7 @@ export declare class Parser {
         [key: string]: Expr;
     };
     /**
-     * @desc Export term declarations for use in bulkAdd().
+     *  Export term declarations for use in bulkAdd().
      * Currently only Alias terms are serialized.
      * @returns {string[]}
      */
@@ -144,7 +144,7 @@ export declare class Parser {
      */
     parse(source: string, options?: ParseOptions): Expr;
     /**
-     * @desc Parse a single line of source code, without splitting it into declarations.
+     *  Parse a single line of source code, without splitting it into declarations.
      *       Internal, always use parse() instead.
      * @template T
      * @param {String} source S(KI)I

package/lib/types/quest.d.ts

@@ -36,6 +36,10 @@ export type InputSpec = {
     numbers?: boolean;
     lambdas?: boolean;
 };
+export type SolEntry = {
+    input: string[];
+    result: QuestResult;
+};
 export type QuestResult = {
     pass: boolean;
     details: CaseResult[];
@@ -45,9 +49,6 @@ export type QuestResult = {
     steps: number;
     weight?: number;
 };
-type QuestMeta = {
-    [key: string]: any;
-};
 export type QuestSpec = {
     input: string | InputSpec | (string | InputSpec)[];
     cases: TestCase[];
@@ -60,12 +61,12 @@ export type QuestSpec = {
     id?: string | number;
     name?: string;
     intro?: string | string[];
-} & QuestMeta;
+} & Record<string, unknown>;
 export type SelfCheck = {
     accepted?: string[][];
     rejected?: string[][];
 };
-type AddCaseOptions = {
+export type AddCaseOptions = {
     engine?: Parser;
     env?: {
         [key: string]: Expr;
@@ -73,25 +74,30 @@ type AddCaseOptions = {
     max?: number;
     note?: string;
     caps?: Capability;
+    canonize?: {
+        max?: number;
+        maxSize?: number;
+        maxArgs?: number;
+    };
 };
+/**
+ *  A combinator problem with a set of test cases for the proposed solution.
+ * @param {QuestSpec} options
+ * @example const quest = new Quest({
+ *    input: 'identity',
+ *    cases: [
+ *      ['identity x', 'x'],
+ *    ],
+ *    allow: 'SK',
+ *    intro: 'Find a combinator that behaves like the identity function.',
+ * });
+ * quest.check('S K K'); // { pass: true, details: [...], ... }
+ * quest.check('K S');   // { pass: false, details: [...], ... }
+ * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
+ *                       //     despite having the same name.
+ * quest.check('I');     // fail! I not in the allowed list.
+ */
 export declare class Quest {
-    /**
-     * @description A combinator problem with a set of test cases for the proposed solution.
-     * @param {QuestSpec} options
-     * @example const quest = new Quest({
-     *    input: 'identity',
-     *    cases: [
-     *      ['identity x', 'x'],
-     *    ],
-     *    allow: 'SK',
-     *    intro: 'Find a combinator that behaves like the identity function.',
-     * });
-     * quest.check('S K K'); // { pass: true, details: [...], ... }
-     * quest.check('K S');   // { pass: false, details: [...], ... }
-     * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
-     *                       //     despite having the same name.
-     * quest.check('I');     // fail! I not in the allowed list.
-     */
     input: (InputSpec & {
         placeholder: FreeVar;
     })[];
@@ -112,7 +118,7 @@ export declare class Quest {
     id?: string | number;
     name?: string;
     intro?: string;
-    meta?: QuestMeta;
+    meta?: Record<string, unknown>;
     constructor(options: QuestSpec);
     /**
      *   Display allowed terms based on what engine thinks of this.env + this.restrict.allow
@@ -128,7 +134,7 @@ export declare class Quest {
      */
     add(opt: AddCaseOptions | string, ...terms: string[]): this;
     /**
-     * @description Statefully parse a list of strings into expressions or fancy aliases thereof.
+     *  Statefully parse a list of strings into expressions or fancy aliases thereof.
      * @param {string[]} input
      * @return {{terms: Expr[], weight: number}}
      */
@@ -138,7 +144,7 @@ export declare class Quest {
     };
     /**
      *
-     * @param {string} input
+     * @param input
      * @return {QuestResult}
      */
     check(...input: string[]): QuestResult;
@@ -152,21 +158,15 @@ export declare class Quest {
         [key: string]: unknown;
     } | null;
     /**
-     * @desc Verify that solutions that are expected to pass/fail do so.
+     *  Verify that solutions that are expected to pass/fail do so.
      * @param {SelfCheck|{[key: string]: SelfCheck}} dataset
      * @return {{shouldPass: {input: string[], result: QuestResult}[], shouldFail: {input: string[], result: QuestResult}[]} | null}
      */
     verifySolutions(dataset: SelfCheck | {
         [key: string | number]: SelfCheck;
     }): {
-        shouldPass: {
-            input: string[];
-            result: QuestResult;
-        }[];
-        shouldFail: {
-            input: string[];
-            result: QuestResult;
-        }[];
+        shouldPass: SolEntry[];
+        shouldFail: SolEntry[];
     } | null;
     verifyMeta(options?: {
         date?: boolean;
@@ -191,9 +191,9 @@ export declare class Quest {
             [key: string]: unknown;
         };
     };
-    static Case: new (input: FreeVar[], options: AddCaseOptions) => Case;
+    static Case: abstract new (input: FreeVar[], options: AddCaseOptions) => Case;
 }
-declare class Case {
+export declare abstract class Case {
     /**
      * @param {FreeVar[]} input
      * @param {{
@@ -213,21 +213,54 @@ declare class Case {
     constructor(input: FreeVar[], options: AddCaseOptions);
     parse(src: string): Subst;
     /**
-     * @param {Expr} expr
+     * @param input
      * @return {CaseResult}
      */
-    check(..._expr: Expr[]): CaseResult;
+    abstract check(...input: Expr[]): CaseResult;
 }
-declare class Subst {
+export declare class ExprCase extends Case {
+    e1: Subst;
+    e2: Subst;
+    canonize?: {
+        max?: number;
+        maxSize?: number;
+        maxArgs?: number;
+    };
     /**
-     * @desc A placeholder object with exactly n free variables to be substituted later.
-     *        Basically a poor man's lambda.
-     * @param {Expr} expr
-     * @param {FreeVar[]} env
+     * @param {FreeVar[]} input
+     * @param {{
+     *    max?: number,
+     *    note?: string,
+     *    env?: {string: Expr},
+     *    canonize?: { max?: number, maxSize?: number, maxArgs?: number },
+     *    engine?: Parser
+     * }} options
+     * @param {[e1: string, e2: string]} terms
      */
+    constructor(input: FreeVar[], options: AddCaseOptions, terms: string[]);
+    check(...input: Expr[]): CaseResult;
+}
+export declare class PropertyCase extends Case {
+    expr: Subst;
+    caps: Capability;
+    isAffine?: boolean;
+    constructor(input: FreeVar[], options: AddCaseOptions, terms: string[]);
+    check(...input: Expr[]): CaseResult;
+}
+/**
+ * A placeholder object with exactly n free variables to be substituted later.
+ * Basically a poor man's n-fold lambda.
+ *
+ * @remarks Internal. Do not rely on name, meaning, or structure. It's only in the docs for completeness sake.
+ *
+ * @experimental
+ *
+ * @param {Expr} expr
+ * @param {FreeVar[]} env
+ */
+export declare class Subst {
     expr: Expr;
     env: FreeVar[];
     constructor(expr: Expr, env: FreeVar[]);
     apply(list: Expr[]): Expr;
 }
-export {};

package/lib/types/toposort.d.ts

@@ -1,6 +1,6 @@
 import { Expr, Named } from './expr';
 /**
- * @desc  Sort a list in such a way that dependent terms come after the (named) terms they depend on.
+ *        Sort a list in such a way that dependent terms come after the (named) terms they depend on.
  *        If env is given, only terms listed there are taken into account.
  *        If env is omitted, it will be implied from the list.
  *        If list is omitted, it will default to values of env.
@@ -18,7 +18,7 @@ import { Expr, Named } from './expr';
  *    const expr = ski.parse(src);
  *    toposort([expr], ski.getTerms()); // returns all terms appearing in Expr in correct order
  */
-type ToposortResult = {
+export type ToposortResult = {
     list: Expr[];
     env: {
         [s: string]: Named;
@@ -27,4 +27,3 @@ type ToposortResult = {
 export declare function toposort(list: Expr[] | Expr | undefined, env: {
     [s: string]: Named;
 } | undefined): ToposortResult;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.6.2",
+  "version": "2.7.0",
   "description": "Simple Kombinator Interpreter - a combinatory logic & lambda calculus parser and interpreter. Supports SKI, BCKW, Church numerals, and setting up assertions ('quests') involving all of the above.",
   "keywords": [
     "combinatory logic",
@@ -14,6 +14,7 @@
   "module": "lib/ski-interpreter.mjs",
   "exports": {
     "types": "./lib/types/index.d.ts",
+    "types/*": "./lib/types/*.d.ts",
     "import": "./lib/ski-interpreter.mjs",
     "require": "./lib/ski-interpreter.cjs.js"
   },
@@ -24,6 +25,7 @@
     "lint": "npx eslint --ext .js,.ts src test bin",
     "tsc": "npx tsc",
     "test": "npm run tsc; npx nyc mocha --recursive test",
+    "tsdoc": "npx typedoc --treatWarningsAsErrors --out docs/man --gitRevision \"$(git log -1 --format='%H' -- src/)\" src/*.ts",
     "build-web": "npx esbuild --bundle --minify --sourcemap --format=iife ./src/index.ts --outfile=docs/build/js/ski-interpreter.min.js",
     "build-cjs": "npx esbuild --bundle --sourcemap --format=cjs ./src/index.ts --outfile=lib/ski-interpreter.cjs.js",
     "build-esm": "npx esbuild --bundle --sourcemap --format=esm ./src/index.ts --outfile=lib/ski-interpreter.mjs",
@@ -61,10 +63,10 @@
     "eslint-plugin-import": "^2.29.1",
     "mocha": "^10.2.0",
     "nyc": "^15.1.0",
+    "typedoc": "^0.28.18",
     "typescript": "^5.8.2"
   },
   "dependencies": {
-    "commander": "^14.0.3",
-    "zod": "^4.3.6"
+    "commander": "^14.0.3"
   }
 }