durability 4.2.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +340 -12
  2. package/dist/dev.d.ts +22 -0
  3. package/dist/dev.js +149 -0
  4. package/dist/durability-alarms.d.ts +16 -3
  5. package/dist/durability-alarms.js +21 -7
  6. package/dist/durability.d.ts +31 -6
  7. package/dist/durability.js +42 -16
  8. package/dist/errors.d.ts +31 -0
  9. package/dist/errors.js +45 -0
  10. package/dist/experimental.d.ts +5 -0
  11. package/dist/experimental.js +3 -0
  12. package/dist/fanout.d.ts +6 -0
  13. package/dist/fanout.js +20 -9
  14. package/dist/index.d.ts +4 -2
  15. package/dist/index.js +3 -2
  16. package/dist/lifecycle.d.ts +6 -1
  17. package/dist/lifecycle.js +3 -2
  18. package/dist/log.js +61 -16
  19. package/dist/memoize.d.ts +34 -0
  20. package/dist/memoize.js +136 -0
  21. package/dist/migrations.d.ts +64 -2
  22. package/dist/migrations.js +179 -34
  23. package/dist/outbox.d.ts +13 -0
  24. package/dist/outbox.js +78 -30
  25. package/dist/scheduler.d.ts +9 -0
  26. package/dist/scheduler.js +53 -11
  27. package/dist/semaphore-leases.js +15 -9
  28. package/dist/semaphore-queue-store.d.ts +12 -2
  29. package/dist/semaphore-queue-store.js +32 -5
  30. package/dist/semaphore-queue.js +109 -43
  31. package/dist/semaphore-server.js +7 -9
  32. package/dist/socket.js +19 -10
  33. package/dist/storage.d.ts +1 -0
  34. package/dist/storage.js +1 -1
  35. package/dist/topology-client.d.ts +40 -0
  36. package/dist/topology-client.js +180 -0
  37. package/dist/topology-snapshot.d.ts +70 -0
  38. package/dist/topology-snapshot.js +48 -0
  39. package/dist/topology.d.ts +94 -0
  40. package/dist/topology.js +468 -0
  41. package/dist/tracked-source.d.ts +2 -0
  42. package/dist/tracker.js +2 -0
  43. package/package.json +3 -2
package/dist/dev.js ADDED
@@ -0,0 +1,149 @@
1
+ import { serializeError } from './errors.js';
2
+ /**
3
+ * True only when the build defines `__DURABILITY_DEV__` as `true`. Bundlers
4
+ * fold the check to a constant, so production builds pay one branch per
5
+ * traced call and log nothing.
6
+ */
7
+ const devMode = typeof __DURABILITY_DEV__ === 'boolean' && __DURABILITY_DEV__;
8
+ let sequence = 0;
9
+ /**
10
+ * Logs one dev-mode trace entry and returns its sequence number. The sequence
11
+ * is process-wide and monotonic so interleaved async work can be reordered
12
+ * and correlated when replaying a simulation.
13
+ */
14
+ export const trace = (operation, details = {}) => {
15
+ if (!devMode) {
16
+ return 0;
17
+ }
18
+ sequence += 1;
19
+ // Tracing is best-effort: a logger that throws must not change the operation.
20
+ try {
21
+ console.debug({
22
+ event: `durability.dev.${operation}`,
23
+ seq: sequence,
24
+ at: Date.now(),
25
+ ...details,
26
+ });
27
+ }
28
+ catch {
29
+ // Keep the sequence number so later entries still order correctly.
30
+ }
31
+ return sequence;
32
+ };
33
+ const traceCall = (operation, details, run) => {
34
+ const call = trace(operation, details);
35
+ let result;
36
+ try {
37
+ result = run();
38
+ }
39
+ catch (error) {
40
+ trace(`${operation}.throw`, { call, error: serializeError(error) });
41
+ throw error;
42
+ }
43
+ if (!(result instanceof Promise)) {
44
+ trace(`${operation}.return`, { call, result });
45
+ return result;
46
+ }
47
+ // Observes the promise without changing what the caller sees.
48
+ void result.then((value) => trace(`${operation}.return`, { call, result: value }), (error) => trace(`${operation}.throw`, { call, error: serializeError(error) }));
49
+ return result;
50
+ };
51
+ const loggableArgs = (args) => args.filter((arg) => typeof arg !== 'function');
52
+ /**
53
+ * Wraps a public function so dev mode logs its arguments and outcome. `details`
54
+ * identifies the receiver when the arguments alone do not.
55
+ */
56
+ export const traceFunction = (method, fn, details = {}) => {
57
+ if (!devMode) {
58
+ return fn;
59
+ }
60
+ return function (...args) {
61
+ return traceCall('call', { method, ...details, args: loggableArgs(args) }, () => fn.apply(this, args));
62
+ };
63
+ };
64
+ /** Wraps every method on a class prototype with {@link traceFunction}. */
65
+ export const traceMethods = (prototype, owner) => {
66
+ if (!devMode) {
67
+ return;
68
+ }
69
+ for (const name of Object.getOwnPropertyNames(prototype)) {
70
+ const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
71
+ if (name === 'constructor' || typeof descriptor?.value !== 'function') {
72
+ continue;
73
+ }
74
+ Object.defineProperty(prototype, name, {
75
+ ...descriptor,
76
+ value: traceFunction(`${owner}.${name}`, descriptor.value),
77
+ });
78
+ }
79
+ };
80
+ /** Logs each lifecycle event before `emit` hands it to the consumer's hooks. */
81
+ export const traceLifecycle = (emit) => {
82
+ if (!devMode) {
83
+ return emit;
84
+ }
85
+ return (event) => {
86
+ trace('lifecycle', event);
87
+ emit(event);
88
+ };
89
+ };
90
+ const compactQuery = (query) => query.replace(/\s+/g, ' ').trim();
91
+ const traceSql = (sql) => new Proxy(sql, {
92
+ get(target, key) {
93
+ const value = Reflect.get(target, key);
94
+ if (key === 'exec') {
95
+ return (query, ...bindings) => {
96
+ trace('sql', { query: compactQuery(query), bindings });
97
+ return target.exec(query, ...bindings);
98
+ };
99
+ }
100
+ return typeof value === 'function' ? value.bind(target) : value;
101
+ },
102
+ });
103
+ const proxyStorage = (storage, scope) => {
104
+ let sql;
105
+ return new Proxy(storage, {
106
+ get(target, key) {
107
+ const value = Reflect.get(target, key);
108
+ if (key === 'sql' && value !== undefined) {
109
+ sql ?? (sql = traceSql(value));
110
+ return sql;
111
+ }
112
+ if (typeof value !== 'function') {
113
+ return value;
114
+ }
115
+ const method = `${scope}.${String(key)}`;
116
+ return (...args) => {
117
+ // Alarm writes inside `transaction` go through the transaction object.
118
+ const forwarded = key === 'transaction' && typeof args[0] === 'function'
119
+ ? [
120
+ (transaction) => args[0](proxyStorage(transaction, 'transaction')),
121
+ ...args.slice(1),
122
+ ]
123
+ : args;
124
+ return traceCall('storage', { method, args: loggableArgs(args) }, () => Reflect.apply(value, target, forwarded));
125
+ };
126
+ },
127
+ });
128
+ };
129
+ const tracedStorage = new WeakMap();
130
+ const storageProxies = new WeakSet();
131
+ /**
132
+ * In dev mode, returns a view of Durable Object storage that logs every SQL
133
+ * statement, transaction, and alarm read or write. Outside dev mode, returns
134
+ * the storage unchanged. Idempotent, so helpers sharing one storage log each
135
+ * call once.
136
+ */
137
+ export const traceStorage = (storage) => {
138
+ if (!devMode || storageProxies.has(storage)) {
139
+ return storage;
140
+ }
141
+ const existing = tracedStorage.get(storage);
142
+ if (existing) {
143
+ return existing;
144
+ }
145
+ const traced = proxyStorage(storage, 'storage');
146
+ tracedStorage.set(storage, traced);
147
+ storageProxies.add(traced);
148
+ return traced;
149
+ };
@@ -2,22 +2,35 @@ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.j
2
2
  import { type DurabilityMigrationResult } from './migrations.js';
3
3
  import { type DurabilityAlarmMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
4
  import { type SchedulerAttachment } from './scheduler.js';
5
+ import { type DurableMemoize } from './memoize.js';
5
6
  /** Information passed to a named alarm handler for one execution attempt. */
6
7
  export type DurableAlarmInfo = {
7
8
  /** Configured name of the logical alarm. */
8
9
  name: string;
9
10
  /** Timestamp originally passed to the named alarm method. */
10
11
  scheduledTime: number;
11
- /** One-based execution attempt for this scheduled occurrence. */
12
+ /**
13
+ * One-based attempt ordinal for this scheduled occurrence, durably recorded
14
+ * before the handler runs. It is retry and logging context, not a record of
15
+ * what the handler did: never gate once-only work on it (such as
16
+ * `attempt === 1`). Key such work on durable state keyed by `idempotencyKey`
17
+ * instead. See the README identity glossary.
18
+ */
12
19
  attempt: number;
13
20
  /** Whether this scheduled occurrence has run before. */
14
21
  isRetry: boolean;
15
22
  /** Number of previous attempts for this scheduled occurrence. */
16
23
  retryCount: number;
17
- /** Stable key shared by every attempt of this scheduled occurrence. */
24
+ /**
25
+ * Stable key shared by every attempt of this scheduled occurrence. This is
26
+ * the occurrence's logical identity: pass it to downstream services for
27
+ * deduplication rather than relying on `attempt`.
28
+ */
18
29
  idempotencyKey: string;
19
30
  /** Aborts when the attempt exceeds its configured timeout. */
20
31
  signal: AbortSignal;
32
+ /** Persists a callback's result by key so a retry of this occurrence reuses it. */
33
+ memoize: DurableMemoize;
21
34
  /** Invocation information for the shared physical Durable Object alarm. */
22
35
  platform: AlarmInvocationInfo | undefined;
23
36
  };
@@ -50,7 +63,7 @@ export type DurableNamedAlarm = (scheduledTime: number) => Promise<void>;
50
63
  declare class DurabilityAlarmsCore<Names extends string> {
51
64
  #private;
52
65
  constructor(config: DurabilityAlarmsConfig<Names>);
53
- /** Applies or reverts the `durability_alarms` schema; see {@link migrate}. */
66
+ /** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
54
67
  static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
55
68
  /** Runs due named alarms and re-arms the physical alarm. */
56
69
  alarm(info?: AlarmInvocationInfo): Promise<void>;
@@ -11,11 +11,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
11
11
  };
12
12
  var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_lifecycle, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_trackedSource, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
13
13
  import { z } from 'zod';
14
+ import { traceFunction, traceMethods } from './dev.js';
14
15
  import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
15
16
  import { createLifecycleHooks, } from './lifecycle.js';
16
- import { durabilityNamedAlarmMigrations, migrate, } from './migrations.js';
17
+ import { durabilityNamedAlarmMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
17
18
  import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
18
19
  import { engineFor, } from './scheduler.js';
20
+ import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
19
21
  import { deleteAttempt, listCreated } from './storage.js';
20
22
  import { registerTrackedSource, } from './tracked-source.js';
21
23
  const alarmRowSchema = z.object({
@@ -36,7 +38,7 @@ const readAlarm = (sql, name) => alarmRowSchema
36
38
  .parse(sql
37
39
  .exec('SELECT * FROM durability_alarms WHERE name = ?', name)
38
40
  .toArray()[0]);
39
- const alarmRecord = (row) => ({
41
+ const alarmRecord = (sql, row) => ({
40
42
  id: row.name,
41
43
  name: row.name,
42
44
  generation: row.generation_id,
@@ -47,6 +49,7 @@ const alarmRecord = (row) => ({
47
49
  attempt: row.attempt,
48
50
  nextAttemptAt: row.next_attempt_at,
49
51
  lastError: row.last_error,
52
+ memoized: memoizedKeys(sql, alarmsTable, row.name, row.generation_id),
50
53
  }
51
54
  : {
52
55
  status: 'failed',
@@ -83,20 +86,23 @@ class DurabilityAlarmsCore {
83
86
  throw new Error(`"${name}" is reserved by DurabilityAlarms`);
84
87
  }
85
88
  Object.defineProperty(this, name, {
86
- value: (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime),
89
+ value: traceFunction(`DurabilityAlarms.${name}`, (scheduledTime) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_schedule).call(this, name, scheduledTime)),
87
90
  enumerable: true,
88
91
  });
89
92
  }
90
93
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('namedAlarms', durabilityNamedAlarmMigrations);
94
+ __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
91
95
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").register({
92
96
  table: alarmsTable,
93
97
  runDue: (now, info) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_runDue).call(this, now, info),
94
98
  });
95
99
  registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_trackedSource).call(this));
96
100
  }
97
- /** Applies or reverts the `durability_alarms` schema; see {@link migrate}. */
101
+ /** Applies or reverts the `durability_alarms` schema; see {@link migrateCapability}. */
98
102
  static migrate(context, target) {
99
- return migrate(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
103
+ const result = migrateCapability(context.storage, 'namedAlarms', durabilityNamedAlarmMigrations, target);
104
+ deleteMemosOfDroppedTable(context.storage.sql, alarmsTable);
105
+ return result;
100
106
  }
101
107
  /** Runs due named alarms and re-arms the physical alarm. */
102
108
  alarm(info) {
@@ -130,7 +136,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
130
136
  return {
131
137
  get: async (name) => {
132
138
  const row = readAlarm(sql, name);
133
- return row && alarmRecord(row);
139
+ return row && alarmRecord(sql, row);
134
140
  },
135
141
  list: async ({ limit, cursor, status, name }) => {
136
142
  const page = listCreated(sql, alarmsTable, 'name', {
@@ -142,7 +148,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
142
148
  const records = alarmRowSchema
143
149
  .array()
144
150
  .parse(page.rows)
145
- .map(alarmRecord);
151
+ .map((row) => alarmRecord(sql, row));
146
152
  return page.next === undefined
147
153
  ? { records }
148
154
  : { records, cursor: page.next };
@@ -200,6 +206,8 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
200
206
  last_error = excluded.last_error,
201
207
  last_error_name = excluded.last_error_name,
202
208
  created_at = excluded.created_at`, name, generation, scheduledTime, scheduledTime, createdAt);
209
+ // Memoized results belong to the replaced occurrence, never to the new one.
210
+ deleteMemos(sql, alarmsTable, name);
203
211
  });
204
212
  // A waiter on the replaced occurrence resolves now instead of at its timeout.
205
213
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").notify(alarmsTable, name);
@@ -244,6 +252,11 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
244
252
  retryCount: attempt - 1,
245
253
  idempotencyKey: `durability-alarm:v1:${row.generation_id}`,
246
254
  signal,
255
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql, alarmsTable, {
256
+ key: row.name,
257
+ generation: row.generation_id,
258
+ attempt,
259
+ }),
247
260
  platform,
248
261
  });
249
262
  },
@@ -259,6 +272,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
259
272
  isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
260
273
  });
261
274
  };
275
+ traceMethods(DurabilityAlarmsCore.prototype, 'DurabilityAlarms');
262
276
  // See Durability: members derived from the handler names cannot be declared on
263
277
  // the class, so the constructor is typed separately.
264
278
  export const DurabilityAlarms = DurabilityAlarmsCore;
@@ -2,6 +2,7 @@ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.j
2
2
  import { type DurabilityMigrationResult } from './migrations.js';
3
3
  import { type DurabilityMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
4
  import { type SchedulerAttachment } from './scheduler.js';
5
+ import { type DurableMemoize } from './memoize.js';
5
6
  /**
6
7
  * The context passed to a durable operation handler for each attempt.
7
8
  *
@@ -16,16 +17,27 @@ import { type SchedulerAttachment } from './scheduler.js';
16
17
  * ```
17
18
  */
18
19
  export type DurableCall<Payload> = {
19
- /** The stable idempotency key supplied when the operation was registered. */
20
+ /**
21
+ * The stable idempotency key supplied when the operation was registered. This
22
+ * is the operation's logical identity: key any external deduplication or
23
+ * once-only effect by `id`, never by `attempt`.
24
+ */
20
25
  id: string;
21
26
  /** The handler name used to register the operation. */
22
27
  operation: string;
23
28
  /** The JSON-serializable payload supplied when the operation was registered. */
24
29
  payload: Payload;
25
- /** The one-based attempt number. */
30
+ /**
31
+ * The one-based attempt ordinal, durably recorded before the handler runs. It
32
+ * is retry and logging context, not a record of what the handler did: never
33
+ * gate once-only work on it (such as `attempt === 1`). Key such work on
34
+ * durable state keyed by `id` instead. See the README identity glossary.
35
+ */
26
36
  attempt: number;
27
37
  /** Aborts when the attempt exceeds its configured timeout. */
28
38
  signal: AbortSignal;
39
+ /** Persists a callback's result by key so a retry of this operation reuses it. */
40
+ memoize: DurableMemoize;
29
41
  };
30
42
  /** A function that executes one attempt of a durable operation. */
31
43
  export type DurableHandler<Payload, Result> = (call: DurableCall<Payload>) => Result | Promise<Result>;
@@ -83,13 +95,15 @@ type TypedOperationEvent<Operation extends string, Result> = OperationEvent exte
83
95
  outcome: 'completed';
84
96
  } ? Omit<Event, 'operation' | 'result'> & {
85
97
  operation: Operation;
86
- result: Result;
98
+ /** Present only when the instance was created with `includeResults: true`. */
99
+ result?: Result;
87
100
  } : Event extends object ? Omit<Event, 'operation'> & {
88
101
  operation: Operation;
89
102
  } : never : never;
90
103
  /**
91
104
  * A lifecycle event for one of this instance's operations. Completed events
92
- * carry the handler's typed result.
105
+ * carry the handler's typed result only when the instance is created with
106
+ * `includeResults: true`.
93
107
  */
94
108
  export type DurabilityOperationEvent<Handlers extends HandlerMap> = {
95
109
  [Operation in Extract<keyof Handlers, string>]: TypedOperationEvent<Operation, HandlerResult<Handlers[Operation]>>;
@@ -120,6 +134,12 @@ export type DurabilityOptions<Handlers extends HandlerMap = HandlerMap> = Execut
120
134
  methods?: Partial<Record<Extract<keyof NoInfer<Handlers>, string>, DurabilityMethodOptions>>;
121
135
  /** Receives best-effort, non-durable lifecycle metrics events. */
122
136
  onLifecycleEvent?: LifecycleHook;
137
+ /**
138
+ * Attach the handler's return value to `completed` lifecycle events.
139
+ * Off by default so results never reach telemetry sinks unintentionally;
140
+ * enable only when the sink is trusted with result content.
141
+ */
142
+ includeResults?: boolean;
123
143
  };
124
144
  /**
125
145
  * Constructor configuration: the operation handlers, their policies, and
@@ -133,7 +153,7 @@ export type DurabilityConfig<Handlers extends HandlerMap = HandlerMap> = Durabil
133
153
  declare class DurabilityCore<Handlers extends HandlerMap> {
134
154
  #private;
135
155
  constructor(config: DurabilityConfig<Handlers>);
136
- /** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
156
+ /** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
137
157
  static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
138
158
  /** Processes due operations and re-arms the physical alarm. */
139
159
  alarm(info?: AlarmInvocationInfo): Promise<void>;
@@ -152,11 +172,16 @@ type OperationMethods<Handlers extends HandlerMap> = {
152
172
  [Operation in keyof Handlers]: DurableOperation<Handlers[Operation]>;
153
173
  };
154
174
  /**
155
- * Alarm-backed, effectively-once durable operations for one Durable Object.
175
+ * Alarm-backed, at-least-once durable operations for one Durable Object.
156
176
  *
157
177
  * Every handler becomes a typed method on the instance. Methods resolve once
158
178
  * the call is durably registered; read outcomes through `getResult`.
159
179
  *
180
+ * Delivery is at least once: a handler may run again after a crash, timeout, or
181
+ * eviction. The call `id` is a stable idempotency key; pass it to external
182
+ * systems and make effects idempotent or reconcilable to reach an effectively
183
+ * once outcome. See the README "Delivery and safety contract".
184
+ *
160
185
  * @example
161
186
  * ```ts
162
187
  * class ImageJobs extends DurableObject<Env> {
@@ -9,14 +9,16 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
12
+ var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_includeResults, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
13
13
  import { z } from 'zod';
14
+ import { traceFunction, traceMethods } from './dev.js';
14
15
  import { DuplicateDurableCallError, DuplicateDurablePayloadError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
15
16
  import { createLifecycleHooks, } from './lifecycle.js';
16
- import { durabilityOperationMigrations, migrate, } from './migrations.js';
17
+ import { durabilityOperationMigrations, durabilityMemoMigrations, migrateCapability, } from './migrations.js';
17
18
  import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
18
19
  import { engineFor, } from './scheduler.js';
19
20
  import { canonical, deserialize, serialize } from './serialization.js';
21
+ import { createMemoize, deleteMemosOfDroppedTable, memoizedKeys, } from './memoize.js';
20
22
  import { listCreated, updateAttempt } from './storage.js';
21
23
  import { registerTrackedSource, } from './tracked-source.js';
22
24
  const callRowSchema = z.object({
@@ -66,13 +68,21 @@ const callState = (call) => {
66
68
  }
67
69
  return { status: 'completed', result: deserialize(call.result) };
68
70
  };
69
- const callRecord = (call) => ({
70
- id: call.id,
71
- name: call.operation,
72
- generation: call.generation_id,
73
- createdAt: call.created_at,
74
- state: callState(call),
75
- });
71
+ const callRecord = (sql, call) => {
72
+ const state = callState(call);
73
+ return {
74
+ id: call.id,
75
+ name: call.operation,
76
+ generation: call.generation_id,
77
+ createdAt: call.created_at,
78
+ state: state.status === 'pending'
79
+ ? {
80
+ ...state,
81
+ memoized: memoizedKeys(sql, callsTable, call.id, call.generation_id),
82
+ }
83
+ : state,
84
+ };
85
+ };
76
86
  const operationEntity = (call) => ({
77
87
  entityKind: 'operation',
78
88
  operation: call.operation,
@@ -87,6 +97,7 @@ class DurabilityCore {
87
97
  _DurabilityCore_policy.set(this, void 0);
88
98
  _DurabilityCore_lifecycle.set(this, void 0);
89
99
  _DurabilityCore_emit.set(this, void 0);
100
+ _DurabilityCore_includeResults.set(this, void 0);
90
101
  _DurabilityCore_active.set(this, new Map());
91
102
  _DurabilityCore_executionStarts.set(this, new Map());
92
103
  const { handlers } = config;
@@ -95,28 +106,33 @@ class DurabilityCore {
95
106
  __classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
96
107
  __classPrivateFieldSet(this, _DurabilityCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
97
108
  __classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").emit, "f");
109
+ __classPrivateFieldSet(this, _DurabilityCore_includeResults, config.includeResults ?? false, "f");
98
110
  const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
99
111
  for (const operation of Object.keys(handlers)) {
100
112
  if (reserved.has(operation)) {
101
113
  throw new Error(`"${operation}" is reserved by Durability`);
102
114
  }
103
- const method = (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation });
104
- method.getResult = (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey);
115
+ const method = Object.assign(traceFunction(`Durability.${operation}`, (input) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_run).call(this, { ...input, operation })), {
116
+ getResult: traceFunction(`Durability.${operation}.getResult`, (idempotencyKey) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_getResult).call(this, operation, idempotencyKey)),
117
+ });
105
118
  Object.defineProperty(this, operation, {
106
119
  value: method,
107
120
  enumerable: true,
108
121
  });
109
122
  }
110
123
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
124
+ __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('memos', durabilityMemoMigrations);
111
125
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
112
126
  table: callsTable,
113
127
  runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
114
128
  });
115
129
  registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_trackedSource).call(this));
116
130
  }
117
- /** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
131
+ /** Applies or reverts the `durability_calls` schema; see {@link migrateCapability}. */
118
132
  static migrate(context, target) {
119
- return migrate(context.storage, 'operations', durabilityOperationMigrations, target);
133
+ const result = migrateCapability(context.storage, 'operations', durabilityOperationMigrations, target);
134
+ deleteMemosOfDroppedTable(context.storage.sql, callsTable);
135
+ return result;
120
136
  }
121
137
  /** Processes due operations and re-arms the physical alarm. */
122
138
  alarm(info) {
@@ -145,12 +161,12 @@ class DurabilityCore {
145
161
  return count;
146
162
  }
147
163
  }
148
- _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
164
+ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_includeResults = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
149
165
  const sql = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql;
150
166
  return {
151
167
  get: async (id) => {
152
168
  const call = readCall(sql, id);
153
- return call && callRecord(call);
169
+ return call && callRecord(sql, call);
154
170
  },
155
171
  list: async ({ limit, cursor, status, name }) => {
156
172
  const page = listCreated(sql, callsTable, 'operation', {
@@ -159,7 +175,10 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
159
175
  status,
160
176
  name,
161
177
  });
162
- const records = callRowSchema.array().parse(page.rows).map(callRecord);
178
+ const records = callRowSchema
179
+ .array()
180
+ .parse(page.rows)
181
+ .map((call) => callRecord(sql, call));
163
182
  return page.next === undefined
164
183
  ? { records }
165
184
  : { records, cursor: page.next };
@@ -287,6 +306,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
287
306
  active: __classPrivateFieldGet(this, _DurabilityCore_active, "f"),
288
307
  policy,
289
308
  emit: __classPrivateFieldGet(this, _DurabilityCore_emit, "f"),
309
+ includeResult: __classPrivateFieldGet(this, _DurabilityCore_includeResults, "f"),
290
310
  exhaustedError: () => new DurableAttemptsExhaustedError('operation', call.operation, policy.maxAttempts),
291
311
  timeoutError: () => new DurableAttemptTimeoutError(call.operation, policy.attemptTimeoutMs),
292
312
  invoke: (attempt, signal) => {
@@ -299,6 +319,11 @@ async function _DurabilityCore_execute(id, eagerPermit) {
299
319
  payload: deserialize(call.payload),
300
320
  attempt,
301
321
  signal,
322
+ memoize: createMemoize(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, {
323
+ key: call.id,
324
+ generation: call.generation_id,
325
+ attempt,
326
+ }),
302
327
  });
303
328
  },
304
329
  complete: (result, attempt) => {
@@ -317,6 +342,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
317
342
  isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
318
343
  }, eagerPermit);
319
344
  };
345
+ traceMethods(DurabilityCore.prototype, 'Durability');
320
346
  // TypeScript cannot declare class members derived from a generic handler map,
321
347
  // so the constructor is typed separately; the constructor installs and reserves
322
348
  // every operation method at runtime.
package/dist/errors.d.ts CHANGED
@@ -36,6 +36,20 @@ export declare class DurableRetryPolicyError extends Error {
36
36
  export declare class DurableResultSerializationError extends Error {
37
37
  constructor(operation: string, reason?: unknown);
38
38
  }
39
+ /**
40
+ * Error persisted when a memoized result cannot be JSON-serialized. It is
41
+ * terminal because every retry would fail the same way.
42
+ */
43
+ export declare class DurableMemoSerializationError extends NonRetryableError {
44
+ constructor(key: string, reason?: unknown);
45
+ }
46
+ /**
47
+ * Error persisted when work memoizes more keys, or a larger result, than the
48
+ * limits allow. It is terminal because every retry would fail the same way.
49
+ */
50
+ export declare class DurableMemoLimitError extends NonRetryableError {
51
+ constructor(message: string);
52
+ }
39
53
  /** Error persisted when pending work has already reached its attempt limit. */
40
54
  export declare class DurableAttemptsExhaustedError extends Error {
41
55
  constructor(entity: 'operation' | 'named alarm', name: string, max: number);
@@ -115,3 +129,20 @@ export declare const isErrorInstance: (error: unknown, constructor: new (...args
115
129
  /** Recognizes this package's NonRetryableError and same-named errors from other packages. */
116
130
  export declare const isNonRetryable: (error: unknown) => boolean;
117
131
  export declare const reportFailure: (event: string, details: Record<string, unknown>, error: unknown) => void;
132
+ /** A definite rejection of a topology change or configuration. */
133
+ export declare class TopologyError extends Error {
134
+ constructor(message: string);
135
+ }
136
+ /** Why a topology client could not use the published snapshot. */
137
+ export type TopologyFallbackReason = 'missing' | 'invalid' | 'timeout' | 'error';
138
+ /**
139
+ * Thrown by a topology client when the published snapshot is unusable and no
140
+ * configured fallback produced one. The client never asks the coordinator.
141
+ */
142
+ export declare class TopologyUnavailableError extends Error {
143
+ readonly group: string;
144
+ readonly reason: TopologyFallbackReason;
145
+ constructor(group: string, reason: TopologyFallbackReason, options?: {
146
+ cause?: unknown;
147
+ });
148
+ }
package/dist/errors.js CHANGED
@@ -57,6 +57,29 @@ export class DurableResultSerializationError extends Error {
57
57
  }
58
58
  }
59
59
  }
60
+ /**
61
+ * Error persisted when a memoized result cannot be JSON-serialized. It is
62
+ * terminal because every retry would fail the same way.
63
+ */
64
+ export class DurableMemoSerializationError extends NonRetryableError {
65
+ constructor(key, reason) {
66
+ super(`Memoized result for key ${JSON.stringify(key)} is not JSON-serializable`);
67
+ this.name = 'DurableMemoSerializationError';
68
+ if (reason !== undefined) {
69
+ Object.defineProperty(this, 'cause', { value: reason });
70
+ }
71
+ }
72
+ }
73
+ /**
74
+ * Error persisted when work memoizes more keys, or a larger result, than the
75
+ * limits allow. It is terminal because every retry would fail the same way.
76
+ */
77
+ export class DurableMemoLimitError extends NonRetryableError {
78
+ constructor(message) {
79
+ super(message);
80
+ this.name = 'DurableMemoLimitError';
81
+ }
82
+ }
60
83
  /** Error persisted when pending work has already reached its attempt limit. */
61
84
  export class DurableAttemptsExhaustedError extends Error {
62
85
  constructor(entity, name, max) {
@@ -234,3 +257,25 @@ export const reportFailure = (event, details, error) => {
234
257
  return;
235
258
  }
236
259
  };
260
+ /** A definite rejection of a topology change or configuration. */
261
+ export class TopologyError extends Error {
262
+ constructor(message) {
263
+ super(message);
264
+ this.name = 'TopologyError';
265
+ }
266
+ }
267
+ /**
268
+ * Thrown by a topology client when the published snapshot is unusable and no
269
+ * configured fallback produced one. The client never asks the coordinator.
270
+ */
271
+ export class TopologyUnavailableError extends Error {
272
+ constructor(group, reason, options) {
273
+ super(`Topology for group "${group}" is unavailable: ${reason}`);
274
+ this.group = group;
275
+ this.reason = reason;
276
+ this.name = 'TopologyUnavailableError';
277
+ if (options?.cause !== undefined) {
278
+ Object.defineProperty(this, 'cause', { value: options.cause });
279
+ }
280
+ }
281
+ }
@@ -9,3 +9,8 @@ export type { TrackedEntry, TrackedPage, TrackedQuery, TrackedRecord, TrackedRes
9
9
  export { DurabilityOutbox, type DurabilityOutboxConfig, type DurabilityOutboxEvent, type OutboxEntry, } from './outbox.js';
10
10
  export { OutboxTimeoutError } from './errors.js';
11
11
  export { durabilityOutboxMigrations } from './migrations.js';
12
+ export { DurabilityTopology, type DurabilityTopologyConfig, type DurabilityTopologyEvent, type TopologyChannel, type TopologyCurrent, type TopologyDraft, type TopologyPublisher, type TopologyRetryOptions, type TopologyRole, type TopologyStateUpdate, } from './topology.js';
13
+ export type { TopologyClient, TopologyClientConfig, TopologySource, TopologyView, } from './topology-client.js';
14
+ export type { TopologyMember, TopologyMemberInput, TopologyMemberState, TopologySnapshot, } from './topology-snapshot.js';
15
+ export { TopologyError, TopologyUnavailableError, type TopologyFallbackReason, } from './errors.js';
16
+ export { durabilityTopologyMigrations } from './migrations.js';
@@ -8,3 +8,6 @@ export { DurabilityTracker, } from './tracker.js';
8
8
  export { DurabilityOutbox, } from './outbox.js';
9
9
  export { OutboxTimeoutError } from './errors.js';
10
10
  export { durabilityOutboxMigrations } from './migrations.js';
11
+ export { DurabilityTopology, } from './topology.js';
12
+ export { TopologyError, TopologyUnavailableError, } from './errors.js';
13
+ export { durabilityTopologyMigrations } from './migrations.js';