@salesforce/lds-drafts 1.454.0 → 1.455.0

package/dist/ldsDrafts.js

@@ -315,6 +315,25 @@ const DRAFT_SEGMENT = 'DRAFT';
  */
 const DRAFT_ACTION_RETRY_COUNT_METADATA_KEY = 'retryCount';
 class DurableDraftQueue {
+    // Instrumentation is strictly measure-only: a broken sink must never change queue behavior.
+    // Pass the sink into the callback so methods are invoked through their owning object and retain
+    // their receiver (some sinks use `this` to reach their metric registry).
+    emitInstrumentation(emit) {
+        const { instrumentation } = this;
+        if (instrumentation === undefined) {
+            return;
+        }
+        try {
+            emit(instrumentation);
+        }
+        catch {
+            // Telemetry failures must not interrupt draft processing.
+        }
+    }
+    resetDrainCycle() {
+        this.drainCycleStart = undefined;
+        this.drainCycleBatchCount = 0;
+    }
     getHandler(id) {
         const handler = this.handlers[id];
         if (handler === undefined) {
@@ -337,9 +356,19 @@ class DurableDraftQueue {
             ? __nimbus.plugins.JSLoggerPlugin
             : undefined;
         this.handlers = {};
+        // Drain-wait attribution state. uploadStartTimes stamps when each action first began
+        // uploading (keyed by action id) so actionCompleted/failed can emit its end-to-end drain time,
+        // including automatic retries/backoff. actionQueueWaitEmittedIds ensures those retries do not
+        // report the original enqueue wait more than once. drainCycleStart/BatchCount track one full
+        // idle->empty sweep. All measure-only; when no instrumentation is injected these stay untouched.
+        this.uploadStartTimes = new Map();
+        this.actionQueueWaitEmittedIds = new Set();
+        this.drainCycleBatchCount = 0;
         this.draftStore = draftStore;
-        this.workerPool = new AsyncWorkerPool(1);
         this.instrumentation = instrumentation;
+        this.workerPool = new AsyncWorkerPool(1, instrumentation?.onWorkerTiming !== undefined
+            ? (waitMs, holdMs, queueDepth) => this.emitInstrumentation((sink) => sink.onWorkerTiming?.(waitMs, holdMs, queueDepth))
+            : undefined);
     }
     addHandler(handler) {
         const id = handler.handlerId;
@@ -427,6 +456,9 @@ class DurableDraftQueue {
             clearTimeout(this.timeoutHandler);
             this.timeoutHandler = undefined;
         }
+        // A stop/user edit breaks the current sweep. A later restart starts a fresh cycle rather
+        // than attributing stopped time to an offline drain.
+        this.resetDrainCycle();
         this.state = DraftQueueState.Stopped;
     }
     async getQueueActions() {
@@ -457,7 +489,7 @@ class DurableDraftQueue {
             }
             return aTime - bTime;
         });
-        instrumentation?.onGetQueueActions?.(Date.now() - start, sorted.length);
+        this.emitInstrumentation((sink) => sink.onGetQueueActions?.(Date.now() - start, sorted.length));
         return sorted;
     }
     async enqueue(handlerId, data, observabilityContext) {
@@ -501,6 +533,13 @@ class DurableDraftQueue {
                 await handler.handleActionCompleted(action, queueOperations, values(this.handlers));
                 this.retryIntervalMilliseconds = 0;
                 this.uploadingActionId = undefined;
+                // The action finished draining — emit its end-to-end drain time and
+                // count it toward the current drain-cycle batch. Measure-only.
+                this.emitActionDrainDuration(action.id, action.handler);
+                this.actionQueueWaitEmittedIds.delete(action.id);
+                if (this.drainCycleStart !== undefined) {
+                    this.drainCycleBatchCount += 1;
+                }
                 await this.notifyChangedListeners({
                     type: DraftQueueEventType.ActionCompleted,
                     action,
@@ -512,6 +551,16 @@ class DurableDraftQueue {
             },
         });
     }
+    // Read+clear the action's upload-start stamp and emit its drain duration. Safe to
+    // call when instrumentation is absent or the id was never stamped (no-op). Never emits the id.
+    emitActionDrainDuration(id, handlerId) {
+        const start = this.uploadStartTimes.get(id);
+        if (start === undefined) {
+            return;
+        }
+        this.uploadStartTimes.delete(id);
+        this.emitInstrumentation((sink) => sink.onActionDrainDuration?.(handlerId, Date.now() - start));
+    }
     async actionFailed(action, retry, retryDelayInMs, actionDataChanged) {
         if (actionDataChanged === true) {
             await this.draftStore.writeAction({
@@ -521,14 +570,24 @@ class DurableDraftQueue {
         }
         this.uploadingActionId = undefined;
         if (retry && this.state !== DraftQueueState.Stopped) {
+            // A retry means this action is NOT done draining. Keep its first-upload stamp and the
+            // open cycle so the eventual outcome includes network time and retry/backoff.
             this.state = DraftQueueState.Waiting;
             return retryDelayInMs !== undefined
                 ? this.scheduleRetryWithSpecifiedDelay(retryDelayInMs)
                 : this.scheduleRetry();
         }
         else if (isDraftError(action)) {
+            // Terminal failure — this action is done draining. Emit its drain time.
+            this.emitActionDrainDuration(action.id, action.handler);
+            // This was not a clean drain-to-empty. Discard the sweep before user intervention so a
+            // later manual retry/removal cannot inherit its elapsed time or completed batch count.
+            this.resetDrainCycle();
             return this.handleServerError(action, action.error);
         }
+        // Any other terminal path — ensure no stale start stamp lingers.
+        this.emitActionDrainDuration(action.id, action.handler);
+        this.resetDrainCycle();
     }
     handle(action) {
         const handler = this.getHandler(action.handler);
@@ -548,12 +607,22 @@ class DurableDraftQueue {
                 this.state = DraftQueueState.Started;
             }
             this.processingAction = undefined;
+            // The queue drained empty — close the drain-cycle window if one was open.
+            if (this.drainCycleStart !== undefined) {
+                const durationMs = Date.now() - this.drainCycleStart;
+                const batchSize = this.drainCycleBatchCount;
+                this.resetDrainCycle();
+                this.emitInstrumentation((sink) => sink.onDrainCycle?.(durationMs, batchSize));
+            }
             return ProcessActionResult.NO_ACTION_TO_PROCESS;
         }
         const { status, id } = action;
         if (status === DraftActionStatus.Error) {
             this.state = DraftQueueState.Error;
             this.processingAction = undefined;
+            // The sweep is blocked on an errored action, not a clean drain-to-empty —
+            // discard the open drain-cycle window so it doesn't inflate a later cycle's duration.
+            this.resetDrainCycle();
             await this.notifyChangedListeners({
                 type: DraftQueueEventType.ActionFailed,
                 action: action,
@@ -571,6 +640,31 @@ class DurableDraftQueue {
         if (this.state === DraftQueueState.Waiting) {
             this.state = DraftQueueState.Started;
         }
+        // The action is now leaving the queue to upload. Emit head-of-line FIFO wait
+        // (enqueue -> upload start), stamp its drain-start for end-to-end timing on completion, and
+        // open a drain-cycle window if the queue was previously idle. All measure-only.
+        const { instrumentation } = this;
+        if (instrumentation !== undefined) {
+            const now = Date.now();
+            const { timestamp } = action;
+            if (instrumentation.onActionQueueWait !== undefined &&
+                !this.actionQueueWaitEmittedIds.has(id) &&
+                typeof timestamp === 'number' &&
+                timestamp > 0) {
+                // Mark before invoking the sink: even a throwing callback must not make a retry
+                // report the same action's enqueue wait again.
+                this.actionQueueWaitEmittedIds.add(id);
+                this.emitInstrumentation((sink) => sink.onActionQueueWait?.(action.handler, now - timestamp));
+            }
+            if (instrumentation.onActionDrainDuration !== undefined &&
+                !this.uploadStartTimes.has(id)) {
+                this.uploadStartTimes.set(id, now);
+            }
+            if (instrumentation.onDrainCycle !== undefined && this.drainCycleStart === undefined) {
+                this.drainCycleStart = now;
+                this.drainCycleBatchCount = 0;
+            }
+        }
         await this.notifyChangedListeners({
             type: DraftQueueEventType.ActionUploading,
             action: { ...action, status: DraftActionStatus.Uploading },
@@ -608,7 +702,7 @@ class DurableDraftQueue {
             results.push(listener(event));
         }
         // W-23515682: listener fan-out per event type. Measure-only.
-        this.instrumentation?.onNotifyChangedListeners?.(event.type, draftQueueLen);
+        this.emitInstrumentation((sink) => sink.onNotifyChangedListeners?.(event.type, draftQueueLen));
         await Promise.all(results);
     }
     /**
@@ -637,9 +731,17 @@ class DurableDraftQueue {
         const shouldDeleteRelated = handler.shouldDeleteActionByTagOnRemoval(action);
         if (shouldDeleteRelated) {
             await this.draftStore.deleteByTag(action.tag);
+            queue.forEach((queuedAction) => {
+                if (queuedAction.tag === action.tag) {
+                    this.uploadStartTimes.delete(queuedAction.id);
+                    this.actionQueueWaitEmittedIds.delete(queuedAction.id);
+                }
+            });
         }
         else {
             await this.draftStore.deleteDraft(action.id);
+            this.uploadStartTimes.delete(action.id);
+            this.actionQueueWaitEmittedIds.delete(action.id);
         }
         await handler.handleActionRemoved(action, queue.filter((x) => x.id !== actionId));
         await this.notifyChangedListeners({

package/dist/types/DraftQueueInstrumentation.d.ts

@@ -2,4 +2,8 @@ export interface DraftQueueInstrumentation {
     onGetQueueActions?(durationMs: number, actionCount: number): void;
     onNotifyChangedListeners?(eventType: string, listenerCount: number): void;
     onDurableOperation?(op: string, segment: string, durationMs: number): void;
+    onWorkerTiming?(waitMs: number, holdMs: number, queueDepth: number): void;
+    onActionQueueWait?(handlerId: string, waitMs: number): void;
+    onActionDrainDuration?(handlerId: string, durationMs: number): void;
+    onDrainCycle?(durationMs: number, batchSize: number): void;
 }

package/dist/types/DurableDraftQueue.d.ts

@@ -29,6 +29,12 @@ export declare class DurableDraftQueue implements DraftQueue {
     private workerPool;
     private handlers;
     private instrumentation?;
+    private uploadStartTimes;
+    private actionQueueWaitEmittedIds;
+    private drainCycleStart?;
+    private drainCycleBatchCount;
+    private emitInstrumentation;
+    private resetDrainCycle;
     private getHandler;
     constructor(draftStore: DraftStore, instrumentation?: DraftQueueInstrumentation);
     addHandler<Data>(handler: ActionHandler<Data, unknown>): Promise<void>;
@@ -46,6 +52,7 @@ export declare class DurableDraftQueue implements DraftQueue {
     enqueue<Data>(handlerId: string, data: unknown, observabilityContext?: ObservabilityContext): Promise<PendingDraftAction<Data>>;
     registerOnChangedListener(listener: DraftQueueChangeListener): () => Promise<void>;
     actionCompleted(action: CompletedDraftAction<unknown, unknown>): Promise<void>;
+    private emitActionDrainDuration;
     actionFailed(action: DraftAction<unknown, unknown>, retry: boolean, retryDelayInMs?: number, actionDataChanged?: boolean): Promise<void>;
     handle(action: DraftAction<unknown, unknown>): Promise<ProcessActionResult>;
     processNextAction(): Promise<ProcessActionResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforce/lds-drafts",
-    "version": "1.454.0",
+    "version": "1.455.0",
     "license": "SEE LICENSE IN LICENSE.txt",
     "description": "LDS Drafts",
     "main": "dist/ldsDrafts.js",
@@ -26,10 +26,10 @@
     "dependencies": {
         "@luvio/engine": "0.161.2",
         "@luvio/environments": "0.161.2",
-        "@salesforce/lds-utils-adapters": "^1.454.0"
+        "@salesforce/lds-utils-adapters": "^1.455.0"
     },
     "devDependencies": {
-        "@salesforce/nimbus-plugin-lds": "^1.454.0"
+        "@salesforce/nimbus-plugin-lds": "^1.455.0"
     },
     "volta": {
         "extends": "../../package.json"