bireactive 0.3.1 → 0.3.3

package/dist/core/values/reg.js

@@ -0,0 +1,649 @@
+import { Cell } from "../cell.js";
+import { optic } from "../optic.js";
+import { Arr } from "./arr.js";
+import { concatAmbiguity, intersects } from "./reg/ambiguity.js";
+import { accepts, alphabetOf, altAll, CharSet, chr, EPS, language, nullable as reNullable, seq as reSeq, star as reStar, seqAll, } from "./reg/engine.js";
+import { compileProgram, parseValue, recognize } from "./reg/nfa.js";
+import { compileRegex, RegError } from "./reg/regex.js";
+import { Str } from "./str.js";
+import { numCodec } from "./template.js";
+const isSilent = (n) => n.kind === "lit";
+// ── memoized structural views (toRe / program) ───────────────────────
+const reMemo = new WeakMap();
+const progMemo = new WeakMap();
+/** The compiled Thompson program for a node (built once, then cached). */
+function progOf(n) {
+    let p = progMemo.get(n);
+    if (p === undefined) {
+        p = compileProgram(n);
+        progMemo.set(n, p);
+    }
+    return p;
+}
+function reOf(n) {
+    let r = reMemo.get(n);
+    if (r === undefined) {
+        r = toRe(n);
+        reMemo.set(n, r);
+    }
+    return r;
+}
+// ── parse (get): linear PikeVM, whole-string ──────────────────────────
+/** Parse `s` fully; `null` if it doesn't match. */
+function parseNode(n, s, spans) {
+    const r = parseValue(n, progOf(n), s, spans);
+    return r === null ? null : r.val;
+}
+/** Whole-string match of a leaf's language — for validating a scalar write. */
+function fullLeafMatch(leaf, s) {
+    return accepts(leaf.engine, s);
+}
+/** Does `n` parse all of `s`? General write-validation. */
+function fullNodeMatch(n, s) {
+    return recognize(progOf(n), s);
+}
+// ── print (put) ──────────────────────────────────────────────────────
+function printNode(n, val) {
+    switch (n.kind) {
+        case "lit":
+            return n.text;
+        case "copy":
+            return String(val ?? "");
+        case "of":
+            return n.codec.format(val);
+        case "seq": {
+            const vals = val ?? [];
+            let out = "";
+            let vi = 0;
+            for (const part of n.parts) {
+                if (isSilent(part))
+                    out += printNode(part, null);
+                else
+                    out += printNode(part, vals[vi++] ?? defaultVal(part));
+            }
+            return out;
+        }
+        case "alt": {
+            const a = val ?? { branch: 0, val: defaultVal(n.branches[0]) };
+            const branch = n.branches[a.branch] ?? n.branches[0];
+            return printNode(branch, a.val);
+        }
+        case "opt":
+            if (val === null || val === undefined)
+                return "";
+            return printNode(n.part, isSilent(n.part) ? null : val);
+        case "star": {
+            const sv = val ?? { items: [], seps: [] };
+            let out = "";
+            for (let k = 0; k < sv.items.length; k++) {
+                if (k > 0)
+                    out += sv.seps[k - 1] ?? n.joiner;
+                out += printNode(n.part, sv.items[k]);
+            }
+            return out;
+        }
+    }
+}
+// ── totalization + nullability ───────────────────────────────────────
+function defaultVal(n) {
+    switch (n.kind) {
+        case "lit":
+            return null;
+        case "copy":
+            return "";
+        case "of":
+            return (n.codec.parse("") ?? n.codec.parse("0") ?? null);
+        case "seq":
+            return n.parts.filter(p => !isSilent(p)).map(defaultVal);
+        case "alt":
+            return { branch: 0, val: defaultVal(n.branches[0]) };
+        case "opt":
+            return null;
+        case "star":
+            return { items: [], seps: [] };
+    }
+}
+function nullable(n) {
+    switch (n.kind) {
+        case "lit":
+            return n.text === "";
+        case "copy":
+        case "of":
+            return reNullable(n.engine);
+        case "seq":
+            return n.parts.every(nullable);
+        case "alt":
+            return n.branches.some(nullable);
+        case "opt":
+            return true;
+        case "star":
+            return n.sep === undefined && n.min === 0 ? true : nullable(n.part);
+    }
+}
+// ── unambiguity checks (thrown at construction) ──────────────────────
+// Each combinator validates only its own new seams (children are already valid),
+// deciding on the derivative automaton (see `reg/ambiguity.ts`). Each error
+// names a concrete witness string that would parse two ways.
+const quote = (s) => (s === "" ? '""' : JSON.stringify(s));
+function checkSeq(parts) {
+    for (let i = 0; i < parts.length - 1; i++) {
+        const a = reOf(parts[i]);
+        const b = seqAll(parts.slice(i + 1).map(reOf));
+        const w = concatAmbiguity(a, b);
+        if (w !== null) {
+            throw new RegError(`Reg.seq: the boundary after part ${i} is ambiguous — ${quote(w)} splits two ways. Insert a lit() delimiter or use disjoint character classes.`);
+        }
+    }
+}
+function checkAlt(branches) {
+    for (let i = 0; i < branches.length; i++) {
+        for (let j = i + 1; j < branches.length; j++) {
+            const w = intersects(reOf(branches[i]), reOf(branches[j]));
+            if (w !== null) {
+                throw new RegError(`Reg.alt: branches ${i} and ${j} both match ${quote(w)} — make the branches' languages disjoint.`);
+            }
+        }
+    }
+}
+function checkOpt(part) {
+    if (nullable(part)) {
+        throw new RegError("Reg.opt: the element is itself nullable — present-vs-absent is ambiguous.");
+    }
+}
+function checkStar(part, sep) {
+    const e = reOf(part);
+    if (sep === undefined) {
+        if (nullable(part)) {
+            throw new RegError('Reg.star/plus: a nullable element with no separator iterates ambiguously — add a separator (e.g. star(lit(","))).');
+        }
+        const w = concatAmbiguity(e, reStar(e)); // element · element* unambiguous?
+        if (w !== null) {
+            throw new RegError(`Reg.star/plus: element boundaries are not self-delimiting — ${quote(w)} iterates two ways. Add a separator.`);
+        }
+        return;
+    }
+    if (nullable(sep)) {
+        throw new RegError("Reg.star/plus: a nullable separator cannot pin element boundaries.");
+    }
+    // Pattern is `E (S E)*`; check each seam: S·E, the (S·E) repetition, and the
+    // leading E · (S E)*.
+    const s = reOf(sep);
+    const se = reSeq(s, e);
+    const tail = reStar(se);
+    const w = concatAmbiguity(s, e) ?? concatAmbiguity(se, tail) ?? concatAmbiguity(e, reSeq(s, tail));
+    if (w !== null) {
+        throw new RegError(`Reg.star/plus: element and separator boundaries overlap — ${quote(w)} parses two ways.`);
+    }
+}
+// ── grammar → capture-free automaton (recognition) ────────────────────
+function toRe(n) {
+    switch (n.kind) {
+        case "lit": {
+            const parts = [];
+            for (let i = 0; i < n.text.length; i++)
+                parts.push(chr(CharSet.char(n.text.charCodeAt(i))));
+            return seqAll(parts);
+        }
+        case "copy":
+        case "of":
+            return n.engine;
+        case "seq":
+            return seqAll(n.parts.map(toRe));
+        case "alt":
+            return altAll(n.branches.map(toRe));
+        case "opt":
+            return altAll([EPS, toRe(n.part)]);
+        case "star": {
+            const P = toRe(n.part);
+            const S = n.sep !== undefined ? toRe(n.sep) : EPS;
+            return altAll([EPS, reSeq(P, reStar(reSeq(S, P)))]);
+        }
+    }
+}
+/** The separator string to emit when inserting into a star: the literal text
+ *  for a `lit`, otherwise the *shortest* string in the separator's language.
+ *  A separator whose language is empty has no insertable member, so the star
+ *  is rejected at construction rather than silently writing off-language text. */
+function joinerFor(sep) {
+    if (sep === undefined)
+        return "";
+    if (sep.kind === "lit")
+        return sep.text;
+    const re = reOf(sep);
+    for (const w of language(re, [...alphabetOf(re)], 1024, 1))
+        return w;
+    throw new RegError("Reg.star/plus: the separator matches no string, so nothing can be inserted between elements.");
+}
+function collectCaptures(n, path, acc) {
+    switch (n.kind) {
+        case "copy":
+        case "of":
+        case "star":
+            if (n.name !== undefined)
+                acc.set(n.name, { node: n, path: path.slice() });
+            return;
+        case "seq": {
+            let vi = 0;
+            for (const part of n.parts) {
+                if (isSilent(part))
+                    continue;
+                collectCaptures(part, [...path, { seq: vi }], acc);
+                vi++;
+            }
+            return;
+        }
+        case "opt":
+            collectCaptures(n.part, path, acc);
+            return;
+        case "alt": {
+            for (let b = 0; b < n.branches.length; b++) {
+                collectCaptures(n.branches[b], [...path, { alt: b }], acc);
+            }
+            return;
+        }
+        case "lit":
+            return;
+    }
+}
+/** Structural value equality, for the print-validate (PutGet) write check. */
+function regEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+const isAltVal = (v) => v !== null && typeof v === "object" && "branch" in v;
+function getAt(val, path) {
+    let v = val;
+    for (const step of path) {
+        if ("seq" in step)
+            v = v?.[step.seq] ?? null;
+        else if (isAltVal(v) && v.branch === step.alt)
+            v = v.val;
+        else
+            return null; // inactive alt branch
+    }
+    return v;
+}
+function setAt(val, path, next) {
+    if (path.length === 0)
+        return next;
+    const [head, ...rest] = path;
+    if ("seq" in head) {
+        const arr = (val ?? []).slice();
+        arr[head.seq] = setAt(arr[head.seq] ?? null, rest, next);
+        return arr;
+    }
+    // alt step: descend only into the active branch; otherwise the write is a no-op.
+    if (isAltVal(val) && val.branch === head.alt) {
+        return { branch: val.branch, val: setAt(val.val, rest, next) };
+    }
+    return val;
+}
+// ── the Reg class ────────────────────────────────────────────────────
+/** An immutable bidirectional string-lens description. Build with the typed
+ *  leaf builders and combinators, then `bind`/`view` onto a `Cell<string>`.
+ *
+ *  The four type parameters are phantom: `V` is the parsed value, `N` whether
+ *  it accepts "", and `F`/`L` the character classes its match can begin/end
+ *  with. `F`/`L`/`N` drive the compile-time ambiguity checks; they have no
+ *  runtime presence. */
+export class Reg {
+    /** @internal */
+    root;
+    #lastParse = null;
+    /** @internal — use the static builders. */
+    constructor(root) {
+        this.root = root;
+    }
+    // ── leaf builders ─────────────────────────────────────────────────
+    /** A fixed delimiter: matched and printed, never surfaced as a value. */
+    static lit(text) {
+        return new Reg({ kind: "lit", text });
+    }
+    /** Text up to (but not including) the delimiter `c` — i.e. `[^c]*`. Nullable
+     *  (an empty field is allowed); the natural companion of `star(lit(c))`. */
+    static until(c) {
+        const escaped = c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return new Reg({
+            kind: "copy",
+            re: new RegExp(`[^${escaped}]*`),
+            engine: compileRegex(new RegExp(`[^${escaped}]*`)),
+        });
+    }
+    /** One or more digits, `\d+`, as a string. */
+    static digits() {
+        return new Reg({ kind: "copy", re: /\d+/, engine: compileRegex(/\d+/) });
+    }
+    /** One or more digits, decoded as a `number` (a quotient lens — leading
+     *  zeros are not preserved). */
+    static int() {
+        return new Reg({
+            kind: "of",
+            re: /\d+/,
+            engine: compileRegex(/\d+/),
+            codec: numCodec(true),
+        });
+    }
+    /** One or more ASCII letters, `[A-Za-z]+`. */
+    static letters() {
+        return new Reg({ kind: "copy", re: /[A-Za-z]+/, engine: compileRegex(/[A-Za-z]+/) });
+    }
+    /** One or more word characters, `\w+` (letters, digits, underscore). */
+    static word() {
+        return new Reg({ kind: "copy", re: /\w+/, engine: compileRegex(/\w+/) });
+    }
+    /** The escape hatch: capture the text matched by an arbitrary regular `re`.
+     *  Non-regular constructs (anchors, lookaround, backreferences) throw. The
+     *  boundary is opaque to the type system (`AnyBound`), so adjacency can't be
+     *  checked at compile time — the construction-time check still applies. */
+    static copy(re) {
+        return new Reg({ kind: "copy", re, engine: compileRegex(re) });
+    }
+    /** Typed escape hatch: `re` recognizes, `codec` decodes/encodes. */
+    static of(re, codec) {
+        return new Reg({
+            kind: "of",
+            re,
+            engine: compileRegex(re),
+            codec: codec,
+        });
+    }
+    // ── combinators ───────────────────────────────────────────────────
+    /** Unambiguous concatenation; every boundary is checked here and throws on
+     *  ambiguity. (For compile-time adjacency checking, prefer the fluent
+     *  `a.then(b).then(c)`, which validates each link.) */
+    static seq(...parts) {
+        const flat = flattenSeq(parts);
+        checkSeq(flat);
+        return new Reg({ kind: "seq", parts: flat });
+    }
+    /** Ordered union; branches must be first-disjoint (checked). */
+    static alt(...branches) {
+        const bs = branches.map(b => b.root);
+        checkAlt(bs);
+        return new Reg({ kind: "alt", branches: bs });
+    }
+    /** Optional (`part` or nothing). `part` must be non-nullable. The value is
+     *  the inner value when present and `null` when absent; an optional with no
+     *  value of its own (e.g. `lit(...).optional()`) records presence as `true`. */
+    static opt(part) {
+        checkOpt(part.root);
+        return new Reg({ kind: "opt", part: part.root });
+    }
+    /** `seq(this, ...next)`. A provably-overlapping boundary between `this` and
+     *  the next part is a *type* error — so `a.then(b).then(c)` statically checks
+     *  every link. Interior boundaries of a multi-arg call, and the `copy`/`of`
+     *  escapes, are checked at construction (throws). */
+    then(...next) {
+        const flat = flattenSeq([this, ...next]);
+        checkSeq(flat);
+        return new Reg({ kind: "seq", parts: flat });
+    }
+    /** `alt(this, other)`. */
+    or(other) {
+        return Reg.alt(this, other);
+    }
+    /** `opt(this)`. Only available when `this` is non-nullable. */
+    optional() {
+        return Reg.opt(this);
+    }
+    /** Iterate zero-or-more, optionally separated by `sep`; binds to an `Arr`.
+     *  A separated star is a *split* (≥1 piece, like `Str.split`). Pass
+     *  `opts.key` for resourceful alignment across reorders. */
+    star(sep, opts = {}) {
+        const part = this.root;
+        const sepNode = sep === undefined ? undefined : sep.root;
+        checkStar(part, sepNode);
+        return new Reg({
+            kind: "star",
+            part,
+            sep: sepNode,
+            joiner: joinerFor(sepNode),
+            min: 0,
+            key: opts.key,
+        });
+    }
+    /** Iterate one-or-more (forbids the empty list when unseparated). */
+    plus(sep, opts = {}) {
+        const part = this.root;
+        const sepNode = sep === undefined ? undefined : sep.root;
+        checkStar(part, sepNode);
+        return new Reg({
+            kind: "star",
+            part,
+            sep: sepNode,
+            joiner: joinerFor(sepNode),
+            min: 1,
+            key: opts.key,
+        });
+    }
+    /** Name this capture so `bind` exposes it as a handle (`copy`/`of`/`star`). */
+    as(name) {
+        const r = this.root;
+        if (r.kind !== "copy" && r.kind !== "of" && r.kind !== "star") {
+            throw new RegError(`Reg.as: can only name copy/of/star, got "${r.kind}"`);
+        }
+        return new Reg({ ...r, name });
+    }
+    /** Attach a codec to a `copy` leaf, turning it into a typed `of` capture. */
+    map(codec) {
+        const r = this.root;
+        if (r.kind !== "copy")
+            throw new RegError(`Reg.map: only on a copy leaf, got "${r.kind}"`);
+        return new Reg({
+            kind: "of",
+            re: r.re,
+            engine: r.engine,
+            codec: codec,
+            name: r.name,
+        });
+    }
+    // ── pure parser / printer ────────────────────────────────────────
+    /** Parse `s` fully (must consume to the end); `null` if it doesn't match.
+     *  Single-pass and linear. */
+    match(s) {
+        if (this.#lastParse !== null && this.#lastParse.s === s)
+            return this.#lastParse.v;
+        const v = parseNode(this.root, s);
+        this.#lastParse = { s, v };
+        return v;
+    }
+    /** Reflective print: render a value back to source text. */
+    print(v) {
+        return printNode(this.root, v);
+    }
+    /** Does `s` fully match? Linear. */
+    test(s) {
+        return recognize(progOf(this.root), s);
+    }
+    /** Source spans of each named capture, keyed by name — the `get`/`put`
+     *  correspondence made visible. Empty if `s` doesn't fully match. */
+    spans(s) {
+        const m = new Map();
+        const r = parseValue(this.root, progOf(this.root), s, m);
+        return r !== null ? Object.fromEntries(m) : {};
+    }
+    // ── reactive binding ─────────────────────────────────────────────
+    /** This grammar as a first-class, composable `Optic<string, V>`: `get`
+     *  parses (falling back to the default value off-language), `put` reprints
+     *  and round-trip-guards (an off-language source or a non-round-tripping
+     *  value leaves the source untouched). Drops straight into `compose(...)`
+     *  and `cell.through(...)`, so it chains with `atKey`/`iso` and string
+     *  lenses like `caseFold`. */
+    optic() {
+        const def = defaultVal(this.root);
+        return optic((s) => (this.match(s) ?? def), (v, s) => {
+            if (this.match(s) === null)
+                return s; // source off-language: don't clobber
+            const next = this.print(v);
+            return this.match(next) === null ? s : next; // print must round-trip
+        });
+    }
+    /** The whole abstract value as a writable lens over `source`. */
+    view(source) {
+        return source.through(this.optic());
+    }
+    bind(source, opts = {}) {
+        const captures = new Map();
+        collectCaptures(this.root, [], captures);
+        if (opts.schema !== undefined) {
+            for (const [name, kind] of Object.entries(opts.schema)) {
+                const cap = captures.get(name);
+                if (cap === undefined)
+                    throw new RegError(`Reg.bind: schema names "${name}", which isn't a capture`);
+                const isArr = cap.node.kind === "star";
+                if ((kind === "arr") !== isArr) {
+                    throw new RegError(`Reg.bind: schema says "${name}" is "${kind}" but it's a ${isArr ? "star" : "scalar"} capture`);
+                }
+            }
+        }
+        const def = defaultVal(this.root);
+        const out = {};
+        for (const [name, cap] of captures) {
+            out[name] =
+                cap.node.kind === "star"
+                    ? this.#starHandle(source, cap, def)
+                    : this.#scalarHandle(source, cap, def);
+        }
+        return out;
+    }
+    // ── internals ────────────────────────────────────────────────────
+    #scalarHandle(source, cap, def) {
+        const leaf = cap.node;
+        const path = cap.path;
+        return Str.lens(source, (s) => {
+            const v = getAt(this.match(s) ?? def, path);
+            return leaf.kind === "of" ? leaf.codec.format(v) : String(v ?? "");
+        }, (target, s) => {
+            if (!fullLeafMatch(leaf, target))
+                return s;
+            const decoded = leaf.kind === "of" ? leaf.codec.parse(target) : target;
+            if (decoded === undefined)
+                return s;
+            const base = this.match(s);
+            if (base === null)
+                return s;
+            const next = this.print(setAt(base, path, decoded));
+            const back = this.match(next);
+            if (back === null || !regEqual(getAt(back, path), decoded))
+                return s;
+            return next;
+        });
+    }
+    #starHandle(source, cap, def) {
+        const starNode = cap.node;
+        if (starNode.part.kind !== "copy" && starNode.part.kind !== "of") {
+            throw new RegError(`Reg.bind: named star "${starNode.name}" needs a copy/of element for an Arr handle (got "${starNode.part.kind}") — use view() for structured elements`);
+        }
+        const path = cap.path;
+        const self = this;
+        const readStar = (s) => getAt(self.match(s) ?? def, path) ?? { items: [], seps: [] };
+        const writeStar = (s, sv) => {
+            const base = self.match(s);
+            if (base === null)
+                return s;
+            const next = self.print(setAt(base, path, sv));
+            return self.match(next) === null ? s : next;
+        };
+        const keyFn = starNode.key;
+        const slotIdsOf = (items) => {
+            if (keyFn === undefined)
+                return items.map((_, i) => String(i));
+            const occ = new Map();
+            return items.map(it => {
+                const k = keyFn(String(it ?? ""));
+                const n = occ.get(k) ?? 0;
+                occ.set(k, n + 1);
+                return `${k}#${n}`;
+            });
+        };
+        const indexOfId = (items, id) => keyFn === undefined
+            ? Number(id) < items.length
+                ? Number(id)
+                : -1
+            : slotIdsOf(items).indexOf(id);
+        const segCache = new Map();
+        const idOfCell = new WeakMap();
+        const seg = (id) => {
+            let c = segCache.get(id);
+            if (c === undefined) {
+                c = Str.lens(source, (s) => {
+                    const sv = readStar(s);
+                    const idx = indexOfId(sv.items, id);
+                    return idx < 0 ? "" : String(sv.items[idx] ?? "");
+                }, (target, s) => {
+                    const sv = readStar(s);
+                    const idx = indexOfId(sv.items, id);
+                    if (idx < 0)
+                        return s;
+                    if (!fullNodeMatch(starNode.part, target))
+                        return s;
+                    const items = sv.items.slice();
+                    items[idx] = target;
+                    return writeStar(s, { items, seps: sv.seps });
+                });
+                segCache.set(id, c);
+                idOfCell.set(c, id);
+            }
+            return c;
+        };
+        const write = (sv) => {
+            source.value = writeStar(source.peek(), sv);
+        };
+        return Arr.fromSource(source, (s) => {
+            const items = readStar(s).items;
+            return slotIdsOf(items).map(seg);
+        }, {
+            insert: (v, at) => {
+                const text = v instanceof Cell ? v.value : v;
+                const sv = readStar(source.peek());
+                const items = sv.items.slice();
+                const seps = sv.seps.slice();
+                const idx = at == null || at > items.length ? items.length : Math.max(0, at);
+                items.splice(idx, 0, text);
+                if (items.length > 1)
+                    seps.splice(Math.min(idx, seps.length), 0, starNode.joiner);
+                write({ items, seps });
+                return seg(slotIdsOf(items)[idx]);
+            },
+            remove: e => {
+                const sv = readStar(source.peek());
+                const id = idOfCell.get(e);
+                const idx = id === undefined ? -1 : indexOfId(sv.items, id);
+                if (idx < 0)
+                    return;
+                const items = sv.items.slice();
+                const seps = sv.seps.slice();
+                items.splice(idx, 1);
+                if (seps.length > 0)
+                    seps.splice(Math.min(idx, seps.length - 1), 1);
+                write({ items, seps });
+            },
+            moveBefore: (e, anchor) => {
+                const sv = readStar(source.peek());
+                const fromId = idOfCell.get(e);
+                const from = fromId === undefined ? -1 : indexOfId(sv.items, fromId);
+                if (from < 0)
+                    return;
+                const items = sv.items.slice();
+                const [moved] = items.splice(from, 1);
+                const anchorId = anchor == null ? undefined : idOfCell.get(anchor);
+                const ai = anchorId === undefined ? -1 : indexOfId(sv.items, anchorId);
+                const at = ai < 0 ? items.length : ai > from ? ai - 1 : ai;
+                items.splice(at, 0, moved);
+                write({ items, seps: sv.seps });
+            },
+        });
+    }
+}
+/** Flatten nested seqs so `a.then(b).then(c)` and `seq(a,b,c)` agree (a flat
+ *  tuple of visible values), and adjacency checks see real neighbours. */
+function flattenSeq(parts) {
+    const flat = [];
+    for (const p of parts) {
+        const r = p.root;
+        if (r.kind === "seq")
+            flat.push(...r.parts);
+        else
+            flat.push(r);
+    }
+    return flat;
+}