@syncular/client 0.0.6-185 → 0.0.6-201

package/dist/client.js

@@ -3,14 +3,12 @@
  *
  * Single entry point for offline-first sync with:
  * - Built-in mutations API
- * - Optional blob support
  * - Automatic migrations
  * - Event-driven state management
  * - Conflict handling with events
  */
 import { countSyncMetric } from '@syncular/core';
 import { sql } from 'kysely';
-import { ensureClientBlobSchema } from './blobs/migrate.js';
 import { SyncEngine } from './engine/SyncEngine.js';
 import { ensureClientSyncSchema } from './migrate.js';
 import { createMutationsApi, createOutboxCommit, } from './mutations.js';
@@ -49,6 +47,7 @@ export class Client {
     engine = null;
     started = false;
     destroyed = false;
+    pluginFeatures = new Map();
     eventListeners = new Map();
     outboxStats = {
         pending: 0,
@@ -59,13 +58,11 @@ export class Client {
     };
     /** Mutations API (always available) */
     mutations;
-    /** Blob client (only available if blobStorage configured) */
-    blobs;
     constructor(options) {
         const plugins = withDefaultClientPlugins(options.plugins);
         this.options = { ...options, plugins };
         // Create mutations API
-        const commitFn = createOutboxCommit({
+        const baseCommitFn = createOutboxCommit({
             db: this.options.db,
             idColumn: this.options.idColumn ?? 'id',
             versionColumn: this.options.versionColumn ?? 'server_version',
@@ -76,11 +73,13 @@ export class Client {
             actorId: this.options.actorId,
             clientId: this.options.clientId,
         });
+        const commitFn = async (fn, options) => {
+            const outcome = await baseCommitFn(fn, options);
+            this.scheduleLocalSyncAfterMutation();
+            return outcome;
+        };
         this.mutations = createMutationsApi(commitFn);
-        // Create blob client if storage provided
-        if (options.blobStorage && options.transport.blobs) {
-            this.blobs = this.createBlobClient(options.blobStorage, options.transport);
-        }
+        this.setupPluginFeatures();
     }
     // ===========================================================================
     // Identity Getters
@@ -113,9 +112,7 @@ export class Client {
         }
         // Run migrations
         await ensureClientSyncSchema(this.options.db);
-        if (this.options.blobStorage) {
-            await ensureClientBlobSchema(this.options.db);
-        }
+        await this.runPluginMigrations();
         // Create and start engine
         this.engine = new SyncEngine({
             db: this.options.db,
@@ -155,6 +152,10 @@ export class Client {
      */
     destroy() {
         this.engine?.destroy();
+        const ctx = this.createPluginLifecycleContext();
+        for (const plugin of this.options.plugins ?? []) {
+            plugin.destroy?.(ctx);
+        }
         this.eventListeners.clear();
         this.destroyed = true;
     }
@@ -358,6 +359,62 @@ export class Client {
             }
         }
     }
+    setupPluginFeatures() {
+        const ctx = this.createPluginLifecycleContext();
+        for (const plugin of this.options.plugins ?? []) {
+            plugin.setup?.(ctx);
+        }
+    }
+    async runPluginMigrations() {
+        const ctx = this.createPluginLifecycleContext();
+        for (const plugin of this.options.plugins ?? []) {
+            if (plugin.migrate) {
+                await plugin.migrate(ctx);
+            }
+        }
+    }
+    createPluginLifecycleContext() {
+        return {
+            actorId: this.options.actorId,
+            clientId: this.options.clientId,
+            db: this.options.db,
+            transport: this.options.transport,
+            defineFeature: (name, value) => {
+                this.defineFeature(name, value);
+            },
+            emit: (event, payload) => {
+                this.emitPluginEvent(event, payload);
+            },
+        };
+    }
+    defineFeature(name, value) {
+        if (this.pluginFeatures.has(name)) {
+            throw new Error(`Client feature "${name}" is already registered`);
+        }
+        this.pluginFeatures.set(name, value);
+        Object.defineProperty(this, name, {
+            configurable: false,
+            enumerable: true,
+            value,
+            writable: false,
+        });
+    }
+    emitPluginEvent(event, payload) {
+        this.emit(event, payload);
+    }
+    scheduleLocalSyncAfterMutation() {
+        if (!this.started || !this.engine || this.destroyed) {
+            return;
+        }
+        const engineState = this.engine.getState();
+        if (engineState.isRetrying ||
+            engineState.connectionState === 'disconnected') {
+            return;
+        }
+        void this.engine.sync({ trigger: 'local' }).catch((error) => {
+            console.error('[Client] Unexpected background sync failure after local mutation:', error);
+        });
+    }
     // ===========================================================================
     // Conflicts
     // ===========================================================================
@@ -473,68 +530,46 @@ export class Client {
      * Get migration info.
      */
     async getMigrationInfo() {
-        // Check if sync tables exist
         let syncMigrated = false;
         try {
-            await this.options.db
-                .selectFrom('sync_outbox_commits')
-                .selectAll()
-                .limit(1)
-                .execute();
+            await sql `
+        select 1
+        from ${sql.table('sync_outbox_commits')}
+        limit 1
+      `.execute(this.options.db);
             syncMigrated = true;
         }
         catch {
             syncMigrated = false;
         }
-        // Check if blob tables exist
-        let blobsMigrated = false;
-        try {
-            await this.options.db
-                .selectFrom('sync_blob_cache')
-                .selectAll()
-                .limit(1)
-                .execute();
-            blobsMigrated = true;
-        }
-        catch {
-            blobsMigrated = false;
-        }
-        return { syncMigrated, blobsMigrated };
+        return { syncMigrated };
     }
     /**
      * Static: Check if migrations are needed.
      */
     static async checkMigrations(db) {
         let syncMigrated = false;
-        let blobsMigrated = false;
         try {
-            await db.selectFrom('sync_outbox_commits').selectAll().limit(1).execute();
+            await sql `
+        select 1
+        from ${sql.table('sync_outbox_commits')}
+        limit 1
+      `.execute(db);
             syncMigrated = true;
         }
         catch {
             syncMigrated = false;
         }
-        try {
-            await db.selectFrom('sync_blob_cache').selectAll().limit(1).execute();
-            blobsMigrated = true;
-        }
-        catch {
-            blobsMigrated = false;
-        }
         return {
             needsMigration: !syncMigrated,
             syncMigrated,
-            blobsMigrated,
         };
     }
     /**
      * Static: Run migrations.
      */
-    static async migrate(db, options) {
+    static async migrate(db) {
         await ensureClientSyncSchema(db);
-        if (options?.blobs) {
-            await ensureClientBlobSchema(db);
-        }
     }
     // ===========================================================================
     // Private Helpers
@@ -633,365 +668,5 @@ export class Client {
             createdAt: info.createdAt,
         };
     }
-    createBlobClient(storage, transport) {
-        const db = this.options.db;
-        const blobs = transport.blobs;
-        const staleUploadingTimeoutMs = 30_000;
-        const maxUploadRetries = 3;
-        return {
-            async store(data, options) {
-                const bytes = await toUint8Array(data);
-                const mimeType = data instanceof Blob
-                    ? data.type
-                    : (options?.mimeType ?? 'application/octet-stream');
-                // Compute hash
-                const hashHex = await computeSha256Hex(bytes);
-                const hash = `sha256:${hashHex}`;
-                // Store locally
-                await storage.write(hash, bytes);
-                // Store metadata
-                const now = Date.now();
-                await sql `
-          insert into ${sql.table('sync_blob_cache')} (
-            ${sql.join([
-                    sql.ref('hash'),
-                    sql.ref('size'),
-                    sql.ref('mime_type'),
-                    sql.ref('cached_at'),
-                    sql.ref('last_accessed_at'),
-                    sql.ref('encrypted'),
-                    sql.ref('key_id'),
-                    sql.ref('body'),
-                ])}
-          ) values (
-            ${sql.join([
-                    sql.val(hash),
-                    sql.val(bytes.length),
-                    sql.val(mimeType),
-                    sql.val(now),
-                    sql.val(now),
-                    sql.val(0),
-                    sql.val(null),
-                    sql.val(bytes),
-                ])}
-          )
-          on conflict (${sql.ref('hash')}) do nothing
-        `.execute(db);
-                // Queue for upload or upload immediately
-                if (options?.immediate) {
-                    // Initiate upload
-                    const initResult = await blobs.initiateUpload({
-                        hash,
-                        size: bytes.length,
-                        mimeType,
-                    });
-                    if (!initResult.exists && initResult.uploadUrl) {
-                        // Upload to presigned URL
-                        const uploadResponse = await fetch(initResult.uploadUrl, {
-                            method: initResult.uploadMethod ?? 'PUT',
-                            body: bytes.buffer,
-                            headers: initResult.uploadHeaders,
-                        });
-                        if (!uploadResponse.ok) {
-                            throw new Error(`Upload failed: ${uploadResponse.statusText}`);
-                        }
-                        // Complete upload
-                        await blobs.completeUpload(hash);
-                    }
-                }
-                else {
-                    // Queue for later upload
-                    await sql `
-            insert into ${sql.table('sync_blob_outbox')} (
-              ${sql.join([
-                        sql.ref('hash'),
-                        sql.ref('size'),
-                        sql.ref('mime_type'),
-                        sql.ref('status'),
-                        sql.ref('created_at'),
-                        sql.ref('updated_at'),
-                        sql.ref('attempt_count'),
-                        sql.ref('error'),
-                        sql.ref('encrypted'),
-                        sql.ref('key_id'),
-                        sql.ref('body'),
-                    ])}
-            ) values (
-              ${sql.join([
-                        sql.val(hash),
-                        sql.val(bytes.length),
-                        sql.val(mimeType),
-                        sql.val('pending'),
-                        sql.val(now),
-                        sql.val(now),
-                        sql.val(0),
-                        sql.val(null),
-                        sql.val(0),
-                        sql.val(null),
-                        sql.val(bytes),
-                    ])}
-            )
-            on conflict (${sql.ref('hash')}) do nothing
-          `.execute(db);
-                }
-                return {
-                    hash,
-                    size: bytes.length,
-                    mimeType,
-                };
-            },
-            async retrieve(ref) {
-                // Check local storage first
-                const local = await storage.read(ref.hash);
-                if (local) {
-                    // Update access time
-                    await sql `
-            update ${sql.table('sync_blob_cache')}
-            set ${sql.ref('last_accessed_at')} = ${sql.val(Date.now())}
-            where ${sql.ref('hash')} = ${sql.val(ref.hash)}
-          `.execute(db);
-                    return local;
-                }
-                // Fetch from server
-                const { url } = await blobs.getDownloadUrl(ref.hash);
-                const response = await fetch(url);
-                if (!response.ok) {
-                    throw new Error(`Download failed: ${response.statusText}`);
-                }
-                const bytes = new Uint8Array(await response.arrayBuffer());
-                // Cache locally
-                await storage.write(ref.hash, bytes);
-                const now = Date.now();
-                await sql `
-          insert into ${sql.table('sync_blob_cache')} (
-            ${sql.join([
-                    sql.ref('hash'),
-                    sql.ref('size'),
-                    sql.ref('mime_type'),
-                    sql.ref('cached_at'),
-                    sql.ref('last_accessed_at'),
-                    sql.ref('encrypted'),
-                    sql.ref('key_id'),
-                    sql.ref('body'),
-                ])}
-          ) values (
-            ${sql.join([
-                    sql.val(ref.hash),
-                    sql.val(bytes.length),
-                    sql.val(ref.mimeType),
-                    sql.val(now),
-                    sql.val(now),
-                    sql.val(0),
-                    sql.val(null),
-                    sql.val(bytes),
-                ])}
-          )
-          on conflict (${sql.ref('hash')}) do nothing
-        `.execute(db);
-                return bytes;
-            },
-            async isLocal(hash) {
-                return storage.exists(hash);
-            },
-            async preload(refs) {
-                await Promise.all(refs.map((ref) => this.retrieve(ref)));
-            },
-            async processUploadQueue() {
-                let uploaded = 0;
-                let failed = 0;
-                const now = Date.now();
-                const staleThreshold = now - staleUploadingTimeoutMs;
-                await sql `
-          update ${sql.table('sync_blob_outbox')}
-          set
-            ${sql.ref('status')} = ${sql.val('failed')},
-            ${sql.ref('attempt_count')} = ${sql.ref('attempt_count')} + ${sql.val(1)},
-            ${sql.ref('error')} = ${sql.val('Upload timed out while in uploading state')},
-            ${sql.ref('updated_at')} = ${sql.val(now)}
-          where ${sql.ref('status')} = ${sql.val('uploading')}
-            and ${sql.ref('updated_at')} < ${sql.val(staleThreshold)}
-            and ${sql.ref('attempt_count')} + ${sql.val(1)} >= ${sql.val(maxUploadRetries)}
-        `.execute(db);
-                await sql `
-          update ${sql.table('sync_blob_outbox')}
-          set
-            ${sql.ref('status')} = ${sql.val('pending')},
-            ${sql.ref('attempt_count')} = ${sql.ref('attempt_count')} + ${sql.val(1)},
-            ${sql.ref('error')} = ${sql.val('Upload timed out while in uploading state; retrying')},
-            ${sql.ref('updated_at')} = ${sql.val(now)}
-          where ${sql.ref('status')} = ${sql.val('uploading')}
-            and ${sql.ref('updated_at')} < ${sql.val(staleThreshold)}
-            and ${sql.ref('attempt_count')} + ${sql.val(1)} < ${sql.val(maxUploadRetries)}
-        `.execute(db);
-                const pendingResult = await sql `
-          select
-            ${sql.ref('hash')},
-            ${sql.ref('size')},
-            ${sql.ref('mime_type')},
-            ${sql.ref('body')},
-            ${sql.ref('attempt_count')}
-          from ${sql.table('sync_blob_outbox')}
-          where ${sql.ref('status')} = ${sql.val('pending')}
-            and ${sql.ref('attempt_count')} < ${sql.val(maxUploadRetries)}
-          limit ${sql.val(10)}
-        `.execute(db);
-                const pending = pendingResult.rows;
-                for (const item of pending) {
-                    const nextAttemptCount = item.attempt_count + 1;
-                    try {
-                        // Mark as uploading
-                        await sql `
-              update ${sql.table('sync_blob_outbox')}
-              set
-                ${sql.ref('status')} = ${sql.val('uploading')},
-                ${sql.ref('attempt_count')} = ${sql.val(nextAttemptCount)},
-                ${sql.ref('error')} = ${sql.val(null)},
-                ${sql.ref('updated_at')} = ${sql.val(Date.now())}
-              where ${sql.ref('hash')} = ${sql.val(item.hash)}
-                and ${sql.ref('status')} = ${sql.val('pending')}
-            `.execute(db);
-                        // Initiate upload
-                        const initResult = await blobs.initiateUpload({
-                            hash: item.hash,
-                            size: item.size,
-                            mimeType: item.mime_type,
-                        });
-                        if (!initResult.exists && initResult.uploadUrl && item.body) {
-                            const uploadBody = new ArrayBuffer(item.body.byteLength);
-                            new Uint8Array(uploadBody).set(item.body);
-                            // Upload
-                            const uploadResponse = await fetch(initResult.uploadUrl, {
-                                method: initResult.uploadMethod ?? 'PUT',
-                                body: uploadBody,
-                                headers: initResult.uploadHeaders,
-                            });
-                            if (!uploadResponse.ok) {
-                                throw new Error(`Upload failed: ${uploadResponse.statusText}`);
-                            }
-                            // Complete
-                            const completeResult = await blobs.completeUpload(item.hash);
-                            if (!completeResult.ok) {
-                                throw new Error(completeResult.error ?? 'Failed to complete blob upload');
-                            }
-                        }
-                        // Mark as complete
-                        await sql `
-              delete from ${sql.table('sync_blob_outbox')}
-              where ${sql.ref('hash')} = ${sql.val(item.hash)}
-            `.execute(db);
-                        uploaded++;
-                    }
-                    catch (err) {
-                        const nextStatus = nextAttemptCount >= maxUploadRetries ? 'failed' : 'pending';
-                        await sql `
-              update ${sql.table('sync_blob_outbox')}
-              set
-                ${sql.ref('status')} = ${sql.val(nextStatus)},
-                ${sql.ref('error')} = ${sql.val(err instanceof Error ? err.message : 'Unknown error')},
-                ${sql.ref('updated_at')} = ${sql.val(Date.now())}
-              where ${sql.ref('hash')} = ${sql.val(item.hash)}
-            `.execute(db);
-                        if (nextStatus === 'failed') {
-                            failed++;
-                        }
-                    }
-                }
-                return { uploaded, failed };
-            },
-            async getUploadQueueStats() {
-                const rowsResult = await sql `
-          select
-            ${sql.ref('status')} as status,
-            count(${sql.ref('hash')}) as count
-          from ${sql.table('sync_blob_outbox')}
-          group by ${sql.ref('status')}
-        `.execute(db);
-                const stats = { pending: 0, uploading: 0, failed: 0 };
-                for (const row of rowsResult.rows) {
-                    if (row.status === 'pending')
-                        stats.pending = Number(row.count);
-                    if (row.status === 'uploading')
-                        stats.uploading = Number(row.count);
-                    if (row.status === 'failed')
-                        stats.failed = Number(row.count);
-                }
-                return stats;
-            },
-            async getCacheStats() {
-                const result = await sql `
-          select
-            count(${sql.ref('hash')}) as count,
-            sum(${sql.ref('size')}) as totalBytes
-          from ${sql.table('sync_blob_cache')}
-        `.execute(db);
-                const row = result.rows[0];
-                return {
-                    count: Number(row?.count ?? 0),
-                    totalBytes: Number(row?.totalBytes ?? 0),
-                };
-            },
-            async pruneCache(maxBytes) {
-                if (!maxBytes)
-                    return 0;
-                // Get current size
-                const stats = await this.getCacheStats();
-                if (stats.totalBytes <= maxBytes)
-                    return 0;
-                // Get oldest entries to delete
-                const toFree = stats.totalBytes - maxBytes;
-                let freed = 0;
-                const oldEntriesResult = await sql `
-          select ${sql.ref('hash')}, ${sql.ref('size')}
-          from ${sql.table('sync_blob_cache')}
-          order by ${sql.ref('last_accessed_at')} asc
-        `.execute(db);
-                const oldEntries = oldEntriesResult.rows;
-                for (const entry of oldEntries) {
-                    if (freed >= toFree)
-                        break;
-                    await storage.delete(entry.hash);
-                    await sql `
-            delete from ${sql.table('sync_blob_cache')}
-            where ${sql.ref('hash')} = ${sql.val(entry.hash)}
-          `.execute(db);
-                    freed += entry.size;
-                }
-                return freed;
-            },
-            async clearCache() {
-                if (storage.clear) {
-                    await storage.clear();
-                }
-                else {
-                    // Delete each entry individually
-                    const entriesResult = await sql `
-            select ${sql.ref('hash')}
-            from ${sql.table('sync_blob_cache')}
-          `.execute(db);
-                    for (const entry of entriesResult.rows) {
-                        await storage.delete(entry.hash);
-                    }
-                }
-                await sql `delete from ${sql.table('sync_blob_cache')}`.execute(db);
-            },
-        };
-    }
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-async function toUint8Array(data) {
-    if (data instanceof Uint8Array) {
-        return data;
-    }
-    const buffer = await data.arrayBuffer();
-    return new Uint8Array(buffer);
-}
-async function computeSha256Hex(data) {
-    const hashBuffer = await crypto.subtle.digest('SHA-256', data.buffer);
-    const hashArray = new Uint8Array(hashBuffer);
-    return Array.from(hashArray)
-        .map((b) => b.toString(16).padStart(2, '0'))
-        .join('');
 }
 //# sourceMappingURL=client.js.map