@fragno-dev/tanstack-db-adapter 0.0.0-stage → 0.0.0

package/dist/protocol.js

@@ -0,0 +1,115 @@
+import "@fragno-dev/db/database-namespace";
+import superjson from "superjson";
+//#region src/protocol.ts
+function decodeFragnoOutboxPayload(payload) {
+	const decoded = superjson.deserialize(payload);
+	if (!isRecord(decoded)) throw new Error("Invalid Fragno outbox payload.");
+	if (decoded["version"] !== 2) throw new Error(`Unsupported Fragno outbox payload version: ${String(decoded["version"])}.`);
+	if (!Array.isArray(decoded["operations"])) throw new Error("Invalid Fragno outbox operations.");
+	for (const mutation of decoded["operations"]) {
+		if (!isRecord(mutation)) throw new Error("Invalid Fragno outbox mutation.");
+		const operation = mutation["op"];
+		if (operation !== "create" && operation !== "update" && operation !== "delete" && operation !== "truncate") throw new Error(`Unsupported Fragno outbox mutation operation: ${String(operation)}.`);
+		if (operation === "truncate") {
+			const match = mutation["match"];
+			if (!isRecord(match)) throw new Error("Fragno outbox truncate match must be an object.");
+			if (!Object.values(match).every(isOutboxMatchScalar)) throw new Error("Fragno outbox truncate match values must be scalars.");
+			const externalIds = mutation["externalIds"];
+			if (!Array.isArray(externalIds) || externalIds.length === 0 || !externalIds.every((externalId) => typeof externalId === "string" && externalId.length > 0)) throw new Error("Fragno outbox truncate external IDs must be non-empty strings.");
+		}
+	}
+	return decoded;
+}
+function projectFragnoOutboxOperations(entry, operations, target) {
+	const table = target.schema.tables[target.table];
+	const externalIdColumnName = table.getIdColumn().name;
+	const changes = [];
+	for (const mutation of operations) {
+		if (mutation.op === "truncate") {
+			for (const externalId of mutation.externalIds) changes.push({
+				type: "delete",
+				key: externalId,
+				origin: "truncate"
+			});
+			continue;
+		}
+		const resolvedMutation = resolveMutationRefs(mutation, table, entry.refMap ?? {});
+		if (resolvedMutation.op === "create") {
+			changes.push({
+				type: "insert",
+				key: resolvedMutation.externalId,
+				value: {
+					...resolvedMutation.values,
+					[externalIdColumnName]: resolvedMutation.externalId
+				}
+			});
+			continue;
+		}
+		if (resolvedMutation.op === "update") {
+			changes.push({
+				type: "update",
+				key: resolvedMutation.externalId,
+				value: {
+					...resolvedMutation.set,
+					[externalIdColumnName]: resolvedMutation.externalId
+				}
+			});
+			continue;
+		}
+		changes.push({
+			type: "delete",
+			key: resolvedMutation.externalId,
+			origin: "delete"
+		});
+	}
+	return changes;
+}
+function fragnoOutboxOperationTarget(operation) {
+	return {
+		namespace: operation.namespace ?? operation.schema,
+		table: operation.table
+	};
+}
+/** Converts the protocol plan to TanStack messages at the sync boundary. */
+function toTanStackChangeMessage(change) {
+	if (change.type === "delete") return {
+		type: "delete",
+		key: change.key
+	};
+	return {
+		type: change.type,
+		value: change.value
+	};
+}
+function isOutboxMatchScalar(value) {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean";
+}
+function resolveMutationRefs(mutation, table, refMap) {
+	if (mutation.op === "create") return {
+		...mutation,
+		values: resolveRecordRefs(mutation.values, table, refMap)
+	};
+	if (mutation.op === "update") return {
+		...mutation,
+		set: resolveRecordRefs(mutation.set, table, refMap)
+	};
+	return mutation;
+}
+function resolveRecordRefs(values, table, refMap) {
+	return Object.fromEntries(Object.entries(values).map(([key, value]) => {
+		if (table.columns[key]?.role !== "reference" || !isReferencePlaceholder(value)) return [key, value];
+		const resolved = refMap[value.__fragno_ref];
+		if (resolved === void 0) throw new Error(`Fragno outbox reference ${value.__fragno_ref} was not resolved.`);
+		return [key, resolved];
+	}));
+}
+function isReferencePlaceholder(value) {
+	return isRecord(value) && Object.keys(value).length === 1 && typeof value["__fragno_ref"] === "string";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+export { decodeFragnoOutboxPayload, fragnoOutboxOperationTarget, projectFragnoOutboxOperations, toTanStackChangeMessage };
+
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","names":[],"sources":["../src/protocol.ts"],"sourcesContent":["import { resolveDatabaseNamespace } from \"@fragno-dev/db/database-namespace\";\nimport type { TableToColumnValues } from \"@fragno-dev/db/query\";\nimport type { AnySchema, AnyTable, FragnoId, FragnoReference } from \"@fragno-dev/db/schema\";\nimport superjson, { type SuperJSONResult } from \"superjson\";\n\nimport type {\n  OutboxEntry,\n  OutboxMatchScalar,\n  OutboxMutation,\n  OutboxOperation,\n  OutboxPayload,\n} from \"@fragno-dev/db\";\n\nimport type { ChangeMessageOrDeleteKeyMessage } from \"@tanstack/db\";\n\nexport type FragnoCollectionTarget<\n  TSchema extends AnySchema = AnySchema,\n  TTableName extends keyof TSchema[\"tables\"] & string = keyof TSchema[\"tables\"] & string,\n> = {\n  schema: TSchema;\n  table: TTableName;\n  /** Defaults to the schema's sanitized database namespace. Use null for no namespace. */\n  namespace?: string | null;\n};\n\ntype MaterializedColumnValue<TValue> = TValue extends FragnoId | FragnoReference ? string : TValue;\n\ntype VisibleTableValues<TTable extends AnyTable> = TableToColumnValues<TTable>;\n\nexport type FragnoCollectionRow<TTable extends AnyTable> = {\n  [TColumnName in keyof VisibleTableValues<TTable> as [\n    VisibleTableValues<TTable>[TColumnName],\n  ] extends [null]\n    ? never\n    : TColumnName]: MaterializedColumnValue<VisibleTableValues<TTable>[TColumnName]>;\n};\n\nexport type FragnoOutboxEntry = Pick<OutboxEntry, \"versionstamp\" | \"uowId\" | \"payload\" | \"refMap\">;\n\nexport type FragnoCollectionChange<TRow extends object> =\n  | {\n      type: \"insert\";\n      key: string;\n      value: TRow;\n    }\n  | {\n      type: \"update\";\n      key: string;\n      value: Partial<TRow>;\n    }\n  | {\n      type: \"delete\";\n      key: string;\n      origin: \"delete\" | \"truncate\";\n    };\n\nexport function decodeFragnoOutboxPayload(payload: unknown): OutboxPayload {\n  const decoded = superjson.deserialize(payload as SuperJSONResult) as unknown;\n\n  if (!isRecord(decoded)) {\n    throw new Error(\"Invalid Fragno outbox payload.\");\n  }\n  if (decoded[\"version\"] !== 2) {\n    throw new Error(`Unsupported Fragno outbox payload version: ${String(decoded[\"version\"])}.`);\n  }\n  if (!Array.isArray(decoded[\"operations\"])) {\n    throw new Error(\"Invalid Fragno outbox operations.\");\n  }\n\n  for (const mutation of decoded[\"operations\"]) {\n    if (!isRecord(mutation)) {\n      throw new Error(\"Invalid Fragno outbox mutation.\");\n    }\n\n    const operation = mutation[\"op\"];\n    if (\n      operation !== \"create\" &&\n      operation !== \"update\" &&\n      operation !== \"delete\" &&\n      operation !== \"truncate\"\n    ) {\n      throw new Error(`Unsupported Fragno outbox mutation operation: ${String(operation)}.`);\n    }\n    if (operation === \"truncate\") {\n      const match = mutation[\"match\"];\n      if (!isRecord(match)) {\n        throw new Error(\"Fragno outbox truncate match must be an object.\");\n      }\n      if (!Object.values(match).every(isOutboxMatchScalar)) {\n        throw new Error(\"Fragno outbox truncate match values must be scalars.\");\n      }\n      const externalIds = mutation[\"externalIds\"];\n      if (\n        !Array.isArray(externalIds) ||\n        externalIds.length === 0 ||\n        !externalIds.every((externalId) => typeof externalId === \"string\" && externalId.length > 0)\n      ) {\n        throw new Error(\"Fragno outbox truncate external IDs must be non-empty strings.\");\n      }\n    }\n  }\n\n  return decoded as OutboxPayload;\n}\n\nexport function projectFragnoOutboxEntry<\n  TSchema extends AnySchema,\n  TTableName extends keyof TSchema[\"tables\"] & string,\n>(\n  entry: FragnoOutboxEntry,\n  target: FragnoCollectionTarget<TSchema, TTableName>,\n): FragnoCollectionChange<FragnoCollectionRow<TSchema[\"tables\"][TTableName]>>[] {\n  const payload = decodeFragnoOutboxPayload(entry.payload);\n  const targetNamespace = resolveDatabaseNamespace(target.schema.name, target.namespace) ?? \"\";\n  const operations = payload.operations.filter((operation) => {\n    const operationTarget = fragnoOutboxOperationTarget(operation);\n    return operationTarget.namespace === targetNamespace && operationTarget.table === target.table;\n  });\n  return projectFragnoOutboxOperations(entry, operations, target);\n}\n\nexport function projectFragnoOutboxOperations<\n  TSchema extends AnySchema,\n  TTableName extends keyof TSchema[\"tables\"] & string,\n>(\n  entry: FragnoOutboxEntry,\n  operations: readonly OutboxOperation[],\n  target: FragnoCollectionTarget<TSchema, TTableName>,\n): FragnoCollectionChange<FragnoCollectionRow<TSchema[\"tables\"][TTableName]>>[] {\n  type Row = FragnoCollectionRow<TSchema[\"tables\"][TTableName]>;\n\n  const table = target.schema.tables[target.table];\n  const externalIdColumnName = table.getIdColumn().name;\n  const changes: FragnoCollectionChange<Row>[] = [];\n\n  for (const mutation of operations) {\n    if (mutation.op === \"truncate\") {\n      for (const externalId of mutation.externalIds) {\n        changes.push({\n          type: \"delete\",\n          key: externalId,\n          origin: \"truncate\",\n        });\n      }\n      continue;\n    }\n\n    const resolvedMutation = resolveMutationRefs(mutation, table, entry.refMap ?? {});\n    if (resolvedMutation.op === \"create\") {\n      changes.push({\n        type: \"insert\",\n        key: resolvedMutation.externalId,\n        value: {\n          ...resolvedMutation.values,\n          [externalIdColumnName]: resolvedMutation.externalId,\n        } as Row,\n      });\n      continue;\n    }\n\n    if (resolvedMutation.op === \"update\") {\n      changes.push({\n        type: \"update\",\n        key: resolvedMutation.externalId,\n        value: {\n          ...resolvedMutation.set,\n          [externalIdColumnName]: resolvedMutation.externalId,\n        } as Partial<Row>,\n      });\n      continue;\n    }\n\n    changes.push({\n      type: \"delete\",\n      key: resolvedMutation.externalId,\n      origin: \"delete\",\n    });\n  }\n\n  return changes;\n}\n\nexport function fragnoOutboxOperationTarget(operation: OutboxOperation): {\n  namespace: string;\n  table: string;\n} {\n  return {\n    namespace: operation.namespace ?? operation.schema,\n    table: operation.table,\n  };\n}\n\n/** Converts the protocol plan to TanStack messages at the sync boundary. */\nexport function toTanStackChangeMessage<TRow extends object>(\n  change: FragnoCollectionChange<TRow>,\n): ChangeMessageOrDeleteKeyMessage<TRow, string> {\n  if (change.type === \"delete\") {\n    return {\n      type: \"delete\",\n      key: change.key,\n    };\n  }\n\n  return {\n    type: change.type,\n    value: change.value as TRow,\n  };\n}\n\nfunction isOutboxMatchScalar(value: unknown): value is OutboxMatchScalar {\n  return (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"number\" ||\n    typeof value === \"bigint\" ||\n    typeof value === \"boolean\"\n  );\n}\n\nfunction resolveMutationRefs(\n  mutation: OutboxMutation,\n  table: AnyTable,\n  refMap: Record<string, string>,\n): OutboxMutation {\n  if (mutation.op === \"create\") {\n    return { ...mutation, values: resolveRecordRefs(mutation.values, table, refMap) };\n  }\n\n  if (mutation.op === \"update\") {\n    return { ...mutation, set: resolveRecordRefs(mutation.set, table, refMap) };\n  }\n\n  return mutation;\n}\n\nfunction resolveRecordRefs(\n  values: Record<string, unknown>,\n  table: AnyTable,\n  refMap: Record<string, string>,\n): Record<string, unknown> {\n  return Object.fromEntries(\n    Object.entries(values).map(([key, value]) => {\n      if (table.columns[key]?.role !== \"reference\" || !isReferencePlaceholder(value)) {\n        return [key, value];\n      }\n\n      const resolved = refMap[value.__fragno_ref];\n      if (resolved === undefined) {\n        throw new Error(`Fragno outbox reference ${value.__fragno_ref} was not resolved.`);\n      }\n\n      return [key, resolved];\n    }),\n  );\n}\n\nfunction isReferencePlaceholder(value: unknown): value is { __fragno_ref: string } {\n  return (\n    isRecord(value) && Object.keys(value).length === 1 && typeof value[\"__fragno_ref\"] === \"string\"\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@fragno-dev/tanstack-db-adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Ingest Fragno database outboxes into TanStack DB collections",
+  "homepage": "https://fragno.dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rejot-dev/fragno.git",
+    "directory": "packages/tanstack-db-adapter"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/coordinator.js",
+  "module": "./dist/coordinator.js",
+  "types": "./dist/coordinator.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/coordinator.d.ts",
+      "default": "./dist/coordinator.js"
+    }
+  },
+  "dependencies": {
+    "@tanstack/db-sqlite-persistence-core": "0.4.11",
+    "superjson": "^2.2.1",
+    "@fragno-dev/db": "0.4.1"
+  },
+  "devDependencies": {
+    "@journeyapps/wa-sqlite": "^1.4.1",
+    "@tanstack/browser-db-sqlite-persistence": "^0.2.36",
+    "@tanstack/db": "^0.15.1",
+    "@tanstack/node-db-sqlite-persistence": "^0.2.36",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.19.7",
+    "@vitest/coverage-istanbul": "^4.1.0",
+    "better-sqlite3": "^12.6.2",
+    "tsdown": "^0.22.4",
+    "vitest": "^4.1.4",
+    "@fragno-dev/core": "0.2.2",
+    "@fragno-dev/test": "2.0.2",
+    "@fragno-private/vitest-config": "0.0.0",
+    "@fragno-private/typescript-config": "0.0.1"
+  },
+  "peerDependencies": {
+    "@fragno-dev/core": "^0.2.2",
+    "@fragno-dev/test": "^2.0.0",
+    "@journeyapps/wa-sqlite": "^1.4.1",
+    "@tanstack/browser-db-sqlite-persistence": "^0.2.36",
+    "@tanstack/db": "^0.15.1",
+    "@tanstack/node-db-sqlite-persistence": "^0.2.36",
+    "better-sqlite3": "^12.6.2"
+  },
+  "peerDependenciesMeta": {
+    "@fragno-dev/core": {
+      "optional": true
+    },
+    "@fragno-dev/test": {
+      "optional": true
+    },
+    "@journeyapps/wa-sqlite": {
+      "optional": true
+    },
+    "@tanstack/browser-db-sqlite-persistence": {
+      "optional": true
+    },
+    "@tanstack/node-db-sqlite-persistence": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
+    "types:check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "format:package": "node ../../scripts/run-package-quality.mjs format",
+    "format:check:package": "node ../../scripts/run-package-quality.mjs format:check",
+    "lint:package": "node ../../scripts/run-package-quality.mjs lint",
+    "lint:fix:package": "node ../../scripts/run-package-quality.mjs lint:fix"
+  }
 }