@dallaylaen/ski-interpreter 2.8.2 → 2.9.0

package/lib/types/extras.d.ts

@@ -2,54 +2,44 @@ import { Expr, Named, FormatOptions, TermInfo, toposort } from './expr';
 /**
  *   Extra utilities that do not belong in the core.
  */
-/**
- * @experimental
- *   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",
- *        a positive number stands for "found",
- *        and a negative means "discard this term from further applications".
- *
- *        The order of search is from shortest to longest expressions.
- *
- * @param {Expr[]} seed
- * @param {object} options
- * @param {number} [options.depth] - maximum generation to search for
- * @param {number} [options.tries] - maximum number of tries before giving up
- * @param {boolean} [options.infer] - whether to call infer(), default true.
- * @param {number} [options.maxArgs] - arguments in infer()
- * @param {number} [options.max] - step limit in infer()
- * @param {boolean} [options.noskip] - prevents skipping equivalent terms. Always true if infer is false.
- * @param {boolean} [retain] - if true. also add the whole cache to returned value
- * @param {({gen: number, total: number, probed: number, step: boolean}) => void} [options.progress]
- * @param {number} [options.progressInterval] - minimum number of tries between calls to options.progress, default 1000.
- * @param {(e: Expr, props: {}) => number?} predicate
- * @return {{expr?: Expr, total: number, probed: number, gen: number, cache?: Expr[][]}}
- */
+export type SearchCallbackResult = {
+    /** ≥0 = cache at gen+offset; negative = discard; omitted = auto-compute */
+    offset?: number;
+    /** true = emit this term as a found result */
+    found?: boolean;
+    /** true = stop the search (after yielding if found is also true) */
+    stop?: boolean;
+};
 export type SearchOptions = {
+    /** maximum generation to search for */
     depth?: number;
+    /** maximum number of tried terms before giving up */
     tries?: number;
+    /** whether to call infer() on each term; default true */
     infer?: boolean;
+    /** maximum number of arguments in infer(), see {@link infer} */
     maxArgs?: number;
+    /** maximum number of steps in infer(), see {@link infer} */
     max?: number;
+    /** prevents skipping equivalent terms. Always true if infer is false. */
     noskip?: boolean;
-    retain?: boolean;
-    progress?: (info: {
-        gen: number;
-        total: number;
-        probed: number;
-        step: boolean;
-    }) => void;
+    /** minimum number of tries between progress yields, default 1000 */
     progressInterval?: number;
 };
-export type SearchCallback = (e: Expr, props: TermInfo) => (number | undefined);
-export type SearchResult = {
+export type SearchCallback = (e: Expr, props: TermInfo) => (SearchCallbackResult | number | undefined);
+/** Yielded by the search generator on every progress tick and on each found term. */
+export type SearchProgress = {
+    /** The found expression; present only when found === true. */
     expr?: Expr;
+    /** True when this yield carries a found term. */
+    found: boolean;
+    /** True when this is a new-generation tick (step progress), false for mid-generation ticks. */
+    step: boolean;
+    gen: number;
     total: number;
     probed: number;
-    gen: number;
-    cache?: Expr[][];
+    /** The full generation cache at the time of this yield. */
+    cache: Expr[][];
 };
 export type EquivResult = {
     steps: number;
@@ -58,7 +48,7 @@ export type EquivResult = {
     canonical: [Expr | null, Expr | null];
 };
 /**
- *   Converts an unknown object into a FormatOptions, or returns an error it it is not valid.
+ *   Converts an unknown object into a FormatOptions, or returns an error if it is not valid.
  *   A null/undefined counts as an empty options object (and is thus valid).
  */
 declare function checkFormatOptions(raw: unknown): {
@@ -102,10 +92,29 @@ declare function declare(expr: Expr, env?: Record<string, Named>): string;
 declare function deepFormat(obj: any, options?: FormatOptions): any;
 /**
  * @experimental
- *   Look for an expression that matches the predicate,
- *        starting with the seed and applying the terms to one another.
+ * Given a seed set of expressions, search for expressions that match the predicate
+ * by applying already known expressions to one another.
+ * Seen terms are organized into generations, with gen(g f) == gen(g) + gen(f) + an optional offset
+ * (e.g. we want to study duplicating terms later than the discarding ones).
+ *
+ * The predicate receives a term and its inferred properties (if `infer` is true) and
+ * returns an object with the following optional properties:
+ * - `found`: boolean - if true, the expression is yielded as a result;
+ * - `stop`: boolean - if true, the search stops after yielding, independent of `found`;
+ * - `offset`: a number with the following meaning:
+ *   - negative: discard the expression entirely;
+ *   - 0: keep the expression to compute further terms;
+ *   - n >0: keep the expression, but delay its use by n generations.
+ * Or it can just return a number, which is shorthand for `{ offset: n }`.
+ *
+ * An intermediate result is yielded, when:
+ *   - a term is found (`found === true`) and/or the search is stopped (`stop === true`);
+ *   - a new generation is started;
+ *   - the number of tries since the last yield exceeds `progressInterval`.
+ * Such approach allows implementing progress bars and prevents the search from blocking for too long.
+ *
  */
-declare function search(seed: Expr[], options: SearchOptions, predicate: SearchCallback): SearchResult;
+declare function search(seed: Expr[], options: SearchOptions, predicate: SearchCallback): Generator<SearchProgress>;
 export declare const extras: {
     search: typeof search;
     deepFormat: typeof deepFormat;

package/lib/types/index.d.ts

@@ -41,7 +41,7 @@ export declare class SKI extends Parser {
     };
     static church(n: number): Church;
     static extras: {
-        search: (seed: import("./expr").Expr[], options: import("./extras").SearchOptions, predicate: import("./extras").SearchCallback) => import("./extras").SearchResult;
+        search: (seed: import("./expr").Expr[], options: import("./extras").SearchOptions, predicate: import("./extras").SearchCallback) => Generator<import("./extras").SearchProgress>;
         deepFormat: (obj: any, options?: import("./expr").FormatOptions) => any;
         declare: (expr: import("./expr").Expr, env?: Record<string, import("./expr").Named>) => string;
         toposort: typeof toposort;

package/lib/types/quest.d.ts

@@ -118,6 +118,7 @@ export declare class Quest {
     id?: string | number;
     name?: string;
     intro?: string;
+    created?: Date;
     meta?: Record<string, unknown>;
     constructor(options: QuestSpec);
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "2.8.2",
+  "version": "2.9.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",