@syncular/client 0.35.0 → 0.36.0

package/dist/client.d.ts

@@ -553,6 +553,14 @@ export declare class SyncClient {
     subscription(id: string): SubscriptionRecord | undefined;
     pendingCommits(): OutboxCommit[];
     subscribe(input: SubscribeInput): void;
+    /**
+     * Register several subscriptions in one local transaction: the same rules
+     * as `subscribe` for each input, and one commit for all of them (on OPFS a
+     * commit costs milliseconds, so a cold start with hundreds of
+     * registrations pays it once). An error rolls back every registration of
+     * the call.
+     */
+    subscribeMany(inputs: readonly SubscribeInput[]): void;
     unsubscribe(id: string): void;
     /**
      * Set the live window units for a base (§4.8): a value-sharded family of

package/dist/client.js

@@ -1824,34 +1824,52 @@ export class SyncClient {
     }
     // -- subscriptions ----------------------------------------------------------
     subscribe(input) {
+        this.subscribeMany([input]);
+    }
+    /**
+     * Register several subscriptions in one local transaction: the same rules
+     * as `subscribe` for each input, and one commit for all of them (on OPFS a
+     * commit costs milliseconds, so a cold start with hundreds of
+     * registrations pays it once). An error rolls back every registration of
+     * the call.
+     */
+    subscribeMany(inputs) {
         this.#requireActive();
-        if (!this.#schema.tables.has(input.table)) {
-            throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
-        }
-        const existing = getSubscription(this.#db, input.id);
-        if (existing !== undefined) {
-            const sameIntent = existing.table === input.table &&
-                canonicalScopeJson(existing.scopes) ===
-                    canonicalScopeJson(input.scopes) &&
-                existing.params === input.params;
-            if (!sameIntent) {
-                throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
+        let registered = false;
+        this.#db.transaction(() => {
+            for (const input of inputs) {
+                if (!this.#schema.tables.has(input.table)) {
+                    throw new ClientSyncError('sync.unknown_table', `subscribe: unknown local table ${JSON.stringify(input.table)}`);
+                }
+                const existing = getSubscription(this.#db, input.id);
+                if (existing !== undefined) {
+                    const sameIntent = existing.table === input.table &&
+                        canonicalScopeJson(existing.scopes) ===
+                            canonicalScopeJson(input.scopes) &&
+                        existing.params === input.params;
+                    if (!sameIntent) {
+                        throw new ClientSyncError('client.subscription_intent_mismatch', 'subscription id already names different table, scopes, or params');
+                    }
+                    // §3.3: a revoked registration keeps its id and intent but no
+                    // progress. Subscribing again with the same intent re-arms it, so
+                    // the next pull resolves its scopes from scratch. A `failed`
+                    // registration is a configuration error and stays put.
+                    if (existing.status !== 'revoked')
+                        continue;
+                }
+                saveSubscription(this.#db, definedObject({
+                    id: input.id,
+                    table: input.table,
+                    scopes: input.scopes,
+                    params: input.params,
+                    cursor: -1,
+                    status: 'active',
+                }));
+                registered = true;
             }
-            // §3.3: a revoked registration keeps its id and intent but no progress.
-            // Subscribing again with the same intent re-arms it, so the next pull
-            // resolves its scopes from scratch. A `failed` registration is a
-            // configuration error and stays put.
-            if (existing.status !== 'revoked')
-                return;
-        }
-        saveSubscription(this.#db, definedObject({
-            id: input.id,
-            table: input.table,
-            scopes: input.scopes,
-            params: input.params,
-            cursor: -1,
-            status: 'active',
-        }));
+        });
+        if (!registered)
+            return;
         this.#setSyncNeeded(true);
         this.#emitSyncIntent({ kind: 'interactive' });
         this.#emitDiagnostics();

package/dist/worker-entry.js

@@ -300,6 +300,7 @@ export function startSyncWorker(overrides = {}) {
     const coreMethods = [
         'securityLifecycle',
         'subscribe',
+        'subscribeMany',
         'unsubscribe',
         'windowState',
         'purgeLocalData',

package/dist/worker-host.d.ts

@@ -224,6 +224,7 @@ export declare class SyncClientHandle implements PromiseMethods<WorkerApi> {
     onRoleChange(listener: (role: HandleRole) => void): () => void;
     onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
     subscribe(input: SubscribeInput): Promise<void>;
+    subscribeMany(inputs: readonly SubscribeInput[]): Promise<void>;
     securityLifecycle(): Promise<SecurityLifecycle>;
     beginSecurityPreflight(): Promise<void>;
     activateSecurity(options?: WorkerSecurityActivation): Promise<void>;

package/dist/worker-host.js

@@ -283,6 +283,9 @@ export class SyncClientHandle {
     subscribe(input) {
         return this.#call('subscribe', [input]);
     }
+    subscribeMany(inputs) {
+        return this.#call('subscribeMany', [inputs]);
+    }
     securityLifecycle() {
         return this.#call('securityLifecycle', []);
     }

package/dist/worker-protocol.d.ts

@@ -113,6 +113,7 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
     beginSecurityPreflight(): Promise<void>;
     activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
     subscribe(input: SubscribeInput): void;
+    subscribeMany(inputs: readonly SubscribeInput[]): void;
     unsubscribe(id: string): void;
     /** §4.8 windowed subscriptions: set the live units for a window base. */
     setWindow(base: WindowBase, units: readonly string[]): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -97,10 +97,10 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.35.0"
+    "@syncular/core": "0.36.0"
   },
   "devDependencies": {
-    "@syncular/server": "0.35.0",
+    "@syncular/server": "0.36.0",
     "playwright": "1.63.0",
     "@electric-sql/pglite": "^0.5.4"
   }

package/src/client.ts

@@ -2894,43 +2894,61 @@ export class SyncClient {
   // -- subscriptions ----------------------------------------------------------
 
   subscribe(input: SubscribeInput): void {
+    this.subscribeMany([input]);
+  }
+
+  /**
+   * Register several subscriptions in one local transaction: the same rules
+   * as `subscribe` for each input, and one commit for all of them (on OPFS a
+   * commit costs milliseconds, so a cold start with hundreds of
+   * registrations pays it once). An error rolls back every registration of
+   * the call.
+   */
+  subscribeMany(inputs: readonly SubscribeInput[]): void {
     this.#requireActive();
-    if (!this.#schema.tables.has(input.table)) {
-      throw new ClientSyncError(
-        'sync.unknown_table',
-        `subscribe: unknown local table ${JSON.stringify(input.table)}`,
-      );
-    }
-    const existing = getSubscription(this.#db, input.id);
-    if (existing !== undefined) {
-      const sameIntent =
-        existing.table === input.table &&
-        canonicalScopeJson(existing.scopes) ===
-          canonicalScopeJson(input.scopes) &&
-        existing.params === input.params;
-      if (!sameIntent) {
-        throw new ClientSyncError(
-          'client.subscription_intent_mismatch',
-          'subscription id already names different table, scopes, or params',
+    let registered = false;
+    this.#db.transaction(() => {
+      for (const input of inputs) {
+        if (!this.#schema.tables.has(input.table)) {
+          throw new ClientSyncError(
+            'sync.unknown_table',
+            `subscribe: unknown local table ${JSON.stringify(input.table)}`,
+          );
+        }
+        const existing = getSubscription(this.#db, input.id);
+        if (existing !== undefined) {
+          const sameIntent =
+            existing.table === input.table &&
+            canonicalScopeJson(existing.scopes) ===
+              canonicalScopeJson(input.scopes) &&
+            existing.params === input.params;
+          if (!sameIntent) {
+            throw new ClientSyncError(
+              'client.subscription_intent_mismatch',
+              'subscription id already names different table, scopes, or params',
+            );
+          }
+          // §3.3: a revoked registration keeps its id and intent but no
+          // progress. Subscribing again with the same intent re-arms it, so
+          // the next pull resolves its scopes from scratch. A `failed`
+          // registration is a configuration error and stays put.
+          if (existing.status !== 'revoked') continue;
+        }
+        saveSubscription(
+          this.#db,
+          definedObject({
+            id: input.id,
+            table: input.table,
+            scopes: input.scopes,
+            params: input.params,
+            cursor: -1,
+            status: 'active',
+          }),
         );
+        registered = true;
       }
-      // §3.3: a revoked registration keeps its id and intent but no progress.
-      // Subscribing again with the same intent re-arms it, so the next pull
-      // resolves its scopes from scratch. A `failed` registration is a
-      // configuration error and stays put.
-      if (existing.status !== 'revoked') return;
-    }
-    saveSubscription(
-      this.#db,
-      definedObject({
-        id: input.id,
-        table: input.table,
-        scopes: input.scopes,
-        params: input.params,
-        cursor: -1,
-        status: 'active',
-      }),
-    );
+    });
+    if (!registered) return;
     this.#setSyncNeeded(true);
     this.#emitSyncIntent({ kind: 'interactive' });
     this.#emitDiagnostics();

package/src/worker-entry.ts

@@ -415,6 +415,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
   const coreMethods = [
     'securityLifecycle',
     'subscribe',
+    'subscribeMany',
     'unsubscribe',
     'windowState',
     'purgeLocalData',

package/src/worker-host.ts

@@ -576,6 +576,10 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#call('subscribe', [input]);
   }
 
+  subscribeMany(inputs: readonly SubscribeInput[]): Promise<void> {
+    return this.#call('subscribeMany', [inputs]);
+  }
+
   securityLifecycle(): Promise<SecurityLifecycle> {
     return this.#call('securityLifecycle', []);
   }

package/src/worker-protocol.ts

@@ -158,6 +158,7 @@ export interface WorkerApi extends Omit<
   beginSecurityPreflight(): Promise<void>;
   activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
   subscribe(input: SubscribeInput): void;
+  subscribeMany(inputs: readonly SubscribeInput[]): void;
   unsubscribe(id: string): void;
   /** §4.8 windowed subscriptions: set the live units for a window base. */
   setWindow(base: WindowBase, units: readonly string[]): Promise<void>;