durability 5.2.1 → 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 (56) hide show
  1. package/README.md +42 -18
  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 -26
  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/migrations.js +37 -37
  16. package/dist/operations/index.js +8 -4
  17. package/dist/outbox/index.d.ts +1 -1
  18. package/dist/outbox/index.js +7 -17
  19. package/dist/policy.d.ts +1 -1
  20. package/dist/policy.js +2 -1
  21. package/dist/predicates.d.ts +9 -0
  22. package/dist/predicates.js +10 -0
  23. package/dist/routing/client.js +3 -4
  24. package/dist/routing/index.d.ts +1 -1
  25. package/dist/routing/index.js +14 -10
  26. package/dist/schedule/index.d.ts +15 -3
  27. package/dist/schedule/index.js +55 -36
  28. package/dist/scheduler/index.d.ts +35 -14
  29. package/dist/scheduler/index.js +78 -74
  30. package/dist/semaphore/client.js +2 -1
  31. package/dist/semaphore/index.d.ts +1 -1
  32. package/dist/semaphore/index.js +10 -5
  33. package/dist/semaphore/leases.d.ts +3 -2
  34. package/dist/semaphore/leases.js +3 -2
  35. package/dist/semaphore/queue-store.js +2 -1
  36. package/dist/semaphore/queue.d.ts +1 -1
  37. package/dist/semaphore/queue.js +36 -37
  38. package/dist/semaphore/server.js +50 -32
  39. package/dist/serialization.d.ts +3 -2
  40. package/dist/serialization.js +16 -13
  41. package/dist/shared-timer.d.ts +27 -0
  42. package/dist/shared-timer.js +191 -0
  43. package/dist/socket/client.d.ts +21 -7
  44. package/dist/socket/client.js +37 -27
  45. package/dist/socket/index.d.ts +20 -13
  46. package/dist/socket/index.js +40 -18
  47. package/dist/socket/protocol.d.ts +37 -17
  48. package/dist/socket/protocol.js +30 -36
  49. package/dist/topology/client.js +36 -19
  50. package/dist/topology/index.d.ts +3 -3
  51. package/dist/topology/index.js +40 -49
  52. package/dist/topology/snapshot.d.ts +6 -5
  53. package/dist/topology/snapshot.js +5 -2
  54. package/dist/tracker/index.js +18 -7
  55. package/dist/tracker/source.d.ts +6 -2
  56. package/package.json +2 -2
@@ -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,20 +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
- let timer;
711
- try {
712
- await Promise.race([
713
- Promise.resolve().then(run),
714
- new Promise((_resolve, reject) => {
715
- timer = setTimeout(() => reject(new FanoutTimeoutError(timeoutMs)), timeoutMs);
716
- }),
717
- ]);
718
- }
719
- finally {
720
- if (timer !== undefined) {
721
- clearTimeout(timer);
722
- }
723
- }
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));
724
713
  };
725
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
  };
@@ -1,6 +1,7 @@
1
1
  import * as v from 'valibot';
2
2
  import { traceFunction } from '../dev.js';
3
3
  import { DurableMemoLimitError, DurableMemoSerializationError, } from '../errors.js';
4
+ import { isNonEmptyString } from '../predicates.js';
4
5
  import { deserialize, serialize } from '../serialization.js';
5
6
  import { channelBindings, pendingGeneration, tableOwner, } from '../storage.js';
6
7
  /** The most keys one operation, alarm occurrence, or fanout delivery may memoize. */
@@ -45,12 +46,14 @@ export const createMemoize = (sql, table, ref) => {
45
46
  throw supersededError(key);
46
47
  }
47
48
  // Return what a replay would return, so later code sees one shape either way.
49
+ // SAFETY: `serialized` encodes `value`, and serialize rejects values JSON
50
+ // cannot round-trip, so this reads back as a T.
48
51
  return deserialize(serialized);
49
52
  };
50
53
  // Everything up to the callback runs synchronously, so a concurrent call
51
54
  // with the same key sees either the saved result or this key as running.
52
55
  const run = async (key, callback) => {
53
- if (typeof key !== 'string' || key === '') {
56
+ if (!isNonEmptyString(key)) {
54
57
  throw new TypeError('Memoize keys must be non-empty strings');
55
58
  }
56
59
  const lookup = v.parse(memoLookupSchema, sql
@@ -66,6 +69,8 @@ export const createMemoize = (sql, table, ref) => {
66
69
  WHERE owner = ? AND key = ? AND generation_id = ?) AS saved`, owner, ref.key, ref.generation, key, ref.key, ref.generation, ...channelBindings(table), ref.attempt, owner, ref.key, ref.generation)
67
70
  .toArray()[0]);
68
71
  if (lookup.result !== null) {
72
+ // SAFETY: only save() writes memos, with the result of the callback
73
+ // memoized under this key, which has type T on every attempt.
69
74
  return deserialize(lookup.result);
70
75
  }
71
76
  // A rescheduled or purged attempt must not start side effects it can never record.
@@ -78,7 +78,7 @@ const runDown = (sql, table, name, down) => {
78
78
  * scripts it stored. Refuses when the schema is further ahead than
79
79
  * {@link maxFutureMigrations}.
80
80
  */
81
- const revertFutureMigrations = (storage, scope, history, known) => {
81
+ const revertFutureMigrations = (sql, scope, history, known) => {
82
82
  const future = history.filter(({ name }) => !known.has(name)).reverse();
83
83
  if (future.length === 0) {
84
84
  return [];
@@ -86,11 +86,9 @@ const revertFutureMigrations = (storage, scope, history, known) => {
86
86
  if (future.length > maxFutureMigrations) {
87
87
  throw new Error(`${scope.label} schema is ${future.length} migrations ahead of this version; refusing to revert more than ${maxFutureMigrations}`);
88
88
  }
89
- storage.transactionSync(() => {
90
- for (const row of future) {
91
- runDown(storage.sql, scope.table, row.name, row.down);
92
- }
93
- });
89
+ for (const row of future) {
90
+ runDown(sql, scope.table, row.name, row.down);
91
+ }
94
92
  return future.map(({ name }) => name);
95
93
  };
96
94
  const currentRowSchema = v.object({
@@ -130,27 +128,29 @@ const migrateScope = (storage, scope, migrations, target) => {
130
128
  if (resolvedTarget !== null && targetIndex === -1) {
131
129
  throw new Error(`Unknown ${scope.label} migration target "${resolvedTarget}"`);
132
130
  }
133
- ensureHistoryTable(storage.sql, scope.table);
134
- if (scope.table === migrationTableName) {
135
- translateLegacyHistory(storage.sql);
136
- }
137
- const known = new Set(migrations.map(({ name }) => name));
138
- const history = readHistory(storage.sql, scope, migrations);
139
- const rolledBack = revertFutureMigrations(storage, scope, history, known);
140
- const applied = new Map(history
141
- .filter(({ name }) => known.has(name))
142
- .map((row) => [row.name, row]));
143
- const toRevert = migrations
144
- .slice(targetIndex + 1)
145
- .filter(({ name }) => applied.has(name))
146
- .reverse();
147
- const toApply = migrations
148
- .slice(0, targetIndex + 1)
149
- .filter(({ name }) => !applied.has(name));
150
- const toRefresh = migrations
151
- .slice(0, targetIndex + 1)
152
- .filter(({ name, down }) => applied.has(name) && applied.get(name)?.down !== down);
153
- storage.transactionSync(() => {
131
+ // Every step shares one transaction so a failure anywhere, including after
132
+ // future migrations were reverted, leaves the schema and history as they were.
133
+ return storage.transactionSync(() => {
134
+ ensureHistoryTable(storage.sql, scope.table);
135
+ if (scope.table === migrationTableName) {
136
+ translateLegacyHistory(storage.sql);
137
+ }
138
+ const known = new Set(migrations.map(({ name }) => name));
139
+ const history = readHistory(storage.sql, scope, migrations);
140
+ const rolledBack = revertFutureMigrations(storage.sql, scope, history, known);
141
+ const applied = new Map(history
142
+ .filter(({ name }) => known.has(name))
143
+ .map((row) => [row.name, row]));
144
+ const toRevert = migrations
145
+ .slice(targetIndex + 1)
146
+ .filter(({ name }) => applied.has(name))
147
+ .reverse();
148
+ const toApply = migrations
149
+ .slice(0, targetIndex + 1)
150
+ .filter(({ name }) => !applied.has(name));
151
+ const toRefresh = migrations
152
+ .slice(0, targetIndex + 1)
153
+ .filter(({ name, down }) => applied.has(name) && applied.get(name)?.down !== down);
154
154
  for (const migration of toRevert) {
155
155
  runDown(storage.sql, scope.table, migration.name, migration.down);
156
156
  }
@@ -162,17 +162,17 @@ const migrateScope = (storage, scope, migrations, target) => {
162
162
  for (const migration of toRefresh) {
163
163
  storage.sql.exec(`UPDATE ${scope.table} SET down = ? WHERE name = ?`, migration.down, migration.name);
164
164
  }
165
+ const remaining = v.parse(v.object({ count: v.pipe(v.number(), v.safeInteger()) }), storage.sql
166
+ .exec(`SELECT COUNT(*) AS count FROM ${scope.table}`)
167
+ .toArray()[0]).count;
168
+ if (remaining === 0) {
169
+ storage.sql.exec(`DROP TABLE IF EXISTS ${scope.table}`);
170
+ }
171
+ return {
172
+ applied: toApply.map(({ name }) => name),
173
+ rolledBack: [...rolledBack, ...toRevert.map(({ name }) => name)],
174
+ };
165
175
  });
166
- const remaining = v.parse(v.object({ count: v.pipe(v.number(), v.safeInteger()) }), storage.sql
167
- .exec(`SELECT COUNT(*) AS count FROM ${scope.table}`)
168
- .toArray()[0]).count;
169
- if (remaining === 0) {
170
- storage.sql.exec(`DROP TABLE IF EXISTS ${scope.table}`);
171
- }
172
- return {
173
- applied: toApply.map(({ name }) => name),
174
- rolledBack: [...rolledBack, ...toRevert.map(({ name }) => name)],
175
- };
176
176
  };
177
177
  /**
178
178
  * Moves one capability's schema to a target migration, applying or reverting as
@@ -152,6 +152,9 @@ class DurabilityCore {
152
152
  * returns a function that detaches it.
153
153
  */
154
154
  lifecycle(hook) {
155
+ // SAFETY: this instance emits only its purge event and events for its own
156
+ // calls, whose `operation` is a key of Handlers and whose result is that
157
+ // handler's return value.
155
158
  return __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").add(hook);
156
159
  }
157
160
  /**
@@ -260,7 +263,7 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_channel = new WeakMap(),
260
263
  if (!eagerPermit) {
261
264
  return;
262
265
  }
263
- const onError = (error) => reportFailure('durability.background_execution.failed', { operation: input.operation, id: input.id }, error);
266
+ const onError = (cause) => reportFailure('durability.background_execution.failed', { operation: input.operation, id: input.id }, cause);
264
267
  const background = __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, key, eagerPermit)
265
268
  .then(() => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").scheduleNextAlarm())
266
269
  .catch(onError);
@@ -307,6 +310,8 @@ async function _DurabilityCore_execute(key, eagerPermit) {
307
310
  }
308
311
  }, _DurabilityCore_start = function _DurabilityCore_start(call, eagerPermit) {
309
312
  const policy = __classPrivateFieldGet(this, _DurabilityCore_policy, "f").call(this, call.operation);
313
+ // SAFETY: the row was stored by the method for `call.operation`, which
314
+ // takes that handler's payload; rows of removed handlers find undefined.
310
315
  const handler = __classPrivateFieldGet(this, _DurabilityCore_handlers, "f")[call.operation];
311
316
  return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").startExecution({
312
317
  table: __classPrivateFieldGet(this, _DurabilityCore_table, "f"),
@@ -354,7 +359,6 @@ async function _DurabilityCore_execute(key, eagerPermit) {
354
359
  }, eagerPermit);
355
360
  };
356
361
  traceMethods(DurabilityCore.prototype, 'Durability');
357
- // TypeScript cannot declare class members derived from a generic handler map,
358
- // so the constructor is typed separately; the constructor installs and reserves
359
- // every operation method at runtime.
362
+ // SAFETY: the constructor defines a method for every handler name on the
363
+ // instance, members TypeScript cannot declare from a generic handler map.
360
364
  export const Durability = DurabilityCore;
@@ -28,7 +28,7 @@ export type DurabilityOutboxConfig<Value> = SchedulerAttachment & {
28
28
  * every entry not marked with `retry()`; throwing retries the whole batch.
29
29
  * Sinks must be idempotent on `(key, version)` and keep the highest version.
30
30
  */
31
- publish(entries: OutboxEntry<Value>[]): unknown | Promise<unknown>;
31
+ publish(entries: OutboxEntry<Value>[]): void | Promise<void>;
32
32
  /** Defaults to 50. */
33
33
  maxBatchSize?: number;
34
34
  /**
@@ -15,6 +15,7 @@ import { OutboxTimeoutError, reportFailure, serializeError, } from '../errors.js
15
15
  import { durabilityOutboxMigrations } from './migrations.js';
16
16
  import { migrateCapability, } from '../migrations.js';
17
17
  import { assertPositiveInteger, } from '../policy.js';
18
+ import { isFunction, isNonEmptyString } from '../predicates.js';
18
19
  import { assertChannel, defaultChannel, engineFor, } from '../scheduler/index.js';
19
20
  import { deserialize, serialize } from '../serialization.js';
20
21
  import { claimAttempt, deleteAttempt, updateAttempt, } from '../storage.js';
@@ -108,7 +109,7 @@ export class DurabilityOutbox {
108
109
  /** The channel's one publish run, never one still waiting for a permit. */
109
110
  _DurabilityOutbox_running.set(this, void 0);
110
111
  __classPrivateFieldSet(this, _DurabilityOutbox_channel, assertChannel('Outbox', config.channel ?? defaultChannel), "f");
111
- if (typeof config.publish !== 'function') {
112
+ if (!isFunction(config.publish)) {
112
113
  throw new TypeError('Outbox requires a publish function');
113
114
  }
114
115
  __classPrivateFieldSet(this, _DurabilityOutbox_maxBatchSize, config.maxBatchSize ?? 50, "f");
@@ -150,7 +151,7 @@ export class DurabilityOutbox {
150
151
  }
151
152
  }
152
153
  _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMap(), _DurabilityOutbox_publish = new WeakMap(), _DurabilityOutbox_maxBatchSize = new WeakMap(), _DurabilityOutbox_batchDelayMs = new WeakMap(), _DurabilityOutbox_attemptTimeoutMs = new WeakMap(), _DurabilityOutbox_delay = new WeakMap(), _DurabilityOutbox_emit = new WeakMap(), _DurabilityOutbox_running = new WeakMap(), _DurabilityOutbox_instances = new WeakSet(), _DurabilityOutbox_stageIn = function _DurabilityOutbox_stageIn(sql, key, value) {
153
- if (typeof key !== 'string' || key.length === 0) {
154
+ if (!isNonEmptyString(key)) {
154
155
  throw new TypeError('Outbox keys must be non-empty strings');
155
156
  }
156
157
  const payload = serialize(value);
@@ -265,6 +266,8 @@ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMa
265
266
  const entries = claims.map((row) => ({
266
267
  key: row.entry_key,
267
268
  version: row.version,
269
+ // SAFETY: #stageIn is the only writer of payloads, each serialized
270
+ // from a Value.
268
271
  value: deserialize(row.payload),
269
272
  attempt: row.attempt,
270
273
  stagedAt: row.created_at,
@@ -360,21 +363,8 @@ _DurabilityOutbox_engine = new WeakMap(), _DurabilityOutbox_channel = new WeakMa
360
363
  reportFailure('durability.outbox.retry_policy_failed', { channel: __classPrivateFieldGet(this, _DurabilityOutbox_channel, "f") }, error);
361
364
  }
362
365
  return infrastructureRetryMs;
363
- }, _DurabilityOutbox_deadline = async function _DurabilityOutbox_deadline(run) {
364
- let timer;
365
- try {
366
- await Promise.race([
367
- Promise.resolve().then(run),
368
- new Promise((_resolve, reject) => {
369
- timer = setTimeout(() => reject(new OutboxTimeoutError(__classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"))), __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"));
370
- }),
371
- ]);
372
- }
373
- finally {
374
- if (timer !== undefined) {
375
- clearTimeout(timer);
376
- }
377
- }
366
+ }, _DurabilityOutbox_deadline = function _DurabilityOutbox_deadline(run) {
367
+ return __classPrivateFieldGet(this, _DurabilityOutbox_engine, "f").timer.withTimeout(Promise.resolve().then(run), __classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f"), () => new OutboxTimeoutError(__classPrivateFieldGet(this, _DurabilityOutbox_attemptTimeoutMs, "f")));
378
368
  };
379
369
  (() => {
380
370
  stageWithin = (outbox, sql, key, value) => {
package/dist/policy.d.ts CHANGED
@@ -71,4 +71,4 @@ export declare const assertPositiveInteger: (name: string, value: number) => voi
71
71
  export type PolicyResolver<Method> = (name: string) => AttemptPolicy & {
72
72
  method: Method | undefined;
73
73
  };
74
- export declare const createPolicyResolver: <Method extends MethodPolicy>(options: ExecutionPolicyOptions, methods: Record<string, unknown>, methodSchema: v.GenericSchema<unknown, Method>) => PolicyResolver<Method>;
74
+ export declare const createPolicyResolver: <Input, Method extends MethodPolicy>(options: ExecutionPolicyOptions, methods: Partial<Record<string, NoInfer<Input>>>, methodSchema: v.GenericSchema<Input, Method>) => PolicyResolver<Method>;
package/dist/policy.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import * as v from 'valibot';
2
+ import { isFunction } from './predicates.js';
2
3
  import { exponential, jitter } from './utils.js';
3
- const functionSchema = () => v.custom((value) => typeof value === 'function');
4
+ const functionSchema = () => v.custom(isFunction);
4
5
  const retryOptionsSchema = v.object({
5
6
  delay: v.optional(functionSchema()),
6
7
  maxAttempts: v.optional(v.number()),
@@ -0,0 +1,9 @@
1
+ import type { Json, JsonObject } from './serialization.js';
2
+ export declare const isString: (value: unknown) => value is string;
3
+ export declare const isNonEmptyString: (value: unknown) => value is string;
4
+ export declare const isNumber: (value: unknown) => value is number;
5
+ export declare const isFunction: (value: unknown) => value is Function;
6
+ /** Excludes functions, unlike {@link isObjectOrFunction}. */
7
+ export declare const isObject: (value: unknown) => value is object;
8
+ export declare const isObjectOrFunction: (value: unknown) => value is object;
9
+ export declare const isJsonObject: (value: Json | undefined) => value is JsonObject;
@@ -0,0 +1,10 @@
1
+ // Runtime checks for values JavaScript callers, storage, and peers hand in
2
+ // without a TypeScript contract.
3
+ export const isString = (value) => typeof value === 'string';
4
+ export const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
5
+ export const isNumber = (value) => typeof value === 'number';
6
+ export const isFunction = (value) => typeof value === 'function';
7
+ /** Excludes functions, unlike {@link isObjectOrFunction}. */
8
+ export const isObject = (value) => typeof value === 'object' && value !== null;
9
+ export const isObjectOrFunction = (value) => isObject(value) || isFunction(value);
10
+ export const isJsonObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -11,6 +11,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
11
11
  };
12
12
  var _RoutingClient_instances, _RoutingClient_config, _RoutingClient_observations, _RoutingClient_limit, _RoutingClient_width, _RoutingClient_lastResize, _RoutingClient_select, _RoutingClient_resize;
13
13
  import { RoutingError } from '../errors.js';
14
+ import { isNonEmptyString, isString } from '../predicates.js';
14
15
  /**
15
16
  * Transport-independent selection and observation. Every push invokes ONE
16
17
  * shard once. A false result is returned unchanged; transport failures throw.
@@ -44,10 +45,8 @@ export class RoutingClient {
44
45
  const target = __classPrivateFieldGet(this, _RoutingClient_config, "f").sharding
45
46
  ? await __classPrivateFieldGet(this, _RoutingClient_config, "f").sharding(input, context, observed)
46
47
  : __classPrivateFieldGet(this, _RoutingClient_instances, "m", _RoutingClient_select).call(this, observed);
47
- const address = typeof target === 'string' ? { shard: target } : target;
48
- if (!address ||
49
- typeof address.shard !== 'string' ||
50
- address.shard.length === 0) {
48
+ const address = isString(target) ? { shard: target } : target;
49
+ if (!address || !isNonEmptyString(address.shard)) {
51
50
  throw new RoutingError('Sharding must return a non-empty shard key or { shard, locationHint }');
52
51
  }
53
52
  const response = await __classPrivateFieldGet(this, _RoutingClient_config, "f").invoke(address, input);
@@ -7,7 +7,7 @@ export type { RoutingAddress, RoutingTarget, Sharding } from './client.js';
7
7
  export type RoutingSession<Input, Value, Context = unknown> = {
8
8
  push(input: Input, context?: Context): Promise<EnqueueResult<Value>>;
9
9
  setContext(context: TransformContext): {
10
- invoke(method: string, args: unknown[]): Promise<unknown>;
10
+ invoke(method: string, args: unknown[]): Promise<EnqueueResult<Value>>;
11
11
  };
12
12
  };
13
13
  export type DurabilityRoutingConfig<Target extends Rpc.DurableObjectBranded, Input, Value, Context = unknown> = DurableObjectTarget<Target> & {
@@ -1,8 +1,9 @@
1
1
  import { createTransformStub, } from '@durability/transforms';
2
2
  import { resolveNamespace, } from '../durable-object-target.js';
3
3
  import { RoutingError } from '../errors.js';
4
+ import { isObject } from '../predicates.js';
4
5
  import { RoutingLoad } from './load.js';
5
- import { RoutingClient } from './client.js';
6
+ import { RoutingClient, } from './client.js';
6
7
  /**
7
8
  * Inside a DO, attach this local load observer to a fanout capability. Outside
8
9
  * the DO, client() routes calls to an application-owned class using ordinary
@@ -10,7 +11,7 @@ import { RoutingClient } from './client.js';
10
11
  */
11
12
  export class DurabilityRouting extends RoutingLoad {
12
13
  static client(config) {
13
- const client = new RoutingClient({
14
+ const clientConfig = {
14
15
  invoke: (address, input) => {
15
16
  const namespace = resolveNamespace(config, (message) => new RoutingError(message));
16
17
  const stub = namespace.getByName(address.shard, address.locationHint === undefined
@@ -18,11 +19,14 @@ export class DurabilityRouting extends RoutingLoad {
18
19
  : { locationHint: address.locationHint });
19
20
  return config.invoke(stub, input);
20
21
  },
21
- ...(config.sharding === undefined ? {} : { sharding: config.sharding }),
22
- ...(config.softBacklogLimit === undefined
23
- ? {}
24
- : { softBacklogLimit: config.softBacklogLimit }),
25
- });
22
+ };
23
+ if (config.sharding !== undefined) {
24
+ clientConfig.sharding = config.sharding;
25
+ }
26
+ if (config.softBacklogLimit !== undefined) {
27
+ clientConfig.softBacklogLimit = config.softBacklogLimit;
28
+ }
29
+ const client = new RoutingClient(clientConfig);
26
30
  const session = {
27
31
  push: (input, context) => client.push(input, context),
28
32
  setContext: (context) => ({
@@ -32,11 +36,11 @@ export class DurabilityRouting extends RoutingLoad {
32
36
  }
33
37
  const positional = args[1];
34
38
  if (positional !== undefined &&
35
- (positional === null ||
36
- typeof positional !== 'object' ||
37
- Array.isArray(positional))) {
39
+ (!isObject(positional) || Array.isArray(positional))) {
38
40
  throw new TypeError('Routing context must be an object when combined with transform context');
39
41
  }
42
+ // SAFETY: the transform stub forwards the arguments of a typed `push`,
43
+ // so args are [Input, Context?]; transform context only adds keys.
40
44
  return client.push(args[0], { ...positional, ...context });
41
45
  },
42
46
  }),
@@ -111,16 +111,17 @@ export type DurabilityScheduleConfig = SchedulerAttachment & {
111
111
  channel?: string;
112
112
  /**
113
113
  * Returns the first tick strictly after `after`, or `undefined` for none.
114
- * Must be synchronous and deterministic; durability ships no cron parser.
114
+ * Must be synchronous; durability ships no cron parser. When its answers
115
+ * change, call {@link DurabilitySchedule.reschedule}.
115
116
  */
116
117
  nextOccurrence(expression: string, after: number): number | undefined;
117
118
  /** The work of one tick. Throwing or timing out makes the run `errored`. */
118
- run(run: ScheduledRunContext): unknown;
119
+ run(run: ScheduledRunContext): void | Promise<void>;
119
120
  /**
120
121
  * Receives each run's outcome at least once. Returning acknowledges it and
121
122
  * deletes the run's row; throwing retries it with `outcomeRetries`.
122
123
  */
123
- onOutcome(run: ScheduledOutcomeDelivery, outcome: ScheduledRunOutcome): unknown;
124
+ onOutcome(run: ScheduledOutcomeDelivery, outcome: ScheduledRunOutcome): void | Promise<void>;
124
125
  /** Runs in flight at once; later runs wait durably in order. Defaults to 10. */
125
126
  maxConcurrentRuns?: number;
126
127
  /** Maximum duration of one run. Defaults to 15 minutes. */
@@ -154,6 +155,17 @@ export declare class DurabilitySchedule {
154
155
  * alarm if it was lost.
155
156
  */
156
157
  set(definition: ScheduleDefinition): Promise<boolean>;
158
+ /**
159
+ * Recomputes the stored next tick with `nextOccurrence`, for when its answers
160
+ * changed for a reason durability can't see, and resolves `true` when the
161
+ * stored next tick changed. Resolves `false` when it didn't, when no schedule
162
+ * is live, or when the stored tick is already due: the alarm fires it, and
163
+ * the advance after it asks `nextOccurrence` again. The search starts from
164
+ * `now - jitterMs`, so a tick whose firing time is still ahead is kept and
165
+ * one whose firing time passed is skipped, not run. The version, the stored
166
+ * jitter, cancellations, and runs are unchanged.
167
+ */
168
+ reschedule(): Promise<boolean>;
157
169
  /**
158
170
  * Stops future ticks and resolves `true` when a schedule was live. Runs
159
171
  * already due or running still finish and report. With `version`, the