durability 5.0.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 (89) hide show
  1. package/README.md +238 -7
  2. package/dist/{durability-alarms.d.ts → alarms/index.d.ts} +23 -6
  3. package/dist/{durability-alarms.js → alarms/index.js} +96 -52
  4. package/dist/alarms/migrations.d.ts +9 -0
  5. package/dist/alarms/migrations.js +133 -0
  6. package/dist/errors.d.ts +15 -0
  7. package/dist/errors.js +24 -0
  8. package/dist/experimental.d.ts +11 -8
  9. package/dist/experimental.js +8 -5
  10. package/dist/{fanout.d.ts → fanout/index.d.ts} +13 -6
  11. package/dist/{fanout.js → fanout/index.js} +55 -49
  12. package/dist/fanout/migrations.d.ts +9 -0
  13. package/dist/fanout/migrations.js +181 -0
  14. package/dist/{stored-message.d.ts → fanout/stored-message.d.ts} +1 -1
  15. package/dist/index.d.ts +14 -9
  16. package/dist/index.js +13 -8
  17. package/dist/{log.d.ts → log/index.d.ts} +15 -3
  18. package/dist/{log.js → log/index.js} +152 -124
  19. package/dist/log/migrations.d.ts +18 -0
  20. package/dist/log/migrations.js +297 -0
  21. package/dist/{memoize.d.ts → memoize/index.d.ts} +1 -1
  22. package/dist/{memoize.js → memoize/index.js} +14 -11
  23. package/dist/memoize/migrations.d.ts +10 -0
  24. package/dist/memoize/migrations.js +21 -0
  25. package/dist/migrations.d.ts +1 -103
  26. package/dist/migrations.js +1 -570
  27. package/dist/{durability.d.ts → operations/index.d.ts} +13 -5
  28. package/dist/{durability.js → operations/index.js} +63 -46
  29. package/dist/operations/migrations.d.ts +10 -0
  30. package/dist/operations/migrations.js +150 -0
  31. package/dist/{outbox.d.ts → outbox/index.d.ts} +4 -4
  32. package/dist/{outbox.js → outbox/index.js} +18 -63
  33. package/dist/outbox/migrations.d.ts +9 -0
  34. package/dist/outbox/migrations.js +43 -0
  35. package/dist/{routing-client.js → routing/client.js} +1 -1
  36. package/dist/{routing.d.ts → routing/index.d.ts} +3 -3
  37. package/dist/{routing.js → routing/index.js} +3 -3
  38. package/dist/{load.d.ts → routing/load.d.ts} +1 -1
  39. package/dist/schedule/index.d.ts +165 -0
  40. package/dist/schedule/index.js +667 -0
  41. package/dist/schedule/migrations.d.ts +9 -0
  42. package/dist/schedule/migrations.js +118 -0
  43. package/dist/{scheduler.d.ts → scheduler/index.d.ts} +122 -22
  44. package/dist/scheduler/index.js +925 -0
  45. package/dist/{semaphore-client.d.ts → semaphore/client.d.ts} +1 -1
  46. package/dist/{semaphore-client.js → semaphore/client.js} +2 -2
  47. package/dist/{semaphore.d.ts → semaphore/index.d.ts} +10 -10
  48. package/dist/{semaphore.js → semaphore/index.js} +7 -7
  49. package/dist/{semaphore-leases.d.ts → semaphore/leases.d.ts} +17 -6
  50. package/dist/{semaphore-leases.js → semaphore/leases.js} +28 -12
  51. package/dist/semaphore/migrations.d.ts +18 -0
  52. package/dist/semaphore/migrations.js +444 -0
  53. package/dist/{semaphore-protocol.d.ts → semaphore/protocol.d.ts} +16 -8
  54. package/dist/{semaphore-protocol.js → semaphore/protocol.js} +37 -14
  55. package/dist/{semaphore-queue-store.d.ts → semaphore/queue-store.d.ts} +12 -6
  56. package/dist/{semaphore-queue-store.js → semaphore/queue-store.js} +87 -75
  57. package/dist/{semaphore-queue.d.ts → semaphore/queue.d.ts} +15 -5
  58. package/dist/{semaphore-queue.js → semaphore/queue.js} +105 -46
  59. package/dist/{semaphore-server.d.ts → semaphore/server.d.ts} +12 -4
  60. package/dist/{semaphore-server.js → semaphore/server.js} +51 -24
  61. package/dist/{semaphore-store.d.ts → semaphore/store.d.ts} +8 -3
  62. package/dist/{semaphore-store.js → semaphore/store.js} +35 -33
  63. package/dist/{client.d.ts → socket/client.d.ts} +3 -3
  64. package/dist/{client.js → socket/client.js} +4 -4
  65. package/dist/{socket.d.ts → socket/index.d.ts} +15 -4
  66. package/dist/{socket.js → socket/index.js} +66 -20
  67. package/dist/socket/migrations.d.ts +9 -0
  68. package/dist/socket/migrations.js +57 -0
  69. package/dist/{socket-protocol.d.ts → socket/protocol.d.ts} +1 -1
  70. package/dist/storage.d.ts +9 -2
  71. package/dist/storage.js +24 -11
  72. package/dist/{topology-client.d.ts → topology/client.d.ts} +2 -2
  73. package/dist/{topology-client.js → topology/client.js} +3 -3
  74. package/dist/{topology.d.ts → topology/index.d.ts} +17 -7
  75. package/dist/{topology.js → topology/index.js} +92 -58
  76. package/dist/topology/migrations.d.ts +10 -0
  77. package/dist/topology/migrations.js +138 -0
  78. package/dist/{tracker.d.ts → tracker/index.d.ts} +3 -3
  79. package/dist/{tracker.js → tracker/index.js} +2 -2
  80. package/package.json +11 -11
  81. package/dist/scheduler.js +0 -577
  82. /package/dist/{stored-message.js → fanout/stored-message.js} +0 -0
  83. /package/dist/{routing-client.d.ts → routing/client.d.ts} +0 -0
  84. /package/dist/{load.js → routing/load.js} +0 -0
  85. /package/dist/{socket-protocol.js → socket/protocol.js} +0 -0
  86. /package/dist/{topology-snapshot.d.ts → topology/snapshot.d.ts} +0 -0
  87. /package/dist/{topology-snapshot.js → topology/snapshot.js} +0 -0
  88. /package/dist/{tracked-source.d.ts → tracker/source.d.ts} +0 -0
  89. /package/dist/{tracked-source.js → tracker/source.js} +0 -0
@@ -1,8 +1,8 @@
1
1
  import { createTransformStub, } from '@durability/transforms';
2
- import { resolveNamespace, } from './durable-object-target.js';
3
- import { RoutingError } from './errors.js';
2
+ import { resolveNamespace, } from '../durable-object-target.js';
3
+ import { RoutingError } from '../errors.js';
4
4
  import { RoutingLoad } from './load.js';
5
- import { RoutingClient } from './routing-client.js';
5
+ import { RoutingClient } from './client.js';
6
6
  /**
7
7
  * Inside a DO, attach this local load observer to a fanout capability. Outside
8
8
  * the DO, client() routes calls to an application-owned class using ordinary
@@ -1,4 +1,4 @@
1
- import type { SerializedError } from './errors.js';
1
+ import type { SerializedError } from '../errors.js';
2
2
  /** Completion counts and timings cover the same rolling observation window. */
3
3
  export type ProcessingLoad = {
4
4
  inFlight: number;
@@ -0,0 +1,165 @@
1
+ import { type SerializedError } from '../errors.js';
2
+ import { type DurabilityMigrationResult } from '../migrations.js';
3
+ import { type DurabilityRetryOptions } from '../policy.js';
4
+ import { type SchedulerAttachment } from '../scheduler/index.js';
5
+ /** A schedule as passed to {@link DurabilitySchedule.set}. */
6
+ export type ScheduleDefinition = {
7
+ /** Opaque to durability: only `nextOccurrence` interprets it. */
8
+ expression: string;
9
+ /**
10
+ * Orders updates: `set` stores only a version higher than the stored one,
11
+ * and the same version only re-arms a lost alarm.
12
+ */
13
+ version: number;
14
+ /**
15
+ * Delays every tick by one fixed offset after its nominal time, to spread
16
+ * objects that share an expression. A number is the offset; `{ maxMs }`
17
+ * picks one uniformly in `[0, maxMs]` when the version is stored, so
18
+ * resending that version keeps it. Defaults to 0, at most 2^31 - 1. Keep
19
+ * it below the expression's interval.
20
+ */
21
+ jitterMs?: number | {
22
+ maxMs: number;
23
+ };
24
+ };
25
+ /** The stored schedule returned by {@link DurabilitySchedule.get}. */
26
+ export type ScheduleState = {
27
+ expression: string;
28
+ version: number;
29
+ /** The stored offset, including one picked from `{ maxMs }`. */
30
+ jitterMs: number;
31
+ /**
32
+ * The next tick's nominal time, or `undefined` once `nextOccurrence`
33
+ * returned none. It fires at `nextAt + jitterMs`.
34
+ */
35
+ nextAt: number | undefined;
36
+ };
37
+ /** One tick's run. */
38
+ export type ScheduledRun = {
39
+ /** The tick's nominal time, as `nextOccurrence` returned it. */
40
+ scheduledTime: number;
41
+ /**
42
+ * When the tick fired: `scheduledTime` plus the schedule's `jitterMs`. A run
43
+ * that waited for a slot starts later.
44
+ */
45
+ dueAt: number;
46
+ /**
47
+ * `<objectId>:<scheduledTime>`, or the bare scheduled time when the context
48
+ * has no object ID. A named channel appends `:` and its JSON-encoded name.
49
+ * A tick fires at most once per channel, so the key is unique per run.
50
+ */
51
+ idempotencyKey: string;
52
+ };
53
+ /** What `run` receives. */
54
+ export type ScheduledRunContext = ScheduledRun & {
55
+ /** Aborted when the run exceeds `runTimeoutMs`. */
56
+ signal: AbortSignal;
57
+ };
58
+ /** What a run ended with, as passed to `onOutcome`. */
59
+ export type ScheduledRunOutcome = {
60
+ status: 'complete';
61
+ } | {
62
+ status: 'errored';
63
+ error: SerializedError;
64
+ };
65
+ /** The run an `onOutcome` call reports. */
66
+ export type ScheduledOutcomeDelivery = ScheduledRun & {
67
+ /** One-based delivery attempt of this outcome. */
68
+ attempt: number;
69
+ };
70
+ type ScheduledRunEntity = {
71
+ entityKind: 'scheduled_run';
72
+ /** The run's idempotency key. */
73
+ id: string;
74
+ scheduledTime: number;
75
+ timestamp: number;
76
+ };
77
+ /** Best-effort lifecycle signal for one scheduled run. */
78
+ export type DurabilityScheduleEvent = ScheduledRunEntity & ({
79
+ /** A tick recorded the run; `queued` when no run slot was free. */
80
+ type: 'due';
81
+ queued: boolean;
82
+ } | {
83
+ type: 'started';
84
+ } | {
85
+ /**
86
+ * The outcome was recorded. An interrupted run has no `durationMs` and
87
+ * a `ScheduledRunInterruptedError`.
88
+ */
89
+ type: 'settled';
90
+ outcome: ScheduledRunOutcome['status'];
91
+ error?: SerializedError;
92
+ durationMs?: number;
93
+ } | {
94
+ type: 'outcome_retry';
95
+ attempt: number;
96
+ error: SerializedError;
97
+ nextAttemptAt: number;
98
+ } | {
99
+ /** `onOutcome` failed `maxAttempts` times; the run's row is deleted. */
100
+ type: 'dead_lettered';
101
+ attempt: number;
102
+ error: SerializedError;
103
+ });
104
+ export type DurabilityScheduleConfig = SchedulerAttachment & {
105
+ /**
106
+ * Stable channel ID. Instances on one scheduler share storage, partitioned
107
+ * by channel; each has its own schedule, runs and hooks. A library should
108
+ * use its own channel so its schedule never meets the application's.
109
+ * Defaults to `default`.
110
+ */
111
+ channel?: string;
112
+ /**
113
+ * Returns the first tick strictly after `after`, or `undefined` for none.
114
+ * Must be synchronous and deterministic; durability ships no cron parser.
115
+ */
116
+ nextOccurrence(expression: string, after: number): number | undefined;
117
+ /** The work of one tick. Throwing or timing out makes the run `errored`. */
118
+ run(run: ScheduledRunContext): unknown;
119
+ /**
120
+ * Receives each run's outcome at least once. Returning acknowledges it and
121
+ * deletes the run's row; throwing retries it with `outcomeRetries`.
122
+ */
123
+ onOutcome(run: ScheduledOutcomeDelivery, outcome: ScheduledRunOutcome): unknown;
124
+ /** Runs in flight at once; later runs wait durably in order. Defaults to 10. */
125
+ maxConcurrentRuns?: number;
126
+ /** Maximum duration of one run. Defaults to 15 minutes. */
127
+ runTimeoutMs?: number;
128
+ /** Maximum duration of one `onOutcome` call. Defaults to 60 seconds. */
129
+ outcomeTimeoutMs?: number;
130
+ /** `onOutcome` retries. `maxAttempts` defaults to 10, counting the first. */
131
+ outcomeRetries?: DurabilityRetryOptions;
132
+ onLifecycleEvent?: (event: DurabilityScheduleEvent) => void | Promise<void>;
133
+ };
134
+ /**
135
+ * Experimental. One recurring schedule per channel of a Durable Object whose
136
+ * ticks start individually tracked, overlapping runs and report each run's
137
+ * outcome once, keeping a run's row only until its outcome is delivered.
138
+ *
139
+ * A tick inserts its run in the transaction that advances the stored next
140
+ * tick, so a tick fires at most once without retaining finished runs. Missed
141
+ * ticks collapse into one run for the earliest missed time.
142
+ */
143
+ export declare class DurabilitySchedule {
144
+ #private;
145
+ constructor(config: DurabilityScheduleConfig);
146
+ static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
147
+ alarm(info?: AlarmInvocationInfo): Promise<void>;
148
+ /** The stored schedule, or `undefined` when none is set or it was cancelled. */
149
+ get(): ScheduleState | undefined;
150
+ /**
151
+ * Stores the schedule and its next tick when `version` is higher than the
152
+ * stored one, and resolves `true` when it did. A lower version is ignored; the
153
+ * same version changes nothing, keeping its stored jitter, but re-arms the
154
+ * alarm if it was lost.
155
+ */
156
+ set(definition: ScheduleDefinition): Promise<boolean>;
157
+ /**
158
+ * Stops future ticks and resolves `true` when a schedule was live. Runs
159
+ * already due or running still finish and report. With `version`, the
160
+ * cancellation is ignored when the stored version is higher, and is
161
+ * otherwise recorded so a later `set` of that version or lower is ignored.
162
+ */
163
+ cancel(version?: number): Promise<boolean>;
164
+ }
165
+ export {};