durability 5.1.0 → 5.2.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 (86) hide show
  1. package/README.md +145 -12
  2. package/dist/{durability-alarms.d.ts → alarms/index.d.ts} +13 -5
  3. package/dist/{durability-alarms.js → alarms/index.js} +69 -55
  4. package/dist/alarms/migrations.d.ts +9 -0
  5. package/dist/alarms/migrations.js +133 -0
  6. package/dist/experimental.d.ts +10 -10
  7. package/dist/experimental.js +7 -7
  8. package/dist/{fanout.d.ts → fanout/index.d.ts} +13 -6
  9. package/dist/{fanout.js → fanout/index.js} +54 -46
  10. package/dist/fanout/migrations.d.ts +9 -0
  11. package/dist/fanout/migrations.js +181 -0
  12. package/dist/{stored-message.d.ts → fanout/stored-message.d.ts} +1 -1
  13. package/dist/index.d.ts +14 -9
  14. package/dist/index.js +13 -8
  15. package/dist/{log.d.ts → log/index.d.ts} +15 -3
  16. package/dist/{log.js → log/index.js} +152 -124
  17. package/dist/log/migrations.d.ts +18 -0
  18. package/dist/log/migrations.js +297 -0
  19. package/dist/{memoize.d.ts → memoize/index.d.ts} +1 -1
  20. package/dist/{memoize.js → memoize/index.js} +14 -11
  21. package/dist/memoize/migrations.d.ts +10 -0
  22. package/dist/memoize/migrations.js +21 -0
  23. package/dist/migrations.d.ts +0 -111
  24. package/dist/migrations.js +0 -612
  25. package/dist/{durability.d.ts → operations/index.d.ts} +13 -5
  26. package/dist/{durability.js → operations/index.js} +59 -47
  27. package/dist/operations/migrations.d.ts +10 -0
  28. package/dist/operations/migrations.js +150 -0
  29. package/dist/{outbox.d.ts → outbox/index.d.ts} +4 -4
  30. package/dist/{outbox.js → outbox/index.js} +16 -60
  31. package/dist/outbox/migrations.d.ts +9 -0
  32. package/dist/outbox/migrations.js +43 -0
  33. package/dist/{routing-client.js → routing/client.js} +1 -1
  34. package/dist/{routing.d.ts → routing/index.d.ts} +3 -3
  35. package/dist/{routing.js → routing/index.js} +3 -3
  36. package/dist/{load.d.ts → routing/load.d.ts} +1 -1
  37. package/dist/{schedule.d.ts → schedule/index.d.ts} +16 -8
  38. package/dist/{schedule.js → schedule/index.js} +65 -49
  39. package/dist/schedule/migrations.d.ts +9 -0
  40. package/dist/schedule/migrations.js +118 -0
  41. package/dist/{scheduler.d.ts → scheduler/index.d.ts} +75 -25
  42. package/dist/{scheduler.js → scheduler/index.js} +300 -63
  43. package/dist/{semaphore-client.d.ts → semaphore/client.d.ts} +1 -1
  44. package/dist/{semaphore-client.js → semaphore/client.js} +2 -2
  45. package/dist/{semaphore.d.ts → semaphore/index.d.ts} +10 -10
  46. package/dist/{semaphore.js → semaphore/index.js} +7 -7
  47. package/dist/{semaphore-leases.d.ts → semaphore/leases.d.ts} +17 -6
  48. package/dist/{semaphore-leases.js → semaphore/leases.js} +28 -12
  49. package/dist/semaphore/migrations.d.ts +18 -0
  50. package/dist/semaphore/migrations.js +444 -0
  51. package/dist/{semaphore-protocol.d.ts → semaphore/protocol.d.ts} +16 -8
  52. package/dist/{semaphore-protocol.js → semaphore/protocol.js} +37 -14
  53. package/dist/{semaphore-queue-store.d.ts → semaphore/queue-store.d.ts} +12 -6
  54. package/dist/{semaphore-queue-store.js → semaphore/queue-store.js} +69 -61
  55. package/dist/{semaphore-queue.d.ts → semaphore/queue.d.ts} +15 -5
  56. package/dist/{semaphore-queue.js → semaphore/queue.js} +105 -46
  57. package/dist/{semaphore-server.d.ts → semaphore/server.d.ts} +12 -4
  58. package/dist/{semaphore-server.js → semaphore/server.js} +51 -24
  59. package/dist/{semaphore-store.d.ts → semaphore/store.d.ts} +8 -3
  60. package/dist/{semaphore-store.js → semaphore/store.js} +35 -33
  61. package/dist/{client.d.ts → socket/client.d.ts} +3 -3
  62. package/dist/{client.js → socket/client.js} +4 -4
  63. package/dist/{socket.d.ts → socket/index.d.ts} +15 -4
  64. package/dist/{socket.js → socket/index.js} +66 -20
  65. package/dist/socket/migrations.d.ts +9 -0
  66. package/dist/socket/migrations.js +57 -0
  67. package/dist/{socket-protocol.d.ts → socket/protocol.d.ts} +1 -1
  68. package/dist/storage.d.ts +4 -0
  69. package/dist/storage.js +13 -6
  70. package/dist/{topology-client.d.ts → topology/client.d.ts} +2 -2
  71. package/dist/{topology-client.js → topology/client.js} +3 -3
  72. package/dist/{topology.d.ts → topology/index.d.ts} +17 -7
  73. package/dist/{topology.js → topology/index.js} +92 -58
  74. package/dist/topology/migrations.d.ts +10 -0
  75. package/dist/topology/migrations.js +138 -0
  76. package/dist/{tracker.d.ts → tracker/index.d.ts} +3 -3
  77. package/dist/{tracker.js → tracker/index.js} +2 -2
  78. package/package.json +11 -11
  79. /package/dist/{stored-message.js → fanout/stored-message.js} +0 -0
  80. /package/dist/{routing-client.d.ts → routing/client.d.ts} +0 -0
  81. /package/dist/{load.js → routing/load.js} +0 -0
  82. /package/dist/{socket-protocol.js → socket/protocol.js} +0 -0
  83. /package/dist/{topology-snapshot.d.ts → topology/snapshot.d.ts} +0 -0
  84. /package/dist/{topology-snapshot.js → topology/snapshot.js} +0 -0
  85. /package/dist/{tracked-source.d.ts → tracker/source.d.ts} +0 -0
  86. /package/dist/{tracked-source.js → tracker/source.js} +0 -0
@@ -1,8 +1,8 @@
1
- import { type SerializedError } from './errors.js';
2
- import { type DurabilityLifecycleEvent, type Emit, type LifecycleEntity } from './lifecycle.js';
3
- import { type MigrationCapability } from './migrations.js';
4
- import { type AttemptPolicy } from './policy.js';
5
- import { type DurableTable } from './storage.js';
1
+ import { type SerializedError } from '../errors.js';
2
+ import { type DurabilityLifecycleEvent, type Emit, type LifecycleEntity } from '../lifecycle.js';
3
+ import { type MigrationCapability } from '../migrations.js';
4
+ import { type AttemptPolicy } from '../policy.js';
5
+ import { type DurableTable } from '../storage.js';
6
6
  import type { DurableMigrations } from '@durability/storage';
7
7
  /** The Durable Object state durability needs: storage plus optional `waitUntil`. */
8
8
  export type DurabilityContext = Pick<DurableObjectState, 'storage'> & Partial<Pick<DurableObjectState, 'waitUntil'>>;
@@ -47,8 +47,9 @@ export type DurabilitySchedulerConfig = DurabilitySchedulerOptions & {
47
47
  context: DurabilityContext;
48
48
  };
49
49
  /**
50
- * How a helper attaches to a scheduler: an existing shared one, or a private
51
- * one created from the Durable Object context with the given scheduler options.
50
+ * How a helper attaches to the object's scheduler: through a
51
+ * {@link DurabilityScheduler}, or from the Durable Object context, which joins
52
+ * the scheduler already there or creates it with the given options.
52
53
  */
53
54
  export type SchedulerAttachment = {
54
55
  scheduler: DurabilityScheduler;
@@ -62,6 +63,8 @@ export type Participant = {
62
63
  runDue(now: number, info: AlarmInvocationInfo | undefined): Promise<void>;
63
64
  /** Earliest due time, for tables without `status` and `next_attempt_at` columns. */
64
65
  nextPendingAt?(sql: SqlStorage): number | undefined;
66
+ /** Earliest work not already executing; active work still keeps its physical fallback. */
67
+ nextTimerAt?(sql: SqlStorage): number | undefined;
65
68
  /**
66
69
  * True while the participant runs its own due work from an alarm invocation
67
70
  * it keeps open. The in-memory timer then ignores its pending time, which only
@@ -69,6 +72,21 @@ export type Participant = {
69
72
  */
70
73
  holding?(): boolean;
71
74
  };
75
+ /** The channel every helper uses when it is not given one. */
76
+ export declare const defaultChannel = "default";
77
+ /**
78
+ * One helper instance's share of a table that several instances partition by
79
+ * a `channel` column. Each runs only its own channel's due rows.
80
+ */
81
+ export type ChannelParticipant = Participant & {
82
+ channel: string;
83
+ /** How errors name the helper, such as `An outbox`. */
84
+ helper: string;
85
+ /** Other tables carrying this capability's channel identity, such as its configuration. */
86
+ channelTables?: readonly string[];
87
+ };
88
+ /** Rejects a channel name a helper would otherwise store rows under. */
89
+ export declare const assertChannel: (helper: string, channel: unknown) => string;
72
90
  /**
73
91
  * Called after a record may have settled. Successful completions pass the
74
92
  * executed row because some tables delete it on success; other changes pass
@@ -114,23 +132,50 @@ export type ExecutionSpec = {
114
132
  */
115
133
  export declare class Engine {
116
134
  readonly sql: SqlStorage;
117
- private readonly context;
135
+ private context;
118
136
  private readonly storage;
119
- private readonly alarmConcurrency;
120
- private readonly alarmMinDelayMs;
121
- private readonly alarmHandoffMs;
122
- readonly liveTimers: boolean;
123
- private readonly onAlarmRetry;
137
+ private alarmConcurrency;
138
+ private alarmMinDelayMs;
139
+ private alarmHandoffMs;
140
+ liveTimers: boolean;
141
+ private onAlarmRetry;
142
+ private explicitOptions;
124
143
  private readonly participants;
144
+ private readonly channelsByTable;
145
+ private readonly claimedChannels;
146
+ private readonly reportedMissingChannels;
125
147
  private readonly migrated;
126
148
  private availablePermits;
127
149
  private readonly permitWaiters;
128
150
  private alarmRefresh;
151
+ private alarmRefreshRequested;
152
+ private failedRuns;
129
153
  private earlyAlarm;
130
154
  private readonly watchers;
131
155
  private readonly activeByTable;
132
156
  constructor(context: DurabilityContext, options: DurabilitySchedulerOptions);
157
+ /**
158
+ * Joins one more helper or scheduler handle to this object's scheduler. The
159
+ * first context that can `waitUntil` is kept, so a bare `{ storage }` context
160
+ * attached first does not hide it from the rest.
161
+ */
162
+ attach(context: DurabilityContext, options: DurabilitySchedulerOptions): void;
163
+ private configure;
133
164
  register(participant: Participant): void;
165
+ /** Reserves an instance identity, including for helpers that do not schedule work. */
166
+ claimChannel(kind: string, channel: string, helper: string): void;
167
+ /**
168
+ * Attaches one channel of a table several helper instances share. The first
169
+ * attachment registers the table; each run then runs every attached
170
+ * channel's due rows and retains the rows of channels nothing attached.
171
+ */
172
+ registerChannel(participant: ChannelParticipant): void;
173
+ /**
174
+ * Due rows of a channel no instance attached, such as one a deploy removed
175
+ * or a library not yet constructed, would keep the alarm awake forever. They
176
+ * are kept and looked at again later, since their owner may return.
177
+ */
178
+ private postponeUnattachedChannels;
134
179
  waitUntil(promise: Promise<unknown>, onError: (error: unknown) => void): void;
135
180
  /**
136
181
  * The owning Durable Object's ID. The public context type omits it, but the
@@ -155,7 +200,7 @@ export declare class Engine {
155
200
  /**
156
201
  * The earliest pending time for one participant: `physical` arms the physical
157
202
  * alarm (eviction fallback) and includes active work; `timer` drives the
158
- * in-memory timer and, under liveTimers, skips work that is already executing
203
+ * in-memory timer and skips work that is already executing
159
204
  * so a still-due active row cannot re-fire a zero-delay timer in a loop.
160
205
  */
161
206
  private pendingTimes;
@@ -165,7 +210,7 @@ export declare class Engine {
165
210
  */
166
211
  private reconcile;
167
212
  private scheduleEarlyAlarm;
168
- /** Coalesces concurrent refresh requests into one reconciliation transaction. */
213
+ /** Coalesces refreshes without dropping requests arriving after the pending-work read. */
169
214
  scheduleNextAlarm(): Promise<void>;
170
215
  /**
171
216
  * Aborts matching active handlers, then deletes one kind's records created
@@ -186,6 +231,13 @@ export declare class Engine {
186
231
  * because the platform drops an alarm after a few failed deliveries.
187
232
  */
188
233
  alarm(info?: AlarmInvocationInfo): Promise<void>;
234
+ /**
235
+ * A transient storage fault would otherwise leave all due work to the
236
+ * fallback alarm, up to `alarmMinDelayMs` away: longer than a holder's
237
+ * grant window, for one. The in-memory timer retries sooner, backing off to
238
+ * that fallback while runs keep failing.
239
+ */
240
+ private retryFailedRun;
189
241
  private notifyAlarmRetry;
190
242
  /**
191
243
  * Runs every participant's due work, hands off to a fresh alarm if the
@@ -205,13 +257,14 @@ export declare class Engine {
205
257
  private settleFailure;
206
258
  }
207
259
  /**
208
- * Owns the Durable Object's physical alarm, storage, and concurrency
209
- * pool so {@link Durability} and {@link DurabilityAlarms} can share them.
260
+ * Owns the Durable Object's physical alarm, storage, and concurrency pool so
261
+ * every durability helper on the object shares them.
210
262
  *
211
- * Construct one per Durable Object when using both helpers, pass it to each,
212
- * and delegate the object's `alarm` method to {@link DurabilityScheduler.alarm}.
213
- * A helper constructed directly from the Durable Object context creates a
214
- * private scheduler instead.
263
+ * A Durable Object has one scheduler. Constructing another for the same
264
+ * object, or a helper from the object's context, joins it; scheduler options
265
+ * merge, and a different value for an option already set throws. Delegate the
266
+ * object's `alarm` method to {@link DurabilityScheduler.alarm} or to any
267
+ * helper's `alarm`: each runs the due work of every helper on the object.
215
268
  *
216
269
  * @example
217
270
  * ```ts
@@ -237,8 +290,5 @@ export declare class DurabilityScheduler {
237
290
  /** Runs due work for every attached helper and re-arms the physical alarm. */
238
291
  alarm(info?: AlarmInvocationInfo): Promise<void>;
239
292
  }
240
- /**
241
- * Resolves the engine a helper should attach to: the shared one behind a
242
- * scheduler, or a private one built from the Durable Object context.
243
- */
293
+ /** Resolves the engine a helper attaches to: the object's one scheduler. */
244
294
  export declare const engineFor: (attachment: SchedulerAttachment) => Engine;