@rocicorp/zero 1.11.0-canary.2 → 1.11.0-canary.21

package/out/zero-cache/src/services/view-syncer/query-shape.d.ts

@@ -0,0 +1,25 @@
+import type { AST } from '../../../../zero-protocol/src/ast.ts';
+/**
+ * A query with its literal values redacted, for logging.
+ */
+export type QueryShape = {
+    /**
+     * The query as ZQL with every literal (and the `start` row) rendered as
+     * `?`, so it can be logged without leaking row data, query arguments, or
+     * auth data substituted in by permissions.
+     */
+    readonly zql: string;
+    /**
+     * A hash of {@link zql}. Queries that differ only in their literal values,
+     * e.g. the same named query called with different arguments, share a hash,
+     * which makes it a key for grouping and throttling logs.
+     */
+    readonly hash: string;
+};
+/**
+ * Never throws: it is computed for every hydration, and a query that cannot be
+ * rendered as ZQL (e.g. a subquery without an alias) must still hydrate. Such
+ * a query is shaped by its AST with the literal values redacted instead.
+ */
+export declare function queryShape(ast: AST): QueryShape;
+//# sourceMappingURL=query-shape.d.ts.map

package/out/zero-cache/src/services/view-syncer/query-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-shape.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/query-shape.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,sCAAsC,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAQ/C"}

package/out/zero-cache/src/services/view-syncer/query-shape.js

@@ -0,0 +1,28 @@
+import { h64 } from "../../../../shared/src/hash.js";
+import { astToZQL } from "../../../../ast-to-zql/src/ast-to-zql.js";
+//#region ../zero-cache/src/services/view-syncer/query-shape.ts
+/**
+* Never throws: it is computed for every hydration, and a query that cannot be
+* rendered as ZQL (e.g. a subquery without an alias) must still hydrate. Such
+* a query is shaped by its AST with the literal values redacted instead.
+*/
+function queryShape(ast) {
+	let zql;
+	try {
+		zql = ast.table + astToZQL(ast, { redactLiterals: true });
+	} catch {
+		zql = JSON.stringify(ast, redactLiterals);
+	}
+	return {
+		zql,
+		hash: h64(zql).toString(36)
+	};
+}
+function redactLiterals(key, value) {
+	if (key === "value" && this.type === "literal" || key === "start") return "?";
+	return value;
+}
+//#endregion
+export { queryShape };
+
+//# sourceMappingURL=query-shape.js.map

package/out/zero-cache/src/services/view-syncer/query-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-shape.js","names":[],"sources":["../../../../../../zero-cache/src/services/view-syncer/query-shape.ts"],"sourcesContent":["// @circular-dep-ignore\nimport {astToZQL} from '../../../../ast-to-zql/src/ast-to-zql.ts';\nimport {h64} from '../../../../shared/src/hash.ts';\nimport type {AST} from '../../../../zero-protocol/src/ast.ts';\n\n/**\n * A query with its literal values redacted, for logging.\n */\nexport type QueryShape = {\n  /**\n   * The query as ZQL with every literal (and the `start` row) rendered as\n   * `?`, so it can be logged without leaking row data, query arguments, or\n   * auth data substituted in by permissions.\n   */\n  readonly zql: string;\n\n  /**\n   * A hash of {@link zql}. Queries that differ only in their literal values,\n   * e.g. the same named query called with different arguments, share a hash,\n   * which makes it a key for grouping and throttling logs.\n   */\n  readonly hash: string;\n};\n\n/**\n * Never throws: it is computed for every hydration, and a query that cannot be\n * rendered as ZQL (e.g. a subquery without an alias) must still hydrate. Such\n * a query is shaped by its AST with the literal values redacted instead.\n */\nexport function queryShape(ast: AST): QueryShape {\n  let zql: string;\n  try {\n    zql = ast.table + astToZQL(ast, {redactLiterals: true});\n  } catch {\n    zql = JSON.stringify(ast, redactLiterals);\n  }\n  return {zql, hash: h64(zql).toString(36)};\n}\n\nfunction redactLiterals(this: unknown, key: string, value: unknown) {\n  if (\n    (key === 'value' && (this as {type?: unknown}).type === 'literal') ||\n    key === 'start'\n  ) {\n    return '?';\n  }\n  return value;\n}\n"],"mappings":";;;;;;;;AA6BA,SAAgB,WAAW,KAAsB;CAC/C,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,QAAQ,SAAS,KAAK,EAAC,gBAAgB,KAAI,CAAC;CACxD,QAAQ;EACN,MAAM,KAAK,UAAU,KAAK,cAAc;CAC1C;CACA,OAAO;EAAC;EAAK,MAAM,IAAI,GAAG,EAAE,SAAS,EAAE;CAAC;AAC1C;AAEA,SAAS,eAA8B,KAAa,OAAgB;CAClE,IACG,QAAQ,WAAY,KAA0B,SAAS,aACxD,QAAQ,SAER,OAAO;CAET,OAAO;AACT"}

package/out/zero-cache/src/services/view-syncer/query-stats.d.ts

@@ -0,0 +1,77 @@
+import type { LogContext } from '@rocicorp/logger';
+import type { PlanWarning } from '../../../../zql/src/planner/planner-warnings.ts';
+import type { QueryShape } from './query-shape.ts';
+/** The query that work is accounted to. */
+export type QueryIdentity = {
+    readonly queryName?: string | undefined;
+    readonly shape: QueryShape;
+};
+export type HydrationOutcome = 'finished' | 'aborted' | 'failed';
+export type HydrationRecord = {
+    readonly outcome: HydrationOutcome;
+    readonly timeMs: number;
+    /** Only for a finished hydration. */
+    readonly rowCount?: number | undefined;
+    /** Only for a finished hydration. */
+    readonly rowsRead?: number | undefined;
+    readonly planWarnings?: readonly PlanWarning[] | undefined;
+};
+export type AdvanceRecord = {
+    /** The time spent processing the pushes to the query. */
+    readonly timeMs: number;
+    /** The number of changes pushed to the query. */
+    readonly changes: number;
+    /** Whether the advancement timed out and reset the pipelines. */
+    readonly timedOut: boolean;
+};
+export type QueryStatsOptions = {
+    /**
+     * The most query shapes tracked per interval. Work on shapes beyond this is
+     * accounted to the interval's totals only, which bounds memory when the
+     * shape space is unbounded (e.g. dynamically built queries).
+     */
+    readonly maxShapes?: number | undefined;
+    /**
+     * The most query shapes logged per interval, those that took the most
+     * time. The rest are included in the interval's totals.
+     */
+    readonly maxReported?: number | undefined;
+    readonly now?: (() => number) | undefined;
+};
+/**
+ * Aggregates the work done for each query shape (the query with its values
+ * redacted, see {@link QueryShape}) on a worker, and periodically logs it,
+ * like `pg_stat_statements` does for Postgres.
+ *
+ * Unlike the slow query logs, which are throttled and only written above a
+ * threshold, every hydration and advancement is counted, so the logs can be
+ * summed over any time range and across workers to rank queries by the time
+ * they take.
+ *
+ * Each {@link flush} logs the interval since the previous one:
+ *
+ * - a `query-stats` event per query shape, for the {@link
+ *   QueryStatsOptions.maxReported} shapes that took the most time, and
+ * - a `query-stats-summary` event with the totals of all shapes, including
+ *   those not reported individually.
+ *
+ * The events carry counts, sums, minimums and maximums, which compose across
+ * intervals and workers.
+ */
+export declare class QueryStats {
+    #private;
+    constructor({ maxShapes, maxReported, now, }?: QueryStatsOptions);
+    recordHydration(query: QueryIdentity, record: HydrationRecord): void;
+    recordAdvance(query: QueryIdentity, record: AdvanceRecord): void;
+    /**
+     * Logs the stats of the interval since the previous flush, and starts a
+     * new interval. Nothing is logged for an interval without any work.
+     */
+    flush(lc: LogContext): void;
+    /**
+     * Flushes every `intervalMs` until the returned function is called, which
+     * flushes one last time.
+     */
+    start(lc: LogContext, intervalMs: number): () => void;
+}
+//# sourceMappingURL=query-stats.d.ts.map

package/out/zero-cache/src/services/view-syncer/query-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-stats.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/query-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,iDAAiD,CAAC;AACjF,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;CAC5D,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C,CAAC;AA+GF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAU;;IAUrB,YAAY,EACV,SAAgB,EAChB,WAAiB,EACjB,GAAc,GACf,GAAE,iBAAsB,EAOxB;IAED,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CASnE;IAED,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAG/D;IAgBD;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAqC1B;IAED;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,IAAI,CAOpD;CACF"}

package/out/zero-cache/src/services/view-syncer/query-stats.js

@@ -0,0 +1,206 @@
+import { assert } from "../../../../shared/src/asserts.js";
+//#region ../zero-cache/src/services/view-syncer/query-stats.ts
+var Distribution = class {
+	count = 0;
+	sumMs = 0;
+	minMs = Infinity;
+	maxMs = 0;
+	add(ms) {
+		this.count++;
+		this.sumMs += ms;
+		this.minMs = Math.min(this.minMs, ms);
+		this.maxMs = Math.max(this.maxMs, ms);
+	}
+	toJSON() {
+		return {
+			count: this.count,
+			sumMs: round(this.sumMs),
+			minMs: round(this.count === 0 ? 0 : this.minMs),
+			maxMs: round(this.maxMs)
+		};
+	}
+};
+var Totals = class {
+	hydrations = new Distribution();
+	hydrationsAborted = 0;
+	hydrationsFailed = 0;
+	hydrationRowCount = 0;
+	hydrationRowsRead = 0;
+	advances = new Distribution();
+	advanceChanges = 0;
+	advanceTimeouts = 0;
+	get timeMs() {
+		return this.hydrations.sumMs + this.advances.sumMs;
+	}
+	addHydration({ outcome, timeMs, rowCount, rowsRead }) {
+		this.hydrations.add(timeMs);
+		if (outcome === "aborted") this.hydrationsAborted++;
+		else if (outcome === "failed") this.hydrationsFailed++;
+		this.hydrationRowCount += rowCount ?? 0;
+		this.hydrationRowsRead += rowsRead ?? 0;
+	}
+	addAdvance({ timeMs, changes, timedOut }) {
+		this.advances.add(timeMs);
+		this.advanceChanges += changes;
+		if (timedOut) this.advanceTimeouts++;
+	}
+	toJSON() {
+		return {
+			timeMs: round(this.timeMs),
+			hydrations: this.hydrations.toJSON(),
+			hydrationsAborted: this.hydrationsAborted,
+			hydrationsFailed: this.hydrationsFailed,
+			hydrationRowCount: this.hydrationRowCount,
+			hydrationRowsRead: this.hydrationRowsRead,
+			advances: this.advances.toJSON(),
+			advanceChanges: this.advanceChanges,
+			advanceTimeouts: this.advanceTimeouts
+		};
+	}
+};
+var ShapeStats = class extends Totals {
+	query;
+	planWarnings;
+	constructor(query) {
+		super();
+		this.query = query;
+	}
+};
+/** A fixed-size linear-counting sketch for shapes beyond the tracking limit. */
+var OverflowShapeCounter = class {
+	#buckets = new Uint8Array(4096);
+	#occupied = 0;
+	add(key) {
+		let hash = 2166136261;
+		for (let i = 0; i < key.length; i++) hash = Math.imul(hash ^ key.charCodeAt(i), 16777619);
+		const bucket = (hash >>> 0) % this.#buckets.length;
+		if (this.#buckets[bucket] === 0) {
+			this.#buckets[bucket] = 1;
+			this.#occupied++;
+		}
+	}
+	get estimatedCount() {
+		const empty = this.#buckets.length - this.#occupied;
+		return empty === 0 ? this.#buckets.length : Math.round(-this.#buckets.length * Math.log(empty / this.#buckets.length));
+	}
+};
+/**
+* Aggregates the work done for each query shape (the query with its values
+* redacted, see {@link QueryShape}) on a worker, and periodically logs it,
+* like `pg_stat_statements` does for Postgres.
+*
+* Unlike the slow query logs, which are throttled and only written above a
+* threshold, every hydration and advancement is counted, so the logs can be
+* summed over any time range and across workers to rank queries by the time
+* they take.
+*
+* Each {@link flush} logs the interval since the previous one:
+*
+* - a `query-stats` event per query shape, for the {@link
+*   QueryStatsOptions.maxReported} shapes that took the most time, and
+* - a `query-stats-summary` event with the totals of all shapes, including
+*   those not reported individually.
+*
+* The events carry counts, sums, minimums and maximums, which compose across
+* intervals and workers.
+*/
+var QueryStats = class {
+	#maxShapes;
+	#maxReported;
+	#now;
+	#shapes = /* @__PURE__ */ new Map();
+	#totals = new Totals();
+	#overflowShapes = new OverflowShapeCounter();
+	#intervalStart;
+	constructor({ maxShapes = 1e3, maxReported = 100, now = Date.now } = {}) {
+		assert(maxShapes > 0, "maxShapes must be positive");
+		assert(maxReported > 0, "maxReported must be positive");
+		this.#maxShapes = maxShapes;
+		this.#maxReported = maxReported;
+		this.#now = now;
+		this.#intervalStart = now();
+	}
+	recordHydration(query, record) {
+		this.#totals.addHydration(record);
+		const stats = this.#stats(query);
+		if (stats) {
+			stats.addHydration(record);
+			if (record.planWarnings !== void 0) stats.planWarnings = record.planWarnings;
+		}
+	}
+	recordAdvance(query, record) {
+		this.#totals.addAdvance(record);
+		this.#stats(query)?.addAdvance(record);
+	}
+	#stats(query) {
+		const key = `${query.queryName ?? ""}:${query.shape.hash}`;
+		let stats = this.#shapes.get(key);
+		if (stats === void 0) {
+			if (this.#shapes.size >= this.#maxShapes) {
+				this.#overflowShapes.add(key);
+				return;
+			}
+			stats = new ShapeStats({
+				queryName: query.queryName,
+				shape: query.shape
+			});
+			this.#shapes.set(key, stats);
+		}
+		return stats;
+	}
+	/**
+	* Logs the stats of the interval since the previous flush, and starts a
+	* new interval. Nothing is logged for an interval without any work.
+	*/
+	flush(lc) {
+		const now = this.#now();
+		const intervalMs = now - this.#intervalStart;
+		const shapes = this.#shapes;
+		const totals = this.#totals;
+		const overflowShapes = this.#overflowShapes.estimatedCount;
+		this.#shapes = /* @__PURE__ */ new Map();
+		this.#totals = new Totals();
+		this.#overflowShapes = new OverflowShapeCounter();
+		this.#intervalStart = now;
+		if (shapes.size === 0 && overflowShapes === 0) return;
+		const reported = [...shapes.values()].toSorted((a, b) => b.timeMs - a.timeMs).slice(0, this.#maxReported);
+		for (const stats of reported) {
+			const { queryName, shape } = stats.query;
+			lc.info?.("query stats", {
+				zeroEvent: "query-stats",
+				intervalMs,
+				...queryName !== void 0 && { queryName },
+				queryShape: shape.hash,
+				...stats.toJSON(),
+				...stats.planWarnings !== void 0 && stats.planWarnings.length > 0 && { planWarnings: stats.planWarnings },
+				zql: shape.zql
+			});
+		}
+		lc.info?.("query stats summary", {
+			zeroEvent: "query-stats-summary",
+			intervalMs,
+			shapes: shapes.size + overflowShapes,
+			shapesReported: reported.length,
+			...totals.toJSON()
+		});
+	}
+	/**
+	* Flushes every `intervalMs` until the returned function is called, which
+	* flushes one last time.
+	*/
+	start(lc, intervalMs) {
+		const timer = setInterval(() => this.flush(lc), intervalMs);
+		timer.unref?.();
+		return () => {
+			clearInterval(timer);
+			this.flush(lc);
+		};
+	}
+};
+function round(ms) {
+	return Math.round(ms * 100) / 100;
+}
+//#endregion
+export { QueryStats };
+
+//# sourceMappingURL=query-stats.js.map

package/out/zero-cache/src/services/view-syncer/query-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-stats.js","names":["#buckets","#occupied","#maxShapes","#maxReported","#now","#intervalStart","#totals","#stats","#shapes","#overflowShapes"],"sources":["../../../../../../zero-cache/src/services/view-syncer/query-stats.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../../shared/src/asserts.ts';\nimport type {PlanWarning} from '../../../../zql/src/planner/planner-warnings.ts';\nimport type {QueryShape} from './query-shape.ts';\n\n/** The query that work is accounted to. */\nexport type QueryIdentity = {\n  readonly queryName?: string | undefined;\n  readonly shape: QueryShape;\n};\n\nexport type HydrationOutcome = 'finished' | 'aborted' | 'failed';\n\nexport type HydrationRecord = {\n  readonly outcome: HydrationOutcome;\n  readonly timeMs: number;\n  /** Only for a finished hydration. */\n  readonly rowCount?: number | undefined;\n  /** Only for a finished hydration. */\n  readonly rowsRead?: number | undefined;\n  readonly planWarnings?: readonly PlanWarning[] | undefined;\n};\n\nexport type AdvanceRecord = {\n  /** The time spent processing the pushes to the query. */\n  readonly timeMs: number;\n  /** The number of changes pushed to the query. */\n  readonly changes: number;\n  /** Whether the advancement timed out and reset the pipelines. */\n  readonly timedOut: boolean;\n};\n\nexport type QueryStatsOptions = {\n  /**\n   * The most query shapes tracked per interval. Work on shapes beyond this is\n   * accounted to the interval's totals only, which bounds memory when the\n   * shape space is unbounded (e.g. dynamically built queries).\n   */\n  readonly maxShapes?: number | undefined;\n\n  /**\n   * The most query shapes logged per interval, those that took the most\n   * time. The rest are included in the interval's totals.\n   */\n  readonly maxReported?: number | undefined;\n\n  readonly now?: (() => number) | undefined;\n};\n\nclass Distribution {\n  count = 0;\n  sumMs = 0;\n  minMs = Infinity;\n  maxMs = 0;\n\n  add(ms: number) {\n    this.count++;\n    this.sumMs += ms;\n    this.minMs = Math.min(this.minMs, ms);\n    this.maxMs = Math.max(this.maxMs, ms);\n  }\n\n  toJSON() {\n    return {\n      count: this.count,\n      sumMs: round(this.sumMs),\n      minMs: round(this.count === 0 ? 0 : this.minMs),\n      maxMs: round(this.maxMs),\n    };\n  }\n}\n\nclass Totals {\n  readonly hydrations = new Distribution();\n  hydrationsAborted = 0;\n  hydrationsFailed = 0;\n  hydrationRowCount = 0;\n  hydrationRowsRead = 0;\n  readonly advances = new Distribution();\n  advanceChanges = 0;\n  advanceTimeouts = 0;\n\n  get timeMs() {\n    return this.hydrations.sumMs + this.advances.sumMs;\n  }\n\n  addHydration({outcome, timeMs, rowCount, rowsRead}: HydrationRecord) {\n    this.hydrations.add(timeMs);\n    if (outcome === 'aborted') {\n      this.hydrationsAborted++;\n    } else if (outcome === 'failed') {\n      this.hydrationsFailed++;\n    }\n    this.hydrationRowCount += rowCount ?? 0;\n    this.hydrationRowsRead += rowsRead ?? 0;\n  }\n\n  addAdvance({timeMs, changes, timedOut}: AdvanceRecord) {\n    this.advances.add(timeMs);\n    this.advanceChanges += changes;\n    if (timedOut) {\n      this.advanceTimeouts++;\n    }\n  }\n\n  toJSON() {\n    return {\n      timeMs: round(this.timeMs),\n      hydrations: this.hydrations.toJSON(),\n      hydrationsAborted: this.hydrationsAborted,\n      hydrationsFailed: this.hydrationsFailed,\n      hydrationRowCount: this.hydrationRowCount,\n      hydrationRowsRead: this.hydrationRowsRead,\n      advances: this.advances.toJSON(),\n      advanceChanges: this.advanceChanges,\n      advanceTimeouts: this.advanceTimeouts,\n    };\n  }\n}\n\nclass ShapeStats extends Totals {\n  readonly query: QueryIdentity;\n  planWarnings: readonly PlanWarning[] | undefined;\n\n  constructor(query: QueryIdentity) {\n    super();\n    this.query = query;\n  }\n}\n\n/** A fixed-size linear-counting sketch for shapes beyond the tracking limit. */\nclass OverflowShapeCounter {\n  readonly #buckets = new Uint8Array(4096);\n  #occupied = 0;\n\n  add(key: string): void {\n    // FNV-1a gives a stable bucket without retaining the key.\n    let hash = 0x811c9dc5;\n    for (let i = 0; i < key.length; i++) {\n      hash = Math.imul(hash ^ key.charCodeAt(i), 0x01000193);\n    }\n    const bucket = (hash >>> 0) % this.#buckets.length;\n    if (this.#buckets[bucket] === 0) {\n      this.#buckets[bucket] = 1;\n      this.#occupied++;\n    }\n  }\n\n  get estimatedCount(): number {\n    const empty = this.#buckets.length - this.#occupied;\n    return empty === 0\n      ? this.#buckets.length\n      : Math.round(\n          -this.#buckets.length * Math.log(empty / this.#buckets.length),\n        );\n  }\n}\n\n/**\n * Aggregates the work done for each query shape (the query with its values\n * redacted, see {@link QueryShape}) on a worker, and periodically logs it,\n * like `pg_stat_statements` does for Postgres.\n *\n * Unlike the slow query logs, which are throttled and only written above a\n * threshold, every hydration and advancement is counted, so the logs can be\n * summed over any time range and across workers to rank queries by the time\n * they take.\n *\n * Each {@link flush} logs the interval since the previous one:\n *\n * - a `query-stats` event per query shape, for the {@link\n *   QueryStatsOptions.maxReported} shapes that took the most time, and\n * - a `query-stats-summary` event with the totals of all shapes, including\n *   those not reported individually.\n *\n * The events carry counts, sums, minimums and maximums, which compose across\n * intervals and workers.\n */\nexport class QueryStats {\n  readonly #maxShapes: number;\n  readonly #maxReported: number;\n  readonly #now: () => number;\n\n  #shapes = new Map<string, ShapeStats>();\n  #totals = new Totals();\n  #overflowShapes = new OverflowShapeCounter();\n  #intervalStart: number;\n\n  constructor({\n    maxShapes = 1000,\n    maxReported = 100,\n    now = Date.now,\n  }: QueryStatsOptions = {}) {\n    assert(maxShapes > 0, 'maxShapes must be positive');\n    assert(maxReported > 0, 'maxReported must be positive');\n    this.#maxShapes = maxShapes;\n    this.#maxReported = maxReported;\n    this.#now = now;\n    this.#intervalStart = now();\n  }\n\n  recordHydration(query: QueryIdentity, record: HydrationRecord): void {\n    this.#totals.addHydration(record);\n    const stats = this.#stats(query);\n    if (stats) {\n      stats.addHydration(record);\n      if (record.planWarnings !== undefined) {\n        stats.planWarnings = record.planWarnings;\n      }\n    }\n  }\n\n  recordAdvance(query: QueryIdentity, record: AdvanceRecord): void {\n    this.#totals.addAdvance(record);\n    this.#stats(query)?.addAdvance(record);\n  }\n\n  #stats(query: QueryIdentity): ShapeStats | undefined {\n    const key = `${query.queryName ?? ''}:${query.shape.hash}`;\n    let stats = this.#shapes.get(key);\n    if (stats === undefined) {\n      if (this.#shapes.size >= this.#maxShapes) {\n        this.#overflowShapes.add(key);\n        return undefined;\n      }\n      stats = new ShapeStats({queryName: query.queryName, shape: query.shape});\n      this.#shapes.set(key, stats);\n    }\n    return stats;\n  }\n\n  /**\n   * Logs the stats of the interval since the previous flush, and starts a\n   * new interval. Nothing is logged for an interval without any work.\n   */\n  flush(lc: LogContext): void {\n    const now = this.#now();\n    const intervalMs = now - this.#intervalStart;\n    const shapes = this.#shapes;\n    const totals = this.#totals;\n    const overflowShapes = this.#overflowShapes.estimatedCount;\n    this.#shapes = new Map();\n    this.#totals = new Totals();\n    this.#overflowShapes = new OverflowShapeCounter();\n    this.#intervalStart = now;\n\n    if (shapes.size === 0 && overflowShapes === 0) {\n      return;\n    }\n    const reported = [...shapes.values()]\n      .toSorted((a, b) => b.timeMs - a.timeMs)\n      .slice(0, this.#maxReported);\n    for (const stats of reported) {\n      const {queryName, shape} = stats.query;\n      lc.info?.('query stats', {\n        zeroEvent: 'query-stats',\n        intervalMs,\n        ...(queryName !== undefined && {queryName}),\n        queryShape: shape.hash,\n        ...stats.toJSON(),\n        ...(stats.planWarnings !== undefined &&\n          stats.planWarnings.length > 0 && {planWarnings: stats.planWarnings}),\n        zql: shape.zql,\n      });\n    }\n    lc.info?.('query stats summary', {\n      zeroEvent: 'query-stats-summary',\n      intervalMs,\n      shapes: shapes.size + overflowShapes,\n      shapesReported: reported.length,\n      ...totals.toJSON(),\n    });\n  }\n\n  /**\n   * Flushes every `intervalMs` until the returned function is called, which\n   * flushes one last time.\n   */\n  start(lc: LogContext, intervalMs: number): () => void {\n    const timer = setInterval(() => this.flush(lc), intervalMs);\n    timer.unref?.();\n    return () => {\n      clearInterval(timer);\n      this.flush(lc);\n    };\n  }\n}\n\nfunction round(ms: number) {\n  return Math.round(ms * 100) / 100;\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The default maximum number of entries retained by a {@link SnapshotRowCache}.
+ *
+ * Each entry is a raw SQLite row (or the list of rows conflicting with
+ * a row on its unique keys) read while computing a snapshot diff. A
+ * replicated transaction of N rows produces up to 2N entries (the new value
+ * and the previous value(s) of each row), so the cache should be large enough
+ * to hold the largest transactions that are commonly replicated in order for
+ * all of the client groups on a worker to share the reads.
+ */
+export declare const DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES = 50000;
+/**
+ * How a statement's results are read: a single row (`Statement.get()`) or
+ * all rows (`Statement.all()`).
+ */
+export type ReadMode = 'get' | 'all';
+/**
+ * The maximum number of distinct SQL statements interned by a
+ * {@link SnapshotRowCache} before it is cleared. There is one per table and
+ * lookup shape, so this is only reached after many schema changes.
+ */
+export declare const MAX_INTERNED_STATEMENTS = 10000;
+/**
+ * A worker-wide, bounded cache of the rows that a `Snapshotter` reads from
+ * replica snapshots when computing the diff between two versions of the
+ * replica.
+ *
+ * Every client group (i.e. view-syncer) on a sync worker computes its own
+ * diff from the shared `_zero.changeLog2`, and each change in the diff costs
+ * two SQLite reads: the new value of the row (from the `curr` snapshot) and
+ * the previous value(s) that it replaces (from the `prev` snapshot). The
+ * reads for a given change are identical for every client group that
+ * traverses it, so a replicated transaction of N rows costs N × 2 × (client
+ * groups) reads per worker, most of which are redundant. This cache lets the
+ * client groups on a worker share those reads.
+ *
+ * ### Keys
+ *
+ * Entries are keyed by the exact SQL statement and arguments of the read
+ * (which encodes the table, the selected columns and the lookup keys), plus
+ * a `tag` supplied by the caller that pins the result to a version of the
+ * replica:
+ *
+ * - The new value of a row is the row as of the `stateVersion` recorded in
+ *   its change log entry (its `_0_version` is asserted to equal that
+ *   version), and is tagged with that `stateVersion`. It is thus shareable
+ *   by all client groups regardless of the snapshots they are advancing
+ *   between.
+ * - Previous values are read from the `prev` snapshot at its version, and
+ *   are tagged with that version (and, when the result can depend on the
+ *   changes applied to the snapshot before the read, the `curr` version
+ *   as well). See `Diff` in `snapshotter.ts` for the details.
+ *
+ * Because every key includes the version(s) that the result depends on,
+ * entries never go stale and are never invalidated; they are only evicted.
+ *
+ * ### Eviction
+ *
+ * The cache is bounded by entry count and evicts in insertion (FIFO) order
+ * rather than by recency. Diffs are traversed in change log order by every
+ * client group, so the entries that will not be needed again are those that
+ * were inserted the earliest (all groups have moved past them), while the
+ * most recently inserted entries are the ones that the trailing groups have
+ * yet to reach. Refreshing an entry on a hit would evict exactly the wrong
+ * entries when a trailing group catches up.
+ *
+ * ### Sharing
+ *
+ * Cached values are shared by reference across client groups and must
+ * therefore never be mutated by callers.
+ */
+export declare class SnapshotRowCache {
+    #private;
+    constructor(maxEntries?: number);
+    get size(): number;
+    get maxEntries(): number;
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+    /**
+     * Returns the cached result of the read identified by `tag`, `sql`, `mode`
+     * and `args`, or performs the read via `read()`, caching and returning its
+     * result. `undefined` results (i.e. a missing row) are not cached.
+     *
+     * `mode` is part of the key because the same statement can be read both
+     * ways: for a table whose only unique key is its primary key, `getRow()`
+     * and `getRows()` produce identical SQL, args and tags, but the former
+     * caches a row and the latter an array of rows.
+     */
+    getOrRead<T>(tag: string, sql: string, mode: ReadMode, args: unknown[], read: () => T): T;
+    clear(): void;
+}
+//# sourceMappingURL=snapshot-row-cache.d.ts.map

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-row-cache.d.ts","sourceRoot":"","sources":["../../../../../../zero-cache/src/services/view-syncer/snapshot-row-cache.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,eAAO,MAAM,sCAAsC,QAAS,CAAC;AAwB7D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAK9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,gBAAgB;;IAmB3B,YAAY,UAAU,SAAyC,EAE9D;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,KAAK,IAAI;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAEpD;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EACT,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,MAAM,CAAC,GACZ,CAAC,CAoBH;IAED,KAAK,IAAI,IAAI,CAIZ;CAsBF"}

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.js

@@ -0,0 +1,155 @@
+import { getOrInsert } from "../../../../shared/src/map.js";
+import { must } from "../../../../shared/src/must.js";
+import { stringify } from "../../../../shared/src/bigint-json.js";
+import { getOrCreateCounter } from "../../observability/metrics.js";
+import { RingBuffer } from "../../../../shared/src/ring-buffer.js";
+//#region ../zero-cache/src/services/view-syncer/snapshot-row-cache.ts
+/**
+* The default maximum number of entries retained by a {@link SnapshotRowCache}.
+*
+* Each entry is a raw SQLite row (or the list of rows conflicting with
+* a row on its unique keys) read while computing a snapshot diff. A
+* replicated transaction of N rows produces up to 2N entries (the new value
+* and the previous value(s) of each row), so the cache should be large enough
+* to hold the largest transactions that are commonly replicated in order for
+* all of the client groups on a worker to share the reads.
+*/
+var DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES = 5e4;
+/**
+* Serializes a lookup key value (i.e. a SQLite-bound parameter). Numbers and
+* bigints serialize identically, as row keys parsed from the change log are
+* JSON numbers whereas the values read from SQLite are bigints; both address
+* the same row. Strings are prefixed to distinguish them from numbers.
+*/
+function serialize(v) {
+	switch (typeof v) {
+		case "string": return "s" + v;
+		case "number":
+		case "bigint": return String(v);
+		case "boolean": return v ? "true" : "false";
+		case "object": return v === null ? "null" : "o" + stringify(v);
+		default: return "u" + String(v);
+	}
+}
+var HIT = { result: "hit" };
+var MISS = { result: "miss" };
+/**
+* A worker-wide, bounded cache of the rows that a `Snapshotter` reads from
+* replica snapshots when computing the diff between two versions of the
+* replica.
+*
+* Every client group (i.e. view-syncer) on a sync worker computes its own
+* diff from the shared `_zero.changeLog2`, and each change in the diff costs
+* two SQLite reads: the new value of the row (from the `curr` snapshot) and
+* the previous value(s) that it replaces (from the `prev` snapshot). The
+* reads for a given change are identical for every client group that
+* traverses it, so a replicated transaction of N rows costs N × 2 × (client
+* groups) reads per worker, most of which are redundant. This cache lets the
+* client groups on a worker share those reads.
+*
+* ### Keys
+*
+* Entries are keyed by the exact SQL statement and arguments of the read
+* (which encodes the table, the selected columns and the lookup keys), plus
+* a `tag` supplied by the caller that pins the result to a version of the
+* replica:
+*
+* - The new value of a row is the row as of the `stateVersion` recorded in
+*   its change log entry (its `_0_version` is asserted to equal that
+*   version), and is tagged with that `stateVersion`. It is thus shareable
+*   by all client groups regardless of the snapshots they are advancing
+*   between.
+* - Previous values are read from the `prev` snapshot at its version, and
+*   are tagged with that version (and, when the result can depend on the
+*   changes applied to the snapshot before the read, the `curr` version
+*   as well). See `Diff` in `snapshotter.ts` for the details.
+*
+* Because every key includes the version(s) that the result depends on,
+* entries never go stale and are never invalidated; they are only evicted.
+*
+* ### Eviction
+*
+* The cache is bounded by entry count and evicts in insertion (FIFO) order
+* rather than by recency. Diffs are traversed in change log order by every
+* client group, so the entries that will not be needed again are those that
+* were inserted the earliest (all groups have moved past them), while the
+* most recently inserted entries are the ones that the trailing groups have
+* yet to reach. Refreshing an entry on a hit would evict exactly the wrong
+* entries when a trailing group catches up.
+*
+* ### Sharing
+*
+* Cached values are shared by reference across client groups and must
+* therefore never be mutated by callers.
+*/
+var SnapshotRowCache = class {
+	#maxEntries;
+	#entries = /* @__PURE__ */ new Map();
+	#keys = new RingBuffer();
+	#sqlIDs = /* @__PURE__ */ new Map();
+	#reads = getOrCreateCounter("sync", "ivm.snapshot-row-reads", "Row reads performed while computing snapshot diffs for IVM, labeled by whether the read was served by the worker-wide snapshot row cache.");
+	#hits = 0;
+	#misses = 0;
+	constructor(maxEntries = DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES) {
+		this.#maxEntries = Math.max(0, maxEntries);
+	}
+	get size() {
+		return this.#entries.size;
+	}
+	get maxEntries() {
+		return this.#maxEntries;
+	}
+	stats() {
+		return {
+			hits: this.#hits,
+			misses: this.#misses,
+			size: this.#entries.size
+		};
+	}
+	/**
+	* Returns the cached result of the read identified by `tag`, `sql`, `mode`
+	* and `args`, or performs the read via `read()`, caching and returning its
+	* result. `undefined` results (i.e. a missing row) are not cached.
+	*
+	* `mode` is part of the key because the same statement can be read both
+	* ways: for a table whose only unique key is its primary key, `getRow()`
+	* and `getRows()` produce identical SQL, args and tags, but the former
+	* caches a row and the latter an array of rows.
+	*/
+	getOrRead(tag, sql, mode, args, read) {
+		const key = this.#key(tag, sql, mode, args);
+		const cached = this.#entries.get(key);
+		if (cached !== void 0) {
+			this.#hits++;
+			this.#reads.add(1, HIT);
+			return cached;
+		}
+		this.#misses++;
+		this.#reads.add(1, MISS);
+		const value = read();
+		if (value !== void 0 && this.#maxEntries > 0) {
+			this.#entries.set(key, value);
+			this.#keys.push(key);
+			if (this.#keys.size > this.#maxEntries) this.#entries.delete(must(this.#keys.shift()));
+		}
+		return value;
+	}
+	clear() {
+		this.#entries.clear();
+		this.#keys.clear();
+		this.#sqlIDs.clear();
+	}
+	#key(tag, sql, mode, args) {
+		if (this.#sqlIDs.size >= 1e4 && !this.#sqlIDs.has(sql)) this.clear();
+		let key = `${tag}\0${mode}${getOrInsert(this.#sqlIDs, sql, this.#sqlIDs.size)}`;
+		for (const arg of args) {
+			const serialized = serialize(arg);
+			key += `\0${serialized.length}:${serialized}`;
+		}
+		return key;
+	}
+};
+//#endregion
+export { SnapshotRowCache };
+
+//# sourceMappingURL=snapshot-row-cache.js.map

package/out/zero-cache/src/services/view-syncer/snapshot-row-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-row-cache.js","names":["#maxEntries","#entries","#keys","#sqlIDs","#reads","#hits","#misses","#key"],"sources":["../../../../../../zero-cache/src/services/view-syncer/snapshot-row-cache.ts"],"sourcesContent":["import {stringify} from '../../../../shared/src/bigint-json.ts';\nimport {getOrInsert} from '../../../../shared/src/map.ts';\nimport {must} from '../../../../shared/src/must.ts';\nimport {RingBuffer} from '../../../../shared/src/ring-buffer.ts';\nimport {getOrCreateCounter} from '../../observability/metrics.ts';\n\n/**\n * The default maximum number of entries retained by a {@link SnapshotRowCache}.\n *\n * Each entry is a raw SQLite row (or the list of rows conflicting with\n * a row on its unique keys) read while computing a snapshot diff. A\n * replicated transaction of N rows produces up to 2N entries (the new value\n * and the previous value(s) of each row), so the cache should be large enough\n * to hold the largest transactions that are commonly replicated in order for\n * all of the client groups on a worker to share the reads.\n */\nexport const DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES = 50_000;\n\n/**\n * Serializes a lookup key value (i.e. a SQLite-bound parameter). Numbers and\n * bigints serialize identically, as row keys parsed from the change log are\n * JSON numbers whereas the values read from SQLite are bigints; both address\n * the same row. Strings are prefixed to distinguish them from numbers.\n */\nfunction serialize(v: unknown): string {\n  switch (typeof v) {\n    case 'string':\n      return 's' + v;\n    case 'number':\n    case 'bigint':\n      return String(v);\n    case 'boolean':\n      return v ? 'true' : 'false';\n    case 'object':\n      return v === null ? 'null' : 'o' + stringify(v);\n    default:\n      return 'u' + String(v);\n  }\n}\n\n/**\n * How a statement's results are read: a single row (`Statement.get()`) or\n * all rows (`Statement.all()`).\n */\nexport type ReadMode = 'get' | 'all';\n\n/**\n * The maximum number of distinct SQL statements interned by a\n * {@link SnapshotRowCache} before it is cleared. There is one per table and\n * lookup shape, so this is only reached after many schema changes.\n */\nexport const MAX_INTERNED_STATEMENTS = 10_000;\n\nconst HIT = {result: 'hit'} as const;\nconst MISS = {result: 'miss'} as const;\n\n/**\n * A worker-wide, bounded cache of the rows that a `Snapshotter` reads from\n * replica snapshots when computing the diff between two versions of the\n * replica.\n *\n * Every client group (i.e. view-syncer) on a sync worker computes its own\n * diff from the shared `_zero.changeLog2`, and each change in the diff costs\n * two SQLite reads: the new value of the row (from the `curr` snapshot) and\n * the previous value(s) that it replaces (from the `prev` snapshot). The\n * reads for a given change are identical for every client group that\n * traverses it, so a replicated transaction of N rows costs N × 2 × (client\n * groups) reads per worker, most of which are redundant. This cache lets the\n * client groups on a worker share those reads.\n *\n * ### Keys\n *\n * Entries are keyed by the exact SQL statement and arguments of the read\n * (which encodes the table, the selected columns and the lookup keys), plus\n * a `tag` supplied by the caller that pins the result to a version of the\n * replica:\n *\n * - The new value of a row is the row as of the `stateVersion` recorded in\n *   its change log entry (its `_0_version` is asserted to equal that\n *   version), and is tagged with that `stateVersion`. It is thus shareable\n *   by all client groups regardless of the snapshots they are advancing\n *   between.\n * - Previous values are read from the `prev` snapshot at its version, and\n *   are tagged with that version (and, when the result can depend on the\n *   changes applied to the snapshot before the read, the `curr` version\n *   as well). See `Diff` in `snapshotter.ts` for the details.\n *\n * Because every key includes the version(s) that the result depends on,\n * entries never go stale and are never invalidated; they are only evicted.\n *\n * ### Eviction\n *\n * The cache is bounded by entry count and evicts in insertion (FIFO) order\n * rather than by recency. Diffs are traversed in change log order by every\n * client group, so the entries that will not be needed again are those that\n * were inserted the earliest (all groups have moved past them), while the\n * most recently inserted entries are the ones that the trailing groups have\n * yet to reach. Refreshing an entry on a hit would evict exactly the wrong\n * entries when a trailing group catches up.\n *\n * ### Sharing\n *\n * Cached values are shared by reference across client groups and must\n * therefore never be mutated by callers.\n */\nexport class SnapshotRowCache {\n  readonly #maxEntries: number;\n  readonly #entries = new Map<string, unknown>();\n  // The keys of #entries in insertion order, so that the oldest can be\n  // evicted in O(1). (Finding the oldest key with a fresh Map iterator\n  // instead costs O(evictions) per insert, as V8 leaves deleted entries in\n  // the table until it is compacted and every new iterator walks over them.)\n  readonly #keys = new RingBuffer<string>();\n  // Interns the SQL text of each distinct read so that entry keys\n  // do not repeat the (long) column list of every statement.\n  readonly #sqlIDs = new Map<string, number>();\n  readonly #reads = getOrCreateCounter(\n    'sync',\n    'ivm.snapshot-row-reads',\n    'Row reads performed while computing snapshot diffs for IVM, labeled by whether the read was served by the worker-wide snapshot row cache.',\n  );\n  #hits = 0;\n  #misses = 0;\n\n  constructor(maxEntries = DEFAULT_MAX_SNAPSHOT_ROW_CACHE_ENTRIES) {\n    this.#maxEntries = Math.max(0, maxEntries);\n  }\n\n  get size(): number {\n    return this.#entries.size;\n  }\n\n  get maxEntries(): number {\n    return this.#maxEntries;\n  }\n\n  stats(): {hits: number; misses: number; size: number} {\n    return {hits: this.#hits, misses: this.#misses, size: this.#entries.size};\n  }\n\n  /**\n   * Returns the cached result of the read identified by `tag`, `sql`, `mode`\n   * and `args`, or performs the read via `read()`, caching and returning its\n   * result. `undefined` results (i.e. a missing row) are not cached.\n   *\n   * `mode` is part of the key because the same statement can be read both\n   * ways: for a table whose only unique key is its primary key, `getRow()`\n   * and `getRows()` produce identical SQL, args and tags, but the former\n   * caches a row and the latter an array of rows.\n   */\n  getOrRead<T>(\n    tag: string,\n    sql: string,\n    mode: ReadMode,\n    args: unknown[],\n    read: () => T,\n  ): T {\n    const key = this.#key(tag, sql, mode, args);\n    const cached = this.#entries.get(key);\n    if (cached !== undefined) {\n      this.#hits++;\n      this.#reads.add(1, HIT);\n      return cached as T;\n    }\n    this.#misses++;\n    this.#reads.add(1, MISS);\n    const value = read();\n    if (value !== undefined && this.#maxEntries > 0) {\n      // `key` is not in #entries (this is a miss), so it is always added.\n      this.#entries.set(key, value);\n      this.#keys.push(key);\n      if (this.#keys.size > this.#maxEntries) {\n        this.#entries.delete(must(this.#keys.shift()));\n      }\n    }\n    return value;\n  }\n\n  clear(): void {\n    this.#entries.clear();\n    this.#keys.clear();\n    this.#sqlIDs.clear();\n  }\n\n  #key(tag: string, sql: string, mode: ReadMode, args: unknown[]): string {\n    if (\n      this.#sqlIDs.size >= MAX_INTERNED_STATEMENTS &&\n      !this.#sqlIDs.has(sql)\n    ) {\n      // Statements are only added (e.g. when schema changes produce new\n      // column lists), so bound them by starting over. The entries refer to\n      // statements by ID and are cleared with them.\n      this.clear();\n    }\n    const sqlID = getOrInsert(this.#sqlIDs, sql, this.#sqlIDs.size);\n    let key = `${tag}\\0${mode}${sqlID}`;\n    // Include each value's length so separators inside string values cannot\n    // make different argument arrays produce the same key.\n    for (const arg of args) {\n      const serialized = serialize(arg);\n      key += `\\0${serialized.length}:${serialized}`;\n    }\n    return key;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAa,yCAAyC;;;;;;;AAQtD,SAAS,UAAU,GAAoB;CACrC,QAAQ,OAAO,GAAf;EACE,KAAK,UACH,OAAO,MAAM;EACf,KAAK;EACL,KAAK,UACH,OAAO,OAAO,CAAC;EACjB,KAAK,WACH,OAAO,IAAI,SAAS;EACtB,KAAK,UACH,OAAO,MAAM,OAAO,SAAS,MAAM,UAAU,CAAC;EAChD,SACE,OAAO,MAAM,OAAO,CAAC;CACzB;AACF;AAeA,IAAM,MAAM,EAAC,QAAQ,MAAK;AAC1B,IAAM,OAAO,EAAC,QAAQ,OAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmD5B,IAAa,mBAAb,MAA8B;CAC5B;CACA,2BAAoB,IAAI,IAAqB;CAK7C,QAAiB,IAAI,WAAmB;CAGxC,0BAAmB,IAAI,IAAoB;CAC3C,SAAkB,mBAChB,QACA,0BACA,2IACF;CACA,QAAQ;CACR,UAAU;CAEV,YAAY,aAAa,wCAAwC;EAC/D,KAAKA,cAAc,KAAK,IAAI,GAAG,UAAU;CAC3C;CAEA,IAAI,OAAe;EACjB,OAAO,KAAKC,SAAS;CACvB;CAEA,IAAI,aAAqB;EACvB,OAAO,KAAKD;CACd;CAEA,QAAsD;EACpD,OAAO;GAAC,MAAM,KAAKK;GAAO,QAAQ,KAAKC;GAAS,MAAM,KAAKL,SAAS;EAAI;CAC1E;;;;;;;;;;;CAYA,UACE,KACA,KACA,MACA,MACA,MACG;EACH,MAAM,MAAM,KAAKM,KAAK,KAAK,KAAK,MAAM,IAAI;EAC1C,MAAM,SAAS,KAAKN,SAAS,IAAI,GAAG;EACpC,IAAI,WAAW,KAAA,GAAW;GACxB,KAAKI;GACL,KAAKD,OAAO,IAAI,GAAG,GAAG;GACtB,OAAO;EACT;EACA,KAAKE;EACL,KAAKF,OAAO,IAAI,GAAG,IAAI;EACvB,MAAM,QAAQ,KAAK;EACnB,IAAI,UAAU,KAAA,KAAa,KAAKJ,cAAc,GAAG;GAE/C,KAAKC,SAAS,IAAI,KAAK,KAAK;GAC5B,KAAKC,MAAM,KAAK,GAAG;GACnB,IAAI,KAAKA,MAAM,OAAO,KAAKF,aACzB,KAAKC,SAAS,OAAO,KAAK,KAAKC,MAAM,MAAM,CAAC,CAAC;EAEjD;EACA,OAAO;CACT;CAEA,QAAc;EACZ,KAAKD,SAAS,MAAM;EACpB,KAAKC,MAAM,MAAM;EACjB,KAAKC,QAAQ,MAAM;CACrB;CAEA,KAAK,KAAa,KAAa,MAAgB,MAAyB;EACtE,IACE,KAAKA,QAAQ,QAAA,OACb,CAAC,KAAKA,QAAQ,IAAI,GAAG,GAKrB,KAAK,MAAM;EAGb,IAAI,MAAM,GAAG,IAAI,IAAI,OADP,YAAY,KAAKA,SAAS,KAAK,KAAKA,QAAQ,IAC9B;EAG5B,KAAK,MAAM,OAAO,MAAM;GACtB,MAAM,aAAa,UAAU,GAAG;GAChC,OAAO,KAAK,WAAW,OAAO,GAAG;EACnC;EACA,OAAO;CACT;AACF"}