durability 5.3.0 → 5.4.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 (53) hide show
  1. package/README.md +23 -14
  2. package/dist/alarms/index.d.ts +1 -1
  3. package/dist/alarms/index.js +6 -3
  4. package/dist/dev.d.ts +7 -3
  5. package/dist/dev.js +17 -11
  6. package/dist/durable-object-target.js +8 -4
  7. package/dist/errors.d.ts +13 -7
  8. package/dist/errors.js +34 -32
  9. package/dist/fanout/index.d.ts +1 -1
  10. package/dist/fanout/index.js +15 -13
  11. package/dist/lifecycle.d.ts +1 -0
  12. package/dist/lifecycle.js +2 -2
  13. package/dist/log/index.js +5 -2
  14. package/dist/memoize/index.js +6 -1
  15. package/dist/operations/index.js +8 -4
  16. package/dist/outbox/index.d.ts +1 -1
  17. package/dist/outbox/index.js +7 -4
  18. package/dist/policy.d.ts +1 -1
  19. package/dist/policy.js +2 -1
  20. package/dist/predicates.d.ts +9 -0
  21. package/dist/predicates.js +10 -0
  22. package/dist/routing/client.js +3 -4
  23. package/dist/routing/index.d.ts +1 -1
  24. package/dist/routing/index.js +14 -10
  25. package/dist/schedule/index.d.ts +2 -2
  26. package/dist/schedule/index.js +16 -12
  27. package/dist/scheduler/index.d.ts +16 -13
  28. package/dist/scheduler/index.js +39 -33
  29. package/dist/semaphore/client.js +2 -1
  30. package/dist/semaphore/index.d.ts +1 -1
  31. package/dist/semaphore/index.js +10 -5
  32. package/dist/semaphore/leases.d.ts +3 -2
  33. package/dist/semaphore/leases.js +3 -2
  34. package/dist/semaphore/queue-store.js +2 -1
  35. package/dist/semaphore/queue.d.ts +1 -1
  36. package/dist/semaphore/queue.js +34 -22
  37. package/dist/semaphore/server.js +31 -22
  38. package/dist/serialization.d.ts +3 -2
  39. package/dist/serialization.js +16 -13
  40. package/dist/socket/client.d.ts +21 -7
  41. package/dist/socket/client.js +12 -5
  42. package/dist/socket/index.d.ts +20 -13
  43. package/dist/socket/index.js +40 -18
  44. package/dist/socket/protocol.d.ts +37 -17
  45. package/dist/socket/protocol.js +30 -36
  46. package/dist/topology/client.js +9 -6
  47. package/dist/topology/index.d.ts +3 -3
  48. package/dist/topology/index.js +38 -33
  49. package/dist/topology/snapshot.d.ts +6 -5
  50. package/dist/topology/snapshot.js +5 -2
  51. package/dist/tracker/index.js +10 -2
  52. package/dist/tracker/source.d.ts +6 -2
  53. package/package.json +2 -2
package/README.md CHANGED
@@ -666,9 +666,9 @@ export class TodoList extends DurableObject<Env> {
666
666
  readonly socket = new DurabilitySocket({
667
667
  context: this.ctx,
668
668
  inbound: {
669
- // Bare handlers take no input (or `unknown` input they validate themselves).
670
- list: () => [...this.todos.values()],
671
- // Typed input requires a Standard Schema; here the handler is a durable operation.
669
+ // Every handler validates its input; `list` takes none.
670
+ list: { input: v.undefined(), handle: () => [...this.todos.values()] },
671
+ // Here the handler is a durable operation.
672
672
  createTodo: {
673
673
  input: v.object({ id: v.string(), payload: TodoSchema }),
674
674
  handle: this.durability.createTodo,
@@ -744,7 +744,7 @@ export default {
744
744
  };
745
745
  ```
746
746
 
747
- An inbound handler is either a bare function, which receives no input or `unknown` input it validates itself, or `{ input, handle }`, where `input` is any [Standard Schema](https://standardschema.dev) validator (zod, Valibot, ArkType, …) and `handle` declares its parameter type. A bare function that claims a typed parameter does not compile. Handlers receive `call.metadata`, the value `metadata(request)` returned at upgrade time; it is stored in the WebSocket attachment, so it survives hibernation. The fronting Worker is responsible for authentication and for routing the upgrade to the right object; the socket does no authorization of its own. `metadata` must be assignable to every `SocketCall<…>` annotation the handlers declare.
747
+ Every inbound handler is `{ input, handle }`, where `input` is any [Standard Schema](https://standardschema.dev) validator (zod, Valibot, ArkType, …) and `handle` receives the schema's output. A handler without a schema, or whose `handle` does not accept the schema's output, does not compile. A method that takes no input uses a schema for `undefined`, such as Valibot's `v.undefined()`, and the client calls it without arguments. Handlers receive `call.metadata`, the value `metadata(request)` returned at upgrade time; it is stored in the WebSocket attachment, so it survives hibernation. The fronting Worker is responsible for authentication and for routing the upgrade to the right object; the socket does no authorization of its own. `metadata` must be assignable to every `SocketCall<…>` annotation the handlers declare, and is required when any of them excludes `undefined`, so a handler never runs without the metadata it declares. A connection accepted before the socket had `metadata`, such as one from before the deploy that added it, carries none: its next frame closes it with code `1012` before reaching a handler, and the browser client reconnects with backoff so the new upgrade captures it.
748
748
 
749
749
  Every outbound event is persisted to `durability_socket_events` with a sequence number before it is pushed. A reconnecting client subscribes from the last sequence it saw: events still within `retention` (default 1000) are replayed in order, otherwise the client is told to resync and should rebuild its state from an inbound snapshot call. Payloads must be JSON. Keep-alive pings are answered by the runtime through `setWebSocketAutoResponse`, so idle connections never wake the object. Frames over 1 MiB are rejected; malformed frames close the connection with code `4002`.
750
750
 
@@ -756,7 +756,9 @@ Like the other helpers, `DurabilitySocket` takes a `channel` option, `default` u
756
756
  readonly librarySocket = new DurabilitySocket({
757
757
  context: this.ctx,
758
758
  channel: 'durable-alerts',
759
- inbound: { list: () => this.alerts.list() },
759
+ inbound: {
760
+ list: { input: v.undefined(), handle: () => this.alerts.list() },
761
+ },
760
762
  outbound: { updated: event<Alert>() },
761
763
  });
762
764
 
@@ -867,7 +869,7 @@ readonly socket = new DurabilitySocket({
867
869
  inbound: {
868
870
  work: {
869
871
  input: v.object({ cursor: v.optional(v.string()) }),
870
- handle: (query: { cursor?: string }) => this.tracker.records(query),
872
+ handle: (query) => this.tracker.records(query),
871
873
  },
872
874
  },
873
875
  outbound: { settled: event<DurabilityOperationEvent<typeof handlers>>() },
@@ -1017,10 +1019,11 @@ export class JobShard extends DurableObject<Env> {
1017
1019
  scheduler: this.scheduler,
1018
1020
  clientId: this.ctx.id.toString(),
1019
1021
  server: limits.with(timeout, 5_000),
1020
- admit: (items) =>
1021
- Promise.all(
1022
+ admit: async (items) => {
1023
+ await Promise.all(
1022
1024
  items.map((item) => this.jobs.run({ id: item.id, payload: item.body }))
1023
- ),
1025
+ );
1026
+ },
1024
1027
  // The hook above is best-effort; this check returns any permit it missed.
1025
1028
  finished: async (ids) => {
1026
1029
  const results = await Promise.all(
@@ -1290,8 +1293,9 @@ export class Coordinator extends DurableObject<Env> {
1290
1293
  private readonly topology = new DurabilityTopology({
1291
1294
  scheduler: this.scheduler,
1292
1295
  publish: {
1293
- write: (snapshot, encoded) =>
1294
- this.env.TOPOLOGY.put(`topology/${snapshot.group}`, encoded),
1296
+ write: async (snapshot, encoded) => {
1297
+ await this.env.TOPOLOGY.put(`topology/${snapshot.group}`, encoded);
1298
+ },
1295
1299
  delete: (group) => this.env.TOPOLOGY.delete(`topology/${group}`),
1296
1300
  },
1297
1301
  states: {
@@ -1397,8 +1401,9 @@ private readonly libraryTopology = new DurabilityTopology({
1397
1401
  scheduler: this.scheduler,
1398
1402
  channel: 'library',
1399
1403
  publish: {
1400
- write: (snapshot, encoded) =>
1401
- this.env.TOPOLOGY.put(`library/${snapshot.group}`, encoded),
1404
+ write: async (snapshot, encoded) => {
1405
+ await this.env.TOPOLOGY.put(`library/${snapshot.group}`, encoded);
1406
+ },
1402
1407
  delete: (group) => this.env.TOPOLOGY.delete(`library/${group}`),
1403
1408
  },
1404
1409
  });
@@ -1491,7 +1496,11 @@ Records leave only through `trim()`, which enforces `maxAgeMs` and `maxRecords`,
1491
1496
  ```ts
1492
1497
  private readonly alarms = new DurabilityAlarms({
1493
1498
  scheduler: this.scheduler,
1494
- handlers: { compact: () => this.log.trim() },
1499
+ handlers: {
1500
+ compact: async () => {
1501
+ await this.log.trim();
1502
+ },
1503
+ },
1495
1504
  });
1496
1505
 
1497
1506
  alarm(info?: AlarmInvocationInfo) {
@@ -35,7 +35,7 @@ export type DurableAlarmInfo = {
35
35
  platform: AlarmInvocationInfo | undefined;
36
36
  };
37
37
  /** A handler for one named logical alarm. */
38
- export type DurableAlarmHandler = (info: DurableAlarmInfo) => unknown | Promise<unknown>;
38
+ export type DurableAlarmHandler = (info: DurableAlarmInfo) => void | Promise<void>;
39
39
  /** Policy configuration for named alarms. */
40
40
  export type DurabilityAlarmsOptions<Names extends string = string> = ExecutionPolicyOptions & {
41
41
  /** Execution policy overrides keyed by alarm name. */
@@ -18,6 +18,7 @@ import { durabilityNamedAlarmMigrations } from './migrations.js';
18
18
  import { durabilityMemoMigrations } from '../memoize/migrations.js';
19
19
  import { migrateCapability, } from '../migrations.js';
20
20
  import { alarmMethodOptionsSchema, createPolicyResolver, } from '../policy.js';
21
+ import { isFunction } from '../predicates.js';
21
22
  import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
22
23
  import { createMemoize, deleteMemos, deleteMemosOfDroppedTable, memoizedKeys, } from '../memoize/index.js';
23
24
  import { deleteAttempt, listCreated } from '../storage.js';
@@ -35,7 +36,7 @@ const alarmRowSchema = v.object({
35
36
  created_at: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
36
37
  });
37
38
  const alarmsTable = { name: 'durability_alarms', key: 'name' };
38
- const alarmHandlerSchema = v.custom((value) => typeof value === 'function');
39
+ const alarmHandlerSchema = v.custom(isFunction);
39
40
  const readAlarm = (sql, channel, name) => v.parse(v.optional(alarmRowSchema), sql
40
41
  .exec('SELECT * FROM durability_alarms WHERE channel = ? AND name = ?', channel, name)
41
42
  .toArray()[0]);
@@ -123,6 +124,8 @@ class DurabilityAlarmsCore {
123
124
  * returns a function that detaches it.
124
125
  */
125
126
  lifecycle(hook) {
127
+ // SAFETY: every event this instance emits, from scheduling, alarmEntity
128
+ // attempts, and purges, has entityKind 'named_alarm'.
126
129
  return __classPrivateFieldGet(this, _DurabilityAlarmsCore_lifecycle, "f").add(hook);
127
130
  }
128
131
  /**
@@ -314,6 +317,6 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_channel = ne
314
317
  });
315
318
  };
316
319
  traceMethods(DurabilityAlarmsCore.prototype, 'DurabilityAlarms');
317
- // See Durability: members derived from the handler names cannot be declared on
318
- // the class, so the constructor is typed separately.
320
+ // SAFETY: the constructor defines a scheduling method for every handler name on
321
+ // the instance, members TypeScript cannot declare from a generic name union.
319
322
  export const DurabilityAlarms = DurabilityAlarmsCore;
package/dist/dev.d.ts CHANGED
@@ -3,14 +3,17 @@
3
3
  * is process-wide and monotonic so interleaved async work can be reordered
4
4
  * and correlated when replaying a simulation.
5
5
  */
6
- export declare const trace: (operation: string, details?: Record<string, unknown>) => number;
6
+ export declare const trace: <Details extends object>(operation: string, details?: Details) => number;
7
7
  /**
8
8
  * Wraps a public function so dev mode logs its arguments and outcome. `details`
9
9
  * identifies the receiver when the arguments alone do not.
10
10
  */
11
- export declare const traceFunction: <Args extends unknown[], Result>(method: string, fn: (...args: Args) => Result, details?: Record<string, unknown>) => ((...args: Args) => Result);
11
+ export declare const traceFunction: <This, Args extends unknown[], Result, Details extends object>(method: string, fn: (this: This, ...args: Args) => Result, details?: Details) => ((this: This, ...args: Args) => Result);
12
+ type ClassPrototype = {
13
+ readonly constructor: Function;
14
+ };
12
15
  /** Wraps every method on a class prototype with {@link traceFunction}. */
13
- export declare const traceMethods: (prototype: object, owner: string) => void;
16
+ export declare const traceMethods: (prototype: ClassPrototype, owner: string) => void;
14
17
  /** Logs each lifecycle event before `emit` hands it to the consumer's hooks. */
15
18
  export declare const traceLifecycle: <Event extends Record<string, unknown>>(emit: (event: Event) => void) => ((event: Event) => void);
16
19
  /**
@@ -20,3 +23,4 @@ export declare const traceLifecycle: <Event extends Record<string, unknown>>(emi
20
23
  * call once.
21
24
  */
22
25
  export declare const traceStorage: <Storage extends object>(storage: Storage) => Storage;
26
+ export {};
package/dist/dev.js CHANGED
@@ -1,17 +1,18 @@
1
1
  import { serializeError } from './errors.js';
2
+ import { isFunction } from './predicates.js';
2
3
  /**
3
4
  * True only when the build defines `__DURABILITY_DEV__` as `true`. Bundlers
4
5
  * fold the check to a constant, so production builds pay one branch per
5
6
  * traced call and log nothing.
6
7
  */
7
- const devMode = typeof __DURABILITY_DEV__ === 'boolean' && __DURABILITY_DEV__;
8
+ const devMode = typeof __DURABILITY_DEV__ !== 'undefined' && __DURABILITY_DEV__ === true;
8
9
  let sequence = 0;
9
10
  /**
10
11
  * Logs one dev-mode trace entry and returns its sequence number. The sequence
11
12
  * is process-wide and monotonic so interleaved async work can be reordered
12
13
  * and correlated when replaying a simulation.
13
14
  */
14
- export const trace = (operation, details = {}) => {
15
+ export const trace = (operation, details) => {
15
16
  if (!devMode) {
16
17
  return 0;
17
18
  }
@@ -45,15 +46,15 @@ const traceCall = (operation, details, run) => {
45
46
  return result;
46
47
  }
47
48
  // 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
+ void result.then((value) => trace(`${operation}.return`, { call, result: value }), (cause) => trace(`${operation}.throw`, { call, error: serializeError(cause) }));
49
50
  return result;
50
51
  };
51
- const loggableArgs = (args) => args.filter((arg) => typeof arg !== 'function');
52
+ const loggableArgs = (args) => args.filter((arg) => !isFunction(arg));
52
53
  /**
53
54
  * Wraps a public function so dev mode logs its arguments and outcome. `details`
54
55
  * identifies the receiver when the arguments alone do not.
55
56
  */
56
- export const traceFunction = (method, fn, details = {}) => {
57
+ export const traceFunction = (method, fn, details) => {
57
58
  if (!devMode) {
58
59
  return fn;
59
60
  }
@@ -68,7 +69,7 @@ export const traceMethods = (prototype, owner) => {
68
69
  }
69
70
  for (const name of Object.getOwnPropertyNames(prototype)) {
70
71
  const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
71
- if (name === 'constructor' || typeof descriptor?.value !== 'function') {
72
+ if (name === 'constructor' || !isFunction(descriptor?.value)) {
72
73
  continue;
73
74
  }
74
75
  Object.defineProperty(prototype, name, {
@@ -97,7 +98,7 @@ const traceSql = (sql) => new Proxy(sql, {
97
98
  return target.exec(query, ...bindings);
98
99
  };
99
100
  }
100
- return typeof value === 'function' ? value.bind(target) : value;
101
+ return isFunction(value) ? value.bind(target) : value;
101
102
  },
102
103
  });
103
104
  const proxyStorage = (storage, scope) => {
@@ -106,22 +107,25 @@ const proxyStorage = (storage, scope) => {
106
107
  get(target, key) {
107
108
  const value = Reflect.get(target, key);
108
109
  if (key === 'sql' && value !== undefined) {
110
+ // SAFETY: proxyStorage wraps DurableObjectStorage, whose `sql` is a
111
+ // SqlStorage; a transaction has no `sql` and never reaches here.
109
112
  sql ?? (sql = traceSql(value));
110
113
  return sql;
111
114
  }
112
- if (typeof value !== 'function') {
115
+ if (!isFunction(value)) {
113
116
  return value;
114
117
  }
115
118
  const method = `${scope}.${String(key)}`;
116
119
  return (...args) => {
120
+ const [closure] = args;
117
121
  // Alarm writes inside `transaction` go through the transaction object.
118
- const forwarded = key === 'transaction' && typeof args[0] === 'function'
122
+ const forwarded = key === 'transaction' && isFunction(closure)
119
123
  ? [
120
- (transaction) => args[0](proxyStorage(transaction, 'transaction')),
124
+ (transaction) => closure(proxyStorage(transaction, 'transaction')),
121
125
  ...args.slice(1),
122
126
  ]
123
127
  : args;
124
- return traceCall('storage', { method, args: loggableArgs(args) }, () => Reflect.apply(value, target, forwarded));
128
+ return traceCall('storage', { method, args: loggableArgs(args) }, () => value.apply(target, forwarded));
125
129
  };
126
130
  },
127
131
  });
@@ -140,6 +144,8 @@ export const traceStorage = (storage) => {
140
144
  }
141
145
  const existing = tracedStorage.get(storage);
142
146
  if (existing) {
147
+ // SAFETY: tracedStorage maps a storage only to the proxy of that same
148
+ // storage, set below.
143
149
  return existing;
144
150
  }
145
151
  const traced = proxyStorage(storage, 'storage');
@@ -1,4 +1,5 @@
1
1
  import { exports as workerExports } from 'cloudflare:workers';
2
+ import { isFunction, isObjectOrFunction } from './predicates.js';
2
3
  export const resolveNamespace = (config, error) => {
3
4
  const namespace = config.namespace?.();
4
5
  if (namespace) {
@@ -7,11 +8,14 @@ export const resolveNamespace = (config, error) => {
7
8
  if (!config.exportName) {
8
9
  throw error('Use the durability Vite plugin, exportName, or an explicit namespace to resolve the target');
9
10
  }
10
- const exported = Reflect.get(workerExports, config.exportName);
11
- if (exported === null ||
12
- (typeof exported !== 'object' && typeof exported !== 'function') ||
13
- typeof Reflect.get(exported, 'getByName') !== 'function') {
11
+ const exportsByName = workerExports;
12
+ const exported = exportsByName[config.exportName];
13
+ if (!isObjectOrFunction(exported) ||
14
+ !('getByName' in exported) ||
15
+ !isFunction(exported.getByName)) {
14
16
  throw error(`Export "${config.exportName}" is not a Durable Object namespace`);
15
17
  }
18
+ // SAFETY: exportName names the binding of the target class (set by the Vite
19
+ // plugin or the caller), and the check above found its getByName.
16
20
  return exported;
17
21
  };
package/dist/errors.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { Json } from './serialization.js';
1
2
  /**
2
3
  * Marks a handler failure as terminal so it is persisted without another retry.
3
4
  *
@@ -30,18 +31,18 @@ export declare class DurableAlarmTimeoutError extends Error {
30
31
  }
31
32
  /** Error persisted when retry-delay evaluation fails or is unsafe. */
32
33
  export declare class DurableRetryPolicyError extends Error {
33
- constructor(entity: string, reason?: unknown);
34
+ constructor(entity: string, cause?: unknown);
34
35
  }
35
36
  /** Error persisted when a successful result cannot be JSON-serialized. */
36
37
  export declare class DurableResultSerializationError extends Error {
37
- constructor(operation: string, reason?: unknown);
38
+ constructor(operation: string, cause?: unknown);
38
39
  }
39
40
  /**
40
41
  * Error persisted when a memoized result cannot be JSON-serialized. It is
41
42
  * terminal because every retry would fail the same way.
42
43
  */
43
44
  export declare class DurableMemoSerializationError extends NonRetryableError {
44
- constructor(key: string, reason?: unknown);
45
+ constructor(key: string, cause?: unknown);
45
46
  }
46
47
  /**
47
48
  * Error persisted when work memoizes more keys, or a larger result, than the
@@ -139,11 +140,15 @@ export type SerializedError = {
139
140
  message: string;
140
141
  };
141
142
  /** Reduces any thrown value to a persistable name and message, never throwing. */
142
- export declare const serializeError: (error: unknown) => SerializedError;
143
- export declare const isErrorInstance: (error: unknown, constructor: new (...args: never[]) => Error) => boolean;
143
+ export declare const serializeError: (cause: unknown) => SerializedError;
144
+ export declare const isErrorInstance: <Instance extends Error>(error: unknown, constructor: new (...args: never[]) => Instance) => error is Instance;
144
145
  /** Recognizes this package's NonRetryableError and same-named errors from other packages. */
145
- export declare const isNonRetryable: (error: unknown) => boolean;
146
- export declare const reportFailure: (event: string, details: Record<string, unknown>, error: unknown) => void;
146
+ export declare const isNonRetryable: (cause: unknown) => boolean;
147
+ /** Fields logged with a failure to identify the work that failed. */
148
+ type FailureDetails = {
149
+ readonly [field: string]: Json;
150
+ };
151
+ export declare const reportFailure: (event: string, details: FailureDetails, cause: unknown) => void;
147
152
  /** A definite rejection of a topology change or configuration. */
148
153
  export declare class TopologyError extends Error {
149
154
  constructor(message: string);
@@ -161,3 +166,4 @@ export declare class TopologyUnavailableError extends Error {
161
166
  cause?: unknown;
162
167
  });
163
168
  }
169
+ export {};
package/dist/errors.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { isNonEmptyString, isObjectOrFunction } from './predicates.js';
1
2
  /**
2
3
  * Marks a handler failure as terminal so it is persisted without another retry.
3
4
  *
@@ -39,21 +40,21 @@ export class DurableAlarmTimeoutError extends Error {
39
40
  }
40
41
  /** Error persisted when retry-delay evaluation fails or is unsafe. */
41
42
  export class DurableRetryPolicyError extends Error {
42
- constructor(entity, reason) {
43
+ constructor(entity, cause) {
43
44
  super(`Retry policy for ${entity} must produce a non-negative safe-integer timestamp`);
44
45
  this.name = 'DurableRetryPolicyError';
45
- if (reason !== undefined) {
46
- Object.defineProperty(this, 'cause', { value: reason });
46
+ if (cause !== undefined) {
47
+ Object.defineProperty(this, 'cause', { value: cause });
47
48
  }
48
49
  }
49
50
  }
50
51
  /** Error persisted when a successful result cannot be JSON-serialized. */
51
52
  export class DurableResultSerializationError extends Error {
52
- constructor(operation, reason) {
53
+ constructor(operation, cause) {
53
54
  super(`Result for durable operation "${operation}" is not JSON-serializable`);
54
55
  this.name = 'DurableResultSerializationError';
55
- if (reason !== undefined) {
56
- Object.defineProperty(this, 'cause', { value: reason });
56
+ if (cause !== undefined) {
57
+ Object.defineProperty(this, 'cause', { value: cause });
57
58
  }
58
59
  }
59
60
  }
@@ -62,11 +63,11 @@ export class DurableResultSerializationError extends Error {
62
63
  * terminal because every retry would fail the same way.
63
64
  */
64
65
  export class DurableMemoSerializationError extends NonRetryableError {
65
- constructor(key, reason) {
66
+ constructor(key, cause) {
66
67
  super(`Memoized result for key ${JSON.stringify(key)} is not JSON-serializable`);
67
68
  this.name = 'DurableMemoSerializationError';
68
- if (reason !== undefined) {
69
- Object.defineProperty(this, 'cause', { value: reason });
69
+ if (cause !== undefined) {
70
+ Object.defineProperty(this, 'cause', { value: cause });
70
71
  }
71
72
  }
72
73
  }
@@ -213,26 +214,24 @@ export class RoutingError extends Error {
213
214
  }
214
215
  const readString = (value, property) => {
215
216
  try {
216
- const candidate = Reflect.get(value, property);
217
- return typeof candidate === 'string' && candidate.length > 0
218
- ? candidate
219
- : undefined;
217
+ const candidate = value[property];
218
+ return isNonEmptyString(candidate) ? candidate : undefined;
220
219
  }
221
220
  catch {
222
221
  return undefined;
223
222
  }
224
223
  };
225
224
  /** Reduces any thrown value to a persistable name and message, never throwing. */
226
- export const serializeError = (error) => {
227
- if (error === null) {
225
+ export const serializeError = (cause) => {
226
+ if (cause === null) {
228
227
  return { name: 'Error', message: 'null' };
229
228
  }
230
- if (typeof error !== 'object' && typeof error !== 'function') {
231
- return { name: 'Error', message: String(error) };
229
+ if (!isObjectOrFunction(cause)) {
230
+ return { name: 'Error', message: String(cause) };
232
231
  }
233
232
  return {
234
- name: readString(error, 'name') ?? 'Error',
235
- message: readString(error, 'message') ?? 'Unknown thrown value',
233
+ name: readString(cause, 'name') ?? 'Error',
234
+ message: readString(cause, 'message') ?? 'Unknown thrown value',
236
235
  };
237
236
  };
238
237
  export const isErrorInstance = (error, constructor) => {
@@ -244,37 +243,40 @@ export const isErrorInstance = (error, constructor) => {
244
243
  }
245
244
  };
246
245
  /** Recognizes this package's NonRetryableError and same-named errors from other packages. */
247
- export const isNonRetryable = (error) => {
248
- if (isErrorInstance(error, NonRetryableError)) {
246
+ export const isNonRetryable = (cause) => {
247
+ if (isErrorInstance(cause, NonRetryableError)) {
249
248
  return true;
250
249
  }
251
- if ((typeof error !== 'object' && typeof error !== 'function') ||
252
- error === null) {
250
+ if (!isObjectOrFunction(cause)) {
253
251
  return false;
254
252
  }
255
- if (readString(error, 'name') === 'NonRetryableError') {
253
+ if (readString(cause, 'name') === 'NonRetryableError') {
256
254
  return true;
257
255
  }
258
256
  try {
259
- const constructor = Reflect.get(error, 'constructor');
260
- return (constructor !== null &&
261
- (typeof constructor === 'object' || typeof constructor === 'function') &&
257
+ const constructor = cause.constructor;
258
+ return (isObjectOrFunction(constructor) &&
262
259
  readString(constructor, 'name') === 'NonRetryableError');
263
260
  }
264
261
  catch {
265
262
  return false;
266
263
  }
267
264
  };
268
- export const reportFailure = (event, details, error) => {
265
+ export const reportFailure = (event, details, cause) => {
269
266
  try {
270
- const stack = error !== null &&
271
- (typeof error === 'object' || typeof error === 'function')
272
- ? readString(error, 'stack')
267
+ const stack = isObjectOrFunction(cause)
268
+ ? readString(cause, 'stack')
273
269
  : undefined;
270
+ const logged = {
271
+ ...serializeError(cause),
272
+ };
273
+ if (stack) {
274
+ logged.stack = stack;
275
+ }
274
276
  console.error({
275
277
  event,
276
278
  ...details,
277
- error: { ...serializeError(error), ...(stack ? { stack } : {}) },
279
+ error: logged,
278
280
  });
279
281
  }
280
282
  catch {
@@ -28,7 +28,7 @@ export type DurabilityFanoutMessage<Body = unknown> = {
28
28
  deadLetter(): Promise<void>;
29
29
  };
30
30
  export type FanoutTarget<Body> = ExecutionPolicyOptions & ({
31
- deliver(messages: DurabilityFanoutMessage<Body>[]): unknown | Promise<unknown>;
31
+ deliver(messages: DurabilityFanoutMessage<Body>[]): void | Promise<void>;
32
32
  /**
33
33
  * Acks every message the consumer leaves unsettled when `deliver`
34
34
  * returns without throwing, in one transaction instead of one call
@@ -20,6 +20,7 @@ import { durabilityFanoutMigrations } from './migrations.js';
20
20
  import { durabilityMemoMigrations } from '../memoize/migrations.js';
21
21
  import { migrateCapability } from '../migrations.js';
22
22
  import { assertPositiveInteger, createPolicyResolver, methodOptionsSchema, } from '../policy.js';
23
+ import { isFunction, isNonEmptyString } from '../predicates.js';
23
24
  import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
24
25
  import { deserialize, serialize } from '../serialization.js';
25
26
  import { claimAttempt, deleteAttempt, updateAttempt, } from '../storage.js';
@@ -116,9 +117,7 @@ export class DurabilityFanout {
116
117
  }
117
118
  __classPrivateFieldSet(this, _DurabilityFanout_policies, new Map(), "f");
118
119
  for (const [id, target] of __classPrivateFieldGet(this, _DurabilityFanout_targets, "f")) {
119
- if (!id ||
120
- (typeof target.deliver !== 'function' &&
121
- typeof target.storage !== 'function')) {
120
+ if (!id || (!isFunction(target.deliver) && !isFunction(target.storage))) {
122
121
  throw new TypeError(`Invalid fanout target "${id}"`);
123
122
  }
124
123
  __classPrivateFieldGet(this, _DurabilityFanout_policies, "f").set(id, createPolicyResolver(config, { [id]: target }, methodOptionsSchema)(id));
@@ -150,6 +149,8 @@ export class DurabilityFanout {
150
149
  * returns a function that detaches it.
151
150
  */
152
151
  lifecycle(hook) {
152
+ // SAFETY: every event this instance emits spreads entity(claim), so it is
153
+ // a fanout_delivery event.
153
154
  return __classPrivateFieldGet(this, _DurabilityFanout_lifecycle, "f").add(hook);
154
155
  }
155
156
  async load() {
@@ -175,10 +176,7 @@ export class DurabilityFanout {
175
176
  entries = (Array.isArray(messages) ? messages : [messages]).map((message) => {
176
177
  const id = message.id ?? crypto.randomUUID();
177
178
  const key = message.deduplicationKey ?? id;
178
- if (typeof id !== 'string' ||
179
- !id ||
180
- typeof key !== 'string' ||
181
- !key) {
179
+ if (!isNonEmptyString(id) || !isNonEmptyString(key)) {
182
180
  throw new FanoutEnqueueError('Message IDs and deduplication keys must be non-empty strings');
183
181
  }
184
182
  return { key, id, payload: serialize(message.body) };
@@ -284,7 +282,7 @@ export class DurabilityFanout {
284
282
  const load = await this.load();
285
283
  // Delayed first attempts are not due yet; the scheduler wakes for them.
286
284
  if (registered.length > 0 && __classPrivateFieldGet(this, _DurabilityFanout_batchDelayMs, "f") === 0) {
287
- const onError = (error) => reportFailure('durability.fanout.failed', {}, error);
285
+ const onError = (cause) => reportFailure('durability.fanout.failed', {}, cause);
288
286
  const work = __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_runDue).call(this)
289
287
  .then(() => __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").scheduleNextAlarm())
290
288
  .catch(onError);
@@ -388,7 +386,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
388
386
  attempt: claim.row.attempt,
389
387
  });
390
388
  }
391
- let failure = new Error('Consumer returned without settling the message');
389
+ let failure = serializeError(new Error('Consumer returned without settling the message'));
392
390
  try {
393
391
  await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_deadline).call(this, async () => {
394
392
  let invocationFailed = false;
@@ -439,7 +437,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
439
437
  }, policy.attemptTimeoutMs);
440
438
  }
441
439
  catch (error) {
442
- failure = error;
440
+ failure = serializeError(error);
443
441
  }
444
442
  finally {
445
443
  for (const state of states) {
@@ -470,7 +468,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
470
468
  }
471
469
  state.outcome = 'retry';
472
470
  // eslint-disable-next-line no-await-in-loop
473
- await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, undefined, serializeError(failure), startedAt);
471
+ await __classPrivateFieldGet(this, _DurabilityFanout_instances, "m", _DurabilityFanout_retry).call(this, state.claim, policy, undefined, failure, startedAt);
474
472
  }
475
473
  }, _DurabilityFanout_ackUnsettled = function _DurabilityFanout_ackUnsettled(states, startedAt) {
476
474
  const unsettled = states.filter((state) => state.outcome === undefined);
@@ -535,6 +533,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
535
533
  return {
536
534
  id: message.id,
537
535
  ...identity,
536
+ // SAFETY: enqueue is the only writer of message payloads, each
537
+ // serialized from a Body.
538
538
  body: deserialize(message.payload),
539
539
  enqueuedAt: message.created_at,
540
540
  attempt: row.attempt,
@@ -644,6 +644,8 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
644
644
  id: deliveryIdentity(row),
645
645
  messageId: message.id,
646
646
  target: row.target_id,
647
+ // SAFETY: enqueue is the only writer of message payloads, each
648
+ // serialized from a Body.
647
649
  body: deserialize(message.payload),
648
650
  enqueuedAt: message.created_at,
649
651
  storedAt: timestamp,
@@ -706,7 +708,7 @@ _DurabilityFanout_engine = new WeakMap(), _DurabilityFanout_channel = new WeakMa
706
708
  LIMIT ?`, __classPrivateFieldGet(this, _DurabilityFanout_channel, "f"), target, now, __classPrivateFieldGet(this, _DurabilityFanout_maxBatchSize, "f") - first.length)
707
709
  .toArray());
708
710
  return [...first, ...retries];
709
- }, _DurabilityFanout_deadline = async function _DurabilityFanout_deadline(run, timeoutMs) {
710
- await __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").timer.withTimeout(Promise.resolve().then(run), timeoutMs, () => new FanoutTimeoutError(timeoutMs));
711
+ }, _DurabilityFanout_deadline = function _DurabilityFanout_deadline(run, timeoutMs) {
712
+ return __classPrivateFieldGet(this, _DurabilityFanout_engine, "f").timer.withTimeout(Promise.resolve().then(run), timeoutMs, () => new FanoutTimeoutError(timeoutMs));
711
713
  };
712
714
  traceMethods(DurabilityFanout.prototype, 'DurabilityFanout');
@@ -90,5 +90,6 @@ export declare const createLifecycleHooks: (emitter: (hook: LifecycleHook) => Em
90
90
  export declare const createEmitter: <Event extends {
91
91
  entityKind: string;
92
92
  type: string;
93
+ id?: string;
93
94
  } = DurabilityLifecycleEvent>(hook: ((event: Event) => void | Promise<void>) | undefined, waitUntil: ((promise: Promise<unknown>) => void) | undefined) => ((event: Event) => void);
94
95
  export {};
package/dist/lifecycle.js CHANGED
@@ -31,11 +31,11 @@ export const createEmitter = (hook, waitUntil) => {
31
31
  return () => undefined;
32
32
  }
33
33
  return (event) => {
34
- const report = (error) => reportFailure('durability.lifecycle_hook.failed', {
34
+ const report = (cause) => reportFailure('durability.lifecycle_hook.failed', {
35
35
  entityKind: event.entityKind,
36
36
  lifecycleType: event.type,
37
37
  entityId: 'id' in event ? event.id : 'durability',
38
- }, error);
38
+ }, cause);
39
39
  try {
40
40
  const result = hook(event);
41
41
  if (result === undefined) {
package/dist/log/index.js CHANGED
@@ -17,6 +17,7 @@ import { RoutingLoad, } from '../routing/load.js';
17
17
  import { durabilityLogLeaseMigrations, durabilityLogMigrations, } from './migrations.js';
18
18
  import { migrateCapability } from '../migrations.js';
19
19
  import { assertPositiveInteger } from '../policy.js';
20
+ import { isNonEmptyString } from '../predicates.js';
20
21
  import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
21
22
  import { deserialize, serialize } from '../serialization.js';
22
23
  const logRecordRowSchema = v.object({
@@ -497,7 +498,7 @@ export class DurabilityLog {
497
498
  lastOffset: last.offset,
498
499
  records,
499
500
  });
500
- if (typeof locator !== 'string' || locator.length === 0) {
501
+ if (!isNonEmptyString(locator)) {
501
502
  throw new TypeError('Cold storage must return a non-empty locator');
502
503
  }
503
504
  // Indexed before deletion: a crash in between leaves the segment
@@ -683,6 +684,8 @@ async function _DurabilityLog_rehydrate(from, limit, bounds) {
683
684
  return {
684
685
  offset: row.offset,
685
686
  deduplicationKey: row.dedup_key,
687
+ // SAFETY: append is the only writer of this channel's payloads, each
688
+ // serialized from a Body.
686
689
  body: deserialize(row.payload),
687
690
  appendedAt: row.appended_at,
688
691
  };
@@ -768,7 +771,7 @@ async function _DurabilityLog_between(first, last) {
768
771
  };
769
772
  traceMethods(DurabilityLog.prototype, 'DurabilityLog');
770
773
  const assertConsumer = (consumer) => {
771
- if (typeof consumer !== 'string' || consumer.length === 0) {
774
+ if (!isNonEmptyString(consumer)) {
772
775
  throw new LogAppendError('Consumer must be a non-empty string');
773
776
  }
774
777
  };