@spooky-sync/core 0.0.1-canary.27 → 0.0.1-canary.271

package/dist/otel/index.d.ts

@@ -1,4 +1,4 @@
-import { c as PinoTransmit } from "../types.js";
+import { p as PinoTransmit } from "../types.js";
 import { Level } from "pino";
 
 //#region src/otel/index.d.ts
@@ -10,7 +10,7 @@ import { Level } from "pino";
  * ```ts
  * import { createOtelTransmit } from '@spooky-sync/core/otel';
  *
- * new SpookyClient({
+ * new Sp00kyClient({
  *   // ...
  *   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
  * });

package/dist/otel/index.js

@@ -18,7 +18,7 @@ async function loadOtelModules(otelEndpoint) {
 		import("@opentelemetry/semantic-conventions")
 	]);
 	const loggerProvider = new LoggerProvider({
-		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "spooky-client" }),
+		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "sp00ky-client" }),
 		processors: [new BatchLogRecordProcessor(new OTLPLogExporter({ url: otelEndpoint }))]
 	});
 	const otelLoggerCache = {};
@@ -34,7 +34,7 @@ async function loadOtelModules(otelEndpoint) {
 * ```ts
 * import { createOtelTransmit } from '@spooky-sync/core/otel';
 *
-* new SpookyClient({
+* new Sp00kyClient({
 *   // ...
 *   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
 * });
@@ -50,10 +50,10 @@ function createOtelTransmit(endpoint, level = "info") {
 					const messages = [...logEvent.messages];
 					const severityNumber = mapLevelToSeverityNumber(levelLabel);
 					let body = "";
-					const msg = messages.pop();
-					if (typeof msg === "string") body = msg;
-					else if (msg) body = JSON.stringify(msg);
-					let category = "spooky-client::unknown";
+					const lastMsg = messages.pop();
+					if (typeof lastMsg === "string") body = lastMsg;
+					else if (lastMsg) body = JSON.stringify(lastMsg);
+					let category = "sp00ky-client::unknown";
 					const attributes = {};
 					for (const msg of messages) if (typeof msg === "object") {
 						if (msg.Category) {

package/dist/sqlite-open.js

@@ -0,0 +1,331 @@
+//#region src/services/database/cache-engine.ts
+/** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
+*  a guard against a cyclic schema producing unbounded fan-out. */
+var RelationCycleError = class extends Error {
+	constructor(path) {
+		super(`Relation nesting exceeded safe depth; possible cyclic schema: ${path.join(" -> ")}`);
+		this.name = "RelationCycleError";
+	}
+};
+/** Defensive ceiling on relation nesting depth. A finite plan tree never hits
+*  this in practice; it exists so a malformed/cyclic plan fails loudly instead
+*  of running away. */
+const MAX_RELATION_DEPTH = 12;
+
+//#endregion
+//#region src/services/database/relation-resolver.ts
+/**
+* Resolve the `.related()` tree of a query by **level-ordered, batched
+* fan-out** — the engine-neutral replacement for SurrealQL's nested
+* `(SELECT..) AS alias` projections. One batched fetch per relation per level
+* (never per-row N+1, never a flat join); grouping, per-parent ORDER/LIMIT and
+* attachment happen in JS.
+*
+* Correlation (mirrors `buildSubquery`):
+* - `one`  → parent[`foreignKeyField`] = child.id  → attach `bucket[0] ?? null`
+* - `many` → child[`foreignKeyField`] = parent.id   → attach `bucket`
+*
+* Cross-level dependency is handled by ordering: a child's correlation key is a
+* field on its parent, known only once the parent level has resolved, so each
+* level's batch runs after the previous level's rows exist. `parents` is
+* mutated in place — each resolved alias is appended LAST so key order matches
+* SurrealQL's `SELECT *, <sub> AS alias` (base fields, then alias).
+*
+* @throws {RelationCycleError} if nesting exceeds {@link MAX_RELATION_DEPTH}.
+*/
+async function resolveRelations(parents, relations, fetcher, depth = 0, path = []) {
+	if (!relations || relations.length === 0 || parents.length === 0) return;
+	if (depth >= MAX_RELATION_DEPTH) throw new RelationCycleError([...path, relations.map((r) => r.alias).join("|")]);
+	await Promise.all(relations.map((relation) => resolveOne(parents, relation, fetcher, depth, path)));
+}
+async function resolveOne(parents, relation, fetcher, depth, path) {
+	const isOne = relation.cardinality === "one";
+	const matchField = isOne ? "id" : relation.foreignKeyField;
+	const parentKeyOf = (parent) => isOne ? parent[relation.foreignKeyField] : parent["id"];
+	const keySet = /* @__PURE__ */ new Map();
+	for (const parent of parents) {
+		const key = parentKeyOf(parent);
+		if (key == null) continue;
+		if (isOne && !looksLikeRecordId(key)) continue;
+		const k = stableKey(key);
+		if (!keySet.has(k)) keySet.set(k, key);
+	}
+	const grouped = /* @__PURE__ */ new Map();
+	if (keySet.size > 0) {
+		const children = await fetcher.fetchRelation({
+			table: relation.table,
+			matchField,
+			keys: [...keySet.values()],
+			where: relation.where,
+			orderBy: relation.orderBy,
+			select: relation.select
+		});
+		await resolveRelations(children, relation.relations, fetcher, depth + 1, [...path, relation.alias]);
+		for (const child of children) {
+			const k = stableKey(child[matchField]);
+			const bucket = grouped.get(k);
+			if (bucket) bucket.push(child);
+			else grouped.set(k, [child]);
+		}
+	}
+	for (const parent of parents) {
+		const key = parentKeyOf(parent);
+		let bucket = key == null ? [] : grouped.get(stableKey(key)) ?? [];
+		if (relation.orderBy && relation.orderBy.length > 0) bucket = sortRows(bucket, relation.orderBy);
+		if (relation.limit !== void 0) bucket = bucket.slice(0, relation.limit);
+		if (isOne) {
+			const raw = parent[relation.alias];
+			const keepRaw = relation.alias === relation.foreignKeyField && raw != null && !looksLikeRecordId(raw);
+			parent[relation.alias] = bucket[0] ?? (keepRaw ? raw : null);
+		} else parent[relation.alias] = bucket;
+	}
+}
+/**
+* Whether a correlation value can address a record: a RecordId (duck-typed) or
+* a `table:id` string. Anything else (a plain display string, a number) cannot
+* be the target of a to-one relation and is skipped rather than fetched.
+*/
+function looksLikeRecordId(value) {
+	if (value == null) return false;
+	if (typeof value === "string") return /^[A-Za-z_][A-Za-z0-9_]*:.+/.test(value);
+	if (typeof value === "object") {
+		const rid = value;
+		return rid.tb !== void 0 && rid.id !== void 0;
+	}
+	return false;
+}
+/**
+* Stable grouping key for a correlation value. A `RecordId` (duck-typed to
+* avoid a hard surrealdb dependency here) and its `table:id` string form must
+* collapse to the same key so a parent FK stored either way matches the child.
+*/
+function stableKey(value) {
+	if (value == null) return "\0null";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (typeof value === "object") {
+		const rid = value;
+		if (rid.tb !== void 0 && rid.id !== void 0) return `${String(rid.tb)}:${stableKey(rid.id)}`;
+		if (typeof rid.toString === "function") {
+			const s = rid.toString();
+			if (s !== "[object Object]") return s;
+		}
+		return JSON.stringify(value);
+	}
+	return String(value);
+}
+/**
+* Stable, multi-key sort matching SurrealQL `ORDER BY` semantics closely
+* enough for cache display order: ascending null-last, type-aware compare, and
+* a stable tiebreak (original index) so equal rows keep input order.
+*/
+function sortRows(rows, orderBy) {
+	const indexed = rows.map((row, i) => [row, i]);
+	indexed.sort((a, b) => {
+		for (const [field, direction] of orderBy) {
+			const cmp = compareValues(a[0][field], b[0][field]);
+			if (cmp !== 0) return direction === "desc" ? -cmp : cmp;
+		}
+		return a[1] - b[1];
+	});
+	return indexed.map(([row]) => row);
+}
+function compareValues(a, b) {
+	if (a == null && b == null) return 0;
+	if (a == null) return 1;
+	if (b == null) return -1;
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	const as = stableKey(a);
+	const bs = stableKey(b);
+	return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+//#endregion
+//#region src/services/database/sqlite-plan-sql.ts
+/**
+* SQL rendering + value (de)serialization for the SQLite cache backend.
+* Extracted from `sqlite-cache-engine.ts` so BOTH sides of the worker boundary
+* can use it: the engine (main thread) for the legacy/shim paths, and
+* `sqlite-worker.js` for worker-side plan execution (`select`). Pure module —
+* no DOM, no worker, no engine imports — mirroring `plan-render.ts`.
+*/
+function renderOrderSql(orderBy) {
+	return ` ORDER BY ${orderBy.map(([f, d]) => `json_extract(data, '$.${f}') ${d === "desc" ? "DESC" : "ASC"}`).join(", ")}`;
+}
+function comparisonSql(c, bind, params) {
+	const lhs = c.field === "id" ? "id" : `json_extract(data, '$.${c.field}')`;
+	const value = c.paramRef !== void 0 && (c.value === void 0 || Object.prototype.hasOwnProperty.call(params, c.paramRef)) ? params[c.paramRef] : c.value;
+	bind.push(scalar(value));
+	const op = c.op === "!=" ? "!=" : c.op;
+	return c.swap ? `? ${op} ${lhs}` : `${lhs} ${op} ?`;
+}
+function renderWhereSql(nodes, bind, params) {
+	return nodes.map((node) => {
+		if ("or" in node) return `(${node.or.map((c) => comparisonSql(c, bind, params)).join(" OR ")})`;
+		return comparisonSql(node, bind, params);
+	}).join(" AND ");
+}
+/** A comparable scalar for SQL binding: record links → `table:id`, everything
+*  else passed through (numbers/strings/bools). */
+function scalar(value) {
+	if (value == null) return null;
+	if (typeof value === "object") return stableKey(value);
+	return value;
+}
+function serializeRow(row) {
+	return JSON.stringify(row, (_k, v) => {
+		if (v instanceof Uint8Array) return { __u8: toBase64(v) };
+		if (v && typeof v === "object") {
+			const rid = v;
+			if (rid.tb !== void 0 && rid.id !== void 0) return stableKey(v);
+		}
+		return v;
+	});
+}
+function reviveRow(json) {
+	if (json.indexOf("\"__u8\"") === -1) return JSON.parse(json);
+	return JSON.parse(json, (_k, v) => {
+		if (v && typeof v === "object" && typeof v.__u8 === "string") return fromBase64(v.__u8);
+		return v;
+	});
+}
+/**
+* SELECT-clause expression yielding the row's `data` narrowed to `fields` (plus
+* `id`), so SQLite never returns — and neither side ever parses — the fields the
+* caller did not ask for. On a game list that is every row's `pgn`, which was
+* being read, parsed and thrown away 50 rows at a time for eight rendered fields.
+*
+* Byte-identical to running {@link project} over the fully-parsed row, which is
+* what both paths did before, and verified so against real SQLite:
+* `json_each` walks the keys the row ACTUALLY has, so an ABSENT key stays absent
+* rather than becoming an explicit null — the difference `json_object`/
+* `json_extract` would have introduced. A stored null, nested objects and
+* arrays, and `{__u8}` blob tags all round-trip unchanged, because
+* `json_group_object` understands `json_each`'s `value` column as JSON rather
+* than as text. `COALESCE` covers a row sharing none of the requested keys,
+* where the subquery yields NULL and `reviveRow` would throw.
+*
+* The one value `je.value` does NOT carry back is a TOP-LEVEL boolean. SQLite
+* has no boolean type, so `json_each` hands `true`/`false` out as the integers
+* 1/0 and `json_group_object` writes integers back. A projected row therefore
+* read `published: 1` where the same row read whole read `published: true`,
+* and every `=== true` in an app turned false the moment a screen painted from
+* the local cache. (A boolean NESTED in an object or array survives: those come
+* back as whole JSON documents, untouched.) `je.type` still knows what it was,
+* so the two boolean types are rebuilt as JSON literals on the way out.
+*
+* Deliberately unaliased, so the emitted statement keeps the exact shape the
+* callers already produce (`FROM "t" WHERE id IN (…)`).
+*
+* Binds one parameter per key, pushed onto `bind` — these land in the SELECT
+* clause, so they must be bound BEFORE any WHERE parameters.
+*/
+function projectedDataSql(fields, bind) {
+	const keys = ["id", ...fields];
+	for (const k of keys) bind.push(k);
+	return `COALESCE((SELECT json_group_object(je.key, CASE je.type WHEN 'true' THEN json('true') WHEN 'false' THEN json('false') ELSE je.value END) FROM json_each(data) je WHERE je.key IN (${keys.map(() => "?").join(", ")})), '{}') AS data`;
+}
+function project(row, fields) {
+	const out = {};
+	for (const f of ["id", ...fields]) if (f in row) out[f] = row[f];
+	return out;
+}
+function toBase64(bytes) {
+	let bin = "";
+	for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+	return typeof btoa !== "undefined" ? btoa(bin) : Buffer.from(bytes).toString("base64");
+}
+function fromBase64(b64) {
+	if (typeof atob !== "undefined") {
+		const bin = atob(b64);
+		const out = new Uint8Array(bin.length);
+		for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+		return out;
+	}
+	return new Uint8Array(Buffer.from(b64, "base64"));
+}
+
+//#endregion
+//#region src/services/database/sqlite-open.ts
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Bounded on purpose: this runs on the boot path, before the first query. */
+const DEFAULT_BACKOFF_MS = [250, 500];
+/**
+* Leader-promotion profile (~5.8s worst case). A dead leader's sync access
+* handles release when the browser garbage-collects its worker, typically
+* well under a second but not synchronously with the Web Lock release the
+* election observed, so promotion retries longer than a cold boot.
+*/
+const PROMOTION_OPEN_OPTIONS = {
+	maxAttempts: 10,
+	backoffMs: [
+		50,
+		100,
+		200,
+		400,
+		800,
+		1e3
+	]
+};
+/** Failures no retry can fix: the APIs aren't there at all (insecure context,
+*  or a browser without sync access handles). Fall back immediately. */
+const UNRETRYABLE = ["Missing required OPFS APIs"];
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Keep the DOMException name (e.g. `NoModificationAllowedError` for a pool
+*  locked by another tab): it is the most diagnostic part of the failure. */
+function errMessage(e) {
+	if (e instanceof Error) return e.name && e.name !== "Error" ? `${e.name}: ${e.message}` : e.message;
+	return String(e);
+}
+function fallbackToMemory(sqlite3, dbName, reason, attempts) {
+	const tried = attempts > 0 ? ` after ${attempts} attempt${attempts === 1 ? "" : "s"}` : "";
+	console.error(`[sp00ky] OPFS persistence unavailable for "${dbName}"${tried}: ${reason}. The local SQLite cache is running IN MEMORY, which keeps the whole dataset in RAM and loses every local write on reload. The usual cause is another tab of this app holding the storage lock, so closing the other tabs and reloading restores persistence.`);
+	return {
+		db: new sqlite3.oo1.DB(":memory:", "c"),
+		persisted: false,
+		opfsError: reason
+	};
+}
+/**
+* Open `dbName`'s handle. Never throws for a storage problem: a caller that
+* asked for persistence and can't have it gets a working in-memory handle plus
+* `persisted: false` and an `opfsError` to report.
+*/
+async function openDb(sqlite3, dbName, useOpfs, opts = {}) {
+	if (!useOpfs) return {
+		db: new sqlite3.oo1.DB(":memory:", "c"),
+		persisted: false
+	};
+	if (!sqlite3.installOpfsSAHPoolVfs) {
+		if (opts.disallowMemoryFallback) throw new Error("opfs-unavailable: sqlite-wasm build has no installOpfsSAHPoolVfs");
+		return fallbackToMemory(sqlite3, dbName, "sqlite-wasm build has no installOpfsSAHPoolVfs", 0);
+	}
+	const maxAttempts = Math.max(1, opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+	const backoffMs = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+	const sleep = opts.sleep ?? defaultSleep;
+	let lastError = "unknown error";
+	let attempts = 0;
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		attempts = attempt;
+		try {
+			const pool = await sqlite3.installOpfsSAHPoolVfs({
+				name: `sp00ky-${dbName}`,
+				...attempt > 1 ? { forceReinitIfPreviouslyFailed: true } : {}
+			});
+			return {
+				db: new pool.OpfsSAHPoolDb(`/${dbName}.sqlite3`),
+				persisted: true,
+				pool
+			};
+		} catch (e) {
+			lastError = errMessage(e);
+			if (attempt === maxAttempts || UNRETRYABLE.some((m) => lastError.includes(m))) break;
+			await sleep(backoffMs[Math.min(attempt - 1, backoffMs.length - 1)] ?? 0);
+		}
+	}
+	if (opts.disallowMemoryFallback) throw new Error(`opfs-unavailable: ${lastError} (after ${attempts} attempts)`);
+	return fallbackToMemory(sqlite3, dbName, lastError, attempts);
+}
+
+//#endregion
+export { renderOrderSql as a, serializeRow as c, projectedDataSql as i, resolveRelations as l, openDb as n, renderWhereSql as o, project as r, reviveRow as s, PROMOTION_OPEN_OPTIONS as t, stableKey as u };

package/dist/sqlite-worker.d.ts

@@ -0,0 +1 @@
+export {};