@cadenza.io/core 3.26.1 → 3.27.0

package/dist/index.d.mts

@@ -1993,6 +1993,7 @@ interface ActorSpec<D extends Record<string, any>, R = AnyObject> {
 interface ActorFactoryOptions<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
     isMeta?: boolean;
     definitionSource?: ActorDefinition<D, R>;
+    hydrateDurableState?: (actorKey: string) => Promise<ActorDurableStateHydration<D> | null>;
 }
 /**
  * Optional per-binding behavior when wrapping actor handlers.
@@ -2075,6 +2076,10 @@ interface ActorTaskContext<D extends Record<string, any>, R = AnyObject> {
  * Handler signature used by `actor.task(...)`.
  */
 type ActorTaskHandler<D extends Record<string, any>, R = AnyObject> = (context: ActorTaskContext<D, R>) => TaskResult | ActorStateReducer<D> | Promise<TaskResult | ActorStateReducer<D>>;
+interface ActorDurableStateHydration<D extends Record<string, any>> {
+    durableState: D;
+    durableVersion: number;
+}
 /**
  * Metadata attached to wrapped actor task functions.
  */
@@ -2101,9 +2106,11 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     readonly spec: ActorSpec<D, R>;
     readonly kind: ActorKind;
     private readonly sourceDefinition?;
+    private readonly hydrateDurableState?;
     private readonly stateByKey;
     private readonly sessionByKey;
     private readonly idempotencyByKey;
+    private readonly pendingHydrationByKey;
     private readonly writeQueueByKey;
     private nextTaskBindingIndex;
     /**
@@ -2154,6 +2161,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private resolveInitialDurableState;
     private resolveInitialRuntimeState;
     private ensureStateRecord;
+    private maybeHydrateStateRecord;
     private touchSession;
     private pruneExpiredActorKeys;
     private isSessionExpired;

package/dist/index.d.ts

@@ -1993,6 +1993,7 @@ interface ActorSpec<D extends Record<string, any>, R = AnyObject> {
 interface ActorFactoryOptions<D extends Record<string, any> = Record<string, any>, R = AnyObject> {
     isMeta?: boolean;
     definitionSource?: ActorDefinition<D, R>;
+    hydrateDurableState?: (actorKey: string) => Promise<ActorDurableStateHydration<D> | null>;
 }
 /**
  * Optional per-binding behavior when wrapping actor handlers.
@@ -2075,6 +2076,10 @@ interface ActorTaskContext<D extends Record<string, any>, R = AnyObject> {
  * Handler signature used by `actor.task(...)`.
  */
 type ActorTaskHandler<D extends Record<string, any>, R = AnyObject> = (context: ActorTaskContext<D, R>) => TaskResult | ActorStateReducer<D> | Promise<TaskResult | ActorStateReducer<D>>;
+interface ActorDurableStateHydration<D extends Record<string, any>> {
+    durableState: D;
+    durableVersion: number;
+}
 /**
  * Metadata attached to wrapped actor task functions.
  */
@@ -2101,9 +2106,11 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     readonly spec: ActorSpec<D, R>;
     readonly kind: ActorKind;
     private readonly sourceDefinition?;
+    private readonly hydrateDurableState?;
     private readonly stateByKey;
     private readonly sessionByKey;
     private readonly idempotencyByKey;
+    private readonly pendingHydrationByKey;
     private readonly writeQueueByKey;
     private nextTaskBindingIndex;
     /**
@@ -2154,6 +2161,7 @@ declare class Actor<D extends Record<string, any> = AnyObject, R = AnyObject> {
     private resolveInitialDurableState;
     private resolveInitialRuntimeState;
     private ensureStateRecord;
+    private maybeHydrateStateRecord;
     private touchSession;
     private pruneExpiredActorKeys;
     private isSessionExpired;

package/dist/index.js

@@ -3893,6 +3893,7 @@ var Actor = class {
     this.stateByKey = /* @__PURE__ */ new Map();
     this.sessionByKey = /* @__PURE__ */ new Map();
     this.idempotencyByKey = /* @__PURE__ */ new Map();
+    this.pendingHydrationByKey = /* @__PURE__ */ new Map();
     this.writeQueueByKey = /* @__PURE__ */ new Map();
     this.nextTaskBindingIndex = 0;
     if (!spec.name || typeof spec.name !== "string") {
@@ -3904,6 +3905,7 @@ var Actor = class {
     }
     this.kind = options.isMeta || spec.kind === "meta" ? "meta" : "standard";
     this.sourceDefinition = options.definitionSource;
+    this.hydrateDurableState = options.hydrateDurableState;
     this.spec = {
       ...spec,
       defaultKey: normalizedDefaultKey,
@@ -3931,7 +3933,7 @@ var Actor = class {
       this.pruneExpiredActorKeys(now2);
       this.touchSession(actorKey, invocationOptions.touchSession, now2);
       const runTask = async () => {
-        const stateRecord = this.ensureStateRecord(actorKey);
+        const stateRecord = await this.maybeHydrateStateRecord(actorKey);
         stateRecord.lastReadAt = Date.now();
         let durableStateChanged = false;
         let runtimeStateChanged = false;
@@ -4173,6 +4175,7 @@ var Actor = class {
       this.stateByKey.clear();
       this.sessionByKey.clear();
       this.idempotencyByKey.clear();
+      this.pendingHydrationByKey.clear();
       if ((this.spec.loadPolicy ?? "eager") === "eager") {
         this.ensureStateRecord(this.spec.defaultKey);
       }
@@ -4184,6 +4187,7 @@ var Actor = class {
     }
     this.stateByKey.delete(normalizedKey);
     this.sessionByKey.delete(normalizedKey);
+    this.pendingHydrationByKey.delete(normalizedKey);
     for (const key of this.idempotencyByKey.keys()) {
       if (key.startsWith(`${normalizedKey}:`)) {
         this.idempotencyByKey.delete(key);
@@ -4269,6 +4273,7 @@ var Actor = class {
       runtimeState: this.resolveInitialRuntimeState(),
       version: 0,
       runtimeVersion: 0,
+      hydrationResolved: this.hydrateDurableState === void 0,
       createdAt: now2,
       lastReadAt: now2,
       lastDurableWriteAt: now2,
@@ -4278,6 +4283,54 @@ var Actor = class {
     this.touchSession(actorKey, true, now2);
     return record;
   }
+  async maybeHydrateStateRecord(actorKey) {
+    const record = this.ensureStateRecord(actorKey);
+    if (record.hydrationResolved || !this.hydrateDurableState) {
+      return record;
+    }
+    const pending = this.pendingHydrationByKey.get(actorKey);
+    if (pending) {
+      return pending;
+    }
+    let hydrationPromise;
+    hydrationPromise = (async () => {
+      const current = this.ensureStateRecord(actorKey);
+      if (current.hydrationResolved || !this.hydrateDurableState) {
+        return current;
+      }
+      const snapshot = await this.hydrateDurableState(actorKey);
+      const latest = this.ensureStateRecord(actorKey);
+      if (latest.hydrationResolved) {
+        return latest;
+      }
+      if (snapshot) {
+        const durableVersion = Number(snapshot.durableVersion);
+        if (!Number.isInteger(durableVersion) || durableVersion < 0) {
+          throw new Error(
+            `Actor "${this.spec.name}" received invalid hydrated durable version for key "${actorKey}"`
+          );
+        }
+        if (!isObject2(snapshot.durableState) || Array.isArray(snapshot.durableState)) {
+          throw new Error(
+            `Actor "${this.spec.name}" received invalid hydrated durable state for key "${actorKey}"`
+          );
+        }
+        const hydratedAt = Date.now();
+        latest.durableState = cloneForDurableState(snapshot.durableState);
+        latest.version = durableVersion;
+        latest.lastReadAt = hydratedAt;
+        latest.lastDurableWriteAt = hydratedAt;
+      }
+      latest.hydrationResolved = true;
+      return latest;
+    })().finally(() => {
+      if (this.pendingHydrationByKey.get(actorKey) === hydrationPromise) {
+        this.pendingHydrationByKey.delete(actorKey);
+      }
+    });
+    this.pendingHydrationByKey.set(actorKey, hydrationPromise);
+    return hydrationPromise;
+  }
   touchSession(actorKey, shouldTouch, touchedAt) {
     if (!this.spec.session?.enabled || !shouldTouch) {
       return;
@@ -7375,7 +7428,8 @@ var Cadenza = class {
     };
     const actorOptions = {
       isMeta: options.isMeta,
-      definitionSource: definition
+      definitionSource: definition,
+      hydrateDurableState: options.hydrateDurableState
     };
     return this.createActor(spec, actorOptions);
   }