@minnowdb/core 0.0.1 → 0.1.0

package/dist/engine/join-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-index.js","sourceRoot":"","sources":["../../src/engine/join-index.ts"],"names":[],"mappings":"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"}

package/dist/engine/live.d.ts

@@ -0,0 +1,86 @@
+import { type Manifest, type StoragePage } from "../storage/index.js";
+import { type CompiledQuery, type QueryResult } from "./query.js";
+/**
+ * Correctness-first live queries with selective re-execution. Every hint path — a local commit,
+ * a cross-tab channel message, a poll tick, or an explicit refresh — converges on the same
+ * authoritative check: read the durable manifest version, and when it moved, derive the changed
+ * tables from the persisted per-commit change sets in bounded pages. Missed hints therefore delay
+ * a refresh but can never produce a stale result, and a manifest without a change set (written
+ * before tracking, or outside a transaction) conservatively affects every subscription.
+ *
+ * Memory discipline: a subscription retains its plan text, dependency table IDs, and a numeric
+ * result digest — never result rows. Results flow to the subscriber and are dropped; unchanged
+ * digests suppress the notification entirely.
+ */
+export interface LiveQueryHintChannel {
+    postMessage(message: unknown): void;
+    addEventListener(type: "message", listener: () => void): void;
+    removeEventListener(type: "message", listener: () => void): void;
+    close?(): void;
+}
+export interface LiveQuerySetOptions {
+    readonly channel?: LiveQueryHintChannel;
+    /**
+     * Convenience form of `channel`: the set creates (and owns, closing it with the set) a
+     * BroadcastChannel of this name when the platform provides one. Ignored when `channel` is
+     * given or BroadcastChannel is unavailable.
+     */
+    readonly channelName?: string;
+    readonly pollIntervalMs?: number;
+    /** Called once when the set closes; the owner uses this to drop its reference. */
+    readonly onClosed?: () => void;
+}
+export interface LiveQuerySubscribeOptions {
+    onChange(result: QueryResult): void;
+    onError?(error: unknown): void;
+    /** Called once when the subscription ends because the subscription or its set closed. */
+    onComplete?(): void;
+}
+export interface LiveQuerySubscription {
+    readonly dependencyTableIds: readonly string[];
+    close(): void;
+}
+export interface LiveQueryStats {
+    hints: number;
+    versionChecks: number;
+    sweeps: number;
+    reruns: number;
+    rerunsAvoided: number;
+    /** Re-runs skipped because the data layer proved the commits could not change the result. */
+    zoneSkips: number;
+    notificationsSuppressed: number;
+    lastSweepMs: number;
+}
+/** A live query: SQL text or a compiled-plan envelope from the typed builder. */
+export type LiveQueryInput = string | {
+    kind: "typed-query";
+    plan: CompiledQuery;
+};
+interface LiveQueryHost {
+    currentVersion(): Promise<number | null>;
+    manifestPage(afterVersion: number | null, limit: number): Promise<StoragePage<Manifest, number>>;
+    dependencyTableIds(query: LiveQueryInput): Promise<Set<string>>;
+    execute(query: LiveQueryInput): Promise<QueryResult>;
+    /**
+     * Optional data-layer selectivity: whether commits in (after, until] to the given
+     * dependency tables can possibly change this query's result. A host answers false only
+     * on proof — e.g. every introduced segment is a data-neutral compaction rewrite, or every
+     * new insert block's zone statistics reject the query's predicates — so a false skips the
+     * re-run entirely. Errors and unknown shapes must answer true.
+     */
+    changeCanAffect?(query: LiveQueryInput, tableIds: readonly string[], after: number | null, until: number): Promise<boolean>;
+}
+export declare class LiveQuerySet {
+    #private;
+    constructor(host: LiveQueryHost, options?: LiveQuerySetOptions);
+    get stats(): LiveQueryStats;
+    /** Registers a query, delivers its initial result, and re-runs it when its tables change. */
+    subscribe(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<LiveQuerySubscription>;
+    /** Called by the owning database after each local write commit; also hints other tabs. */
+    notifyLocalCommit(): void;
+    /** Runs one authoritative version check and selective re-execution sweep. */
+    refresh(): Promise<void>;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=live.d.ts.map

package/dist/engine/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../src/engine/live.ts"],"names":[],"mappings":"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"}

package/dist/engine/live.js

@@ -0,0 +1,289 @@
+/** Companion to LiveQuerySet#stillOpen for the per-subscription flag. */
+function isSubscriptionClosed(subscription) {
+    return subscription.closed;
+}
+function digestResult(result) {
+    let hash = 0x811c9dc5;
+    const mix = (text) => {
+        for (let index = 0; index < text.length; index += 1) {
+            const code = text.charCodeAt(index);
+            hash = Math.imul(hash ^ (code & 0xff), 0x01000193) >>> 0;
+            hash = Math.imul(hash ^ (code >>> 8), 0x01000193) >>> 0;
+        }
+        hash = Math.imul(hash ^ 0xff, 0x01000193) >>> 0;
+    };
+    for (const column of result.columns)
+        mix(column);
+    for (const row of result.rows) {
+        for (const column of result.columns) {
+            const value = row[column] ?? null;
+            if (value === null)
+                mix("\0n");
+            else if (value instanceof Date)
+                mix(`\0d${String(value.getTime())}`);
+            else
+                mix(`\0${typeof value}${String(value)}`);
+        }
+        hash = Math.imul(hash ^ 0xfe, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+export class LiveQuerySet {
+    #host;
+    #channel;
+    #channelListener = () => {
+        this.#hint();
+    };
+    #subscriptions = new Set();
+    #stats = {
+        hints: 0,
+        versionChecks: 0,
+        sweeps: 0,
+        reruns: 0,
+        rerunsAvoided: 0,
+        zoneSkips: 0,
+        notificationsSuppressed: 0,
+        lastSweepMs: 0,
+    };
+    #lastSeenVersion = null;
+    #sweepChain = Promise.resolve();
+    #sweepQueued = false;
+    #pollTimer;
+    #closed = false;
+    #ownsChannel;
+    #onClosed;
+    constructor(host, options = {}) {
+        this.#host = host;
+        if (options.channel !== undefined) {
+            this.#channel = options.channel;
+            this.#ownsChannel = false;
+        }
+        else if (options.channelName !== undefined && typeof BroadcastChannel !== "undefined") {
+            this.#channel = new BroadcastChannel(options.channelName);
+            this.#ownsChannel = true;
+        }
+        else {
+            this.#channel = undefined;
+            this.#ownsChannel = false;
+        }
+        this.#onClosed = options.onClosed;
+        this.#channel?.addEventListener("message", this.#channelListener);
+        if (options.pollIntervalMs !== undefined) {
+            this.#pollTimer = setInterval(() => {
+                this.#hint();
+            }, options.pollIntervalMs);
+        }
+    }
+    get stats() {
+        return { ...this.#stats };
+    }
+    /** Registers a query, delivers its initial result, and re-runs it when its tables change. */
+    async subscribe(query, options) {
+        if (this.#closed)
+            throw new Error("Live query set is closed");
+        const dependencies = await this.#host.dependencyTableIds(query);
+        const version = await this.#host.currentVersion();
+        const subscription = {
+            query,
+            dependencies,
+            options,
+            digest: undefined,
+            seenVersion: version,
+            closed: false,
+        };
+        if (this.#lastSeenVersion === null || (version !== null && version < this.#lastSeenVersion)) {
+            this.#lastSeenVersion = version;
+        }
+        const result = await this.#host.execute(query);
+        subscription.digest = digestResult(result);
+        this.#subscriptions.add(subscription);
+        try {
+            options.onChange(result);
+        }
+        catch (error) {
+            // A throwing initial handler would leak an unclosable subscription; unregister first.
+            subscription.closed = true;
+            this.#subscriptions.delete(subscription);
+            throw error;
+        }
+        return {
+            dependencyTableIds: [...dependencies],
+            close: () => {
+                if (subscription.closed)
+                    return;
+                subscription.closed = true;
+                this.#subscriptions.delete(subscription);
+                subscription.options.onComplete?.();
+            },
+        };
+    }
+    /** Called by the owning database after each local write commit; also hints other tabs. */
+    notifyLocalCommit() {
+        this.#channel?.postMessage("minnow-commit");
+        this.#hint();
+    }
+    /** Runs one authoritative version check and selective re-execution sweep. */
+    async refresh() {
+        this.#hint();
+        await this.#sweepChain;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#channel?.removeEventListener("message", this.#channelListener);
+        if (this.#ownsChannel)
+            this.#channel?.close?.();
+        if (this.#pollTimer !== undefined)
+            clearInterval(this.#pollTimer);
+        const subscriptions = [...this.#subscriptions];
+        this.#subscriptions.clear();
+        // Wake every remaining subscriber so iterators and UI bindings end instead of hanging.
+        for (const subscription of subscriptions) {
+            if (subscription.closed)
+                continue;
+            subscription.closed = true;
+            subscription.options.onComplete?.();
+        }
+        this.#onClosed?.();
+    }
+    #hint() {
+        if (this.#closed)
+            return;
+        this.#stats.hints += 1;
+        if (this.#sweepQueued)
+            return;
+        this.#sweepQueued = true;
+        this.#sweepChain = this.#sweepChain.then(async () => {
+            this.#sweepQueued = false;
+            try {
+                await this.#sweep();
+            }
+            catch (error) {
+                for (const subscription of this.#subscriptions) {
+                    subscription.options.onError?.(error);
+                }
+            }
+        });
+    }
+    /**
+     * Re-reads the closed flags through calls. `close()` runs while a sweep is suspended at an
+     * await, but control-flow analysis assumes flags cannot change across one, so a direct read
+     * would be narrowed to its pre-await value and the guard silently dropped.
+     */
+    #stillOpen() {
+        return !this.#closed;
+    }
+    async #sweep() {
+        if (this.#closed || this.#subscriptions.size === 0)
+            return;
+        this.#stats.versionChecks += 1;
+        const current = await this.#host.currentVersion();
+        if (!this.#stillOpen() || current === null)
+            return;
+        const anyLagging = [...this.#subscriptions].some((subscription) => !subscription.closed &&
+            (subscription.seenVersion === null || subscription.seenVersion < current));
+        if (current === this.#lastSeenVersion && !anyLagging)
+            return;
+        const started = performance.now();
+        this.#stats.sweeps += 1;
+        // The changed-table window starts at the set-level version, so it only gates subscriptions
+        // that were up to date there. A lagging subscription's window starts earlier at its own
+        // seenVersion, so it re-runs unconditionally — the digest suppresses no-op notifications.
+        const changed = current === this.#lastSeenVersion
+            ? new Set()
+            : await this.#changedTablesSince(this.#lastSeenVersion, current);
+        if (!this.#stillOpen())
+            return;
+        for (const subscription of [...this.#subscriptions]) {
+            if (subscription.closed)
+                continue;
+            if (subscription.seenVersion !== null && subscription.seenVersion >= current)
+                continue;
+            if (subscription.seenVersion === this.#lastSeenVersion) {
+                const affected = changed === "all" ||
+                    [...subscription.dependencies].some((tableId) => changed.has(tableId));
+                if (!affected) {
+                    this.#stats.rerunsAvoided += 1;
+                    subscription.seenVersion = current;
+                    continue;
+                }
+                if (changed !== "all" && this.#host.changeCanAffect !== undefined) {
+                    const relevant = [...subscription.dependencies].filter((tableId) => changed.has(tableId));
+                    let canAffect;
+                    try {
+                        canAffect = await this.#host.changeCanAffect(subscription.query, relevant, this.#lastSeenVersion, current);
+                    }
+                    catch {
+                        canAffect = true;
+                    }
+                    if (!this.#stillOpen())
+                        return;
+                    if (isSubscriptionClosed(subscription))
+                        continue;
+                    if (!canAffect) {
+                        this.#stats.rerunsAvoided += 1;
+                        this.#stats.zoneSkips += 1;
+                        subscription.seenVersion = current;
+                        continue;
+                    }
+                }
+            }
+            this.#stats.reruns += 1;
+            try {
+                const result = await this.#host.execute(subscription.query);
+                // The subscription (or the set) may have closed during the execute; a late onChange
+                // after onComplete would break the subscriber contract.
+                if (!this.#stillOpen() || isSubscriptionClosed(subscription))
+                    continue;
+                subscription.seenVersion = current;
+                const digest = digestResult(result);
+                if (digest === subscription.digest) {
+                    this.#stats.notificationsSuppressed += 1;
+                    continue;
+                }
+                subscription.digest = digest;
+                subscription.options.onChange(result);
+            }
+            catch (error) {
+                if (!this.#stillOpen() || isSubscriptionClosed(subscription))
+                    continue;
+                subscription.seenVersion = current;
+                subscription.options.onError?.(error);
+            }
+        }
+        this.#lastSeenVersion = current;
+        this.#stats.lastSweepMs = performance.now() - started;
+    }
+    /**
+     * Unions the persisted change sets of every manifest in (after, until], reading bounded pages.
+     * A missing manifest version or a manifest without a change set widens to "all" — correctness
+     * over selectivity.
+     */
+    async #changedTablesSince(after, until) {
+        const changed = new Set();
+        let cursor = after;
+        let expected = (after ?? -1) + 1;
+        for (;;) {
+            const page = await this.#host.manifestPage(cursor, 64);
+            for (const manifest of page.records) {
+                if (manifest.version > until)
+                    return changed;
+                if (manifest.version !== expected)
+                    return "all";
+                expected += 1;
+                if (manifest.changedTableIds === undefined)
+                    return "all";
+                for (const tableId of manifest.changedTableIds)
+                    changed.add(tableId);
+                if (manifest.version === until)
+                    return changed;
+            }
+            if (page.nextCursor === null) {
+                return expected > until ? changed : "all";
+            }
+            cursor = page.nextCursor;
+        }
+    }
+}
+//# sourceMappingURL=live.js.map

package/dist/engine/live.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.js","sourceRoot":"","sources":["../../src/engine/live.ts"],"names":[],"mappings":"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"}

package/dist/engine/memory.d.ts

@@ -0,0 +1,37 @@
+export interface QueryMemoryUsage {
+    readonly budgetBytes: number;
+    readonly usedBytes: number;
+    readonly peakBytes: number;
+}
+export declare class QueryMemoryBudgetError extends Error {
+    readonly label: string;
+    readonly requestedBytes: number;
+    readonly usedBytes: number;
+    readonly budgetBytes: number;
+    readonly name = "QueryMemoryBudgetError";
+    constructor(label: string, requestedBytes: number, usedBytes: number, budgetBytes: number);
+}
+export declare class QueryMemoryContext {
+    #private;
+    constructor(budgetBytes?: number, parent?: QueryMemoryContext);
+    get usage(): QueryMemoryUsage;
+    createChild(): QueryMemoryContext;
+    reserve(bytes: number, label: string): QueryMemoryReservation;
+    /**
+     * Reserves bytes that live until this context closes, without a per-call reservation object.
+     * The hot accumulation paths (result rows, spill pages) reserve once per row; tracking each
+     * row as a retained `QueryMemoryReservation` in a Set costs O(result rows) live objects on
+     * top of the rows themselves. Tallied bytes share the same budget and error semantics as
+     * `reserve` and are released together when the context closes.
+     */
+    tally(bytes: number, label: string): void;
+    close(): void;
+    release(reservation: QueryMemoryReservation, bytes: number): void;
+}
+export declare class QueryMemoryReservation {
+    #private;
+    readonly bytes: number;
+    constructor(context: QueryMemoryContext, bytes: number);
+    release(): void;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/engine/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/engine/memory.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAI7C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAN9B,SAAkB,IAAI,4BAA4B;gBAGvC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM/B;AAQD,qBAAa,kBAAkB;;gBAQjB,WAAW,GAAE,MAAgC,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAYtF,IAAI,KAAK,IAAI,gBAAgB,CAE5B;IAED,WAAW,IAAI,kBAAkB;IAKjC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,sBAAsB;IAmB7D;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAiBzC,KAAK,IAAI,IAAI;IAWb,OAAO,CAAC,WAAW,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CASlE;AAED,qBAAa,sBAAsB;;IAEjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAGX,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM;IAKtD,OAAO,IAAI,IAAI;CAKhB"}

package/dist/engine/memory.js

@@ -0,0 +1,119 @@
+export class QueryMemoryBudgetError extends Error {
+    label;
+    requestedBytes;
+    usedBytes;
+    budgetBytes;
+    name = "QueryMemoryBudgetError";
+    constructor(label, requestedBytes, usedBytes, budgetBytes) {
+        super(`${label} requested ${String(requestedBytes)} accounted bytes with ${String(usedBytes)} of ${String(budgetBytes)} bytes already reserved`);
+        this.label = label;
+        this.requestedBytes = requestedBytes;
+        this.usedBytes = usedBytes;
+        this.budgetBytes = budgetBytes;
+    }
+}
+export class QueryMemoryContext {
+    #state;
+    #parent;
+    #children = new Set();
+    #reservations = new Set();
+    #talliedBytes = 0;
+    #closed = false;
+    constructor(budgetBytes = Number.MAX_SAFE_INTEGER, parent) {
+        if (!Number.isSafeInteger(budgetBytes) || budgetBytes < 0) {
+            throw new RangeError("Query memory budget must be a non-negative safe integer");
+        }
+        this.#parent = parent;
+        if (parent === undefined)
+            this.#state = { budgetBytes, usedBytes: 0, peakBytes: 0 };
+        else {
+            this.#state = parent.#state;
+            parent.#children.add(this);
+        }
+    }
+    get usage() {
+        return { ...this.#state };
+    }
+    createChild() {
+        this.#assertOpen();
+        return new QueryMemoryContext(this.#state.budgetBytes, this);
+    }
+    reserve(bytes, label) {
+        this.#assertOpen();
+        validateMemoryBytes(bytes, "Query memory reservation");
+        const nextUsed = this.#state.usedBytes + bytes;
+        if (!Number.isSafeInteger(nextUsed) || nextUsed > this.#state.budgetBytes) {
+            throw new QueryMemoryBudgetError(label, bytes, this.#state.usedBytes, this.#state.budgetBytes);
+        }
+        this.#state.usedBytes = nextUsed;
+        this.#state.peakBytes = Math.max(this.#state.peakBytes, nextUsed);
+        const reservation = new QueryMemoryReservation(this, bytes);
+        this.#reservations.add(reservation);
+        return reservation;
+    }
+    /**
+     * Reserves bytes that live until this context closes, without a per-call reservation object.
+     * The hot accumulation paths (result rows, spill pages) reserve once per row; tracking each
+     * row as a retained `QueryMemoryReservation` in a Set costs O(result rows) live objects on
+     * top of the rows themselves. Tallied bytes share the same budget and error semantics as
+     * `reserve` and are released together when the context closes.
+     */
+    tally(bytes, label) {
+        this.#assertOpen();
+        validateMemoryBytes(bytes, "Query memory reservation");
+        const nextUsed = this.#state.usedBytes + bytes;
+        if (!Number.isSafeInteger(nextUsed) || nextUsed > this.#state.budgetBytes) {
+            throw new QueryMemoryBudgetError(label, bytes, this.#state.usedBytes, this.#state.budgetBytes);
+        }
+        this.#state.usedBytes = nextUsed;
+        this.#state.peakBytes = Math.max(this.#state.peakBytes, nextUsed);
+        this.#talliedBytes += bytes;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const child of [...this.#children])
+            child.close();
+        for (const reservation of [...this.#reservations])
+            reservation.release();
+        this.#state.usedBytes -= this.#talliedBytes;
+        this.#talliedBytes = 0;
+        if (this.#state.usedBytes < 0)
+            throw new Error("Query memory accounting underflow");
+        if (this.#parent !== undefined)
+            this.#parent.#children.delete(this);
+    }
+    release(reservation, bytes) {
+        if (!this.#reservations.delete(reservation))
+            return;
+        this.#state.usedBytes -= bytes;
+        if (this.#state.usedBytes < 0)
+            throw new Error("Query memory accounting underflow");
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error("Query memory context is closed");
+    }
+}
+export class QueryMemoryReservation {
+    #context;
+    bytes;
+    #released = false;
+    constructor(context, bytes) {
+        this.#context = context;
+        this.bytes = bytes;
+    }
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        this.#context.release(this, this.bytes);
+    }
+}
+function validateMemoryBytes(bytes, label) {
+    if (!Number.isSafeInteger(bytes) || bytes < 0) {
+        throw new RangeError(`${label} must be a non-negative safe integer`);
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/engine/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/engine/memory.ts"],"names":[],"mappings":"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"}

package/dist/engine/optimizer.d.ts

@@ -0,0 +1,20 @@
+import { type CompiledQuery } from "./query.js";
+/**
+ * Deterministic plan-to-plan rewrites over the shared compiled representation. Every rule
+ * preserves result semantics exactly; rules that cannot prove safety leave the plan unchanged.
+ * The optimizer runs before subquery resolution, so subquery blocks optimize recursively and
+ * predicates containing subqueries stay self-contained when they move.
+ */
+export declare function optimizePlan(plan: CompiledQuery): CompiledQuery;
+/**
+ * Cost-based build-side selection using prepared or catalog-derived row counts. A single inner
+ * equi-join probes from the base into an index over the joined table, so a joined input more than
+ * twice the base size swaps sides and builds over the smaller input. Asymmetric and observable
+ * source-order shapes stay unchanged.
+ */
+export declare function chooseJoinOrder(plan: CompiledQuery, inputs: ReadonlyMap<string, {
+    readonly rowCount: number;
+}>): CompiledQuery;
+/** Renders a stable, human-readable plan for snapshot tests and explain(). */
+export declare function renderPlan(plan: CompiledQuery): string;
+//# sourceMappingURL=optimizer.d.ts.map

package/dist/engine/optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/engine/optimizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,aAAa,EAMnB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAI/D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GACzD,aAAa,CAoBf;AAqkCD,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAItD"}