@abloatai/ablo 0.10.1 → 0.11.0

package/dist/transactions/TransactionQueue.js

@@ -225,6 +225,7 @@ export class TransactionQueue extends EventEmitter {
     // Per-model in-flight tracking and merge buffer
     inFlightByModel = new Set();
     pendingMergeByModel = new Map();
+    deferredDeletesByCreate = new Map();
     // Commit lane: pre-built atomic multi-op envelopes from `ablo.commits.create()`.
     // Drained serially (one envelope at a time) since each is atomic; no
     // coalescing with model-proxy transactions.
@@ -242,6 +243,102 @@ export class TransactionQueue extends EventEmitter {
             transaction.priorityScore = this.computePriorityScore(transaction.type, transaction.modelName);
         }
     }
+    entityKey(modelName, modelId) {
+        return `${modelName}:${modelId}`;
+    }
+    isTransactionForModel(transaction, modelName, modelId) {
+        return transaction.modelName === modelName && transaction.modelId === modelId;
+    }
+    resolveConfirmation(transaction) {
+        const resolver = this.confirmationResolvers.get(transaction.id);
+        if (!resolver)
+            return;
+        this.confirmationResolvers.delete(transaction.id);
+        resolver.resolve();
+    }
+    takeUnsentCreateForModel(modelName, modelId) {
+        const isUnsentCreate = (tx) => tx.type === 'create' &&
+            tx.status === 'pending' &&
+            tx.attempts === 0 &&
+            this.isTransactionForModel(tx, modelName, modelId);
+        const stagedIndex = this.createdTransactions.findIndex(isUnsentCreate);
+        if (stagedIndex >= 0) {
+            return this.createdTransactions.splice(stagedIndex, 1)[0];
+        }
+        const queuedIndex = this.executionQueue.findIndex(isUnsentCreate);
+        if (queuedIndex >= 0) {
+            return this.executionQueue.splice(queuedIndex, 1)[0];
+        }
+        return this.store.getByStatus('pending').find(isUnsentCreate);
+    }
+    async cancelUnsentCreateForDelete(transaction) {
+        this.store.updateStatus(transaction.id, 'rolled_back');
+        if (this.config.enableOptimistic) {
+            await this.rollbackOptimistic(transaction, 'model_cancelled');
+        }
+        this.resolveConfirmation(transaction);
+    }
+    findCreateBarrierForDelete(modelName, modelId) {
+        const liveCreates = [
+            ...this.store.getByStatus('pending'),
+            ...this.store.getByStatus('executing'),
+            ...this.store.getByStatus('awaiting_delta'),
+        ].filter((tx) => tx.type === 'create' &&
+            this.isTransactionForModel(tx, modelName, modelId) &&
+            // A never-attempted pending create can be cancelled instead. Once the
+            // create has been sent, even a retry-pending state is a causal barrier:
+            // the server may already have applied it and only the response was lost.
+            (tx.status !== 'pending' || tx.attempts > 0));
+        return liveCreates.sort((a, b) => b.createdAt - a.createdAt)[0];
+    }
+    completeLocalDelete(model, context, writeOptions) {
+        const actualModelName = model.getModelName();
+        const modelKey = normalizeModelKey(actualModelName);
+        const transaction = {
+            id: this.generateId(),
+            type: 'delete',
+            modelName: actualModelName,
+            modelId: model.id,
+            modelKey,
+            priorityScore: this.computePriorityScore('delete', actualModelName),
+            previousData: model.toJSON ? model.toJSON() : { ...model },
+            context,
+            status: 'completed',
+            createdAt: Date.now(),
+            attempts: 0,
+            priority: 'high',
+            writeOptions,
+            localOnly: true,
+        };
+        this.attachConfirmation(transaction);
+        this.store.add(transaction);
+        if (this.config.enableOptimistic) {
+            this.applyOptimisticDelete(model, transaction);
+        }
+        this.emit('transaction:created', transaction);
+        this.emit('transaction:completed', transaction);
+        this.emit(`transaction:completed:${transaction.id}`, transaction);
+        this.optimisticUpdates.delete(transaction.id);
+        return transaction;
+    }
+    deferDeleteUntilCreateSettles(createTransaction, deleteTransaction) {
+        const key = this.entityKey(createTransaction.modelName, createTransaction.modelId);
+        const deferred = this.deferredDeletesByCreate.get(key) ?? [];
+        deferred.push(deleteTransaction);
+        this.deferredDeletesByCreate.set(key, deferred);
+    }
+    releaseDeferredDeletesForCreate(createTransaction) {
+        const key = this.entityKey(createTransaction.modelName, createTransaction.modelId);
+        const deferred = this.deferredDeletesByCreate.get(key);
+        if (!deferred || deferred.length === 0)
+            return;
+        this.deferredDeletesByCreate.delete(key);
+        for (const deleteTransaction of deferred) {
+            if (this.store.get(deleteTransaction.id)?.status !== 'pending')
+                continue;
+            this.enqueue(deleteTransaction);
+        }
+    }
     // Merge two GraphQL update payloads with special handling for metadata fields
     mergeUpdateData(left, right, _modelName) {
         const out = { ...(left || {}) };
@@ -374,6 +471,9 @@ export class TransactionQueue extends EventEmitter {
                 this.confirmationResolvers.delete(tx.id);
                 r.resolve();
             }
+            if (tx.type === 'create') {
+                this.releaseDeferredDeletesForCreate(tx);
+            }
         });
         this.on('transaction:failed', ({ transaction, error }) => {
             const r = this.confirmationResolvers.get(transaction.id);
@@ -381,6 +481,9 @@ export class TransactionQueue extends EventEmitter {
                 this.confirmationResolvers.delete(transaction.id);
                 r.reject(error);
             }
+            if (transaction.type === 'create') {
+                this.releaseDeferredDeletesForCreate(transaction);
+            }
         });
     }
     /**
@@ -726,6 +829,7 @@ export class TransactionQueue extends EventEmitter {
                 attempts: 0,
                 priority: 'high',
                 writeOptions,
+                localOnly: true,
                 // Activity deletes complete synchronously (audit-record skip path).
                 // Pre-resolved so consumers can still `await tx.confirmation` uniformly.
                 confirmation: Promise.resolve(),
@@ -740,6 +844,11 @@ export class TransactionQueue extends EventEmitter {
         }
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('delete', actualModelName);
+        const unsentCreate = this.takeUnsentCreateForModel(actualModelName, model.id);
+        if (unsentCreate) {
+            await this.cancelUnsentCreateForDelete(unsentCreate);
+            return this.completeLocalDelete(model, context, writeOptions);
+        }
         const transaction = {
             id: this.generateId(),
             type: 'delete',
@@ -760,15 +869,22 @@ export class TransactionQueue extends EventEmitter {
         // Cancel any pending/in-flight updates for this model to prevent "no rows" errors
         // when the delete executes before the update (race condition fix)
         this.cancelTransactionsForModel(model.id, 'update');
-        this.pendingMergeByModel.delete(`${actualModelName}:${model.id}`);
-        this.inFlightByModel.delete(`${actualModelName}:${model.id}`);
+        const entityKey = this.entityKey(actualModelName, model.id);
+        this.pendingMergeByModel.delete(entityKey);
+        this.inFlightByModel.delete(entityKey);
         // Apply optimistic delete
         if (this.config.enableOptimistic) {
             this.applyOptimisticDelete(model, transaction);
         }
-        // LINEAR PATTERN: Stage transaction for microtask commit
-        // All deletes in same event loop will be batched together
-        this.stageTransaction(transaction);
+        const createBarrier = this.findCreateBarrierForDelete(actualModelName, model.id);
+        if (createBarrier) {
+            this.deferDeleteUntilCreateSettles(createBarrier, transaction);
+        }
+        else {
+            // LINEAR PATTERN: Stage transaction for microtask commit
+            // All deletes in same event loop will be batched together
+            this.stageTransaction(transaction);
+        }
         this.emit('transaction:created', transaction);
         return transaction;
     }
@@ -1015,7 +1131,7 @@ export class TransactionQueue extends EventEmitter {
                             tx.syncIdNeededForCompletion = lastSyncId;
                             // Safety net: when lastSyncId is 0, DELETE transactions should be confirmed
                             // immediately. DELETEs are idempotent — if no delta was emitted, the entity
-                            // is already gone and the intent was achieved. Parking DELETEs in awaiting_delta
+                            // is already gone and the claim was achieved. Parking DELETEs in awaiting_delta
                             // with threshold 0 causes 30s reconciliation delays.
                             if (lastSyncId === 0 && tx.type === 'delete') {
                                 this.store.updateStatus(tx.id, 'completed');
@@ -1110,14 +1226,14 @@ export class TransactionQueue extends EventEmitter {
                         });
                         // LINEAR PATTERN: Handle "no rows in result set" gracefully
                         // This error means the entity was already deleted - for UPDATE/DELETE ops, this is success
-                        // The intent was achieved (the data doesn't exist), so treat as completed
+                        // The claim was achieved (the data doesn't exist), so treat as completed
                         if (errorMessage.includes('no rows in result set')) {
                             getContext().logger.info('[TransactionQueue] Graceful handling: entity already deleted', {
                                 batchSize: batchOps.length,
                             });
                             for (const { tx, op } of batchOps) {
                                 if (op.type === 'UPDATE' || op.type === 'DELETE') {
-                                    // Entity gone = intent achieved, mark as completed
+                                    // Entity gone = claim achieved, mark as completed
                                     this.store.updateStatus(tx.id, 'completed');
                                     this.emit('transaction:completed', tx);
                                     getContext().logger.debug('[TransactionQueue] Orphaned transaction treated as success', {
@@ -1973,6 +2089,8 @@ export class TransactionQueue extends EventEmitter {
         this.store.clear();
         this.optimisticUpdates.clear();
         this.executionQueue = [];
+        this.createdTransactions = [];
+        this.deferredDeletesByCreate.clear();
         // Clear event listeners
         this.removeAllListeners();
         // Reset state

package/dist/types/global.d.ts

@@ -1,9 +1,9 @@
 /**
  * Type registration point for SDK consumers.
  *
- * A consumer registers their Schema, Presence, Intents, and UserMeta ONCE by
+ * A consumer registers their Schema, Presence, Claims, and UserMeta ONCE by
  * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useIntent` — reads its types from the
+ * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from the
  * resolved registration. No generics at call sites, no `schema` arg per call.
  *
  * Registration is done via **module augmentation** of `@abloatai/ablo` —
@@ -22,7 +22,7 @@
  *   interface Register {
  *     Schema: typeof schema;
  *     Presence: { cursor: { x: number; y: number } | null };
- *     Intents: { editLayer: { layerId: string } };
+ *     Claims: { editLayer: { layerId: string } };
  *     UserMeta: { id: string; email: string };
  *   }
  * }
@@ -44,7 +44,7 @@ export interface DefaultSyncShape {
         readonly models: Record<string, unknown>;
     };
     readonly Presence: Record<string, unknown>;
-    readonly Intents: Record<string, unknown>;
+    readonly Claims: Record<string, unknown>;
     readonly UserMeta: {
         readonly id: string;
     };
@@ -75,13 +75,13 @@ export type ResolvePresence = Register extends {
     Presence: infer P;
 } ? P : DefaultSyncShape['Presence'];
 /**
- * The consumer's intent vocabulary, or the default if unregistered. Keys are
- * intent names; values are the claim payload for each intent. Used by
- * `useIntent(intentName)`.
+ * The consumer's claim vocabulary, or the default if unregistered. Keys are
+ * claim names; values are the claim payload for each claim. Used by
+ * `useClaim(claimName)`.
  */
-export type ResolveIntents = Register extends {
-    Intents: infer I;
-} ? I : DefaultSyncShape['Intents'];
+export type ResolveClaims = Register extends {
+    Claims: infer I;
+} ? I : DefaultSyncShape['Claims'];
 /**
  * The consumer's user-metadata shape, or the default if unregistered. Carries
  * identity info the consumer trusts from their auth layer — not SDK-validated.

package/dist/types/global.js

@@ -1,9 +1,9 @@
 /**
  * Type registration point for SDK consumers.
  *
- * A consumer registers their Schema, Presence, Intents, and UserMeta ONCE by
+ * A consumer registers their Schema, Presence, Claims, and UserMeta ONCE by
  * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useIntent` — reads its types from the
+ * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from the
  * resolved registration. No generics at call sites, no `schema` arg per call.
  *
  * Registration is done via **module augmentation** of `@abloatai/ablo` —
@@ -22,7 +22,7 @@
  *   interface Register {
  *     Schema: typeof schema;
  *     Presence: { cursor: { x: number; y: number } | null };
- *     Intents: { editLayer: { layerId: string } };
+ *     Claims: { editLayer: { layerId: string } };
  *     UserMeta: { id: string; email: string };
  *   }
  * }

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@
  * Foundational type definitions for the model-driven sync architecture.
  * These types define how properties are tracked, loaded, and synchronized.
  */
+import type { FieldMeta } from '../schema/field.js';
 /**
  * Model Scope - lifecycle filter for queries.
  * Controls whether live, archived, or all entities are returned.
@@ -108,14 +109,15 @@ export interface ModelMetadata {
      * JSON-typed values) inside the transaction queue.
      *
      * Populated by `registerModelsFromSchema`. Each entry carries the
-     * sync-engine type tag (`'string' | 'number' | 'boolean' | 'date' |
-     * 'enum' | 'json'`), which tells the wire serializer how to handle
-     * the value. Missing → projection becomes identity pass-through
-     * (back-compat for models registered outside the schema path).
+     * sync-engine type tag (the canonical {@link FieldMeta.type} union),
+     * which tells the wire serializer how to handle the value. Missing →
+     * projection becomes identity pass-through (back-compat for models
+     * registered outside the schema path).
+     *
+     * Narrowed to the canonical union via `Pick` rather than re-declared —
+     * a hand-rolled copy silently drifts when a new field type lands.
      */
-    fields?: Readonly<Record<string, {
-        type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'json';
-    }>>;
+    fields?: Readonly<Record<string, Pick<FieldMeta, 'type'>>>;
     /**
      * Fields to back-fill from the sync client identity when missing
      * during IndexedDB self-healing. Populated from

package/dist/types/index.js

@@ -65,6 +65,6 @@ export var MutationOperationType;
 })(MutationOperationType || (MutationOperationType = {}));
 // Re-export stream + snapshot + principal types for the engine surface
 // (PresenceStream,
-// IntentStream, Snapshot, etc.) consumed by `Ablo({...}).presence`,
-// `.intents`, `.snapshot()`.
+// ClaimStream, Snapshot, etc.) consumed by `Ablo({...}).presence`,
+// `.claims`, `.snapshot()`.
 export * from "./streams.js";