@cadenza.io/core 3.26.0 → 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,7 +2161,10 @@ 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;
     private runWithOptionalIdempotency;
     private runWithPerKeyWriteSerialization;
     private getActiveIdempotencyRecord;

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,7 +2161,10 @@ 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;
     private runWithOptionalIdempotency;
     private runWithPerKeyWriteSerialization;
     private getActiveIdempotencyRecord;

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,
@@ -3927,9 +3929,11 @@ var Actor = class {
         bindingOptions.touchSession
       );
       const actorKey = this.resolveActorKey(normalizedInput, invocationOptions);
-      this.touchSession(actorKey, invocationOptions.touchSession, Date.now());
+      const now2 = Date.now();
+      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;
@@ -4098,6 +4102,7 @@ var Actor = class {
    */
   getDurableState(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
+    this.pruneExpiredActorKeys(Date.now());
     return cloneForDurableState(this.ensureStateRecord(key).durableState);
   }
   /**
@@ -4105,6 +4110,7 @@ var Actor = class {
    */
   getRuntimeState(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
+    this.pruneExpiredActorKeys(Date.now());
     return this.ensureStateRecord(key).runtimeState;
   }
   /**
@@ -4118,6 +4124,7 @@ var Actor = class {
    */
   getDurableVersion(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
+    this.pruneExpiredActorKeys(Date.now());
     return this.ensureStateRecord(key).version;
   }
   /**
@@ -4125,6 +4132,7 @@ var Actor = class {
    */
   getRuntimeVersion(actorKey) {
     const key = normalizeActorKey(actorKey) ?? this.spec.defaultKey;
+    this.pruneExpiredActorKeys(Date.now());
     return this.ensureStateRecord(key).runtimeVersion;
   }
   /**
@@ -4167,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);
       }
@@ -4178,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);
@@ -4263,6 +4273,7 @@ var Actor = class {
       runtimeState: this.resolveInitialRuntimeState(),
       version: 0,
       runtimeVersion: 0,
+      hydrationResolved: this.hydrateDurableState === void 0,
       createdAt: now2,
       lastReadAt: now2,
       lastDurableWriteAt: now2,
@@ -4272,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;
@@ -4295,6 +4354,30 @@ var Actor = class {
       existing.absoluteExpiresAt = touchedAt + absoluteTtlMs;
     }
   }
+  pruneExpiredActorKeys(now2) {
+    if (!this.spec.session?.enabled || this.sessionByKey.size === 0) {
+      return;
+    }
+    for (const [actorKey, session] of this.sessionByKey.entries()) {
+      if (!this.isSessionExpired(session, now2)) {
+        continue;
+      }
+      if (this.writeQueueByKey.has(actorKey)) {
+        continue;
+      }
+      this.stateByKey.delete(actorKey);
+      this.sessionByKey.delete(actorKey);
+    }
+  }
+  isSessionExpired(session, now2) {
+    if (session.absoluteExpiresAt !== null && now2 >= session.absoluteExpiresAt) {
+      return true;
+    }
+    if (session.idleExpiresAt !== null && now2 >= session.idleExpiresAt) {
+      return true;
+    }
+    return false;
+  }
   runWithOptionalIdempotency(taskBindingId, actorKey, options, runTask) {
     const idempotencyPolicy = this.spec.idempotency;
     const enabled = idempotencyPolicy?.enabled ?? false;
@@ -7345,7 +7428,8 @@ var Cadenza = class {
     };
     const actorOptions = {
       isMeta: options.isMeta,
-      definitionSource: definition
+      definitionSource: definition,
+      hydrateDurableState: options.hydrateDurableState
     };
     return this.createActor(spec, actorOptions);
   }