@foretag/tanstack-db-surrealdb 0.6.0 → 0.6.2

package/README.md

@@ -190,6 +190,46 @@ DEFINE INDEX crdt_doc_ts ON crdt_update FIELDS doc, ts;
 
 If a single `crdt_update` table is shared across multiple base tables, use a union type such as `record<doc> | record<sheet>`.
 
+## Permissions Templates
+
+The adapter does not manage Surreal table permissions. Define them in schema.
+
+### E2EE-only table permissions
+
+```sql
+DEFINE TABLE secret_note SCHEMAFULL
+	PERMISSIONS
+		FOR select, create, update, delete WHERE owner = $auth.id;
+```
+
+### CRDT updates table permissions (append-only)
+
+```sql
+DEFINE TABLE crdt_update SCHEMAFULL
+	PERMISSIONS
+		FOR select, create WHERE owner = $auth.id
+		FOR update, delete NONE;
+
+-- Add owner metadata on update rows for simple ACL checks
+DEFINE FIELD owner ON crdt_update TYPE record<account>;
+DEFINE INDEX crdt_owner_doc_ts ON crdt_update FIELDS owner, doc, ts;
+```
+
+### CRDT snapshots table permissions
+
+```sql
+DEFINE TABLE crdt_snapshot SCHEMAFULL
+	PERMISSIONS
+		FOR select WHERE owner = $auth.id
+		FOR create, update, delete NONE;
+
+-- Common pattern: clients read snapshots; only trusted backend writes/prunes them
+DEFINE FIELD owner ON crdt_snapshot TYPE record<account>;
+DEFINE INDEX snap_owner_doc_ts ON crdt_snapshot FIELDS owner, doc, ts;
+```
+
+If you run snapshot compaction from a trusted backend/service account, grant create/delete to that account only.
+
 ## Usage Snippets
 
 ### E2EE-only secret table

package/dist/index.d.mts

@@ -136,8 +136,6 @@ type SurrealCollectionOptionsReturn<T extends {
     utils: UtilsRecord;
 };
 
-declare const toRecordKeyString: (rid: RecordId | string) => string;
-
 interface CRDTProfileAdapter<T extends object> {
     materialize: (doc: LoroDoc, id: string) => T;
     applyLocalChange: (doc: LoroDoc, change: LocalChange<T>) => void;
@@ -150,6 +148,8 @@ declare const materializeLoroRichtext: <T extends object>(doc: LoroDoc, id: stri
 declare const applyLoroRichtextChange: <T extends object>(doc: LoroDoc, change: LocalChange<T>) => void;
 declare const createLoroProfile: <T extends object = Record<string, unknown>>(profile: LoroProfile) => CRDTProfileAdapter<T>;
 
+declare const toRecordKeyString: (rid: RecordId | string) => string;
+
 type MutationInput<T extends {
     id: string | RecordId;
 }> = Omit<T, 'id'> & {

package/dist/index.d.ts

@@ -136,8 +136,6 @@ type SurrealCollectionOptionsReturn<T extends {
     utils: UtilsRecord;
 };
 
-declare const toRecordKeyString: (rid: RecordId | string) => string;
-
 interface CRDTProfileAdapter<T extends object> {
     materialize: (doc: LoroDoc, id: string) => T;
     applyLocalChange: (doc: LoroDoc, change: LocalChange<T>) => void;
@@ -150,6 +148,8 @@ declare const materializeLoroRichtext: <T extends object>(doc: LoroDoc, id: stri
 declare const applyLoroRichtextChange: <T extends object>(doc: LoroDoc, change: LocalChange<T>) => void;
 declare const createLoroProfile: <T extends object = Record<string, unknown>>(profile: LoroProfile) => CRDTProfileAdapter<T>;
 
+declare const toRecordKeyString: (rid: RecordId | string) => string;
+
 type MutationInput<T extends {
     id: string | RecordId;
 }> = Omit<T, 'id'> & {

package/dist/index.js

@@ -6,6 +6,66 @@ var surrealdb = require('surrealdb');
 var db = require('@tanstack/db');
 
 // src/index.ts
+
+// src/crdt.ts
+var toRecord = (value) => typeof value === "object" && value !== null ? value : {};
+var materializeLoroJson = (doc, id) => {
+  const root = toRecord(doc.getMap("root").toJSON());
+  return {
+    id,
+    ...root
+  };
+};
+var applyLoroJsonChange = (doc, change) => {
+  const root = doc.getMap("root");
+  if (change.type === "delete") {
+    root.set("deleted", true);
+    return;
+  }
+  const value = toRecord(change.value);
+  for (const [key, fieldValue] of Object.entries(value)) {
+    if (key === "id") continue;
+    root.set(key, fieldValue);
+  }
+};
+var materializeLoroRichtext = (doc, id) => {
+  const metadata = toRecord(doc.getMap("root").toJSON());
+  const content = doc.getText("content").toString();
+  return {
+    id,
+    content,
+    ...metadata
+  };
+};
+var applyLoroRichtextChange = (doc, change) => {
+  const text = doc.getText("content");
+  const metadata = doc.getMap("root");
+  if (change.type === "delete") {
+    metadata.set("deleted", true);
+    return;
+  }
+  const value = toRecord(change.value);
+  for (const [key, fieldValue] of Object.entries(value)) {
+    if (key === "id") continue;
+    if (key === "content") {
+      if (typeof fieldValue === "string") text.update(fieldValue);
+      continue;
+    }
+    metadata.set(key, fieldValue);
+  }
+};
+var createLoroProfile = (profile) => {
+  if (profile === "richtext") {
+    return {
+      materialize: materializeLoroRichtext,
+      applyLocalChange: applyLoroRichtextChange
+    };
+  }
+  return {
+    materialize: materializeLoroJson,
+    applyLocalChange: applyLoroJsonChange
+  };
+};
 var recordIdIdentityPool = /* @__PURE__ */ new Map();
 var nativeRecordIdPool = /* @__PURE__ */ new Map();
 var internRecordIdIdentity = (canonical, preferred) => {
@@ -193,66 +253,6 @@ var toRecordId = (tableName, id) => {
   const key = normalized.startsWith(prefixed) ? normalized.slice(prefixed.length) : normalized;
   return new surrealdb.RecordId(tableName, key);
 };
-
-// src/crdt.ts
-var toRecord = (value) => typeof value === "object" && value !== null ? value : {};
-var materializeLoroJson = (doc, id) => {
-  const root = toRecord(doc.getMap("root").toJSON());
-  return {
-    id,
-    ...root
-  };
-};
-var applyLoroJsonChange = (doc, change) => {
-  const root = doc.getMap("root");
-  if (change.type === "delete") {
-    root.set("deleted", true);
-    return;
-  }
-  const value = toRecord(change.value);
-  for (const [key, fieldValue] of Object.entries(value)) {
-    if (key === "id") continue;
-    root.set(key, fieldValue);
-  }
-};
-var materializeLoroRichtext = (doc, id) => {
-  const metadata = toRecord(doc.getMap("root").toJSON());
-  const content = doc.getText("content").toString();
-  return {
-    id,
-    content,
-    ...metadata
-  };
-};
-var applyLoroRichtextChange = (doc, change) => {
-  const text = doc.getText("content");
-  const metadata = doc.getMap("root");
-  if (change.type === "delete") {
-    metadata.set("deleted", true);
-    return;
-  }
-  const value = toRecord(change.value);
-  for (const [key, fieldValue] of Object.entries(value)) {
-    if (key === "id") continue;
-    if (key === "content") {
-      if (typeof fieldValue === "string") text.update(fieldValue);
-      continue;
-    }
-    metadata.set(key, fieldValue);
-  }
-};
-var createLoroProfile = (profile) => {
-  if (profile === "richtext") {
-    return {
-      materialize: materializeLoroRichtext,
-      applyLocalChange: applyLoroRichtextChange
-    };
-  }
-  return {
-    materialize: materializeLoroJson,
-    applyLocalChange: applyLoroJsonChange
-  };
-};
 var IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var firstRow = (res) => {
   if (!res) return void 0;
@@ -291,11 +291,12 @@ var mapRelationPath = (path, relation) => {
   return path;
 };
 var normalizeFilterValue = (value) => {
-  if (Array.isArray(value)) {
+  if (Array.isArray(value))
     return value.map((item) => normalizeFilterValue(item));
-  }
   const native = toNativeRecordIdLikeValue(value);
   if (native !== value) return native;
+  if (value && typeof value === "object")
+    return normalizeRecordIdLikeValue(value);
   return normalizeRecordIdLikeValue(value);
 };
 var toSqlFragment = (value) => {
@@ -454,7 +455,8 @@ function manageTable(db, config) {
       if (action === "KILLED") return;
       if (action === "CREATE") cb({ type: "insert", row: value });
       else if (action === "UPDATE") cb({ type: "update", row: value });
-      else if (action === "DELETE") cb({ type: "delete", row: { id: value.id } });
+      else if (action === "DELETE")
+        cb({ type: "delete", row: { id: value.id } });
     };
     const start = async () => {
       if (!db.isFeatureSupported(surrealdb.Features.LiveQueries)) return;
@@ -687,7 +689,8 @@ function createInsertSchema(tableName) {
         const data = normalizeRecordIdLikeFields({
           ...value
         });
-        if (!data.id) data.id = createTempRecordId(tableName);
+        if (!data.id)
+          data.id = createTempRecordId(tableName);
         return { value: data };
       },
       types: void 0
@@ -942,7 +945,9 @@ function modernSurrealCollectionOptions(config) {
     const ensureBaseLive = async () => {
       if (cleanupBaseLive !== NOOP) return;
       if (!db.isFeatureSupported?.(surrealdb.Features.LiveQueries)) return;
-      const live = await db.live(tableResource);
+      const live = await db.live(
+        tableResource
+      );
       if (killed) {
         await live.kill();
         return;
@@ -952,14 +957,18 @@ function modernSurrealCollectionOptions(config) {
         const row = message.value;
         const id = toRecordKeyString(row.id);
         const wasVisible = activeOnDemandIds.has(id);
-        if (isStrictOnDemand && !wasVisible && message.action !== "DELETE") return;
+        if (isStrictOnDemand && !wasVisible && message.action !== "DELETE")
+          return;
         if (message.action === "DELETE") {
           for (const ids of subsetIds.values()) ids.delete(id);
           updateActiveOnDemandIds();
           if (isStrictOnDemand && !wasVisible) return;
           ctx.begin();
           try {
-            ctx.write({ type: "delete", key: `${tableName}:${id}` });
+            ctx.write({
+              type: "delete",
+              key: `${tableName}:${id}`
+            });
           } finally {
             ctx.commit();
           }
@@ -985,7 +994,9 @@ function modernSurrealCollectionOptions(config) {
       if (!crdtEnabled || !updatesTable) return;
       if (cleanupUpdateLive !== NOOP) return;
       if (!db.isFeatureSupported?.(surrealdb.Features.LiveQueries)) return;
-      const live = await db.live(updatesTable);
+      const live = await db.live(
+        updatesTable
+      );
       if (killed) {
         await live.kill();
         return;
@@ -1037,7 +1048,13 @@ function modernSurrealCollectionOptions(config) {
         return;
       }
       for (const id of ids) {
-        await hydrateCrdtDoc(id, ctx.write, ctx.begin, ctx.commit, "insert");
+        await hydrateCrdtDoc(
+          id,
+          ctx.write,
+          ctx.begin,
+          ctx.commit,
+          "insert"
+        );
       }
       await ensureUpdateLive();
     };
@@ -1085,13 +1102,19 @@ function modernSurrealCollectionOptions(config) {
         }
         if (!crdtEnabled) {
           if (!isOnDemandLike) {
-            const rows2 = await toRecordArray(await db.select(tableResource));
+            const rows2 = await toRecordArray(
+              await db.select(tableResource)
+            );
             const decoded2 = await Promise.all(
-              rows2.map((row) => decodeBaseRow(row))
+              rows2.map(
+                (row) => decodeBaseRow(row)
+              )
             );
             return decoded2;
           }
-          const rows = await tableAccess.loadSubset(meta?.loadSubsetOptions);
+          const rows = await tableAccess.loadSubset(
+            meta?.loadSubsetOptions
+          );
           const decoded = await Promise.all(
             rows.map(
               (row) => decodeBaseRow(row)
@@ -1177,7 +1200,9 @@ function modernSurrealCollectionOptions(config) {
       const writeUtils = getWriteUtils(params.collection.utils);
       for (const mutation of params.transaction.mutations) {
         if (mutation.type !== "update") continue;
-        const mutationId = normalizeMutationId(mutation.key);
+        const mutationId = normalizeMutationId(
+          mutation.key
+        );
         const normalizedModified = omitUndefined(
           normalizeRecordIdLikeFields({
             ...mutation.modified
@@ -1209,7 +1234,9 @@ function modernSurrealCollectionOptions(config) {
             toRecordKeyString(mutationId)
           );
           await db.update(mutationId).merge(encoded);
-          writeUtils.writeUpsert?.(normalizeRow({ ...decodedCurrent, ...merged }));
+          writeUtils.writeUpsert?.(
+            normalizeRow({ ...decodedCurrent, ...merged })
+          );
           continue;
         }
         const id = toRecordKeyString(mutationId);
@@ -1232,7 +1259,9 @@ function modernSurrealCollectionOptions(config) {
       const writeUtils = getWriteUtils(params.collection.utils);
       for (const mutation of params.transaction.mutations) {
         if (mutation.type !== "delete") continue;
-        const mutationId = normalizeMutationId(mutation.key);
+        const mutationId = normalizeMutationId(
+          mutation.key
+        );
         const id = toRecordKeyString(mutationId);
         if (!crdtEnabled) {
           await db.delete(mutationId);
@@ -1259,14 +1288,22 @@ function modernSurrealCollectionOptions(config) {
       const canRunBaseSync = typeof ctx.collection?.on === "function";
       const baseResult = canRunBaseSync ? baseSync(ctx) : void 0;
       const baseCleanup = typeof baseResult === "function" ? baseResult : typeof baseResult === "object" && baseResult && "cleanup" in baseResult && typeof baseResult.cleanup === "function" ? baseResult.cleanup : NOOP;
-      const runtime = createSyncRuntime(ctx);
+      const runtime = createSyncRuntime(
+        ctx
+      );
       const start = async () => {
         if (!isOnDemandLike) {
           if (!crdtEnabled) {
             const rows = toRecordArray(
               await db.select(tableResource)
             );
-            await hydratePlainRows(rows, ctx.write, ctx.begin, ctx.commit, "insert");
+            await hydratePlainRows(
+              rows,
+              ctx.write,
+              ctx.begin,
+              ctx.commit,
+              "insert"
+            );
             await runtime.startRealtime();
             ctx.markReady();
             return;
@@ -1280,7 +1317,10 @@ function modernSurrealCollectionOptions(config) {
             for (const update of updates) {
               const id = idFromDocRef(update.doc);
               const doc = getDoc(id);
-              const bytes = await decodeUpdateBytes(update, "update");
+              const bytes = await decodeUpdateBytes(
+                update,
+                "update"
+              );
               if (!bytes.byteLength) continue;
               doc.import(bytes);
             }
@@ -1289,7 +1329,9 @@ function modernSurrealCollectionOptions(config) {
               for (const [id, doc] of docs.entries()) {
                 ctx.write({
                   type: "insert",
-                  value: normalizeRow(materializeCrdt(doc, id))
+                  value: normalizeRow(
+                    materializeCrdt(doc, id)
+                  )
                 });
               }
             } finally {