tanstack-db-pglite 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Valerii Strilets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# tanstack-db-pglite
+
+A seamless integration between [TanStack DB](https://tanstack.com/db) and [PGLite](https://github.com/electric-sql/pglite) with [Drizzle ORM](https://orm.drizzle.team/) for browser-based database management, providing powerful collection management with automatic synchronization and offline-first capabilities.
+
+## Installation
+
+```bash
+npm install tanstack-db-pglite @tanstack/db drizzle-orm @electric-sql/pglite
+```
+
+> **Note:** `@tanstack/db` and `drizzle-orm` are peer dependencies and must be installed separately.
+
+## Quick Start
+
+```typescript
+import { PGLite } from '@electric-sql/pglite'
+import { createCollection } from '@tanstack/react-db'
+import { drizzle } from 'drizzle-orm/pglite'
+import { drizzleCollectionOptions } from 'tanstack-db-pglite'
+import { chats } from '~/drizzle'
+
+const pglite = new PGLite()
+const db = drizzle(pglite)
+
+export const chatsCollection = createCollection(drizzleCollectionOptions({
+  db,
+  table: chats,
+  primaryColumn: chats.id,
+  prepare: async () => {
+    // Prepare your database before starting the collection (e.g., run migrations)
+    await waitForMigrations()
+  },
+  sync: async ({ collection, write }) => {
+    // Send some data to your backend to sync and receive the response
+    const sync = await syncWithCloud(
+      collection.toArray.map(c => ({
+        id: c.id,
+        updatedAt: c.updatedAt
+      }))
+    )
+
+    sync.forEach((item) => {
+      if (item.type === 'delete') {
+        write({ type: 'delete', value: collection.get(item.value)! })
+      }
+      else {
+        write(item)
+      }
+    })
+  },
+  onInsert: async (params) => {
+    await saveInCloud(params)
+  },
+  onUpdate: async (params) => {
+    await updateInCloud(params)
+  },
+  onDelete: async (params) => {
+    await deleteInCloud(params)
+  },
+}))
+```

package/dist/drizzle-collection-options.d.ts

@@ -0,0 +1,20 @@
+import type { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncConfig, UpdateMutationFnParams } from '@tanstack/db';
+import type { IndexColumn, PgTable } from 'drizzle-orm/pg-core';
+import type { PgliteDatabase } from 'drizzle-orm/pglite';
+export declare function drizzleCollectionOptions<Table extends PgTable>({ startSync, ...config }: {
+    db: PgliteDatabase<any>;
+    table: Table;
+    primaryColumn: IndexColumn;
+    onInsert?: (params: InsertMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
+    onUpdate?: (params: UpdateMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
+    onDelete?: (params: DeleteMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
+    startSync?: boolean;
+    sync: {
+        prepare?: () => Promise<any> | any;
+        sync: (params: Pick<Parameters<SyncConfig<Table['$inferSelect'], string>['sync']>[0], 'write' | 'collection'>) => Promise<void>;
+    };
+}): CollectionConfig<Table['$inferSelect'], string> & {
+    utils: {
+        runSync: () => Promise<void>;
+    };
+};

package/dist/drizzle-collection-options.js

@@ -0,0 +1,106 @@
+import { eq, inArray } from 'drizzle-orm';
+import { createSelectSchema } from 'drizzle-zod';
+export function drizzleCollectionOptions({ startSync = true, ...config }) {
+    // Sync params can be null while running PGLite migrations
+    const { promise: syncParams, resolve: resolveSyncParams } = Promise.withResolvers();
+    async function runMutations(mutations) {
+        const { begin, write, commit } = await syncParams;
+        begin();
+        mutations.forEach((m) => {
+            write({ type: m.type, value: m.modified });
+        });
+        commit();
+    }
+    async function onDrizzleInsert(data) {
+        // @ts-expect-error drizzle types
+        await config.db.insert(config.table).values(data);
+    }
+    async function onDrizzleUpdate(id, changes) {
+        await config.db
+            .update(config.table)
+            .set(changes)
+            .where(eq(config.primaryColumn, id));
+    }
+    async function onDrizzleDelete(ids) {
+        await config.db
+            .delete(config.table)
+            .where(inArray(config.primaryColumn, ids));
+    }
+    const getSyncParams = async () => {
+        const params = await syncParams;
+        return {
+            write: async (p) => {
+                params.begin();
+                try {
+                    if (p.type === 'insert') {
+                        await onDrizzleInsert([p.value]);
+                    }
+                    else if (p.type === 'update') {
+                        await onDrizzleUpdate(params.collection.getKeyFromItem(p.value), p.value);
+                    }
+                    else if (p.type === 'delete') {
+                        await onDrizzleDelete([params.collection.getKeyFromItem(p.value)]);
+                    }
+                    params.write(p);
+                }
+                finally {
+                    params.commit();
+                }
+            },
+            collection: params.collection,
+        };
+    };
+    return {
+        startSync: true,
+        sync: {
+            sync: async (params) => {
+                try {
+                    resolveSyncParams(params);
+                    await config.sync.prepare?.();
+                    params.begin();
+                    // @ts-expect-error drizzle types
+                    const dbs = await config.db.select().from(config.table);
+                    dbs.forEach((db) => {
+                        params.write({ type: 'insert', value: db });
+                    });
+                    params.commit();
+                    if (config.sync && startSync) {
+                        await config.sync.sync(await getSyncParams());
+                    }
+                }
+                finally {
+                    params.markReady();
+                }
+            },
+        },
+        gcTime: 0,
+        schema: createSelectSchema(config.table),
+        getKey: t => t[config.primaryColumn.name],
+        onDelete: async (params) => {
+            await onDrizzleDelete(params.transaction.mutations.map(m => m.key));
+            const result = await config.onDelete?.(params);
+            await runMutations(params.transaction.mutations);
+            return result;
+        },
+        onInsert: async (params) => {
+            await onDrizzleInsert(params.transaction.mutations.map(m => m.modified));
+            const result = await config.onInsert?.(params);
+            await runMutations(params.transaction.mutations);
+            return result;
+        },
+        onUpdate: async (params) => {
+            await Promise.all(params.transaction.mutations.map(m => onDrizzleUpdate(m.key, m.changes)));
+            const result = await config.onUpdate?.(params);
+            await runMutations(params.transaction.mutations);
+            return result;
+        },
+        utils: {
+            runSync: async () => {
+                const params = await getSyncParams();
+                // To wait the first sync
+                await params.collection.stateWhenReady();
+                await config.sync.sync(params);
+            },
+        },
+    };
+}

package/dist/drizzle.d.ts

@@ -0,0 +1,18 @@
+import type { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncConfig, UpdateMutationFnParams } from '@tanstack/db';
+import type { IndexColumn, PgTable } from 'drizzle-orm/pg-core';
+import type { PgliteDatabase } from 'drizzle-orm/pglite';
+export declare function drizzleCollectionOptions<Table extends PgTable>({ startSync, ...config }: {
+    db: PgliteDatabase<any>;
+    table: Table;
+    primaryColumn: IndexColumn;
+    onInsert?: (params: InsertMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
+    onUpdate?: (params: UpdateMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
+    onDelete?: (params: DeleteMutationFnParams<Table['$inferSelect'], string>) => Promise<void>;
+    startSync?: boolean;
+    prepare?: () => Promise<any> | any;
+    sync: (params: Pick<Parameters<SyncConfig<Table['$inferSelect'], string>['sync']>[0], 'write' | 'collection'>) => Promise<void>;
+}): CollectionConfig<Table['$inferSelect'], string> & {
+    utils: {
+        runSync: () => Promise<void>;
+    };
+};

package/dist/drizzle.js

@@ -0,0 +1,106 @@
+import { eq, inArray } from 'drizzle-orm';
+import { createSelectSchema } from 'drizzle-zod';
+export function drizzleCollectionOptions({ startSync = true, ...config }) {
+    // Sync params can be null while running PGLite migrations
+    const { promise: syncParams, resolve: resolveSyncParams } = Promise.withResolvers();
+    async function runMutations(mutations) {
+        const { begin, write, commit } = await syncParams;
+        begin();
+        mutations.forEach((m) => {
+            write({ type: m.type, value: m.modified });
+        });
+        commit();
+    }
+    async function onDrizzleInsert(data) {
+        // @ts-expect-error drizzle types
+        await config.db.insert(config.table).values(data);
+    }
+    async function onDrizzleUpdate(id, changes) {
+        await config.db
+            .update(config.table)
+            .set(changes)
+            .where(eq(config.primaryColumn, id));
+    }
+    async function onDrizzleDelete(ids) {
+        await config.db
+            .delete(config.table)
+            .where(inArray(config.primaryColumn, ids));
+    }
+    const getSyncParams = async () => {
+        const params = await syncParams;
+        return {
+            write: async (p) => {
+                params.begin();
+                try {
+                    if (p.type === 'insert') {
+                        await onDrizzleInsert([p.value]);
+                    }
+                    else if (p.type === 'update') {
+                        await onDrizzleUpdate(params.collection.getKeyFromItem(p.value), p.value);
+                    }
+                    else if (p.type === 'delete') {
+                        await onDrizzleDelete([params.collection.getKeyFromItem(p.value)]);
+                    }
+                    params.write(p);
+                }
+                finally {
+                    params.commit();
+                }
+            },
+            collection: params.collection,
+        };
+    };
+    return {
+        startSync: true,
+        sync: {
+            sync: async (params) => {
+                try {
+                    resolveSyncParams(params);
+                    await config.prepare?.();
+                    params.begin();
+                    // @ts-expect-error drizzle types
+                    const dbs = await config.db.select().from(config.table);
+                    dbs.forEach((db) => {
+                        params.write({ type: 'insert', value: db });
+                    });
+                    params.commit();
+                    if (config.sync && startSync) {
+                        await config.sync(await getSyncParams());
+                    }
+                }
+                finally {
+                    params.markReady();
+                }
+            },
+        },
+        gcTime: 0,
+        schema: createSelectSchema(config.table),
+        getKey: t => t[config.primaryColumn.name],
+        onDelete: async (params) => {
+            await onDrizzleDelete(params.transaction.mutations.map(m => m.key));
+            const result = await config.onDelete?.(params);
+            await runMutations(params.transaction.mutations);
+            return result;
+        },
+        onInsert: async (params) => {
+            await onDrizzleInsert(params.transaction.mutations.map(m => m.modified));
+            const result = await config.onInsert?.(params);
+            await runMutations(params.transaction.mutations);
+            return result;
+        },
+        onUpdate: async (params) => {
+            await Promise.all(params.transaction.mutations.map(m => onDrizzleUpdate(m.key, m.changes)));
+            const result = await config.onUpdate?.(params);
+            await runMutations(params.transaction.mutations);
+            return result;
+        },
+        utils: {
+            runSync: async () => {
+                const params = await getSyncParams();
+                // To wait the first sync
+                await params.collection.stateWhenReady();
+                await config.sync(params);
+            },
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './drizzle';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './drizzle';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "tanstack-db-pglite",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.16.1",
+  "description": "",
+  "author": "Valerii Strilets",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/letstri/tanstack-db-pglite.git",
+    "directory": "tanstack-db-pglite"
+  },
+  "keywords": [
+    "tanstack",
+    "db",
+    "pglite",
+    "drizzle"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "prepublishOnly": "pnpm build",
+    "build": "tsc",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "peerDependencies": {
+    "@tanstack/db": ">=0.2.0",
+    "drizzle-orm": ">=0.44.0"
+  },
+  "dependencies": {
+    "drizzle-zod": "^0.8.3"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^5.3.0",
+    "eslint": "^9.35.0",
+    "jiti": "^2.5.1",
+    "typescript": "^5.9.2"
+  }
+}