tanstack-db-pglite 1.2.6 → 1.3.1

package/dist/drizzle.d.ts

@@ -5,12 +5,21 @@ import type { PgliteDatabase } from 'drizzle-orm/pglite';
 import type { PgliteUtils } from './utils';
 type Schema<Table extends PgTable> = StandardSchemaV1<Table['$inferSelect'], Table['$inferSelect']>;
 type SyncParams<Table extends PgTable> = Parameters<SyncConfig<Table['$inferSelect'], string>['sync']>[0];
+/**
+ * Creates collection options backed by Drizzle ORM on PGlite.
+ *
+ * The adapter loads initial data from PGlite before invoking the user-provided `sync` callback.
+ * If your sync establishes a real-time subscription, events emitted during the initial PGlite
+ * read may be missed. To avoid data loss, subscribe to real-time events first and buffer them
+ * until `markReady()` is called.
+ */
 export declare function drizzleCollectionOptions<Table extends PgTable>({ startSync, ...config }: {
     db: PgliteDatabase<any>;
     startSync?: boolean;
     table: Table;
     primaryColumn: IndexColumn;
-    sync?: (params: Pick<SyncParams<Table>, 'write' | 'collection'>) => Promise<void>;
+    rowUpdateMode?: 'partial' | 'full';
+    sync?: (params: Pick<SyncParams<Table>, 'write' | 'collection' | 'markReady' | 'metadata'>) => Promise<(() => void) | void>;
     prepare?: () => Promise<unknown> | unknown;
     onInsert?: (params: InsertMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
     onUpdate?: (params: UpdateMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;

package/dist/drizzle.js

@@ -1,8 +1,15 @@
 import { BasicIndex } from '@tanstack/db';
 import { eq, inArray } from 'drizzle-orm';
 import { createSelectSchema } from 'drizzle-zod';
+/**
+ * Creates collection options backed by Drizzle ORM on PGlite.
+ *
+ * The adapter loads initial data from PGlite before invoking the user-provided `sync` callback.
+ * If your sync establishes a real-time subscription, events emitted during the initial PGlite
+ * read may be missed. To avoid data loss, subscribe to real-time events first and buffer them
+ * until `markReady()` is called.
+ */
 export function drizzleCollectionOptions({ startSync = true, ...config }) {
-    let resolvers = Promise.withResolvers();
     // Sync params can be null while running PGLite migrations
     const { promise: syncParams, resolve: resolveSyncParams } = Promise.withResolvers();
     // eslint-disable-next-line ts/no-explicit-any
@@ -63,15 +70,16 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
             .from(config.table)
             .where(eq(config.primaryColumn, m.key))));
     }
-    const sync = async () => {
+    const sync = async (force = false) => {
+        const params = await syncParams;
+        if (force) {
+            params.truncate();
+        }
         if (!config.sync) {
+            params.markReady();
             return;
         }
-        const params = await syncParams;
-        const previousResolvers = resolvers;
-        resolvers = Promise.withResolvers();
-        previousResolvers.resolve({ continue: true });
-        await config.sync({
+        return config.sync({
             write: async (message) => {
                 if (message.type === 'insert') {
                     await onDrizzleInsert([message.value]);
@@ -88,37 +96,41 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
                 params.commit();
             },
             collection: params.collection,
+            markReady: params.markReady,
+            ...(params.metadata && { metadata: params.metadata }),
         });
-        resolvers.resolve({ continue: false });
-    };
-    const waitForSync = async () => {
-        await resolvers.promise.then(r => r.continue ? waitForSync() : undefined);
     };
     return {
-        startSync: true,
+        startSync,
         autoIndex: 'eager',
         defaultIndexType: BasicIndex,
         sync: {
+            ...(config.rowUpdateMode && { rowUpdateMode: config.rowUpdateMode }),
             sync: (params) => {
                 resolveSyncParams(params);
+                let cleanup;
                 (async () => {
-                    try {
-                        await config.prepare?.();
-                        // @ts-expect-error drizzle types
-                        const dbs = await config.db.select().from(config.table);
-                        params.begin();
-                        dbs.forEach((db) => {
-                            params.write({ type: 'insert', value: db });
-                        });
-                        params.commit();
-                        if (startSync) {
-                            sync();
+                    await config.prepare?.();
+                    // @ts-expect-error drizzle types
+                    const dbs = await config.db.select().from(config.table);
+                    params.begin();
+                    dbs.forEach((db) => {
+                        params.write({ type: 'insert', value: db });
+                    });
+                    params.commit();
+                    if (startSync) {
+                        const result = await sync();
+                        if (typeof result === 'function') {
+                            cleanup = result;
                         }
                     }
-                    finally {
+                    else {
                         params.markReady();
                     }
                 })();
+                return () => {
+                    cleanup?.();
+                };
             },
         },
         schema: createSelectSchema(config.table),
@@ -160,9 +172,8 @@ export function drizzleCollectionOptions({ startSync = true, ...config }) {
                 }
                 const params = await syncParams;
                 await params.collection.stateWhenReady();
-                await sync();
+                await sync(true);
             },
-            waitForSync,
         },
     };
 }

package/dist/sql.d.ts

@@ -5,15 +5,24 @@ import type { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams,
 import type { PgliteUtils } from './utils';
 type Output<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
 type SyncParams<ItemType extends Record<string, unknown>> = Parameters<SyncConfig<ItemType, string>['sync']>[0];
+/**
+ * Creates collection options backed by raw SQL on PGlite.
+ *
+ * The adapter loads initial data from PGlite before invoking the user-provided `sync` callback.
+ * If your sync establishes a real-time subscription, events emitted during the initial PGlite
+ * read may be missed. To avoid data loss, subscribe to real-time events first and buffer them
+ * until `markReady()` is called.
+ */
 export declare function sqlCollectionOptions<Schema extends StandardSchemaV1<Record<string, unknown>>>({ startSync, ...config }: {
     db: PGlite | PGliteWorker;
     startSync?: boolean;
     tableName: string;
     primaryKeyColumn: Extract<keyof Output<Schema>, string>;
+    rowUpdateMode?: 'partial' | 'full';
     schema: Schema;
     getKey?: (row: Output<Schema>) => string;
     prepare?: () => Promise<unknown> | unknown;
-    sync?: (params: Pick<SyncParams<Output<Schema>>, 'write' | 'collection'>) => Promise<void>;
+    sync?: (params: Pick<SyncParams<Output<Schema>>, 'write' | 'collection' | 'markReady' | 'metadata'>) => Promise<(() => void) | void>;
     onInsert?: (params: InsertMutationFnParams<Output<Schema>, string>) => Promise<void>;
     onUpdate?: (params: UpdateMutationFnParams<Output<Schema>, string>) => Promise<void>;
     onDelete?: (params: DeleteMutationFnParams<Output<Schema>, string>) => Promise<void>;

package/dist/sql.js

@@ -3,8 +3,15 @@ function quoteId(name) {
     // eslint-disable-next-line e18e/prefer-static-regex
     return `"${String(name).replace(/"/g, '""')}"`;
 }
+/**
+ * Creates collection options backed by raw SQL on PGlite.
+ *
+ * The adapter loads initial data from PGlite before invoking the user-provided `sync` callback.
+ * If your sync establishes a real-time subscription, events emitted during the initial PGlite
+ * read may be missed. To avoid data loss, subscribe to real-time events first and buffer them
+ * until `markReady()` is called.
+ */
 export function sqlCollectionOptions({ startSync = true, ...config }) {
-    let resolvers = Promise.withResolvers();
     const table = quoteId(config.tableName);
     const primaryKey = quoteId(config.primaryKeyColumn);
     const getKey = config.getKey ?? ((row) => String(row[config.primaryKeyColumn]));
@@ -50,15 +57,16 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
         });
         commit();
     }
-    const sync = async () => {
+    const sync = async (force = false) => {
+        const params = await syncParams;
+        if (force) {
+            params.truncate();
+        }
         if (!config.sync) {
+            params.markReady();
             return;
         }
-        const params = await syncParams;
-        const previousResolvers = resolvers;
-        resolvers = Promise.withResolvers();
-        previousResolvers.resolve({ continue: true });
-        await config.sync({
+        return config.sync({
             write: async (p) => {
                 if (p.type === 'insert') {
                     await runInsert(config.db, [p.value]);
@@ -75,36 +83,40 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
                 params.commit();
             },
             collection: params.collection,
+            markReady: params.markReady,
+            ...(params.metadata && { metadata: params.metadata }),
         });
-        resolvers.resolve({ continue: false });
-    };
-    const waitForSync = async () => {
-        await resolvers.promise.then(r => r.continue ? waitForSync() : undefined);
     };
     return {
         startSync,
         autoIndex: 'eager',
         defaultIndexType: BasicIndex,
         sync: {
+            ...(config.rowUpdateMode && { rowUpdateMode: config.rowUpdateMode }),
             sync: (params) => {
                 resolveSyncParams(params);
+                let cleanup;
                 (async () => {
-                    try {
-                        await config.prepare?.();
-                        const rows = await runSelect(config.db);
-                        params.begin();
-                        rows.forEach((row) => {
-                            params.write({ type: 'insert', value: row });
-                        });
-                        params.commit();
-                        if (startSync) {
-                            sync();
+                    await config.prepare?.();
+                    const rows = await runSelect(config.db);
+                    params.begin();
+                    rows.forEach((row) => {
+                        params.write({ type: 'insert', value: row });
+                    });
+                    params.commit();
+                    if (startSync) {
+                        const result = await sync();
+                        if (typeof result === 'function') {
+                            cleanup = result;
                         }
                     }
-                    finally {
+                    else {
                         params.markReady();
                     }
                 })();
+                return () => {
+                    cleanup?.();
+                };
             },
         },
         schema: config.schema,
@@ -143,9 +155,8 @@ export function sqlCollectionOptions({ startSync = true, ...config }) {
                 }
                 const params = await syncParams;
                 await params.collection.stateWhenReady();
-                await sync();
+                await sync(true);
             },
-            waitForSync,
         },
     };
 }

package/dist/utils.d.ts

@@ -1,5 +1,4 @@
 import type { UtilsRecord } from '@tanstack/db';
 export interface PgliteUtils extends UtilsRecord {
     runSync: () => Promise<void>;
-    waitForSync: () => Promise<void>;
 }

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "tanstack-db-pglite",
-  "version": "1.2.6",
-  "description": "",
+  "version": "1.3.1",
   "author": "Valerii Strilets",
   "license": "MIT",
   "repository": {
@@ -12,7 +11,8 @@
     "tanstack",
     "db",
     "pglite",
-    "drizzle"
+    "drizzle",
+    "sql"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",