@minnowdb/core 0.0.1 → 0.1.1

package/dist/engine/join-index.js

@@ -0,0 +1,217 @@
+import { copyScratchKey, encodeSingleScalarKey, equalsScratch, hashScratch, } from "./group-index.js";
+const INITIAL_ENTRY_CAPACITY = 4;
+const INITIAL_BUCKET_CAPACITY = 8;
+const INITIAL_KEY_CAPACITY = 32;
+const ENTRY_FIELDS = 6;
+const UINT32_BYTES = Uint32Array.BYTES_PER_ELEMENT;
+/** Collision-checked scalar-key hash index with typed duplicate row chains. */
+export class ByteJoinIndex {
+    #memory;
+    #rowNext;
+    #buckets = new Int32Array(0);
+    #hashes = new Uint32Array(0);
+    #offsets = new Uint32Array(0);
+    #lengths = new Uint32Array(0);
+    #bucketNext = new Int32Array(0);
+    #rowHeads = new Int32Array(0);
+    #rowTails = new Int32Array(0);
+    #keys = new Uint8Array(0);
+    #keyLength = 0;
+    #entryCount = 0;
+    #unique = true;
+    #entryReservation;
+    #bucketReservation;
+    #keyReservation;
+    constructor(memory, rowCapacity) {
+        if (!Number.isSafeInteger(rowCapacity) || rowCapacity < 0) {
+            throw new RangeError("Join index row capacity must be a non-negative safe integer");
+        }
+        this.#memory = memory;
+        memory.reserve(safeProduct(rowCapacity, Int32Array.BYTES_PER_ELEMENT, "Join duplicate row chains"), "Join duplicate row chains");
+        this.#rowNext = new Int32Array(rowCapacity);
+        this.#rowNext.fill(-1);
+    }
+    get unique() {
+        return this.#unique;
+    }
+    add(value, row) {
+        if (!Number.isSafeInteger(row) || row < 0 || row >= this.#rowNext.length) {
+            throw new RangeError("Join index row is outside its declared capacity");
+        }
+        const length = encodeJoinKey(value);
+        if (length < 0)
+            return;
+        const hash = hashScratch(length);
+        const existing = this.#find(length, hash);
+        if (existing >= 0) {
+            const tail = this.#rowTails[existing] ?? -1;
+            if (tail < 0)
+                throw new Error("Join index row chain is corrupt");
+            this.#rowNext[tail] = row;
+            this.#rowTails[existing] = row;
+            this.#unique = false;
+            return;
+        }
+        const encoded = copyScratchKey(length);
+        const index = this.#entryCount;
+        this.#ensureEntryCapacity(index + 1);
+        this.#ensureBucketCapacity(index + 1);
+        this.#ensureKeyCapacity(encoded.byteLength);
+        const offset = this.#keyLength;
+        this.#keys.set(encoded, offset);
+        this.#keyLength += encoded.byteLength;
+        this.#hashes[index] = hash;
+        this.#offsets[index] = offset;
+        this.#lengths[index] = encoded.byteLength;
+        this.#rowHeads[index] = row;
+        this.#rowTails[index] = row;
+        const bucket = hash & (this.#buckets.length - 1);
+        this.#bucketNext[index] = this.#buckets[bucket] ?? -1;
+        this.#buckets[bucket] = index;
+        this.#entryCount += 1;
+    }
+    firstRow(value) {
+        const length = encodeJoinKey(value);
+        if (length < 0)
+            return -1;
+        const index = this.#find(length, hashScratch(length));
+        return index < 0 ? -1 : (this.#rowHeads[index] ?? -1);
+    }
+    nextRow(row) {
+        return row < 0 || row >= this.#rowNext.length ? -1 : (this.#rowNext[row] ?? -1);
+    }
+    /** Matches the scratch arena's first `length` bytes against stored keys without copying them. */
+    #find(length, hash) {
+        if (this.#buckets.length === 0)
+            return -1;
+        let index = this.#buckets[hash & (this.#buckets.length - 1)] ?? -1;
+        while (index >= 0) {
+            if (this.#hashes[index] === hash &&
+                this.#lengths[index] === length &&
+                equalsScratch(this.#keys, this.#offsets[index] ?? 0, length)) {
+                return index;
+            }
+            index = this.#bucketNext[index] ?? -1;
+        }
+        return -1;
+    }
+    #ensureEntryCapacity(required) {
+        if (required <= this.#hashes.length)
+            return;
+        let capacity = Math.max(INITIAL_ENTRY_CAPACITY, this.#hashes.length * 2);
+        while (capacity < required)
+            capacity = safeDouble(capacity, "Join index entries");
+        const reservation = this.#memory.reserve(safeProduct(capacity, ENTRY_FIELDS * UINT32_BYTES, "Join index entry storage"), "Join index entry storage");
+        try {
+            const hashes = new Uint32Array(capacity);
+            const offsets = new Uint32Array(capacity);
+            const lengths = new Uint32Array(capacity);
+            const bucketNext = new Int32Array(capacity);
+            const rowHeads = new Int32Array(capacity);
+            const rowTails = new Int32Array(capacity);
+            bucketNext.fill(-1);
+            rowHeads.fill(-1);
+            rowTails.fill(-1);
+            hashes.set(this.#hashes);
+            offsets.set(this.#offsets);
+            lengths.set(this.#lengths);
+            bucketNext.set(this.#bucketNext);
+            rowHeads.set(this.#rowHeads);
+            rowTails.set(this.#rowTails);
+            this.#hashes = hashes;
+            this.#offsets = offsets;
+            this.#lengths = lengths;
+            this.#bucketNext = bucketNext;
+            this.#rowHeads = rowHeads;
+            this.#rowTails = rowTails;
+            this.#entryReservation?.release();
+            this.#entryReservation = reservation;
+        }
+        catch (error) {
+            reservation.release();
+            throw error;
+        }
+    }
+    #ensureBucketCapacity(requiredEntries) {
+        let capacity = this.#buckets.length;
+        if (capacity === 0)
+            capacity = INITIAL_BUCKET_CAPACITY;
+        while (requiredEntries * 4 > capacity * 3) {
+            capacity = safeDouble(capacity, "Join index buckets");
+        }
+        if (capacity === this.#buckets.length)
+            return;
+        const reservation = this.#memory.reserve(safeProduct(capacity, Int32Array.BYTES_PER_ELEMENT, "Join index bucket storage"), "Join index bucket storage");
+        try {
+            const buckets = new Int32Array(capacity);
+            buckets.fill(-1);
+            for (let index = 0; index < this.#entryCount; index += 1) {
+                const bucket = (this.#hashes[index] ?? 0) & (capacity - 1);
+                this.#bucketNext[index] = buckets[bucket] ?? -1;
+                buckets[bucket] = index;
+            }
+            this.#buckets = buckets;
+            this.#bucketReservation?.release();
+            this.#bucketReservation = reservation;
+        }
+        catch (error) {
+            reservation.release();
+            throw error;
+        }
+    }
+    #ensureKeyCapacity(additionalBytes) {
+        const required = this.#keyLength + additionalBytes;
+        if (!Number.isSafeInteger(required))
+            throw new RangeError("Join key arena is too large");
+        if (required > 0xffff_ffff)
+            throw new RangeError("Join key arena exceeds uint32 offsets");
+        if (required <= this.#keys.byteLength)
+            return;
+        let capacity = Math.max(INITIAL_KEY_CAPACITY, this.#keys.byteLength * 2);
+        while (capacity < required)
+            capacity = safeDouble(capacity, "Join key arena");
+        const reservation = this.#memory.reserve(capacity, "Join key arena");
+        try {
+            const keys = new Uint8Array(capacity);
+            keys.set(this.#keys.subarray(0, this.#keyLength));
+            this.#keys = keys;
+            this.#keyReservation?.release();
+            this.#keyReservation = reservation;
+        }
+        catch (error) {
+            reservation.release();
+            throw error;
+        }
+    }
+}
+/**
+ * Encodes one join key into the shared scratch arena and returns its byte length, or -1 for keys
+ * SQL equality can never match (null, undefined, NaN). Dates coerce to their epoch milliseconds,
+ * so a Date and its number representation join as the same key.
+ */
+function encodeJoinKey(value) {
+    const key = value instanceof Date ? value.getTime() : value;
+    if (key === null || key === undefined)
+        return -1;
+    if (typeof key === "number" && Number.isNaN(key))
+        return -1;
+    if (typeof key === "boolean" || typeof key === "number" || typeof key === "string") {
+        return encodeSingleScalarKey(key);
+    }
+    throw new TypeError("Join keys must be SQL scalar values");
+}
+function safeDouble(value, label) {
+    const doubled = value * 2;
+    if (!Number.isSafeInteger(doubled)) {
+        throw new RangeError(`${label} exceeds the safe integer range`);
+    }
+    return doubled;
+}
+function safeProduct(left, right, label) {
+    const product = left * right;
+    if (!Number.isSafeInteger(product)) {
+        throw new RangeError(`${label} exceeds the safe integer range`);
+    }
+    return product;
+}
+//# sourceMappingURL=join-index.js.map

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