@dallaylaen/ski-interpreter 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-01-25
+
+### BREAKING CHANGES
+
+- Remove `Expr.reduce()` method for good (too ambiguous). See also `Expr.invoke()` below.
+- Remove `onApply` hook from `Native` combinators.
+
+### Added
+
+- Expr: Add `invoke(arg: Expr)` method implementing actual rewriting rules.
+- SKI: `add(term, impl, note?)` method now accepts a function as `impl` to define native combinators directly.
+- Improved jsdoc somewhat.
+
 ## [1.2.0] - 2025-12-14
 
 ### BREAKING CHANGES

package/README.md

@@ -46,6 +46,25 @@ that has enough arguments is executed and the step ends there.
 Lambda terms are lazy, i.e. the body is not touched until
 all free variables are bound.
 
+# Playground
+
+https://dallaylaen.github.io/ski-interpreter/
+
+* all of the above features (except comparison and JS-native terms) in your browser
+* expressions have permalinks
+* can configure verbosity & executeion speed
+
+# Quests
+
+https://dallaylaen.github.io/ski-interpreter/quest.html
+
+This page contains small tasks of increasing complexity.
+Each task requires the user to build a combinator with specific properties.
+
+# CLI
+
+REPL comes with the package as [bin/ski.js](bin/ski.js).
+
 # Installation
 
 ```bash
@@ -100,24 +119,6 @@ const [x, y] = SKI.free('x', 'y'); // free variables
 SKI.church(5).apply(x, y).run().expr + ''; // 'x(x(x(x(x y))))'
 ```
 
-# Playground
-
-https://dallaylaen.github.io/ski-interpreter/
-
-* all of the above features (except comparison and JS-native terms) in your browser
-* expressions have permalinks
-* can configure verbosity & executeion speed
-
-# Quests
-
-https://dallaylaen.github.io/ski-interpreter/quest.html
-
-This page contains small tasks of increasing complexity. 
-Each task requires the user to build a combinator with specific properties.
-
-# CLI
-
-REPL comes with the package as [bin/ski.js](bin/ski.js).
 
 
 
@@ -131,6 +132,7 @@ REPL comes with the package as [bin/ski.js](bin/ski.js).
 * "To Mock The Mockingbird" by Raymond Smulian.
 * [combinator birds](https://www.angelfire.com/tx4/cus/combinator/birds.html) by [Chris Rathman](https://www.angelfire.com/tx4/cus/index.html)
 * [Fun with combinators](https://doisinkidney.com/posts/2020-10-17-ski.html) by [@oisdk](https://github.com/oisdk)
+* [Conbinatris](https://dirk.rave.org/combinatris/) by Dirk van Deun
 
 # License and copyright
 

package/lib/expr.js

@@ -8,6 +8,10 @@ const globalOptions = {
   maxArgs: 32,
 };
 
+/**
+ * @typedef {Expr | function(Expr): Partial} Partial
+ */
+
 class Expr {
   /**
    *  @descr A generic combinatory logic expression.
@@ -242,16 +246,6 @@ class Expr {
     return this;
   }
 
-  /**
-     * Apply self to list of given args.
-     * Normally, only native combinators know how to do it.
-     * @param {Expr[]} args
-     * @return {Expr|null}
-     */
-  reduce (args) {
-    return null;
-  }
-
   /**
    * Replace all instances of plug in the expression with value and return the resulting expression,
    * or null if no changes could be made.
@@ -268,7 +262,30 @@ class Expr {
   }
 
   /**
-     * @desc iterate one step of calculation in accordance with known rules.
+   * @desc Apply term reduction rules, if any, to the given argument.
+   * A returned value of null means no reduction is possible.
+   * A returned value of Expr means the reduction is complete and the application
+   *     of this and arg can be replaced with the result.
+   * A returned value of a function means that further arguments are needed,
+   *     and can be cached for when they arrive.
+   *
+   * This method is between apply() which merely glues terms together,
+   *     and step() which reduces the whole expression.
+   *
+   * foo.invoke(bar) is what happens inside foo.apply(bar).step() before
+   *     reduction of either foo or bar is attempted.
+   *
+   * The name 'invoke' was chosen to avoid confusion with either 'apply' or 'reduce'.
+   *
+   * @param {Expr} arg
+   * @returns {Partial | null}
+   */
+  invoke (arg) {
+    return null;
+  }
+
+  /**
+     * @desc iterate one step of a calculation.
      * @return {{expr: Expr, steps: number, changed: boolean}}
      */
   step () { return { expr: this, steps: 0, changed: false } }
@@ -432,7 +449,7 @@ class Expr {
         var:      ['<var>', '</var>'],
         lambda:   ['', '-&gt;', ''],
         around:   ['', ''],
-        redex:    ['<b>', '</b>'],
+        redex:    ['', ''],
       }
       : {
         brackets: ['(', ')'],
@@ -544,12 +561,6 @@ class App extends Expr {
     return this.fun._firstVar();
   }
 
-  apply (...args) {
-    if (args.length === 0)
-      return this;
-    return new App(this, ...args);
-  }
-
   expand () {
     return this.fun.expand().apply(this.arg.expand());
   }
@@ -576,34 +587,48 @@ class App extends Expr {
   step () {
     // normal reduction order: first try root, then at most 1 step
     if (!this.final) {
-      if (this.arity === 0) {
-        // aha! we have just fulfilled some previous function's argument demands
-        const reduced = this.fun.reduce([this.arg]);
-        // should always be true, but whatever
-        if (reduced)
-          return { expr: reduced, steps: 1, changed: true };
-      }
-      // now try recursing
-
+      // try to apply rewriting rules, if applicable, at first
+      const partial = this.fun.invoke(this.arg);
+      if (partial instanceof Expr)
+        return { expr: partial, steps: 1, changed: true };
+      else if (typeof partial === 'function')
+        this.invoke = partial; // cache for next time
+
+      // descend into the leftmost term
       const fun = this.fun.step();
       if (fun.changed)
         return { expr: fun.expr.apply(this.arg), steps: fun.steps, changed: true };
 
+      // descend into arg
       const arg = this.arg.step();
       if (arg.changed)
         return { expr: this.fun.apply(arg.expr), steps: arg.steps, changed: true };
 
-      this.final = true;
+      // mark as irreducible
+      this.final = true; // mark as irreducible at root
     }
+
     return { expr: this, steps: 0, changed: false };
   }
 
-  reduce (args) {
-    return this.fun.reduce([this.arg, ...args]);
+  invoke (arg) {
+    // propagate invocation towards the root term,
+    // caching partial applications as we go
+    const partial = this.fun.invoke(this.arg);
+    if (partial instanceof Expr)
+      return partial.apply(arg);
+    else if (typeof partial === 'function') {
+      this.invoke = partial;
+      return partial(arg);
+    } else {
+      // invoke = null => we're uncomputable, cache for next time
+      this.invoke = _ => null;
+      return null;
+    }
   }
 
   split () {
-    // pretend we are an elegant (cons fun arg) and not a sleazy imperative array
+    // leftover from array-based older design
     return [this.fun, this.arg];
   }
 
@@ -707,51 +732,36 @@ class FreeVar extends Named {
   }
 }
 
-/**
- * @typedef {function(Expr): Expr | AnyArity} AnyArity
- */
-
 class Native extends Named {
   /**
-   * @desc A term named 'name' that converts next 'arity' arguments into
-   *       an expression returned by 'impl' function
-   *       If an apply: Expr=>Expr|null function is given, it will be attempted upon application
-   *       before building an App object. This allows to plug in argument coercions,
-   *       e.g. instantly perform a numeric operation natively if the next term is a number.
+   * @desc A named term with a known rewriting rule.
+   *       'impl' is a function with signature Expr => Expr => ... => Expr
+   *       (see typedef Partial).
+   *       This is how S, K, I, and company are implemented.
+   *
+   *       Note that as of current something like a=>b=>b(a) is not possible,
+   *       use full form instead: a=>b=>b.apply(a).
+   *
+   * @example new Native('K', x => y => x); // constant
+   * @example new Native('Y', function(f) { return f.apply(this.apply(f)); }); // self-application
+   *
    * @param {String} name
-   * @param {AnyArity} impl
-   * @param {{note: string?, arity: number?, canonize: boolean?, apply: function(Expr):(Expr|null) }} [opt]
+   * @param {Partial} impl
+   * @param {{note?: string, arity?: number, canonize?: boolean, apply?: function(Expr):(Expr|null) }} [opt]
    */
   constructor (name, impl, opt = {}) {
     super(name);
     // setup essentials
-    this.impl  = impl;
-    if (opt.apply)
-      this.onApply = opt.apply;
-    this.arity = opt.arity ?? 1;
+    this.invoke  = impl;
 
+    // TODO guess lazily (on demand, only once); app capabilities such as discard and duplicate
     // try to bootstrap and guess some of our properties
     const guess = (opt.canonize ?? true) ? this.guess() : { normal: false };
 
-    if (!opt.arity)
-      this.arity = guess.arity || 1;
-
+    this.arity = opt.arity || guess.arity || 1;
     this.note = opt.note ?? guess.expr?.format({ terse: true, html: true, lambda: ['', ' &mapsto; ', ''] });
   }
 
-  apply (...args) {
-    if (this.onApply && args.length >= 1) {
-      if (typeof this.onApply !== 'function') {
-        throw new Error('Native combinator ' + this + ' has an invalid onApply property  of type'
-          + typeof this.onApply + ': ' + this.onApply);
-      }
-      const subst = this.onApply(args[0]);
-      if (subst instanceof Expr)
-        return subst.apply(...args.slice(1));
-    }
-    return super.apply(...args);
-  }
-
   _rski (options) {
     if (this === native.I || this === native.K || this === native.S || (options.steps >= options.max))
       return this;
@@ -761,21 +771,6 @@ class Native extends Named {
     options.steps++;
     return canon._rski(options);
   }
-
-  reduce (args) {
-    if (args.length < this.arity)
-      return null;
-    let egde = 0;
-    let step = this.impl;
-    while (typeof step === 'function') {
-      if (egde >= args.length)
-        return null;
-      step = step(args[egde++]);
-    }
-    if (!(step instanceof Expr))
-      throw new Error('Native combinator ' + this + ' reduced to a non-expression: ' + step);
-    return step.apply(...args.slice(egde));
-  }
 }
 
 const native = {};
@@ -785,9 +780,20 @@ function addNative (name, impl, opt) {
 
 class Lambda extends Expr {
   /**
-     * @param {FreeVar|FreeVar[]} arg
-     * @param {Expr} impl
-     */
+   * @desc Lambda abstraction of arg over impl.
+   *     Upon evaluation, all occurrences of 'arg' within 'impl' will be replaced
+   *     with the provided argument.
+   *
+   * Note that 'arg' will be replaced by a localized placeholder, so the original
+   * variable can be used elsewhere without interference.
+   * Listing symbols contained in the lambda will omit such placeholder.
+   *
+   * Legacy ([FreeVar], impl) constructor is supported but deprecated.
+   * It will create a nested lambda expression.
+   *
+   * @param {FreeVar} arg
+   * @param {Expr} impl
+   */
   constructor (arg, impl) {
     if (Array.isArray(arg)) {
       // check args before everything
@@ -834,16 +840,11 @@ class Lambda extends Expr {
       return { normal: false, steps };
 
     const push = nthvar(preArgs.length + options.index);
-    return this.reduce([push])._guess(options, [...preArgs, push], steps + 1);
+    return this.invoke(push)._guess(options, [...preArgs, push], steps + 1);
   }
 
-  reduce (input) {
-    if (input.length === 0)
-      return null;
-
-    const [head, ...tail] = input;
-
-    return (this.impl.subst(this.arg, head) ?? this.impl).apply(...tail);
+  invoke (arg) {
+    return this.impl.subst(this.arg, arg) ?? this.impl;
   }
 
   subst (search, replace) {
@@ -894,7 +895,7 @@ class Lambda extends Expr {
 
     const t = new FreeVar('t');
 
-    return other.reduce([t]).equals(this.reduce([t]));
+    return other.invoke(t).equals(this.invoke(t));
   }
 
   contains (other) {
@@ -920,6 +921,11 @@ class Lambda extends Expr {
 }
 
 class Church extends Native {
+  /**
+   * @desc Church numeral representing non-negative integer n:
+   *      n f x = f(f(...(f x)...)) with f applied n times.
+   * @param {number} n
+   */
   constructor (n) {
     const p = Number.parseInt(n);
     if (!(p >= 0))
@@ -949,9 +955,23 @@ class Church extends Native {
   }
 }
 
+function waitn (expr, n) {
+  return arg => n <= 1 ? expr.apply(arg) : waitn(expr.apply(arg), n - 1);
+}
+
 class Alias extends Named {
   /**
-   * @desc An existing expression under a different name.
+   * @desc A named alias for an existing expression.
+   *
+   *     Upon evaluation, the alias expands into the original expression,
+   *     unless it has a known arity > 0 and is marked terminal,
+   *     in which case it waits for enough arguments before expanding.
+   *
+   *     A hidden mutable property 'outdated' is used to silently
+   *     replace the alias with its definition in all contexts.
+   *     This is used when declaring named terms in an interpreter,
+   *     to avoid confusion between old and new terms with the same name.
+   *
    * @param {String} name
    * @param {Expr} impl
    * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
@@ -970,6 +990,7 @@ class Alias extends Named {
     this.proper = guess.proper ?? false;
     this.terminal = options.terminal ?? this.proper;
     this.canonical = guess.expr;
+    this.invoke = waitn(impl, this.arity);
   }
 
   getSymbols () {
@@ -1006,12 +1027,6 @@ class Alias extends Named {
     return { expr: this.impl, steps: 0, changed: true };
   }
 
-  reduce (args) {
-    if (args.length < this.arity)
-      return null;
-    return this.impl.apply(...args);
-  }
-
   _firstVar () {
     return this.impl._firstVar();
   }
@@ -1040,6 +1055,7 @@ class Alias extends Named {
   }
 
   _declare (output, inventory, seen) {
+    // this is part of the 'declare' function, see below
     // only once
     if (seen.has(this))
       return;
@@ -1064,10 +1080,15 @@ addNative('B', x => y => z => x.apply(y.apply(z)));
 addNative('C', x => y => z => x.apply(z).apply(y));
 addNative('W', x => y => x.apply(y).apply(y));
 
-addNative('+', x => y => z => y.apply(x.apply(y, z)), {
-  note:  '<var>n</var> &mapsto; <var>n</var> + 1 <i>or</i> SB',
-  apply: arg => arg instanceof Church ? new Church(arg.n + 1) : null
-});
+addNative(
+  '+',
+  n => n instanceof Church
+    ? new Church(n.n + 1)
+    : f => x => f.apply(n.apply(f, x)),
+  {
+    note: 'Increase a Church numeral argument by 1, otherwise n => f => x => f(n f x)',
+  }
+);
 
 // A global value meaning "lambda is used somewhere in this expression"
 // Can't be used (at least for now) to construct lambda expressions, or anything at all.

package/lib/parser.js

@@ -89,29 +89,32 @@ class SKI {
   }
 
   /**
+   * @desc 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.
+   *
+   * If impl is a function, it should have signature (Expr) => ... => Expr
+   * (see typedef Partial at top of expr.js)
+   *
+   * @example ski.add('T', 'S(K(SI))K', 'swap combinator')
+   * @example ski.add( ski.parse('T = S(K(SI))K') ) // ditto but one-arg form
+   * @example ski.add('T', x => y => y.apply(x), 'swap combinator') // heavy artillery
+   * @example ski.add('Y', function (f) { return f.apply(this.apply(f)); }, 'Y combinator')
    *
    * @param {Alias|String} term
-   * @param {Expr|String|[number, function(...Expr): Expr, {note: string?, fast: boolean?}]} [impl]
+   * @param {String|Expr|function(Expr):Partial} [impl]
    * @param {String} [note]
    * @return {SKI} chainable
    */
   add (term, impl, note ) {
-    if (typeof term === 'string') {
-      if (typeof impl === 'string')
-        term = new Alias(term, this.parse(impl), { canonize: true });
-      else if (impl instanceof Expr)
-        term = new Alias(term, impl, { canonize: true });
-      else
-        throw new Error('add: term must be an Alias or a string and impl must be an Expr or a string');
-    } else if (term instanceof Alias)
-      term = new Alias(term.name, term.impl, { canonize: true });
-
-    // This should normally be unreachable but let's keep just in case
-    if (!(term instanceof Alias))
-      throw new Error('add: term must be an Alias or a string (accompanied with an implementation)');
+    term = this._named(term, impl);
 
-    if (this.annotate && note === undefined && term.canonical)
-      note = term.canonical.format({ terse: true, html: true, lambda: ['', ' ↦ ', ''] });
+    if (this.annotate && note === undefined) {
+      const guess = term.guess();
+      if (guess.expr)
+        note = guess.expr.format({ terse: true, html: true, lambda: ['', ' ↦ ', ''] });
+    }
     if (note !== undefined)
       term.note = note;
 
@@ -123,6 +126,23 @@ class SKI {
     return this;
   }
 
+  _named (term, impl) {
+    if (term instanceof Alias)
+      return new Alias(term.name, term.impl, { canonize: true });
+    if (typeof term !== 'string')
+      throw new Error('add(): term must be an Alias or a string');
+    if (impl === undefined)
+      throw new Error('add(): impl must be provided when term is a string');
+    if (typeof impl === 'string')
+      return new Alias(term, this.parse(impl), { canonize: true });
+    if (impl instanceof Expr)
+      return new Alias(term, impl, { canonize: true });
+    if (typeof impl === 'function')
+      return new Native(term, impl);
+    // idk what this is
+    throw new Error('add(): impl must be an Expr, a string, or a function with a signature Expr => ... => Expr');
+  }
+
   maybeAdd (name, impl) {
     if (this.known[name])
       this.allow.add(name);

package/lib/quest.js

@@ -225,16 +225,25 @@ class Quest {
 }
 
 class Case {
+  /**
+   * @param {FreeVar[]} input
+   * @param {{
+   *   max?: number,
+   *   note?: string,
+   *   vars?: {string: Expr},
+   *   engine: SKI
+   * }} options
+   */
   constructor (input, options) {
     this.max = options.max ?? 1000;
     this.note = options.note;
-    this.vars = { ...(options.vars ?? {}) }; // shallow copy to avoid modifying the original
+    this.vars = { ...(options.vars ?? {}) }; // note: context already contains input placeholders
     this.input = input;
     this.engine = options.engine;
   }
 
   parse (src) {
-    return new Lambda(this.input, this.engine.parse(src, this.vars));
+    return new Subst(this.engine.parse(src, this.vars), this.input);
   }
 
   /**
@@ -263,17 +272,15 @@ class ExprCase extends Case {
 
     super(input, options);
 
-    [this.e1, this.e2] = terms.map(src => this.parse(src));
+    [this.e1, this.e2] = terms.map( s => this.parse(s) );
   }
 
-  check (...expr) {
-    // we do it the fancy way and instead of just "apply" to avoid
-    // displaying (foo->foo this that)(user input) as 1st step
-    const subst = (outer, inner) => outer.reduce(inner) ?? outer.apply(...inner);
+  check (...args) {
+    const e1 = this.e1.apply(args);
+    const r1 = e1.run({ max: this.max });
+    const e2 = this.e2.apply(args);
+    const r2 = e2.run({ max: this.max });
 
-    const start = subst(this.e1, expr);
-    const r1 = start.run({ max: this.max });
-    const r2 = subst(this.e2, expr).run({ max: this.max });
     let reason = null;
     if (!r1.final || !r2.final)
       reason = 'failed to reach normal form in ' + this.max + ' steps';
@@ -285,11 +292,11 @@ class ExprCase extends Case {
       pass:     !reason,
       reason,
       steps:    r1.steps,
-      start,
+      start:    e1,
       found:    r1.expr,
       expected: r2.expr,
       note:     this.note,
-      args:     expr,
+      args,
       case:     this,
     };
   }
@@ -335,7 +342,7 @@ class PropertyCase extends Case {
   }
 
   check (...expr) {
-    const start = this.expr.apply(...expr);
+    const start = this.expr.apply(expr);
     const r = start.run({ max: this.max });
     const guess = r.expr.guess({ max: this.max });
 
@@ -358,6 +365,29 @@ class PropertyCase extends Case {
   }
 }
 
+class Subst {
+  /**
+   * @descr A placeholder object with exactly n free variables to be substituted later.
+   * @param {Expr} expr
+   * @param {FreeVar[]} vars
+   */
+  constructor (expr, vars) {
+    this.expr = expr;
+    this.vars = vars;
+  }
+
+  apply (list) {
+    if (list.length !== this.vars.length)
+      throw new Error('Subst: expected ' + this.vars.length + ' terms, got ' + list.length);
+
+    let expr = this.expr;
+    for (let i = 0; i < this.vars.length; i++)
+      expr = expr.subst(this.vars[i], list[i]) ?? expr;
+
+    return expr;
+  }
+}
+
 function list2str (str) {
   if (str === undefined)
     return str;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dallaylaen/ski-interpreter",
-  "version": "1.2.0",
+  "version": "1.3.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",
@@ -19,7 +19,8 @@
     "types": "npx -p typescript tsc index.js --declaration --allowJs --emitDeclarationOnly --outDir types",
     "test": "npx nyc mocha",
     "minify": "npx esbuild --bundle ./index.js --outfile=docs/build/js/ski-interpreter.min.js --minify --sourcemap",
-    "build": "npm run lint && npm run types && npm run test && npm run minify"
+    "build-site": "npx esbuild --bundle ./site-src/index.js --outfile=docs/build/js/util.min.js --minify --sourcemap",
+    "build": "npm run lint && npm run types && npm run test && npm run minify && npm run build-site"
   },
   "files": [
     "package.json",

package/types/lib/expr.d.ts

@@ -1,4 +1,7 @@
-export type AnyArity = (arg0: Expr) => Expr | AnyArity;
+export type Partial = Expr | ((arg0: Expr) => Partial);
+/**
+ * @typedef {Expr | function(Expr): Partial} Partial
+ */
 export class Expr {
     /**
        * postprocess term after parsing. typically return self but may return other term or die
@@ -131,13 +134,6 @@ export class Expr {
         steps: number;
     }>;
     _rski(options: any): this;
-    /**
-       * Apply self to list of given args.
-       * Normally, only native combinators know how to do it.
-       * @param {Expr[]} args
-       * @return {Expr|null}
-       */
-    reduce(args: Expr[]): Expr | null;
     /**
      * Replace all instances of plug in the expression with value and return the resulting expression,
      * or null if no changes could be made.
@@ -151,7 +147,27 @@ export class Expr {
      */
     subst(search: Expr, replace: Expr): Expr | null;
     /**
-       * @desc iterate one step of calculation in accordance with known rules.
+     * @desc Apply term reduction rules, if any, to the given argument.
+     * A returned value of null means no reduction is possible.
+     * A returned value of Expr means the reduction is complete and the application
+     *     of this and arg can be replaced with the result.
+     * A returned value of a function means that further arguments are needed,
+     *     and can be cached for when they arrive.
+     *
+     * This method is between apply() which merely glues terms together,
+     *     and step() which reduces the whole expression.
+     *
+     * foo.invoke(bar) is what happens inside foo.apply(bar).step() before
+     *     reduction of either foo or bar is attempted.
+     *
+     * The name 'invoke' was chosen to avoid confusion with either 'apply' or 'reduce'.
+     *
+     * @param {Expr} arg
+     * @returns {Partial | null}
+     */
+    invoke(arg: Expr): Partial | null;
+    /**
+       * @desc iterate one step of a calculation.
        * @return {{expr: Expr, steps: number, changed: boolean}}
        */
     step(): {
@@ -279,7 +295,6 @@ export class App extends Expr {
     arity: any;
     weight(): any;
     _firstVar(): any;
-    apply(...args: any[]): App;
     expand(): any;
     subst(search: any, replace: any): any;
     /**
@@ -289,7 +304,7 @@ export class App extends Expr {
         expr: Expr;
         steps: number;
     };
-    reduce(args: any): any;
+    invoke(arg: any): any;
     split(): any[];
     _aslist(): any[];
     equals(other: any): any;
@@ -304,14 +319,25 @@ export class FreeVar extends Named {
 }
 export class Lambda extends Expr {
     /**
-       * @param {FreeVar|FreeVar[]} arg
-       * @param {Expr} impl
-       */
-    constructor(arg: FreeVar | FreeVar[], impl: Expr);
+     * @desc Lambda abstraction of arg over impl.
+     *     Upon evaluation, all occurrences of 'arg' within 'impl' will be replaced
+     *     with the provided argument.
+     *
+     * Note that 'arg' will be replaced by a localized placeholder, so the original
+     * variable can be used elsewhere without interference.
+     * Listing symbols contained in the lambda will omit such placeholder.
+     *
+     * Legacy ([FreeVar], impl) constructor is supported but deprecated.
+     * It will create a nested lambda expression.
+     *
+     * @param {FreeVar} arg
+     * @param {Expr} impl
+     */
+    constructor(arg: FreeVar, impl: Expr);
     arg: FreeVar;
     impl: Expr;
     arity: number;
-    reduce(input: any): Expr;
+    invoke(arg: any): Expr;
     subst(search: any, replace: any): Lambda;
     expand(): Lambda;
     _rski(options: any): any;
@@ -319,37 +345,47 @@ export class Lambda extends Expr {
     _format(options: any, nargs: any): string;
     _braced(first: any): boolean;
 }
-/**
- * @typedef {function(Expr): Expr | AnyArity} AnyArity
- */
 export class Native extends Named {
     /**
-     * @desc A term named 'name' that converts next 'arity' arguments into
-     *       an expression returned by 'impl' function
-     *       If an apply: Expr=>Expr|null function is given, it will be attempted upon application
-     *       before building an App object. This allows to plug in argument coercions,
-     *       e.g. instantly perform a numeric operation natively if the next term is a number.
+     * @desc A named term with a known rewriting rule.
+     *       'impl' is a function with signature Expr => Expr => ... => Expr
+     *       (see typedef Partial).
+     *       This is how S, K, I, and company are implemented.
+     *
+     *       Note that as of current something like a=>b=>b(a) is not possible,
+     *       use full form instead: a=>b=>b.apply(a).
+     *
+     * @example new Native('K', x => y => x); // constant
+     * @example new Native('Y', function(f) { return f.apply(this.apply(f)); }); // self-application
+     *
      * @param {String} name
-     * @param {AnyArity} impl
-     * @param {{note: string?, arity: number?, canonize: boolean?, apply: function(Expr):(Expr|null) }} [opt]
+     * @param {Partial} impl
+     * @param {{note?: string, arity?: number, canonize?: boolean, apply?: function(Expr):(Expr|null) }} [opt]
      */
-    constructor(name: string, impl: AnyArity, opt?: {
-        note: string | null;
-        arity: number | null;
-        canonize: boolean | null;
-        apply: (arg0: Expr) => (Expr | null);
+    constructor(name: string, impl: Partial, opt?: {
+        note?: string;
+        arity?: number;
+        canonize?: boolean;
+        apply?: (arg0: Expr) => (Expr | null);
     });
-    impl: AnyArity;
-    onApply: (arg0: Expr) => (Expr | null);
+    invoke: Partial;
     arity: any;
     note: any;
-    apply(...args: any[]): Expr;
     _rski(options: any): any;
-    reduce(args: any): any;
 }
 export class Alias extends Named {
     /**
-     * @desc An existing expression under a different name.
+     * @desc A named alias for an existing expression.
+     *
+     *     Upon evaluation, the alias expands into the original expression,
+     *     unless it has a known arity > 0 and is marked terminal,
+     *     in which case it waits for enough arguments before expanding.
+     *
+     *     A hidden mutable property 'outdated' is used to silently
+     *     replace the alias with its definition in all contexts.
+     *     This is used when declaring named terms in an interpreter,
+     *     to avoid confusion between old and new terms with the same name.
+     *
      * @param {String} name
      * @param {Expr} impl
      * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
@@ -367,6 +403,7 @@ export class Alias extends Named {
     proper: any;
     terminal: any;
     canonical: any;
+    invoke: (arg: any) => any;
     subst(search: any, replace: any): any;
     /**
      *
@@ -376,14 +413,18 @@ export class Alias extends Named {
         expr: Expr;
         steps: number;
     };
-    reduce(args: any): Expr;
     equals(other: any): any;
     _rski(options: any): Expr;
     _braced(first: any): boolean;
     _format(options: any, nargs: any): string | void;
 }
 export class Church extends Native {
-    constructor(n: any);
+    /**
+     * @desc Church numeral representing non-negative integer n:
+     *      n f x = f(f(...(f x)...)) with f applied n times.
+     * @param {number} n
+     */
+    constructor(n: number);
     n: any;
     arity: number;
     equals(other: any): boolean;

package/types/lib/parser.d.ts

@@ -24,16 +24,26 @@ export class SKI {
     hasLambdas: boolean;
     allow: any;
     /**
+     * @desc 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.
+     *
+     * If impl is a function, it should have signature (Expr) => ... => Expr
+     * (see typedef Partial at top of expr.js)
+     *
+     * @example ski.add('T', 'S(K(SI))K', 'swap combinator')
+     * @example ski.add( ski.parse('T = S(K(SI))K') ) // ditto but one-arg form
+     * @example ski.add('T', x => y => y.apply(x), 'swap combinator') // heavy artillery
+     * @example ski.add('Y', function (f) { return f.apply(this.apply(f)); }, 'Y combinator')
      *
      * @param {Alias|String} term
-     * @param {Expr|String|[number, function(...Expr): Expr, {note: string?, fast: boolean?}]} [impl]
+     * @param {String|Expr|function(Expr):Partial} [impl]
      * @param {String} [note]
      * @return {SKI} chainable
      */
-    add(term: Alias | string, impl?: Expr | string | [number, (...args: Expr[]) => Expr, {
-        note: string | null;
-        fast: boolean | null;
-    }], note?: string): SKI;
+    add(term: Alias | string, impl?: string | Expr | ((arg0: Expr) => Partial), note?: string): SKI;
+    _named(term: any, impl: any): Native | Alias;
     maybeAdd(name: any, impl: any): this;
     /**
      * @desc Declare and remove multiple terms at once

package/types/lib/quest.d.ts

@@ -144,13 +144,31 @@ export class Quest {
     show(): TestCase[];
 }
 declare class Case {
-    constructor(input: any, options: any);
-    max: any;
-    note: any;
-    vars: any;
-    input: any;
-    engine: any;
-    parse(src: any): import("./expr").Lambda;
+    /**
+     * @param {FreeVar[]} input
+     * @param {{
+     *   max?: number,
+     *   note?: string,
+     *   vars?: {string: Expr},
+     *   engine: SKI
+     * }} options
+     */
+    constructor(input: typeof import("./expr").FreeVar[], options: {
+        max?: number;
+        note?: string;
+        vars?: {
+            string: typeof import("./expr").Expr;
+        };
+        engine: SKI;
+    });
+    max: number;
+    note: string;
+    vars: {
+        string?: typeof import("./expr").Expr;
+    };
+    input: typeof import("./expr").FreeVar[];
+    engine: SKI;
+    parse(src: any): Subst;
     /**
      * @param {Expr} expr
      * @return {CaseResult}
@@ -158,4 +176,15 @@ declare class Case {
     check(...expr: typeof import("./expr").Expr): CaseResult;
 }
 import { SKI } from "./parser";
+declare class Subst {
+    /**
+     * @descr A placeholder object with exactly n free variables to be substituted later.
+     * @param {Expr} expr
+     * @param {FreeVar[]} vars
+     */
+    constructor(expr: typeof import("./expr").Expr, vars: typeof import("./expr").FreeVar[]);
+    expr: typeof import("./expr").Expr;
+    vars: typeof import("./expr").FreeVar[];
+    apply(list: any): typeof import("./expr").Expr;
+}
 export {};