@metta-ts/edsl 1.0.3 → 1.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @metta-ts/edsl
 
-A typed TypeScript eDSL for [MeTTa TS](https://github.com/MesTTo/Meta-TypeScript-Talk). Write MeTTa with typed term builders and special-form combinators, or a tagged-template surface, and run it on the real interpreter. Any TypeScript value drops in as a grounded atom automatically.
+A typed TypeScript eDSL for [MeTTa TS](https://github.com/MesTTo/Meta-TypeScript-Talk). Mint symbols, functors, and logic variables from proxies, build MeTTa with combinators or a tagged template, and run it on the real interpreter. Any TypeScript value drops in as a grounded atom automatically, and TypeScript functions bridge in both directions.
 
 It is a thin layer over [`@metta-ts/hyperon`](https://github.com/MesTTo/Meta-TypeScript-Talk/tree/main/packages/hyperon): every builder produces an ordinary atom that runs on the existing engine, so you get MeTTa's full semantics: rewrite rules, nondeterminism, pattern matching, and types.
 
@@ -13,39 +13,87 @@ npm install @metta-ts/edsl
 ## Usage
 
 ```ts
-import { mettaDB, S, v, rel, iff, gt, lt, mul, sub, m, ValueAtom, type GroundedAtom } from "@metta-ts/edsl";
+import { mettaDB, names, vars, If, gt, lt, mul, sub, m } from "@metta-ts/edsl";
 
 const db = mettaDB();
 
-// Facts + a typed match query (rows are typed by the variables).
-db.add(rel("Likes")(S.Ada, S.Coffee), rel("Likes")(S.Ada, S.Chocolate));
-const thing = v<string>("thing");
-db.query(rel("Likes")(S.Ada, thing), { thing }); // [{ thing: "Coffee" }, { thing: "Chocolate" }]
+// `names()` mints symbols and functors on demand; `vars()` mints logic variables. No name is written
+// twice: the JS binding IS the name. A bare name grounds to its symbol; a called name applies it.
+const { Likes, fact, Ada, Coffee, Chocolate } = names();
+const { thing, x } = vars();
+
+// Facts + a match query. With no explicit vars, the row keys are inferred from the pattern.
+db.add(Likes(Ada, Coffee), Likes(Ada, Chocolate));
+db.query(Likes(Ada, thing)); // [{ thing: "Coffee" }, { thing: "Chocolate" }]
 
 // Rewrite rules + grounded arithmetic, recursion, nondeterminism.
-const x = v<number>("x");
-db.rule(rel("fact")(x), iff(gt(x, 0), mul(x, rel("fact")(sub(x, 1))), 1));
-db.evalJs(rel("fact")(5)); // [120]
-
-// Pass a TypeScript object straight in (auto-grounded), operated on by a TS function.
-db.op("balance-of", (args) => [ValueAtom((args[0] as GroundedAtom).jsValue<{ balance: number }>().balance)]);
-const account = { owner: "Tom", balance: 100 };
-db.evalJs(rel("balance-of")(account)); // [100]
-db.evalJs(m`(balance-of ${account})`); // [100], same, via the template
-
-// Async grounded ops, awaited.
-db.asyncOp("fetch", async () => [ValueAtom(await getTemp())]);
-await db.evalJsAsync(rel("fetch")());
+db.rule(fact(x), If(gt(x, 0), mul(x, fact(sub(x, 1))), 1));
+db.evalJs(fact(5)); // [120]
+
+// Grounded functions: a plain typed function, args auto-unwrapped, result auto-grounded.
+db.fn("balance-of", (a: { balance: number }) => a.balance);
+db.evalJs(m`(balance-of ${{ owner: "Tom", balance: 100 }})`); // [100]
+
+// Call MeTTa functions from TypeScript, quick or typed.
+db.call.fact(5); // [120]
+const factorial = db.import<[number], number>("fact");
+factorial(6); // 720
+```
+
+## The two term surfaces
+
+- **Proxies + combinators.** `names()` and `vars()` mint names and variables (`const { parent, x } = ...`), and the capitalized combinators build the special forms: `If`, `Case`, `Let`, `LetStar`, `Match`, `Superpose`, `Collapse`, `Empty`, `Unify`, `Sealed`, `Quote`. Lowercase builders cover the grounded ops: `add`/`sub`/`mul`/`div`/`mod`, `eq`/`gt`/`lt`/`ge`/`le`, `and`/`or`/`not`, `carAtom`/`cdrAtom`/`consAtom`/`deconsAtom`, and `list`/`nil`/`e`. Builders compose, so nested patterns and repeated variables are just nested calls.
+- **The tagged template `m\`...\`` (and `mAll` for several atoms)** runs the real parser, so it expresses every MeTTa form, and `${value}` auto-grounds, which is the easiest way to drop a TS object in.
+
+## The runner and the host bridge
+
+`mettaDB()` keeps MeTTa's two query mechanisms distinct: `query(pattern)` does `match &self` over stored atoms and returns binding rows (keys inferred from the pattern, or typed by an explicit `vars` map); `eval(atom)` (and `evalJs`, `evalAsync`, `evalJsAsync`) rewrites with the `=` rules and returns the nondeterministic results.
+
+The host bridge runs both directions:
+
+- **TypeScript into MeTTa (grounded functions).** `db.fn("name", fn)` registers a plain typed function with arguments auto-unwrapped to JS and the result auto-grounded; `db.fns({ ... })` registers several at once keyed by name; `db.asyncFn` awaits an async function. The raw `db.op`/`db.asyncOp` stay for full atom control (multiple results, custom matching).
+- **MeTTa into TypeScript (backward import).** `db.call.<name>(...)` builds and evaluates `(<name> ...args)` and returns every result unwrapped to JS; use bracket access for hyphenated names (`db.call["is-even"](4)`). `db.import("name")` returns a callable.
+
+### Typing the host bridge
+
+Pass a schema to `mettaDB` and `call`, `import`, and `fn` become statically typed; with no schema they stay permissive. Both an `interface` and a `type` schema work.
+
+```ts
+interface Api {
+  fact: (n: number) => number;
+  isEven: (n: number) => boolean;
+}
+const db = mettaDB<Api>();
+db.call.fact(5); // number[]
+const factorial = db.import("fact"); // (n: number) => number | undefined
+db.fn("fact", (n: number) => n + 1); // checked against the schema
+// db.fn("fact", (s: string) => s)  // compile error: wrong signature
 ```
 
-## The two surfaces
+`ground(x)` is the primitive behind auto-grounding, and `patternVars(atom)` returns the free variables of a pattern (what `query` uses to infer row keys).
 
-- Typed builders construct terms with static types: `S`/`v`/`e`/`rel`, `rule`/`decl`/`arrow`, the special forms `iff`/`caseOf`/`lett`/`letStar`/`matchSelf`/`superpose`/`collapse`/`empty`/`unify`, the grounded ops `add`/`sub`/`mul`/`div`/`mod`, `eq`/`gt`/`lt`/`ge`/`le`, `and`/`or`/`not`, `carAtom`/`cdrAtom`/`consAtom`, and `list`/`nil`. Builders compose, so nested patterns and repeated variables are just nested calls.
-- The tagged template `m\`...\`` (and `mAll` for several atoms) runs the real parser, so it expresses every MeTTa form, and `${value}` auto-grounds (the easiest way to drop a TS object in).
+## Typed source queries
 
-## The runner
+`db.q("...")` runs `match &self` from a plain MeTTa source string and types the result rows by the pattern's `$`-variables, extracted at compile time. The keys are known and autocompleted, and a key that is not a variable in the source is a compile error.
+
+```ts
+const rows = db.q("(Likes Ada $thing)"); // Array<{ thing: unknown }>
+rows[0]!.thing; // ok, autocompleted
+// rows[0]!.other  // compile error: not a variable in the source
+```
 
-`mettaDB()` keeps MeTTa's two query mechanisms distinct: `query(pattern, vars)` does `match &self` over stored atoms and returns typed binding rows; `eval(atom)` (and `evalJs`, `evalAsync`, `evalJsAsync`) rewrites with the `=` rules and returns the nondeterministic results. `op`/`asyncOp` register TypeScript functions as grounded operations. `ground(x)` is the primitive behind auto-grounding.
+This types the variable *structure*, not the result *values* (those come from runtime rewriting, which the type system cannot evaluate), so values are `unknown`. It works on a plain string, not the `m\`\`` tag: TypeScript widens a tagged template's text to `string`, which discards the literal the type-level parser needs. For a builder-form query with the same auto-inferred keys, use `db.query(pattern)`.
+
+## JSON and dict-spaces
+
+`db.useJson()` enables the JSON module, then the `jsonEncode`/`jsonDecode`/`dictSpace`/`getKeys`/`getValue` builders bridge JSON and MeTTa spaces. `json-decode` turns a JSON object into a dict-space of `(key value)` pairs, so a fetched payload becomes a queryable space.
+
+```ts
+const db = mettaDB().useJson();
+db.evalJs(jsonEncode(42)); // ["42"]
+const doc = jsonDecode('{"name": "Ada", "age": 36}'); // a dict-space
+db.evalFirst(getValue(doc, "name")); // "Ada"  (JSON keys decode to strings)
+```
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Atom, VariableAtom, SymbolAtom, ExpressionAtom, MeTTa } from '@metta-ts/hyperon';
+import { Atom, ExpressionAtom, SymbolAtom, VariableAtom, MeTTa } from '@metta-ts/hyperon';
 export { Atom, GroundedAtom, ValueAtom, atomToJs } from '@metta-ts/hyperon';
 
 /** A typed variable. The phantom `T` is the JS type its binding unwraps to in a query result; it is a
@@ -6,25 +6,43 @@ export { Atom, GroundedAtom, ValueAtom, atomToJs } from '@metta-ts/hyperon';
 type Var<T = unknown> = VariableAtom & {
     readonly __varType?: T;
 };
-/** Anything a builder accepts in term position: an atom (incl. a {@link Var}), or a JS value to ground. */
-type Term = Atom | number | string | boolean | bigint | object | null | undefined;
+/** Brand marking a functor/symbol builder minted by {@link names}. A branded builder is a callable
+ *  object (TS call-signature pattern) whose brand carries its head symbol, so {@link ground} can turn a
+ *  bare, uncalled builder into that symbol. A real `unique symbol` (runtime value and type-level key)
+ *  cannot collide with user data. */
+declare const HEAD: unique symbol;
+/** A name minted by {@link names}: call it to apply the functor (`parent(a, b)` -> `(parent a b)`), or
+ *  use it bare as a term, where it grounds to its symbol (`Ada` -> the symbol `Ada`). */
+type Name = ((...args: Term[]) => ExpressionAtom) & {
+    readonly [HEAD]: SymbolAtom;
+};
+/** Anything a builder accepts in term position: an atom (incl. a {@link Var}), a {@link Name}, or a JS
+ *  value to ground. `Name` is a function, hence covered by `object`, but is listed for intent. */
+type Term = Atom | Name | number | string | boolean | bigint | object | null | undefined;
 /** Extract a {@link Var}'s phantom type (defaults to `unknown`). */
 type VarValue<X> = X extends Var<infer T> ? T : unknown;
-/** A fresh typed variable: `v("x")` or `v<number>("n")`. */
-declare const v: <T = unknown>(name: string) => Var<T>;
-/** `S` builds a symbol two ways: as a function `S("foo")` or as a property `S.foo`. */
-type SymbolBuilder = ((name: string) => SymbolAtom) & {
-    readonly [key: string]: SymbolAtom;
-};
-declare const S: SymbolBuilder;
-/** Coerce a {@link Term} to an atom: atoms and variables pass through; every other JS value is grounded. */
+/** Coerce a {@link Term} to an atom: atoms and variables pass through; a bare builder becomes its head
+ *  symbol; every other JS value is grounded. */
 declare function ground(x: Term): Atom;
+/** A proxy that mints a {@link Name} per property, memoised so `p.parent` is stable within one scope:
+ *  `const { parent, Ada, Bob } = names()`. Symbols and functors share this one namespace; a name is a
+ *  symbol when used bare and a functor when applied. Optionally type the known names:
+ *  `names<{ parent: unknown; Ada: unknown }>()` restricts the keys. */
+type Names<K extends string = string> = Record<K, Name>;
+declare function names<K extends string = string>(): Names<K>;
+/** A proxy that mints a fresh {@link Var} per property, memoised so `q.x` is the same variable
+ *  everywhere in one scope: `const { x, y } = vars()`. Type the bindings with a record:
+ *  `const { n, name } = vars<{ n: number; name: string }>()`. */
+type Vars<T extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly [K in keyof T]: Var<T[K]>;
+};
+declare function vars<T extends Record<string, unknown> = Record<string, unknown>>(): Vars<T>;
+/** Collect the distinct variables occurring in a pattern, in first-seen order. Backs auto-inferred
+ *  query rows: the free variables ARE the columns. */
+declare function patternVars(atom: Atom): Var[];
 /** A raw expression (tuple) from its items, each auto-grounded: `e(x, y, x)` builds `($x $y $x)`. Use it
- *  for patterns that are not headed by a functor, e.g. repeated-variable patterns or pair structures. */
+ *  for patterns not headed by a functor, e.g. repeated-variable patterns or pair structures. */
 declare const e: (...items: Term[]) => ExpressionAtom;
-/** A functor builder: `rel("parent")` returns `(a, b) => (parent a b)`, auto-grounding each argument.
- *  Builders compose, so nested patterns like `rel("swap")(rel("Pair")(x, y))` are just function calls. */
-declare function rel(name: string): (...args: Term[]) => ExpressionAtom;
 /** The empty expression `()`, MeTTa's conventional empty/nil list. */
 declare const nil: () => ExpressionAtom;
 /** A Lisp-style cons list: `list([a, b, c])` builds `(:: a (:: b (:: c ())))`. Override the constructor
@@ -41,23 +59,28 @@ declare const decl: (subject: Term, type: Term) => ExpressionAtom;
 /** A function type `(-> A B ... R)`. */
 declare const arrow: (...types: Term[]) => ExpressionAtom;
 /** `(if cond then else)`. Only the taken branch is evaluated. */
-declare const iff: (cond: Term, then: Term, els: Term) => ExpressionAtom;
+declare const If: (cond: Term, then: Term, els: Term) => ExpressionAtom;
 /** `(case scrutinee ((pat body) ...))`, sequential mutually-exclusive pattern matching. */
-declare const caseOf: (scrutinee: Term, cases: ReadonlyArray<readonly [Term, Term]>) => ExpressionAtom;
+declare const Case: (scrutinee: Term, cases: ReadonlyArray<readonly [Term, Term]>) => ExpressionAtom;
 /** `(let pattern value body)`: unify `value` against `pattern`, then evaluate `body`. */
-declare const lett: (pattern: Term, value: Term, body: Term) => ExpressionAtom;
+declare const Let: (pattern: Term, value: Term, body: Term) => ExpressionAtom;
 /** `(let* ((pat val) ...) body)`: sequential lets. */
-declare const letStar: (bindings: ReadonlyArray<readonly [Term, Term]>, body: Term) => ExpressionAtom;
+declare const LetStar: (bindings: ReadonlyArray<readonly [Term, Term]>, body: Term) => ExpressionAtom;
 /** `(match space pattern template)`. Defaults to `&self`, the program's own space. */
-declare const matchSelf: (pattern: Term, template: Term, space?: Term) => ExpressionAtom;
+declare const Match: (pattern: Term, template: Term, space?: Term) => ExpressionAtom;
 /** `(superpose (a b ...))`: a nondeterministic choice among the items. */
-declare const superpose: (...items: Term[]) => ExpressionAtom;
+declare const Superpose: (...items: Term[]) => ExpressionAtom;
 /** `(collapse x)`: gather all nondeterministic results of `x` into a single expression. */
-declare const collapse: (x: Term) => ExpressionAtom;
+declare const Collapse: (x: Term) => ExpressionAtom;
 /** `(empty)`: no results, which prunes a branch. */
-declare const empty: () => ExpressionAtom;
+declare const Empty: () => ExpressionAtom;
 /** `(unify a b then else)`: low-level unification with then/else continuations. */
-declare const unify: (a: Term, b: Term, then: Term, els: Term) => ExpressionAtom;
+declare const Unify: (a: Term, b: Term, then: Term, els: Term) => ExpressionAtom;
+/** `(sealed (vars...) body)`: alpha-rename `body`'s variables (except `vars`) to fresh names, so a
+ *  template can be reused without variable capture. */
+declare const Sealed: (vars: ReadonlyArray<Term>, body: Term) => ExpressionAtom;
+/** `(quote x)`: hold `x` as data so the interpreter does not evaluate it. */
+declare const Quote: (x: Term) => ExpressionAtom;
 /** Arithmetic grounded operations. */
 declare const add: (a: Term, b: Term) => ExpressionAtom;
 declare const sub: (a: Term, b: Term) => ExpressionAtom;
@@ -80,15 +103,13 @@ declare const cdrAtom: (x: Term) => ExpressionAtom;
 declare const consAtom: (head: Term, tail: Term) => ExpressionAtom;
 /** `(decons-atom expr)`: split a non-empty expression into `(head tail)`. */
 declare const deconsAtom: (x: Term) => ExpressionAtom;
-/** `(quote x)`: hold `x` as data so the interpreter does not evaluate it. */
-declare const quote: (x: Term) => ExpressionAtom;
 /** Type introspection. `getType` reports an atom's declared/inferred type; `getMetatype` reports its
  *  meta-type (`Symbol`/`Variable`/`Expression`/`Grounded`). */
 declare const getType: (x: Term) => ExpressionAtom;
 declare const getMetatype: (x: Term) => ExpressionAtom;
-/** Assertions for eDSL tests. Each returns the unit atom `()` on success and an
- *  `(Error ...)` atom on failure, matching Hyperon's stdlib. `assertEqual` compares evaluated results;
- *  `assertAlphaEqual` compares up to a consistent renaming of variables. */
+/** Assertions for eDSL tests. Each returns the unit atom `()` on success and an `(Error ...)` atom on
+ *  failure, matching Hyperon's stdlib. `assertEqual` compares evaluated results; `assertAlphaEqual`
+ *  compares up to a consistent renaming of variables. */
 declare const assertEqual: (a: Term, b: Term) => ExpressionAtom;
 declare const assertAlphaEqual: (a: Term, b: Term) => ExpressionAtom;
 /** Set operations over the (collapsed) results of their arguments, deduplicating modulo equality.
@@ -99,21 +120,67 @@ declare const intersection: (a: Term, b: Term) => ExpressionAtom;
 declare const subtraction: (a: Term, b: Term) => ExpressionAtom;
 /** `(println! x)`: print `x` (a side effect); returns the unit atom `()`. */
 declare const println: (x: Term) => ExpressionAtom;
-/** `(sealed (vars...) body)`: alpha-rename `body`'s variables (except `vars`) to fresh names, so a
- *  template can be reused without variable capture. */
-declare const sealed: (vars: ReadonlyArray<Term>, body: Term) => ExpressionAtom;
+/** `(json-encode x)`: encode a MeTTa atom (string, number, expression, dict-space, or a mix) to a JSON
+ *  string. */
+declare const jsonEncode: (x: Term) => ExpressionAtom;
+/** `(json-decode s)`: decode a JSON string to MeTTa (array to expression, object to a dict-space of
+ *  `(key value)` pairs, string to string, number to number). */
+declare const jsonDecode: (x: Term) => ExpressionAtom;
+/** `(dict-space ((k v) ...))`: build a grounded Space of `(key value)` pairs from key-value tuples. */
+declare const dictSpace: (pairs: ReadonlyArray<readonly [Term, Term]>) => ExpressionAtom;
+/** `(get-keys space)`: every key in a dict-space, one result per key. */
+declare const getKeys: (x: Term) => ExpressionAtom;
+/** `(get-value space key)`: the value tied to `key` in a dict-space, empty if absent. */
+declare const getValue: (a: Term, b: Term) => ExpressionAtom;
 
 /** Parse a MeTTa template into the atoms it contains, with `${...}` holes auto-grounded. */
 declare function mAll(strings: TemplateStringsArray, ...values: Term[]): Atom[];
 /** Parse a MeTTa template into one top-level atom. Throws otherwise; use {@link mAll} for several. */
 declare function m(strings: TemplateStringsArray, ...values: Term[]): Atom;
+/** Parse one atom from a plain source string (no interpolation). Throws unless the source is exactly one
+ *  atom. Backs the typed source query {@link MettaDB.q}. */
+declare function parseSource(src: string): Atom;
+
+/** Characters allowed in a MeTTa variable name after the `$`. */
+type IdentChar = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "_" | "-";
+/** The leading identifier of `S` (characters up to the first non-identifier character). */
+type IdentHead<S extends string, Acc extends string = ""> = S extends `${infer C}${infer R}` ? C extends IdentChar ? IdentHead<R, `${Acc}${C}`> : Acc : Acc;
+/** `S` with its leading identifier removed. */
+type AfterIdent<S extends string> = S extends `${infer C}${infer R}` ? C extends IdentChar ? AfterIdent<R> : S : S;
+/** The union of every `$`-prefixed variable name in the source string `S` (a bare `$` yields nothing). */
+type SourceVars<S extends string> = S extends `${string}$${infer Rest}` ? (IdentHead<Rest> extends "" ? never : IdentHead<Rest>) | SourceVars<AfterIdent<Rest>> : never;
+/** A typed query row: each variable in the source mapped to its (runtime-unwrapped) JS value. */
+type SourceRow<S extends string> = {
+    [K in SourceVars<S>]: unknown;
+};
 
-/** One typed binding row from a {@link MettaDB.query}: each requested variable mapped to its JS value. */
+/** One typed binding row from {@link MettaDB.query} with explicit vars: each requested variable mapped
+ *  to its JS value. */
 type Row<V extends Record<string, Var>> = {
     [K in keyof V]: VarValue<V[K]>;
 };
-/** A typed MeTTa runner. Build it with {@link mettaDB}. */
-declare class MettaDB {
+/** Any function, used as the permissive default for names outside a schema. */
+type AnyFn = (...args: never[]) => unknown;
+/** A schema mapping MeTTa function names to their TypeScript signatures, for a typed runner:
+ *  `mettaDB<{ fact: (n: number) => number }>()`. Both an `interface` and a `type` work. */
+type FnSchema = Record<string, AnyFn>;
+/** The argument tuple / return type of a schema entry (like `Parameters`/`ReturnType`, but tolerant of
+ *  a non-function member, which extracts as `never`). */
+type FnArgs<F> = F extends (...a: infer A) => unknown ? A : never;
+type FnRet<F> = F extends (...a: never[]) => infer R ? R : never;
+/** A MeTTa function imported as a typed TypeScript callable (see {@link MettaDB.import}). Returns the
+ *  first result unwrapped to JS, or `undefined` when the call produces no result. */
+type ImportedFn<Args extends unknown[], Ret> = (...args: Args) => Ret | undefined;
+/** Proxy surface for calling MeTTa functions by name. A name in the schema `S` is typed by its
+ *  signature (`db.call.fact(5): number[]`); any other name falls back to `unknown[]`. Bracket access
+ *  handles hyphenated names: `db.call["is-son"]("Bob", "Tom")`. */
+type CallProxy<S> = {
+    [K in keyof S]: (...args: FnArgs<S[K]>) => FnRet<S[K]>[];
+} & Record<string, (...args: Term[]) => unknown[]>;
+/** A typed MeTTa runner. Build it with {@link mettaDB}. The optional schema `S` types the host bridge
+ *  (`call`, `import`, `fn`); the default is an empty schema, so with no schema those stay permissive
+ *  (`db.call.<any>(...)` is `unknown[]`, `db.import(name)` a permissive callable) but still work. */
+declare class MettaDB<S = Record<never, never>> {
     /** The underlying hyperon runner, for anything the eDSL does not wrap. */
     readonly metta: MeTTa;
     /** Add atoms (facts, rules, type declarations) to the program space. JS values are auto-grounded. */
@@ -136,16 +203,49 @@ declare class MettaDB {
     evalAsync(atom: Term): Promise<Atom[]>;
     /** Like {@link evalJs}, awaiting async grounded operations. */
     evalJsAsync(atom: Term): Promise<unknown[]>;
-    /** `match &self pattern` over stored atoms, returning one typed row of JS bindings per match. */
+    /** `match &self pattern` over stored atoms, returning one binding row per match. With no `vars`, the
+     *  row keys are inferred from the pattern's free variables and the values come back as plain JS
+     *  (typed `unknown`); pass an explicit `vars` map to get statically-typed values. */
+    query(pattern: Term): Array<Record<string, unknown>>;
     query<V extends Record<string, Var>>(pattern: Term, vars: V): Array<Row<V>>;
-    /** Register a synchronous TypeScript function as a grounded operation callable from MeTTa. */
+    /** `match &self` from a plain MeTTa source string, with the result rows typed by the pattern's
+     *  `$`-variables: `db.q("(Likes Ada $thing)")` returns `Array<{ thing: unknown }>`, keys inferred and
+     *  autocompleted at compile time. Values are `unknown` (they come from runtime rewriting). For the
+     *  builder form use {@link query}. */
+    q<Src extends string>(src: Src): Array<SourceRow<Src>>;
+    /** Register a synchronous TypeScript function as a raw grounded operation (atoms in, atoms out). */
     op(name: string, fn: (args: Atom[]) => Atom[]): this;
-    /** Register an async TypeScript function (I/O) as a grounded operation; await it via {@link evalAsync}. */
+    /** Register an async TypeScript function (I/O) as a raw grounded operation; await it via
+     *  {@link evalAsync}. */
     asyncOp(name: string, fn: (args: Atom[]) => Promise<Atom[]>): this;
+    /** Shared body of {@link fn}/{@link fns}: unwrap args to JS, call, ground the result. */
+    private registerFn;
+    /** Register a plain typed function as a grounded operation, with arguments auto-unwrapped to JS and the
+     *  single result auto-grounded: `db.fn("balance-of", (a: {balance: number}) => a.balance)`. When the
+     *  name is in the schema `S`, `fn` is checked against its declared signature. Return an array from `fn`
+     *  to yield it as one grounded list; use {@link op} for multiple (nondeterministic) results or full
+     *  atom control. */
+    fn<K extends string>(name: K, fn: K extends keyof S ? S[K] : AnyFn): this;
+    /** Register several typed functions at once, keyed by name: `db.fns({ inc: n => n+1, ... })`. The JS
+     *  key becomes the MeTTa token. */
+    fns(map: Record<string, AnyFn>): this;
+    /** Register a plain async typed function as a grounded operation (args unwrapped, result grounded). */
+    asyncFn(name: string, fn: (...args: never[]) => Promise<unknown>): this;
+    /** Import a MeTTa function as a typed TypeScript callable. Arguments are auto-grounded, the call is
+     *  `(name ...args)`, and the first result is unwrapped to JS. A name in the schema `S` is typed from
+     *  its signature (`db.import("fact")`); a name outside the schema returns a permissive callable. */
+    import<K extends string>(name: K): K extends keyof S ? ImportedFn<FnArgs<S[K]>, FnRet<S[K]>> : ImportedFn<unknown[], unknown>;
+    /** Proxy for calling MeTTa functions by name from TypeScript. `db.call.fib(5)` evaluates `(fib 5)` and
+     *  returns each result unwrapped to JS; bracket access handles hyphenated names. */
+    get call(): CallProxy<S>;
+    /** Enable the JSON module on this runner, registering `json-encode`, `json-decode`, `dict-space`,
+     *  `get-keys`, and `get-value` (see the builders of the same name). Chainable. */
+    useJson(): this;
     /** Run raw MeTTa source, one result group per `!`-query. */
     run(src: string): Atom[][];
 }
-/** Create an ergonomic, typed MeTTa runner. */
-declare const mettaDB: () => MettaDB;
+/** Create an ergonomic, typed MeTTa runner. Pass a schema to type the host bridge:
+ *  `mettaDB<{ fact: (n: number) => number }>()`. */
+declare const mettaDB: <S = Record<never, never>>() => MettaDB<S>;
 
-export { MettaDB, type Row, S, type SymbolBuilder, type Term, type Var, type VarValue, add, and, arrow, assertAlphaEqual, assertEqual, carAtom, caseOf, cdrAtom, collapse, consAtom, decl, deconsAtom, div, e, empty, eq, ge, getMetatype, getType, ground, gt, iff, intersection, le, letStar, lett, list, lt, m, mAll, matchSelf, mettaDB, mod, mul, nil, not, or, println, quote, rel, rule, sealed, sub, subtraction, superpose, unify, union, unique, v };
+export { type CallProxy, Case, Collapse, Empty, type FnSchema, If, type ImportedFn, Let, LetStar, Match, MettaDB, type Name, type Names, Quote, type Row, Sealed, type SourceRow, type SourceVars, Superpose, type Term, Unify, type Var, type VarValue, type Vars, add, and, arrow, assertAlphaEqual, assertEqual, carAtom, cdrAtom, consAtom, decl, deconsAtom, dictSpace, div, e, eq, ge, getKeys, getMetatype, getType, getValue, ground, gt, intersection, jsonDecode, jsonEncode, le, list, lt, m, mAll, mettaDB, mod, mul, names, nil, not, or, parseSource, patternVars, println, rule, sub, subtraction, union, unique, vars };

package/dist/index.js

@@ -4,23 +4,63 @@ import {
   S as hS,
   V,
   E,
-  ValueAtom
+  ValueAtom,
+  VariableAtom,
+  ExpressionAtom
 } from "@metta-ts/hyperon";
-var v = (name) => V(name);
-var S = new Proxy(((name) => hS(name)), {
-  get(_target, prop) {
-    return typeof prop === "string" ? hS(prop) : void 0;
-  }
-});
+var HEAD = /* @__PURE__ */ Symbol("metta.edsl.head");
+function isName(x) {
+  return typeof x === "function" && x[HEAD] !== void 0;
+}
 function ground(x) {
   if (x instanceof Atom) return x;
+  if (isName(x)) return x[HEAD];
   return ValueAtom(x);
 }
-var e = (...items) => E(...items.map(ground));
-function rel(name) {
+function makeName(name) {
   const head = hS(name);
-  return (...args) => E(head, ...args.map(ground));
+  const fn = (...args) => E(head, ...args.map(ground));
+  return Object.assign(fn, { [HEAD]: head, toString: () => name });
+}
+function names() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, prop) {
+      if (typeof prop !== "string") return void 0;
+      let n = cache.get(prop);
+      if (n === void 0) {
+        n = makeName(prop);
+        cache.set(prop, n);
+      }
+      return n;
+    }
+  });
+}
+function vars() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, prop) {
+      if (typeof prop !== "string") return void 0;
+      let x = cache.get(prop);
+      if (x === void 0) {
+        x = V(prop);
+        cache.set(prop, x);
+      }
+      return x;
+    }
+  });
 }
+function patternVars(atom) {
+  const seen = /* @__PURE__ */ new Map();
+  const walk = (a) => {
+    if (a instanceof VariableAtom) {
+      if (!seen.has(a.name())) seen.set(a.name(), a);
+    } else if (a instanceof ExpressionAtom) for (const c of a.children()) walk(c);
+  };
+  walk(atom);
+  return [...seen.values()];
+}
+var e = (...items) => E(...items.map(ground));
 var nil = () => E();
 function list(items, opts) {
   const cons = hS(opts?.cons ?? "::");
@@ -30,20 +70,23 @@ function list(items, opts) {
 }
 
 // src/forms.ts
-import { E as E2, S as S2 } from "@metta-ts/hyperon";
-var rule = (head, body) => E2(S2("="), ground(head), ground(body));
-var decl = (subject, type) => E2(S2(":"), ground(subject), ground(type));
-var arrow = (...types) => E2(S2("->"), ...types.map(ground));
-var iff = (cond, then, els) => E2(S2("if"), ground(cond), ground(then), ground(els));
-var caseOf = (scrutinee, cases) => E2(S2("case"), ground(scrutinee), E2(...cases.map(([pat, body]) => E2(ground(pat), ground(body)))));
-var lett = (pattern, value, body) => E2(S2("let"), ground(pattern), ground(value), ground(body));
-var letStar = (bindings, body) => E2(S2("let*"), E2(...bindings.map(([pat, val]) => E2(ground(pat), ground(val)))), ground(body));
-var matchSelf = (pattern, template, space = S2("&self")) => E2(S2("match"), ground(space), ground(pattern), ground(template));
-var superpose = (...items) => E2(S2("superpose"), E2(...items.map(ground)));
-var collapse = (x) => E2(S2("collapse"), ground(x));
-var empty = () => E2(S2("empty"));
-var unify = (a, b, then, els) => E2(S2("unify"), ground(a), ground(b), ground(then), ground(els));
-var op2 = (name) => (a, b) => E2(S2(name), ground(a), ground(b));
+import { E as E2, S } from "@metta-ts/hyperon";
+var rule = (head, body) => E2(S("="), ground(head), ground(body));
+var decl = (subject, type) => E2(S(":"), ground(subject), ground(type));
+var arrow = (...types) => E2(S("->"), ...types.map(ground));
+var If = (cond, then, els) => E2(S("if"), ground(cond), ground(then), ground(els));
+var Case = (scrutinee, cases) => E2(S("case"), ground(scrutinee), E2(...cases.map(([pat, body]) => E2(ground(pat), ground(body)))));
+var Let = (pattern, value, body) => E2(S("let"), ground(pattern), ground(value), ground(body));
+var LetStar = (bindings, body) => E2(S("let*"), E2(...bindings.map(([pat, val]) => E2(ground(pat), ground(val)))), ground(body));
+var Match = (pattern, template, space = S("&self")) => E2(S("match"), ground(space), ground(pattern), ground(template));
+var Superpose = (...items) => E2(S("superpose"), E2(...items.map(ground)));
+var Collapse = (x) => E2(S("collapse"), ground(x));
+var Empty = () => E2(S("empty"));
+var Unify = (a, b, then, els) => E2(S("unify"), ground(a), ground(b), ground(then), ground(els));
+var Sealed = (vars2, body) => E2(S("sealed"), E2(...vars2.map(ground)), ground(body));
+var Quote = (x) => E2(S("quote"), ground(x));
+var op2 = (name) => (a, b) => E2(S(name), ground(a), ground(b));
+var op1 = (name) => (x) => E2(S(name), ground(x));
 var add = op2("+");
 var sub = op2("-");
 var mul = op2("*");
@@ -54,15 +97,13 @@ var gt = op2(">");
 var lt = op2("<");
 var ge = op2(">=");
 var le = op2("<=");
-var op1 = (name) => (x) => E2(S2(name), ground(x));
 var and = op2("and");
 var or = op2("or");
 var not = op1("not");
 var carAtom = op1("car-atom");
 var cdrAtom = op1("cdr-atom");
-var consAtom = (head, tail) => E2(S2("cons-atom"), ground(head), ground(tail));
+var consAtom = (head, tail) => E2(S("cons-atom"), ground(head), ground(tail));
 var deconsAtom = op1("decons-atom");
-var quote = op1("quote");
 var getType = op1("get-type");
 var getMetatype = op1("get-metatype");
 var assertEqual = op2("assertEqual");
@@ -72,13 +113,17 @@ var union = op2("union");
 var intersection = op2("intersection");
 var subtraction = op2("subtraction");
 var println = op1("println!");
-var sealed = (vars, body) => E2(S2("sealed"), E2(...vars.map(ground)), ground(body));
+var jsonEncode = op1("json-encode");
+var jsonDecode = op1("json-decode");
+var dictSpace = (pairs) => E2(S("dict-space"), E2(...pairs.map(([k, v]) => E2(ground(k), ground(v)))));
+var getKeys = op1("get-keys");
+var getValue = op2("get-value");
 
 // src/template.ts
 import {
   SExprParser,
-  SymbolAtom,
-  ExpressionAtom,
+  SymbolAtom as SymbolAtom2,
+  ExpressionAtom as ExpressionAtom2,
   E as E3,
   standardTokenizer
 } from "@metta-ts/hyperon";
@@ -87,11 +132,11 @@ var SLOT_RE = /^__metta_ts_slot_(\d+)__$/;
 var sharedTokenizer;
 var tokenizer = () => sharedTokenizer ??= standardTokenizer();
 function substituteSlots(atom, slots) {
-  if (atom instanceof SymbolAtom) {
+  if (atom instanceof SymbolAtom2) {
     const match = SLOT_RE.exec(atom.name());
     return match ? slots[Number(match[1])] : atom;
   }
-  if (atom instanceof ExpressionAtom)
+  if (atom instanceof ExpressionAtom2)
     return E3(...atom.children().map((c) => substituteSlots(c, slots)));
   return atom;
 }
@@ -109,9 +154,21 @@ function m(strings, ...values) {
     );
   return atoms[0];
 }
+function parseSource(src) {
+  const atoms = new SExprParser(src).parseAll(tokenizer());
+  if (atoms.length !== 1)
+    throw new Error(`parseSource: expected exactly one atom, got ${atoms.length}: ${src}`);
+  return atoms[0];
+}
 
 // src/db.ts
-import { MeTTa, atomToJs } from "@metta-ts/hyperon";
+import {
+  MeTTa,
+  E as E4,
+  S as S2,
+  atomToJs,
+  registerJsonModule
+} from "@metta-ts/hyperon";
 var MettaDB = class {
   /** The underlying hyperon runner, for anything the eDSL does not wrap. */
   metta = new MeTTa();
@@ -158,41 +215,110 @@ var MettaDB = class {
   async evalJsAsync(atom) {
     return (await this.evalAsync(atom)).map(atomToJs);
   }
-  /** `match &self pattern` over stored atoms, returning one typed row of JS bindings per match. */
-  query(pattern, vars) {
-    const set = this.metta.space().query(ground(pattern));
+  query(pattern, vars2) {
+    const pat = ground(pattern);
+    const set = this.metta.space().query(pat);
+    const cols = vars2 ?? Object.fromEntries(patternVars(pat).map((v) => [v.name(), v]));
     return set.frames.map((frame) => {
       const row = {};
-      for (const key in vars) {
-        const bound = frame.resolve(vars[key]);
+      for (const key in cols) {
+        const bound = frame.resolve(cols[key]);
         row[key] = bound === void 0 ? void 0 : atomToJs(bound);
       }
       return row;
     });
   }
-  /** Register a synchronous TypeScript function as a grounded operation callable from MeTTa. */
+  /** `match &self` from a plain MeTTa source string, with the result rows typed by the pattern's
+   *  `$`-variables: `db.q("(Likes Ada $thing)")` returns `Array<{ thing: unknown }>`, keys inferred and
+   *  autocompleted at compile time. Values are `unknown` (they come from runtime rewriting). For the
+   *  builder form use {@link query}. */
+  q(src) {
+    return this.query(parseSource(src));
+  }
+  /** Register a synchronous TypeScript function as a raw grounded operation (atoms in, atoms out). */
   op(name, fn) {
     this.metta.registerOperation(name, fn);
     return this;
   }
-  /** Register an async TypeScript function (I/O) as a grounded operation; await it via {@link evalAsync}. */
+  /** Register an async TypeScript function (I/O) as a raw grounded operation; await it via
+   *  {@link evalAsync}. */
   asyncOp(name, fn) {
     this.metta.registerAsyncOperation(name, fn);
     return this;
   }
+  /** Shared body of {@link fn}/{@link fns}: unwrap args to JS, call, ground the result. */
+  registerFn(name, fn) {
+    return this.op(name, (args) => [ground(fn(...args.map(atomToJs)))]);
+  }
+  /** Register a plain typed function as a grounded operation, with arguments auto-unwrapped to JS and the
+   *  single result auto-grounded: `db.fn("balance-of", (a: {balance: number}) => a.balance)`. When the
+   *  name is in the schema `S`, `fn` is checked against its declared signature. Return an array from `fn`
+   *  to yield it as one grounded list; use {@link op} for multiple (nondeterministic) results or full
+   *  atom control. */
+  fn(name, fn) {
+    return this.registerFn(name, fn);
+  }
+  /** Register several typed functions at once, keyed by name: `db.fns({ inc: n => n+1, ... })`. The JS
+   *  key becomes the MeTTa token. */
+  fns(map) {
+    for (const [name, fn] of Object.entries(map)) this.registerFn(name, fn);
+    return this;
+  }
+  /** Register a plain async typed function as a grounded operation (args unwrapped, result grounded). */
+  asyncFn(name, fn) {
+    return this.asyncOp(name, async (args) => [
+      ground(await fn(...args.map(atomToJs)))
+    ]);
+  }
+  /** Import a MeTTa function as a typed TypeScript callable. Arguments are auto-grounded, the call is
+   *  `(name ...args)`, and the first result is unwrapped to JS. A name in the schema `S` is typed from
+   *  its signature (`db.import("fact")`); a name outside the schema returns a permissive callable. */
+  import(name) {
+    const fn = (...args) => {
+      const results = this.evalJs(callExpr(name, args));
+      return results.length === 0 ? void 0 : results[0];
+    };
+    return fn;
+  }
+  /** Proxy for calling MeTTa functions by name from TypeScript. `db.call.fib(5)` evaluates `(fib 5)` and
+   *  returns each result unwrapped to JS; bracket access handles hyphenated names. */
+  get call() {
+    return new Proxy(/* @__PURE__ */ Object.create(null), {
+      get: (_t, prop) => typeof prop === "string" ? (...args) => this.evalJs(callExpr(prop, args)) : void 0
+    });
+  }
+  /** Enable the JSON module on this runner, registering `json-encode`, `json-decode`, `dict-space`,
+   *  `get-keys`, and `get-value` (see the builders of the same name). Chainable. */
+  useJson() {
+    registerJsonModule(this.metta);
+    return this;
+  }
   /** Run raw MeTTa source, one result group per `!`-query. */
   run(src) {
     return this.metta.run(src);
   }
 };
+function callExpr(name, args) {
+  return E4(S2(name), ...args.map(ground));
+}
 var mettaDB = () => new MettaDB();
 
 // src/index.ts
 import { Atom as Atom3, ValueAtom as ValueAtom2, atomToJs as atomToJs2 } from "@metta-ts/hyperon";
 export {
   Atom3 as Atom,
+  Case,
+  Collapse,
+  Empty,
+  If,
+  Let,
+  LetStar,
+  Match,
   MettaDB,
-  S,
+  Quote,
+  Sealed,
+  Superpose,
+  Unify,
   ValueAtom2 as ValueAtom,
   add,
   and,
@@ -201,47 +327,43 @@ export {
   assertEqual,
   atomToJs2 as atomToJs,
   carAtom,
-  caseOf,
   cdrAtom,
-  collapse,
   consAtom,
   decl,
   deconsAtom,
+  dictSpace,
   div,
   e,
-  empty,
   eq,
   ge,
+  getKeys,
   getMetatype,
   getType,
+  getValue,
   ground,
   gt,
-  iff,
   intersection,
+  jsonDecode,
+  jsonEncode,
   le,
-  letStar,
-  lett,
   list,
   lt,
   m,
   mAll,
-  matchSelf,
   mettaDB,
   mod,
   mul,
+  names,
   nil,
   not,
   or,
+  parseSource,
+  patternVars,
   println,
-  quote,
-  rel,
   rule,
-  sealed,
   sub,
   subtraction,
-  superpose,
-  unify,
   union,
   unique,
-  v
+  vars
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metta-ts/edsl",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "author": "MesTTo",
   "license": "MIT",
   "description": "Ergonomic, typed TypeScript eDSL for MeTTa: typed term builders, rewrite rules, a tagged-template surface, and auto-grounding of TypeScript values.",
@@ -31,7 +31,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@metta-ts/hyperon": "1.0.3"
+    "@metta-ts/hyperon": "1.0.5"
   },
   "repository": {
     "type": "git",