@foretag/tanstack-db-surrealdb 0.6.12 → 0.7.0

package/README.md

@@ -8,10 +8,6 @@ TanStack DB collection adapter for SurrealDB JS with:
 - Optional Loro CRDT replication (`json`, `richtext`)
 - Query-driven sync modes (`eager`, `on-demand`, `progressive`)
 
-### Roadmap
-
-- Persistence: [Issue](https://github.com/TanStack/db/issues/865)
-
 ## Install
 
 ```sh
@@ -34,45 +30,138 @@ const queryClient = new QueryClient();
 type Product = { id: string; name: string; price: number };
 
 export const products = createCollection(
-  surrealCollectionOptions<Product>({
-    db,
-    table: { name: 'product' },
-    queryClient,
-    queryKey: ['product'],
-    syncMode: 'eager',
-  }),
+	surrealCollectionOptions<Product>({
+		db,
+		table: { name: 'product' },
+		queryClient,
+		queryKey: ['product'],
+		syncMode: 'eager',
+	}),
 );
 ```
 
+## Persistence
+
+TanStack DB persistence can wrap this adapter directly. The adapter now returns a
+stable collection `id` by default using:
+
+```ts
+surreal:${tableName}:${hashKey(queryKey)}
+```
+
+That makes it safe to compose with `persistedCollectionOptions(...)` across
+restarts. If you need a custom persistence boundary, pass `id` explicitly and it
+will be preserved.
+
+If you want less boilerplate, use `persistedSurrealCollectionOptions(...)` from
+this package and pass the runtime-specific `persistence` adapter plus
+`schemaVersion` directly.
+
+Create the SQLite database and persistence adapter once per app/runtime, export
+that shared `persistence`, and reuse it across every persisted collection in
+the app.
+
+```ts
+// Create once, reuse everywhere
+const sqlite = await openBrowserWASQLiteOPFSDatabase({
+	databaseName: 'tanstack-db.sqlite',
+});
+
+export const persistence = createBrowserWASQLitePersistence({
+	database: sqlite,
+});
+```
+
+Browser-first example:
+
+```ts
+// persistence.ts
+import { createCollection } from '@tanstack/db';
+import { QueryClient } from '@tanstack/query-core';
+import {
+  createBrowserWASQLitePersistence,
+  openBrowserWASQLiteOPFSDatabase,
+} from '@tanstack/browser-db-sqlite-persistence';
+import { Surreal } from 'surrealdb';
+import { persistedSurrealCollectionOptions } from '@foretag/tanstack-db-surrealdb';
+
+const db = new Surreal();
+const queryClient = new QueryClient();
+
+const sqlite = await openBrowserWASQLiteOPFSDatabase({
+  databaseName: 'tanstack-db.sqlite',
+});
+
+export const persistence = createBrowserWASQLitePersistence({
+  database: sqlite,
+});
+
+type Product = { id: string; name: string; price: number };
+type Category = { id: string; name: string };
+
+export const products = createCollection(
+	persistedSurrealCollectionOptions<Product>({
+		persistence,
+		schemaVersion: 1,
+		db,
+		table: { name: 'product' },
+		queryClient,
+		queryKey: ['product'],
+		syncMode: 'eager',
+	}),
+);
+
+export const categories = createCollection(
+	persistedSurrealCollectionOptions<Category>({
+		persistence,
+		schemaVersion: 1,
+		db,
+		table: { name: 'category' },
+		queryClient,
+		queryKey: ['category'],
+		syncMode: 'eager',
+	}),
+);
+```
+
+You only need one `openBrowserWASQLiteOPFSDatabase(...)` call and one
+`createBrowserWASQLitePersistence(...)` call per browser app, not per
+collection
+
 ## Adapter API
 
 ```ts
 type SurrealCollectionOptions<T> = {
-  db: Surreal;
-  table: Table | { name: string; relation?: boolean } | string;
-  queryClient: QueryClient;
-  queryKey: readonly unknown[];
-  syncMode?: 'eager' | 'on-demand' | 'progressive';
-  e2ee?: {
-    enabled: boolean;
-    crypto: CryptoProvider;
-    aad?: (ctx: { table: string; id: string; kind: 'base'|'update'|'snapshot'; baseTable?: string }) => Uint8Array;
-  };
-  crdt?: {
-    enabled: boolean;
-    profile: 'json' | 'richtext';
-    updatesTable: Table | { name: string } | string;
-    snapshotsTable?: Table | { name: string } | string;
-    // Optional overrides. If omitted, adapter uses built-in handlers for `profile`.
-    materialize?: (doc: LoroDoc, id: string) => T;
-    applyLocalChange?: (doc: LoroDoc, change: { type: 'insert'|'update'|'delete'; value: T }) => void;
-    persistMaterializedView?: boolean;
-    actor?: string | ((ctx: { id: string; change?: { type: 'insert'|'update'|'delete'; value: T } }) => string | undefined);
-    localActorId?: string; // deprecated
-  };
+	id?: string;
+	db: Surreal;
+	table: Table | { name: string; relation?: boolean } | string;
+	queryClient: QueryClient;
+	queryKey: readonly unknown[];
+	syncMode?: 'eager' | 'on-demand' | 'progressive';
+	e2ee?: {
+		enabled: boolean;
+		crypto: CryptoProvider;
+		aad?: (ctx: { table: string; id: string; kind: 'base'|'update'|'snapshot'; baseTable?: string }) => Uint8Array;
+	};
+	crdt?: {
+		enabled: boolean;
+		profile: 'json' | 'richtext';
+		updatesTable: Table | { name: string } | string;
+		snapshotsTable?: Table | { name: string } | string;
+		// Optional overrides. If omitted, adapter uses built-in handlers for `profile`.
+		materialize?: (doc: LoroDoc, id: string) => T;
+		applyLocalChange?: (doc: LoroDoc, change: { type: 'insert'|'update'|'delete'; value: T }) => void;
+		persistMaterializedView?: boolean;
+		actor?: string | ((ctx: { id: string; change?: { type: 'insert'|'update'|'delete'; value: T } }) => string | undefined);
+		localActorId?: string; // deprecated
+	};
 };
 ```
 
+`id` is optional. When omitted, the adapter derives a stable collection id from
+the Surreal table name and `queryKey` so TanStack DB persistence wrappers can
+reuse the same persisted collection state across restarts.
+
 ## E2EE
 
 Envelope fields stored in Surreal records:
@@ -242,14 +331,14 @@ If you run snapshot compaction from a trusted backend/service account, grant cre
 const provider = await WebCryptoAESGCM.fromRawKey(rawKey, { kid: 'org-key-2026-01' });
 
 const secrets = createCollection(
-  surrealCollectionOptions<{ id: string; title: string; body: string }>({
-    db,
-    table: { name: 'secret_note' },
-    queryClient,
-    queryKey: ['secret-note'],
-    syncMode: 'eager',
-    e2ee: { enabled: true, crypto: provider },
-  }),
+	surrealCollectionOptions<{ id: string; title: string; body: string }>({
+		db,
+		table: { name: 'secret_note' },
+		queryClient,
+		queryKey: ['secret-note'],
+		syncMode: 'eager',
+		e2ee: { enabled: true, crypto: provider },
+	}),
 );
 ```
 
@@ -257,20 +346,20 @@ const secrets = createCollection(
 
 ```ts
 const docs = createCollection(
-  surrealCollectionOptions<{ id: string; content: string; title?: string }>({
-    db,
-    table: { name: 'doc' },
-    queryClient,
-    queryKey: ['doc'],
-    syncMode: 'on-demand',
-    crdt: {
-      enabled: true,
-      profile: 'richtext',
-      updatesTable: { name: 'crdt_update' },
-      snapshotsTable: { name: 'crdt_snapshot' },
-      actor: ({ id }) => id.startsWith('team-a') ? 'device:team-a:abc' : 'device:team-b:abc',
-    },
-  }),
+	surrealCollectionOptions<{ id: string; content: string; title?: string }>({
+		db,
+		table: { name: 'doc' },
+		queryClient,
+		queryKey: ['doc'],
+		syncMode: 'on-demand',
+		crdt: {
+			enabled: true,
+			profile: 'richtext',
+			updatesTable: { name: 'crdt_update' },
+			snapshotsTable: { name: 'crdt_snapshot' },
+			actor: ({ id }) => id.startsWith('team-a') ? 'device:team-a:abc' : 'device:team-b:abc',
+		},
+	}),
 );
 ```
 
@@ -280,18 +369,18 @@ const docs = createCollection(
 import { RecordId } from 'surrealdb';
 
 type CalendarEvent = {
-  id: RecordId<'calendar_event'>;
-  owner: RecordId<'account'>;
-  title: string;
-  start_at: string;
+	id: RecordId<'calendar_event'>;
+	owner: RecordId<'account'>;
+	title: string;
+	start_at: string;
 };
 
 await calendarEvents.insert({
-  // id is Optional on insert
-  id: new RecordId('calendar_event', 'evt-001'),
-  owner: new RecordId('account', 'user-123'),
-  title: 'Planning',
-  start_at: '2026-02-23T10:00:00.000Z',
+	// id is Optional on insert
+	id: new RecordId('calendar_event', 'evt-001'),
+	owner: new RecordId('account', 'user-123'),
+	title: 'Planning',
+	start_at: '2026-02-23T10:00:00.000Z',
 });
 ```
 
@@ -303,20 +392,20 @@ Full runnable example: `examples/record-id.ts`.
 import { createLiveQueryCollection, eq } from '@tanstack/db';
 
 const files = createCollection(
-  surrealCollectionOptions<{ id: string; owner: string; updated_at: string; name: string }>({
-    db,
-    table: { name: 'file' },
-    queryClient,
-    queryKey: ['file'],
-    syncMode: 'on-demand',
-  }),
+	surrealCollectionOptions<{ id: string; owner: string; updated_at: string; name: string }>({
+		db,
+		table: { name: 'file' },
+		queryClient,
+		queryKey: ['file'],
+		syncMode: 'on-demand',
+	}),
 );
 
 const ownerFiles = createLiveQueryCollection((q) =>
-  q
-    .from({ files })
-    .where(({ files }) => eq(files.owner, 'account:abc'))
-    .select(({ files }) => files),
+	q
+		.from({ files })
+		.where(({ files }) => eq(files.owner, 'account:abc'))
+		.select(({ files }) => files),
 );
 
 await ownerFiles.preload();

package/dist/index.d.mts

@@ -1,9 +1,17 @@
+import * as _tanstack_db_sqlite_persistence_core from '@tanstack/db-sqlite-persistence-core';
+import { PersistedCollectionPersistence } from '@tanstack/db-sqlite-persistence-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { CollectionConfig, UtilsRecord, LoadSubsetOptions, OperationConfig, Transaction } from '@tanstack/db';
-import { Table, Surreal, RecordId } from 'surrealdb';
+import { RecordId, Surreal, Table } from 'surrealdb';
 import { QueryClient } from '@tanstack/query-core';
 import { LoroDoc } from 'loro-crdt';
 
+type MutationInput<T extends {
+    id: string | RecordId;
+}> = Omit<T, 'id'> & {
+    id?: T['id'];
+};
+
 type EncryptInput = {
     plaintext: Bytes;
     aad?: Bytes;
@@ -116,6 +124,12 @@ type SurrealCRDTOptions<T extends object> = {
 };
 type AdapterSyncMode = 'eager' | 'on-demand' | 'progressive';
 type SurrealCollectionOptions<T extends object> = Omit<CollectionConfig<T>, 'onInsert' | 'onUpdate' | 'onDelete' | 'sync' | 'getKey' | 'syncMode'> & {
+    /**
+     * Optional stable collection identity.
+     * When omitted, the adapter derives one from the Surreal table name and queryKey
+     * so wrappers like TanStack DB persistence can reuse the same collection across restarts.
+     */
+    id?: string;
     db: Surreal;
     table: TableLike;
     queryKey: readonly unknown[];
@@ -125,11 +139,16 @@ type SurrealCollectionOptions<T extends object> = Omit<CollectionConfig<T>, 'onI
     crdt?: SurrealCRDTOptions<T>;
     onError?: (error: unknown) => void;
 };
+type PersistedSurrealCollectionOptions<T extends object> = SurrealCollectionOptions<T> & {
+    persistence: PersistedCollectionPersistence;
+    schemaVersion?: number;
+};
 type SurrealCollectionOptionsReturn<T extends {
     id: string | RecordId;
 }> = CollectionConfig<T, string, StandardSchemaV1<Omit<T, 'id'> & {
     id?: T['id'];
 }, T>, UtilsRecord> & {
+    id: string;
     schema: StandardSchemaV1<Omit<T, 'id'> & {
         id?: T['id'];
     }, T>;
@@ -150,19 +169,21 @@ declare const createLoroProfile: <T extends object = Record<string, unknown>>(pr
 
 declare const toRecordKeyString: (rid: RecordId | string) => string;
 
-type MutationInput<T extends {
-    id: string | RecordId;
-}> = Omit<T, 'id'> & {
-    id?: T['id'];
-};
 declare function surrealCollectionOptions<T extends SyncedTable<object>>(config: SurrealCollectionOptions<T>): CollectionConfig<T, string, StandardSchemaV1<MutationInput<T>, T>, UtilsRecord> & {
     schema: StandardSchemaV1<MutationInput<T>, T>;
     utils: UtilsRecord;
 };
+declare function persistedSurrealCollectionOptions<T extends SyncedTable<object>>(config: PersistedSurrealCollectionOptions<T>): CollectionConfig<T, string, StandardSchemaV1<Omit<T, "id"> & {
+    id?: T["id"];
+}, T>, UtilsRecord> & {
+    persistence: _tanstack_db_sqlite_persistence_core.PersistedCollectionPersistence & {
+        coordinator: _tanstack_db_sqlite_persistence_core.PersistedCollectionCoordinator;
+    };
+};
 declare module '@tanstack/db' {
     interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInsertInput extends object = T> {
         delete(keys: Array<TKey | RecordId | string> | TKey | RecordId | string, config?: OperationConfig): Transaction<Record<string, never>>;
     }
 }
 
-export { type AADContext, type AdapterE2EEOptions, type AdapterSyncMode, type Bytes, type CRDTActorContext, type CryptoProvider, type DecryptInput, type E2EEConfig, type EncryptInput, type EncryptedEnvelope, type EncryptionAADContext, type EncryptionEnvelope, type EnvelopeKind, type LocalChange, type LoroProfile, type SurrealCRDTOptions, type SurrealCollectionOptions, type SurrealCollectionOptionsReturn, type SurrealE2EEOptions, type SurrealSubset, type SyncedTable, type TableLike, type TableOptions, WebCryptoAESGCM, type WithId, applyLoroJsonChange, applyLoroRichtextChange, createLoroProfile, materializeLoroJson, materializeLoroRichtext, surrealCollectionOptions, toRecordKeyString };
+export { type AADContext, type AdapterE2EEOptions, type AdapterSyncMode, type Bytes, type CRDTActorContext, type CryptoProvider, type DecryptInput, type E2EEConfig, type EncryptInput, type EncryptedEnvelope, type EncryptionAADContext, type EncryptionEnvelope, type EnvelopeKind, type LocalChange, type LoroProfile, type PersistedSurrealCollectionOptions, type SurrealCRDTOptions, type SurrealCollectionOptions, type SurrealCollectionOptionsReturn, type SurrealE2EEOptions, type SurrealSubset, type SyncedTable, type TableLike, type TableOptions, WebCryptoAESGCM, type WithId, applyLoroJsonChange, applyLoroRichtextChange, createLoroProfile, materializeLoroJson, materializeLoroRichtext, persistedSurrealCollectionOptions, surrealCollectionOptions, toRecordKeyString };

package/dist/index.d.ts

@@ -1,9 +1,17 @@
+import * as _tanstack_db_sqlite_persistence_core from '@tanstack/db-sqlite-persistence-core';
+import { PersistedCollectionPersistence } from '@tanstack/db-sqlite-persistence-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { CollectionConfig, UtilsRecord, LoadSubsetOptions, OperationConfig, Transaction } from '@tanstack/db';
-import { Table, Surreal, RecordId } from 'surrealdb';
+import { RecordId, Surreal, Table } from 'surrealdb';
 import { QueryClient } from '@tanstack/query-core';
 import { LoroDoc } from 'loro-crdt';
 
+type MutationInput<T extends {
+    id: string | RecordId;
+}> = Omit<T, 'id'> & {
+    id?: T['id'];
+};
+
 type EncryptInput = {
     plaintext: Bytes;
     aad?: Bytes;
@@ -116,6 +124,12 @@ type SurrealCRDTOptions<T extends object> = {
 };
 type AdapterSyncMode = 'eager' | 'on-demand' | 'progressive';
 type SurrealCollectionOptions<T extends object> = Omit<CollectionConfig<T>, 'onInsert' | 'onUpdate' | 'onDelete' | 'sync' | 'getKey' | 'syncMode'> & {
+    /**
+     * Optional stable collection identity.
+     * When omitted, the adapter derives one from the Surreal table name and queryKey
+     * so wrappers like TanStack DB persistence can reuse the same collection across restarts.
+     */
+    id?: string;
     db: Surreal;
     table: TableLike;
     queryKey: readonly unknown[];
@@ -125,11 +139,16 @@ type SurrealCollectionOptions<T extends object> = Omit<CollectionConfig<T>, 'onI
     crdt?: SurrealCRDTOptions<T>;
     onError?: (error: unknown) => void;
 };
+type PersistedSurrealCollectionOptions<T extends object> = SurrealCollectionOptions<T> & {
+    persistence: PersistedCollectionPersistence;
+    schemaVersion?: number;
+};
 type SurrealCollectionOptionsReturn<T extends {
     id: string | RecordId;
 }> = CollectionConfig<T, string, StandardSchemaV1<Omit<T, 'id'> & {
     id?: T['id'];
 }, T>, UtilsRecord> & {
+    id: string;
     schema: StandardSchemaV1<Omit<T, 'id'> & {
         id?: T['id'];
     }, T>;
@@ -150,19 +169,21 @@ declare const createLoroProfile: <T extends object = Record<string, unknown>>(pr
 
 declare const toRecordKeyString: (rid: RecordId | string) => string;
 
-type MutationInput<T extends {
-    id: string | RecordId;
-}> = Omit<T, 'id'> & {
-    id?: T['id'];
-};
 declare function surrealCollectionOptions<T extends SyncedTable<object>>(config: SurrealCollectionOptions<T>): CollectionConfig<T, string, StandardSchemaV1<MutationInput<T>, T>, UtilsRecord> & {
     schema: StandardSchemaV1<MutationInput<T>, T>;
     utils: UtilsRecord;
 };
+declare function persistedSurrealCollectionOptions<T extends SyncedTable<object>>(config: PersistedSurrealCollectionOptions<T>): CollectionConfig<T, string, StandardSchemaV1<Omit<T, "id"> & {
+    id?: T["id"];
+}, T>, UtilsRecord> & {
+    persistence: _tanstack_db_sqlite_persistence_core.PersistedCollectionPersistence & {
+        coordinator: _tanstack_db_sqlite_persistence_core.PersistedCollectionCoordinator;
+    };
+};
 declare module '@tanstack/db' {
     interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInsertInput extends object = T> {
         delete(keys: Array<TKey | RecordId | string> | TKey | RecordId | string, config?: OperationConfig): Transaction<Record<string, never>>;
     }
 }
 
-export { type AADContext, type AdapterE2EEOptions, type AdapterSyncMode, type Bytes, type CRDTActorContext, type CryptoProvider, type DecryptInput, type E2EEConfig, type EncryptInput, type EncryptedEnvelope, type EncryptionAADContext, type EncryptionEnvelope, type EnvelopeKind, type LocalChange, type LoroProfile, type SurrealCRDTOptions, type SurrealCollectionOptions, type SurrealCollectionOptionsReturn, type SurrealE2EEOptions, type SurrealSubset, type SyncedTable, type TableLike, type TableOptions, WebCryptoAESGCM, type WithId, applyLoroJsonChange, applyLoroRichtextChange, createLoroProfile, materializeLoroJson, materializeLoroRichtext, surrealCollectionOptions, toRecordKeyString };
+export { type AADContext, type AdapterE2EEOptions, type AdapterSyncMode, type Bytes, type CRDTActorContext, type CryptoProvider, type DecryptInput, type E2EEConfig, type EncryptInput, type EncryptedEnvelope, type EncryptionAADContext, type EncryptionEnvelope, type EnvelopeKind, type LocalChange, type LoroProfile, type PersistedSurrealCollectionOptions, type SurrealCRDTOptions, type SurrealCollectionOptions, type SurrealCollectionOptionsReturn, type SurrealE2EEOptions, type SurrealSubset, type SyncedTable, type TableLike, type TableOptions, WebCryptoAESGCM, type WithId, applyLoroJsonChange, applyLoroRichtextChange, createLoroProfile, materializeLoroJson, materializeLoroRichtext, persistedSurrealCollectionOptions, surrealCollectionOptions, toRecordKeyString };