@spooky-sync/core 0.0.1-canary.15 → 0.0.1-canary.151

package/dist/otel/index.d.ts

@@ -0,0 +1,21 @@
+import { u as PinoTransmit } from "../types.js";
+import { Level } from "pino";
+
+//#region src/otel/index.d.ts
+
+/**
+ * Creates a pino browser transmit object that forwards logs to an OpenTelemetry collector.
+ *
+ * @example
+ * ```ts
+ * import { createOtelTransmit } from '@spooky-sync/core/otel';
+ *
+ * new Sp00kyClient({
+ *   // ...
+ *   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
+ * });
+ * ```
+ */
+declare function createOtelTransmit(endpoint: string, level?: Level): PinoTransmit;
+//#endregion
+export { createOtelTransmit };

package/dist/otel/index.js

@@ -0,0 +1,86 @@
+//#region src/otel/index.ts
+function mapLevelToSeverityNumber(level) {
+	switch (level) {
+		case "trace": return 1;
+		case "debug": return 5;
+		case "info": return 9;
+		case "warn": return 13;
+		case "error": return 17;
+		case "fatal": return 21;
+		default: return 9;
+	}
+}
+async function loadOtelModules(otelEndpoint) {
+	const [{ LoggerProvider, BatchLogRecordProcessor }, { OTLPLogExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] = await Promise.all([
+		import("@opentelemetry/sdk-logs"),
+		import("@opentelemetry/exporter-logs-otlp-proto"),
+		import("@opentelemetry/resources"),
+		import("@opentelemetry/semantic-conventions")
+	]);
+	const loggerProvider = new LoggerProvider({
+		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "sp00ky-client" }),
+		processors: [new BatchLogRecordProcessor(new OTLPLogExporter({ url: otelEndpoint }))]
+	});
+	const otelLoggerCache = {};
+	return (category) => {
+		if (!otelLoggerCache[category]) otelLoggerCache[category] = loggerProvider.getLogger(category);
+		return otelLoggerCache[category];
+	};
+}
+/**
+* Creates a pino browser transmit object that forwards logs to an OpenTelemetry collector.
+*
+* @example
+* ```ts
+* import { createOtelTransmit } from '@spooky-sync/core/otel';
+*
+* new Sp00kyClient({
+*   // ...
+*   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
+* });
+* ```
+*/
+function createOtelTransmit(endpoint, level = "info") {
+	const otelReady = loadOtelModules(endpoint);
+	return {
+		level,
+		send: (levelLabel, logEvent) => {
+			otelReady.then((getOtelLogger) => {
+				try {
+					const messages = [...logEvent.messages];
+					const severityNumber = mapLevelToSeverityNumber(levelLabel);
+					let body = "";
+					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) {
+							category = msg.Category;
+							delete msg.Category;
+						}
+						Object.assign(attributes, msg);
+					}
+					getOtelLogger(category).emit({
+						severityNumber,
+						severityText: levelLabel.toUpperCase(),
+						body,
+						attributes: {
+							...logEvent.bindings[0],
+							...attributes
+						},
+						timestamp: new Date(logEvent.ts)
+					});
+				} catch (e) {
+					console.warn("Failed to transmit log to OTEL endpoint", e);
+				}
+			}).catch((e) => {
+				console.warn("Failed to load OpenTelemetry modules", e);
+			});
+		}
+	};
+}
+
+//#endregion
+export { createOtelTransmit };

package/dist/sqlite-plan-sql.js

@@ -0,0 +1,194 @@
+//#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;
+		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);
+		parent[relation.alias] = isOne ? bucket[0] ?? null : bucket;
+	}
+}
+/**
+* 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;
+	});
+}
+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
+export { serializeRow as a, reviveRow as i, renderOrderSql as n, resolveRelations as o, renderWhereSql as r, stableKey as s, project as t };

package/dist/sqlite-worker.d.ts

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

package/dist/sqlite-worker.js

@@ -0,0 +1,202 @@
+import { i as reviveRow, n as renderOrderSql, o as resolveRelations, r as renderWhereSql, s as stableKey, t as project } from "./sqlite-plan-sql.js";
+import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+
+//#region src/services/database/sqlite-select.ts
+function ensureTable(db, table) {
+	if (db.knownTables.has(table)) return;
+	db.run(`CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`);
+	db.knownTables.add(table);
+}
+function execRows(db, sql, bind) {
+	return db.exec(sql, bind).map((r) => reviveRow(r.data));
+}
+/** Mirrors the engine's `selectByIds`: fetch by primary id, preserving `ids`
+*  order unless an ORDER BY overrides it. */
+function selectByIds(db, table, ids, opts) {
+	if (ids.length === 0) return [];
+	ensureTable(db, table);
+	const keys = ids.map(stableKey);
+	let sql = `SELECT data FROM "${table}" WHERE id IN (${keys.map(() => "?").join(", ")})`;
+	if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
+	let rows = execRows(db, sql, keys);
+	if (!opts?.orderBy || opts.orderBy.length === 0) {
+		const pos = new Map(keys.map((k, i) => [k, i]));
+		rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
+	}
+	return opts?.select ? rows.map((r) => project(r, opts.select)) : rows;
+}
+/** Mirrors the engine's `fetchRelation` SQL exactly. */
+function fetchRelation(db, req) {
+	ensureTable(db, req.table);
+	const keys = req.keys.map(stableKey);
+	const placeholders = keys.map(() => "?").join(", ");
+	const bind = [...keys];
+	const lhs = req.matchField === "id" ? "id" : `json_extract(data, '$.${req.matchField}')`;
+	let sql = `SELECT data FROM "${req.table}" WHERE ${lhs} IN (${placeholders})`;
+	if (req.where && req.where.length > 0) sql += ` AND ${renderWhereSql(req.where, bind, {})}`;
+	if (req.orderBy && req.orderBy.length > 0) sql += renderOrderSql(req.orderBy);
+	const rows = execRows(db, sql, bind);
+	return req.select ? rows.map((r) => project(r, req.select)) : rows;
+}
+async function executeSelect(plan, params, db) {
+	const counter = { n: 0 };
+	const fetcher = { fetchRelation: (req) => {
+		counter.n++;
+		return Promise.resolve(fetchRelation(db, req));
+	} };
+	if (plan.ids) {
+		const rows = selectByIds(db, plan.table, plan.ids, {
+			select: plan.select,
+			orderBy: plan.orderBy
+		});
+		await resolveRelations(rows, plan.relations, fetcher);
+		return {
+			rows,
+			relationFetches: counter.n
+		};
+	}
+	ensureTable(db, plan.table);
+	const bind = [];
+	let sql = `SELECT data FROM "${plan.table}"`;
+	if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
+	if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
+	if (plan.limit !== void 0) sql += ` LIMIT ${Number(plan.limit)}`;
+	if (plan.offset !== void 0) sql += ` OFFSET ${Number(plan.offset)}`;
+	const rows = execRows(db, sql, bind);
+	const projected = plan.select ? rows.map((r) => project(r, plan.select)) : rows;
+	await resolveRelations(projected, plan.relations, fetcher);
+	return {
+		rows: projected,
+		relationFetches: counter.n
+	};
+}
+
+//#endregion
+//#region src/services/database/sqlite-worker.ts
+/**
+* Dedicated Web Worker that owns the SQLite-WASM handle. All DB access is
+* funnelled through here (the main thread never touches the wasm module), which
+* is also what the OPFS VFS requires — file access must happen off the main
+* thread. Persistence uses the **OPFS SAHPool VFS**: durable, and (unlike the
+* classic OPFS VFS) it does NOT require COOP/COEP cross-origin isolation
+* headers, so host apps embedding the client need no server changes. Falls back
+* to an in-memory DB when OPFS is unavailable.
+*
+* Message protocol (request/response keyed by `id`):
+*   { id, type: 'open',   payload: { dbName, useOpfs } }
+*   { id, type: 'exec',   payload: { sql, bind } }  -> { id, ok, rows }
+*   { id, type: 'run',    payload: { sql, bind } }  -> { id, ok }
+*   { id, type: 'batch',  payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+*   { id, type: 'select', payload: { plan, params } } -> { id, ok, rows, relationFetches }
+*   { id, type: 'close' }
+*
+* `select` executes a whole QueryPlan — table creation, base select, the full
+* `.related()` tree (shared `resolveRelations`), and JSON row parsing — in ONE
+* round-trip, returning structured-clone row objects. This is the first-load
+* hot path; the per-statement ops remain for the write/shim paths.
+*/
+let db = null;
+async function open(dbName, useOpfs, systemTables = []) {
+	const sqlite3 = await sqlite3InitModule();
+	let persisted = false;
+	if (useOpfs && sqlite3.installOpfsSAHPoolVfs) try {
+		db = new (await (sqlite3.installOpfsSAHPoolVfs({ name: `sp00ky-${dbName}` }))).OpfsSAHPoolDb(`/${dbName}.sqlite3`);
+		persisted = true;
+	} catch {}
+	if (!db) db = new sqlite3.oo1.DB(":memory:", "c");
+	for (const t of systemTables) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+	try {
+		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
+	} catch {}
+	return { persisted };
+}
+function exec(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	return db.exec({
+		sql,
+		bind,
+		rowMode: "object",
+		returnValue: "resultRows"
+	});
+}
+function run(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({
+		sql,
+		bind
+	});
+}
+function batch(stmts) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({ sql: "BEGIN" });
+	try {
+		for (const s of stmts) db.exec({
+			sql: s.sql,
+			bind: s.bind
+		});
+		db.exec({ sql: "COMMIT" });
+	} catch (e) {
+		try {
+			db.exec({ sql: "ROLLBACK" });
+		} catch {}
+		throw e;
+	}
+}
+/** DB handle for `executeSelect` (see `sqlite-select.ts`, the unit-testable
+*  plan executor). `knownTables` is cleared on open/close — a bucket switch
+*  spawns a fresh worker anyway. */
+const selectDb = {
+	exec: (sql, bind) => exec(sql, bind),
+	run,
+	knownTables: /* @__PURE__ */ new Set()
+};
+self.onmessage = async (ev) => {
+	const { id, type, payload } = ev.data ?? {};
+	const t0 = performance.now();
+	try {
+		let result;
+		switch (type) {
+			case "open":
+				selectDb.knownTables.clear();
+				result = await open(payload.dbName, payload.useOpfs, payload.systemTables);
+				for (const t of payload.systemTables ?? []) selectDb.knownTables.add(t);
+				break;
+			case "select":
+				result = await executeSelect(payload.plan, payload.params ?? {}, selectDb);
+				break;
+			case "exec":
+				result = { rows: exec(payload.sql, payload.bind) };
+				break;
+			case "run":
+				run(payload.sql, payload.bind);
+				result = {};
+				break;
+			case "batch":
+				batch(payload);
+				result = {};
+				break;
+			case "close":
+				db?.close();
+				db = null;
+				selectDb.knownTables.clear();
+				result = {};
+				break;
+			default: throw new Error(`sqlite worker: unknown message ${type}`);
+		}
+		self.postMessage({
+			id,
+			ok: true,
+			wt: performance.now() - t0,
+			...result
+		});
+	} catch (err) {
+		self.postMessage({
+			id,
+			ok: false,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+};
+
+//#endregion
+export {  };