@elaraai/east 0.0.1-beta.9 → 1.0.0

package/dist/src/location.js

@@ -1,12 +1,12 @@
 /**
- * Formats a location as a human-readable string.
+ * Formats a single location as a human-readable string.
  *
  * @param location - The source location to format
  * @returns A string in the format `"<filename> <line>:<column>"`
  *
  * @example
  * ```ts
- * const loc = { filename: "main.ts", line: 42, column: 15 };
+ * const loc = { filename: "main.ts", line: 42n, column: 15n };
  * printLocation(loc); // "main.ts 42:15"
  * ```
  */
@@ -14,49 +14,246 @@ export function printLocation(location) {
     return `${location.filename} ${location.line}:${location.column}`;
 }
 /**
- * Captures the source location of the calling code using stack trace inspection.
+ * Formats an array of locations as a stack trace string.
  *
- * @param skip - Number of stack frames to skip (default = 1 returns the caller's location)
- * @returns A {@link Location} object representing the source position
+ * @param locations - The source locations to format
+ * @returns A stack trace string with each location on a new line
+ *
+ * @example
+ * ```ts
+ * const locs = [
+ *   { filename: "main.ts", line: 42n, column: 15n },
+ *   { filename: "lib.ts", line: 10n, column: 5n }
+ * ];
+ * printLocations(locs);
+ * // "main.ts 42:15
+ * //   at lib.ts 10:5"
+ * ```
+ */
+export function printLocations(locations) {
+    if (locations.length === 0)
+        return '<unknown>';
+    const [first, ...rest] = locations;
+    const header = printLocation(first);
+    if (rest.length === 0)
+        return header;
+    return header + '\n' + rest.map(loc => `  at ${printLocation(loc)}`).join('\n');
+}
+/**
+ * Determines if a stack frame should be included in location captures.
+ * Filters out internal frames (Node.js internals, node_modules) to show
+ * only user code in error stack traces.
+ *
+ * @param filename - The file path from the stack frame
+ * @returns true if the frame should be included, false to filter it out
+ */
+function shouldIncludeFrame(filename) {
+    // Skip Node.js internal modules (e.g., node:internal/modules/...)
+    if (filename.startsWith('node:'))
+        return false;
+    // Skip node_modules - filters out third-party packages including East
+    // when installed as a dependency. Handles both Unix and Windows paths.
+    if (filename.includes('/node_modules/') || filename.includes('\\node_modules\\'))
+        return false;
+    return true;
+}
+/**
+ * Captures the call stack as an array of source locations, filtered to
+ * show only user code.
+ *
+ * @returns An array of {@link Location} objects representing the call stack,
+ *          from innermost (most recent) to outermost frame
  *
  * @remarks
- * This function uses JavaScript's Error stack traces to determine the caller's
- * source location. Returns `{ filename: "<unknown>", line: 0, column: 0 }` if
- * the stack trace cannot be parsed.
+ * This function uses JavaScript's Error stack traces to capture the call
+ * stack. Internal frames (Node.js internals, node_modules packages) are
+ * filtered out to provide clean stack traces showing only user code.
+ * Returns an empty array if the stack trace cannot be parsed.
  *
  * @example
  * ```ts
  * function myFunction() {
- *   const loc = get_location(); // Gets location of this call
- *   console.log(printLocation(loc));
+ *   const stack = get_location(); // Gets call stack of user code
+ *   console.log(printLocations(stack));
  * }
  * ```
  */
-export function get_location(skip = 1) {
-    // Create an Error object to capture the stack trace
+// ── Frame path normalization ───────────────────────────────────────────
+//
+// Stack-trace paths are absolute and environment-specific (and `file://` URLs
+// under ESM). Baking them into serialized IR leaks the author's filesystem
+// layout and makes the IR non-reproducible across machines and build modes. We
+// normalize each frame path to a portable form: strip the `file://` scheme,
+// normalize separators, and relativize to a base directory. The base defaults
+// to the working directory when one is available (Node) and can be set with
+// `setLocationBasePath` (e.g. for deterministic fixtures). Browser / no-cwd
+// environments keep the cleaned path. This stays free of `node:` imports
+// (browser-safe) and never throws.
+let explicitBaseSet = false;
+let explicitBase;
+let autoBase;
+let autoBaseComputed = false;
+function normalizeSeparators(p) {
+    return p.replace(/\\/g, '/');
+}
+function stripTrailingSlash(p) {
+    return p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p;
+}
+function stripFileUrl(p) {
+    if (!p.startsWith('file://'))
+        return p;
+    try {
+        // `URL` is a universal (WHATWG) global — present in Node and browsers, no
+        // `node:url` import. `.pathname` is percent-encoded; decode it.
+        const pathname = decodeURIComponent(new URL(p).pathname);
+        return pathname.replace(/^\/([A-Za-z]:)/, '$1'); // Windows: "/C:/x" → "C:/x"
+    }
+    catch {
+        return p;
+    }
+}
+function computeAutoBase() {
+    if (!autoBaseComputed) {
+        autoBaseComputed = true;
+        // Guarded global access (not a `node:` import) — `process` is undefined in
+        // the browser, where we simply skip relativization.
+        const proc = globalThis.process;
+        if (proc !== undefined && typeof proc.cwd === 'function') {
+            try {
+                autoBase = stripTrailingSlash(normalizeSeparators(String(proc.cwd())));
+            }
+            catch {
+                autoBase = undefined;
+            }
+        }
+    }
+    return autoBase;
+}
+function currentBase() {
+    return explicitBaseSet ? explicitBase : computeAutoBase();
+}
+/**
+ * Set the base directory that captured locations are relativized against.
+ * Pass a path to relativize against it (paths outside it stay absolute); pass
+ * `undefined` to reset to the automatic default (the working directory in
+ * Node, none in the browser).
+ */
+export function setLocationBasePath(base) {
+    if (base === undefined) {
+        explicitBaseSet = false;
+        explicitBase = undefined;
+    }
+    else {
+        explicitBaseSet = true;
+        explicitBase = stripTrailingSlash(normalizeSeparators(stripFileUrl(base)));
+    }
+}
+/**
+ * Normalize a stack-frame path to a portable, deterministic form: `file://`
+ * stripped, separators as `/`, and relativized to the current base when the
+ * path is under it. Exported for testing. Never throws.
+ */
+export function normalizeFramePath(raw) {
+    try {
+        const cleaned = normalizeSeparators(stripFileUrl(raw));
+        const base = currentBase();
+        if (base !== undefined && base !== '') {
+            if (cleaned === base)
+                return '.';
+            if (cleaned.startsWith(base + '/'))
+                return cleaned.slice(base.length + 1);
+        }
+        return cleaned;
+    }
+    catch {
+        return raw;
+    }
+}
+function capture_stack_frames() {
     const err = new Error();
-    // Parse the stack trace
     const stack = err.stack;
-    if (!stack) {
-        return { filename: "<unknown>", line: 0, column: 0 };
-    }
-    // Split into lines and remove the 'Error' line and this function's line
-    const lines = stack.split('\n').slice(skip + 1);
-    // Find the first meaningful stack frame
+    if (!stack)
+        return [];
+    const lines = stack.split('\n').slice(1); // Skip "Error" line
+    const frames = [];
     for (const line of lines) {
-        // First match the whole path with line and column
-        const match = line.match(/at\s[<>a-zA-Z0-9_$]*\s+(?:(?:\w+\.)*\w+\s+)?\(?(.*?):(\d+):(\d+)\)?$/);
+        // Simple regex that matches file:line:col at end of line
+        const match = line.match(/\(?([^()\s]+):(\d+):(\d+)\)?$/);
         if (match) {
-            const [, fullPath, line, column] = match;
-            // Skip if it's an anonymous internal file
-            if (fullPath == undefined || fullPath === '') {
-                continue;
+            const [, filename, lineNum, column] = match;
+            // `shouldIncludeFrame` runs on the raw path so its node_modules/internal
+            // filters see absolute paths; the stored path is normalized.
+            if (filename && filename !== '' && shouldIncludeFrame(filename)) {
+                frames.push({ filename: normalizeFramePath(filename), line: BigInt(lineNum), column: BigInt(column) });
             }
-            // TODO should we extract a subset of the fullPath?
-            // Return filename with line and column
-            return { filename: fullPath, line: Number(line), column: Number(column) };
         }
     }
-    return { filename: "<unknown>", line: 0, column: 0 };
+    return frames;
+}
+export function get_location() {
+    return capture_stack_frames();
+}
+// ── SourceMap ──────────────────────────────────────────────────────────
+/** Reserved sentinel: resolve(0n) returns [], the "no/unknown location" id. */
+export const UNKNOWN_LOC_ID = 0n;
+export class SourceMap {
+    /** Location stacks, indexed by Number(loc_id). stacks[0] is always []. */
+    stacks = [[]];
+    /** Content key → loc_id for dedup during construction. */
+    intern = new Map();
+    /** Intern a location stack. Returns a stable loc_id (bigint).
+     *  Equal content returns the same id. Empty stack → UNKNOWN_LOC_ID. */
+    intern_stack(stack) {
+        if (stack.length === 0)
+            return UNKNOWN_LOC_ID;
+        const key = stack.map(l => `${l.filename}|${l.line}|${l.column}`).join('\n');
+        const existing = this.intern.get(key);
+        if (existing !== undefined)
+            return existing;
+        const id = BigInt(this.stacks.length);
+        this.stacks.push(stack);
+        this.intern.set(key, id);
+        return id;
+    }
+    /** Resolve a loc_id to its stack. Returns [] for UNKNOWN_LOC_ID or out-of-range. */
+    resolve(loc_id) {
+        return this.stacks[Number(loc_id)] ?? [];
+    }
+    /** Total number of entries, including the reserved empty entry at index 0. */
+    get size() { return BigInt(this.stacks.length); }
+    /** All entries in loc_id order (for serialization). Entry 0 is always []. */
+    entries() { return this.stacks; }
+}
+// ── Scoped context ─────────────────────────────────────────────────────
+let _currentMap = null;
+/** Run `fn` with `map` as the current scope's source map. Re-entrant safe. */
+export function with_source_map(map, fn) {
+    const prev = _currentMap;
+    _currentMap = map;
+    try {
+        return fn();
+    }
+    finally {
+        _currentMap = prev;
+    }
+}
+/** Wraps `fn` in a new `with_source_map` only if no map is currently active.
+ *  Nested calls inherit the existing map. */
+export function ensure_source_map(fn) {
+    if (_currentMap)
+        return fn();
+    return with_source_map(new SourceMap(), fn);
+}
+/** Returns the current SourceMap, or null if outside any with_source_map scope. */
+export function get_current_source_map() {
+    return _currentMap;
+}
+/** Capture current stack and intern into the active SourceMap.
+ *  Returns UNKNOWN_LOC_ID (0n) if no map is active. */
+export function get_location_id() {
+    if (!_currentMap)
+        return UNKNOWN_LOC_ID;
+    const stack = capture_stack_frames();
+    return _currentMap.intern_stack(stack);
 }
 //# sourceMappingURL=location.js.map

package/dist/src/location.js.map

@@ -1 +1 @@
-{"version":3,"file":"location.js","sourceRoot":"","sources":["../../src/location.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,OAAO,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,CAAC;IAC3C,oDAAoD;IACpD,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;IAExB,wBAAwB;IACxB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACvD,CAAC;IAED,wEAAwE;IACxE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAEhD,wCAAwC;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,kDAAkD;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,sEAAsE,CAAC,CAAC;QACjG,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;YAEzC,0CAA0C;YAC1C,IAAI,QAAQ,IAAI,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;gBAC7C,SAAS;YACX,CAAC;YAED,mDAAmD;YAEnD,uCAAuC;YACvC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AACvD,CAAC"}
+{"version":3,"file":"location.js","sourceRoot":"","sources":["../../src/location.ts"],"names":[],"mappings":"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"}

package/dist/src/location.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=location.spec.d.ts.map

package/dist/src/location.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.spec.d.ts","sourceRoot":"","sources":["../../src/location.spec.ts"],"names":[],"mappings":""}

package/dist/src/location.spec.js

@@ -0,0 +1,102 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import assert from "node:assert/strict";
+import { afterEach, describe, test } from "node:test";
+import { normalizeFramePath, setLocationBasePath } from "./location.js";
+describe("normalizeFramePath", () => {
+    // Reset to the automatic (cwd) base after every test so cases don't leak.
+    afterEach(() => setLocationBasePath(undefined));
+    describe("file:// scheme stripping", () => {
+        test("strips a Unix file:// URL and relativizes to the base", () => {
+            setLocationBasePath("/home/u/proj");
+            assert.equal(normalizeFramePath("file:///home/u/proj/dist/src/foo.js"), "dist/src/foo.js");
+        });
+        test("strips a Windows file:// URL (drops the leading slash before the drive)", () => {
+            setLocationBasePath("C:/Users/x/proj");
+            assert.equal(normalizeFramePath("file:///C:/Users/x/proj/src/foo.ts"), "src/foo.ts");
+        });
+        test("decodes percent-encoding (e.g. spaces) in file:// URLs", () => {
+            setLocationBasePath("/home/u/my proj");
+            assert.equal(normalizeFramePath("file:///home/u/my%20proj/src/foo.ts"), "src/foo.ts");
+        });
+        test("a file:// URL outside the base is returned cleaned but absolute", () => {
+            setLocationBasePath("/home/u/proj");
+            assert.equal(normalizeFramePath("file:///opt/other/foo.ts"), "/opt/other/foo.ts");
+        });
+    });
+    describe("plain paths", () => {
+        test("relativizes a plain Unix absolute path under the base", () => {
+            setLocationBasePath("/home/u/proj");
+            assert.equal(normalizeFramePath("/home/u/proj/src/a/b/foo.ts"), "src/a/b/foo.ts");
+        });
+        test("normalizes Windows backslashes and relativizes", () => {
+            setLocationBasePath("C:\\Users\\x\\proj");
+            assert.equal(normalizeFramePath("C:\\Users\\x\\proj\\dist\\foo.js"), "dist/foo.js");
+        });
+        test("a path not under the base is returned unchanged (cleaned)", () => {
+            setLocationBasePath("/home/u/proj");
+            assert.equal(normalizeFramePath("/somewhere/else/foo.ts"), "/somewhere/else/foo.ts");
+        });
+    });
+    describe("base-boundary correctness", () => {
+        test("a sibling dir sharing a prefix is NOT falsely relativized", () => {
+            setLocationBasePath("/a/proj");
+            // "/a/proj-extra/..." must not be treated as inside "/a/proj"
+            assert.equal(normalizeFramePath("/a/proj-extra/foo.ts"), "/a/proj-extra/foo.ts");
+        });
+        test("a trailing slash on the base is handled", () => {
+            setLocationBasePath("/a/proj/");
+            assert.equal(normalizeFramePath("/a/proj/foo.ts"), "foo.ts");
+        });
+        test("a path equal to the base resolves to '.'", () => {
+            setLocationBasePath("/a/proj");
+            assert.equal(normalizeFramePath("/a/proj"), ".");
+        });
+        test("setLocationBasePath accepts a file:// base", () => {
+            setLocationBasePath("file:///home/u/proj");
+            assert.equal(normalizeFramePath("file:///home/u/proj/src/foo.ts"), "src/foo.ts");
+        });
+    });
+    describe("non-file environments", () => {
+        test("a browser http(s) URL is left as-is", () => {
+            setLocationBasePath("/home/u/proj");
+            assert.equal(normalizeFramePath("https://example.com/app/foo.js"), "https://example.com/app/foo.js");
+        });
+    });
+    describe("automatic base (process.cwd) and reset", () => {
+        test("relativizes paths under the working directory when no base is set", () => {
+            setLocationBasePath(undefined); // auto → process.cwd()
+            const cwd = process.cwd().replace(/\\/g, "/");
+            assert.equal(normalizeFramePath(`${cwd}/dist/src/foo.js`), "dist/src/foo.js");
+        });
+        test("leaves paths outside the working directory absolute", () => {
+            setLocationBasePath(undefined);
+            assert.equal(normalizeFramePath("/definitely/not/under/cwd/foo.ts"), "/definitely/not/under/cwd/foo.ts");
+        });
+        test("an explicit base overrides the automatic one, and undefined resets it", () => {
+            setLocationBasePath("/explicit/root");
+            assert.equal(normalizeFramePath("/explicit/root/x.ts"), "x.ts");
+            setLocationBasePath(undefined);
+            // back to cwd-relative: an /explicit/root path is now (almost certainly) absolute
+            assert.equal(normalizeFramePath("/explicit/root/x.ts"), "/explicit/root/x.ts");
+        });
+    });
+    describe("robustness — never throws, returns sensible output", () => {
+        test("empty string", () => {
+            setLocationBasePath("/a/proj");
+            assert.equal(normalizeFramePath(""), "");
+        });
+        test("garbage with no path structure", () => {
+            setLocationBasePath("/a/proj");
+            assert.equal(normalizeFramePath("<anonymous>"), "<anonymous>");
+        });
+        test("malformed file:// URL is returned without throwing", () => {
+            setLocationBasePath(undefined);
+            const out = normalizeFramePath("file://");
+            assert.equal(typeof out, "string");
+        });
+    });
+});
+//# sourceMappingURL=location.spec.js.map

package/dist/src/location.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.spec.js","sourceRoot":"","sources":["../../src/location.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAExE,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,0EAA0E;IAC1E,SAAS,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhD,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACxC,IAAI,CAAC,uDAAuD,EAAE,GAAG,EAAE;YACjE,mBAAmB,CAAC,cAAc,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,qCAAqC,CAAC,EAAE,iBAAiB,CAAC,CAAC;QAC7F,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,yEAAyE,EAAE,GAAG,EAAE;YACnF,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;YACvC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,oCAAoC,CAAC,EAAE,YAAY,CAAC,CAAC;QACvF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;YAClE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;YACvC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,qCAAqC,CAAC,EAAE,YAAY,CAAC,CAAC;QACxF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,iEAAiE,EAAE,GAAG,EAAE;YAC3E,mBAAmB,CAAC,cAAc,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,0BAA0B,CAAC,EAAE,mBAAmB,CAAC,CAAC;QACpF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC3B,IAAI,CAAC,uDAAuD,EAAE,GAAG,EAAE;YACjE,mBAAmB,CAAC,cAAc,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,6BAA6B,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACpF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;YAC1D,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;YAC1C,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,kCAAkC,CAAC,EAAE,aAAa,CAAC,CAAC;QACtF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,2DAA2D,EAAE,GAAG,EAAE;YACrE,mBAAmB,CAAC,cAAc,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,wBAAwB,CAAC,EAAE,wBAAwB,CAAC,CAAC;QACvF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACzC,IAAI,CAAC,2DAA2D,EAAE,GAAG,EAAE;YACrE,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,8DAA8D;YAC9D,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC,CAAC;QACnF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,yCAAyC,EAAE,GAAG,EAAE;YACnD,mBAAmB,CAAC,UAAU,CAAC,CAAC;YAChC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,0CAA0C,EAAE,GAAG,EAAE;YACpD,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;YACtD,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;YAC3C,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,gCAAgC,CAAC,EAAE,YAAY,CAAC,CAAC;QACnF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;QACrC,IAAI,CAAC,qCAAqC,EAAE,GAAG,EAAE;YAC/C,mBAAmB,CAAC,cAAc,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,gCAAgC,CAAC,EAAE,gCAAgC,CAAC,CAAC;QACvG,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,wCAAwC,EAAE,GAAG,EAAE;QACtD,IAAI,CAAC,mEAAmE,EAAE,GAAG,EAAE;YAC7E,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,uBAAuB;YACvD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC9C,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,GAAG,kBAAkB,CAAC,EAAE,iBAAiB,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;YAC/D,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,kCAAkC,CAAC,EAAE,kCAAkC,CAAC,CAAC;QAC3G,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,uEAAuE,EAAE,GAAG,EAAE;YACjF,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;YACtC,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC,CAAC;YAChE,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,kFAAkF;YAClF,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC,CAAC;QACjF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAClE,IAAI,CAAC,cAAc,EAAE,GAAG,EAAE;YACxB,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,gCAAgC,EAAE,GAAG,EAAE;YAC1C,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC;QACjE,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;YAC9D,mBAAmB,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,GAAG,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;YAC1C,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/patch/apply.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * applyFor - Apply a patch to an East value.
+ *
+ * @module
+ */
+import { type EastTypeValue } from "../type_of_type.js";
+import type { EastType, ValueTypeOf } from "../types.js";
+import { type ApplyContext } from "./types.js";
+export declare function applyFor(type: EastTypeValue, ctx?: ApplyContext): (base: any, patch: any) => any;
+export declare function applyFor<T extends EastType>(type: T): (base: ValueTypeOf<T>, patch: any) => ValueTypeOf<T>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/src/patch/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/patch/apply.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAOzD,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,YAAY,CAAC;AAE9D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;AAClG,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC"}