durability 3.0.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,13 +9,54 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
12
+ var _DurabilityAlarmsCore_instances, _DurabilityAlarmsCore_engine, _DurabilityAlarmsCore_handlers, _DurabilityAlarmsCore_policy, _DurabilityAlarmsCore_lifecycle, _DurabilityAlarmsCore_emit, _DurabilityAlarmsCore_active, _DurabilityAlarmsCore_trackedSource, _DurabilityAlarmsCore_runDue, _DurabilityAlarmsCore_schedule, _DurabilityAlarmsCore_execute;
13
13
  import { z } from 'zod';
14
14
  import { DurableAlarmTimeoutError, DurableAttemptsExhaustedError, isErrorInstance, NonRetryableError, } from './errors.js';
15
+ import { createLifecycleHooks, } from './lifecycle.js';
15
16
  import { durabilityNamedAlarmMigrations, migrate, } from './migrations.js';
16
17
  import { alarmMethodOptionsSchema, createPolicyResolver, } from './policy.js';
17
18
  import { engineFor, } from './scheduler.js';
19
+ import { deleteAttempt, listCreated } from './storage.js';
20
+ import { registerTrackedSource, } from './tracked-source.js';
21
+ const alarmRowSchema = z.object({
22
+ name: z.string(),
23
+ generation_id: z.string(),
24
+ status: z.enum(['pending', 'failed']),
25
+ scheduled_at: z.number().int().nonnegative(),
26
+ next_attempt_at: z.number().int().nonnegative(),
27
+ attempt: z.number().int().nonnegative(),
28
+ last_error: z.string().nullable(),
29
+ last_error_name: z.string().nullable(),
30
+ created_at: z.number().int().nonnegative(),
31
+ });
32
+ const alarmsTable = { name: 'durability_alarms', key: 'name' };
18
33
  const alarmHandlerSchema = z.custom((value) => typeof value === 'function');
34
+ const readAlarm = (sql, name) => alarmRowSchema
35
+ .optional()
36
+ .parse(sql
37
+ .exec('SELECT * FROM durability_alarms WHERE name = ?', name)
38
+ .toArray()[0]);
39
+ const alarmRecord = (row) => ({
40
+ id: row.name,
41
+ name: row.name,
42
+ generation: row.generation_id,
43
+ createdAt: row.created_at,
44
+ state: row.status === 'pending'
45
+ ? {
46
+ status: 'pending',
47
+ attempt: row.attempt,
48
+ nextAttemptAt: row.next_attempt_at,
49
+ lastError: row.last_error,
50
+ }
51
+ : {
52
+ status: 'failed',
53
+ attempt: row.attempt,
54
+ error: {
55
+ name: row.last_error_name ?? 'Error',
56
+ message: row.last_error ?? 'Durable alarm failed',
57
+ },
58
+ },
59
+ });
19
60
  const alarmEntity = (row) => ({
20
61
  entityKind: 'named_alarm',
21
62
  alarm: row.name,
@@ -28,12 +69,14 @@ class DurabilityAlarmsCore {
28
69
  _DurabilityAlarmsCore_engine.set(this, void 0);
29
70
  _DurabilityAlarmsCore_handlers.set(this, void 0);
30
71
  _DurabilityAlarmsCore_policy.set(this, void 0);
72
+ _DurabilityAlarmsCore_lifecycle.set(this, void 0);
31
73
  _DurabilityAlarmsCore_emit.set(this, void 0);
32
74
  _DurabilityAlarmsCore_active.set(this, new Map());
33
75
  __classPrivateFieldSet(this, _DurabilityAlarmsCore_engine, engineFor(config), "f");
34
76
  __classPrivateFieldSet(this, _DurabilityAlarmsCore_handlers, new Map(Object.entries(config.handlers).map(([name, handler]) => [name, alarmHandlerSchema.parse(handler)])), "f");
35
77
  __classPrivateFieldSet(this, _DurabilityAlarmsCore_policy, createPolicyResolver(config, config.methods ?? {}, alarmMethodOptionsSchema), "f");
36
- __classPrivateFieldSet(this, _DurabilityAlarmsCore_emit, __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").emitter(config.onLifecycleEvent), "f");
78
+ __classPrivateFieldSet(this, _DurabilityAlarmsCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
79
+ __classPrivateFieldSet(this, _DurabilityAlarmsCore_emit, __classPrivateFieldGet(this, _DurabilityAlarmsCore_lifecycle, "f").emit, "f");
37
80
  const reserved = new Set(Object.getOwnPropertyNames(DurabilityAlarmsCore.prototype));
38
81
  for (const name of __classPrivateFieldGet(this, _DurabilityAlarmsCore_handlers, "f").keys()) {
39
82
  if (reserved.has(name)) {
@@ -46,9 +89,10 @@ class DurabilityAlarmsCore {
46
89
  }
47
90
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").migrateSchema('namedAlarms', durabilityNamedAlarmMigrations);
48
91
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").register({
49
- kind: 'alarms',
92
+ table: alarmsTable,
50
93
  runDue: (now, info) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_runDue).call(this, now, info),
51
94
  });
95
+ registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityAlarmsCore_instances, "m", _DurabilityAlarmsCore_trackedSource).call(this));
52
96
  }
53
97
  /** Applies or reverts the `durability_alarms` schema; see {@link migrate}. */
54
98
  static migrate(context, target) {
@@ -58,12 +102,19 @@ class DurabilityAlarmsCore {
58
102
  alarm(info) {
59
103
  return __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").alarm(info);
60
104
  }
105
+ /**
106
+ * Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
107
+ * returns a function that detaches it.
108
+ */
109
+ lifecycle(hook) {
110
+ return __classPrivateFieldGet(this, _DurabilityAlarmsCore_lifecycle, "f").add(hook);
111
+ }
61
112
  /**
62
113
  * Destructively removes named alarm records created strictly before the
63
114
  * timestamp, regardless of status, and returns how many were removed.
64
115
  */
65
116
  async purgeBefore(before) {
66
- const count = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").purge('alarms', before, __classPrivateFieldGet(this, _DurabilityAlarmsCore_active, "f"), 'Durable alarm was purged');
117
+ const count = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").purge(alarmsTable, before, __classPrivateFieldGet(this, _DurabilityAlarmsCore_active, "f"), 'Durable alarm was purged');
67
118
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f").call(this, {
68
119
  type: 'purged',
69
120
  entityKind: 'named_alarm',
@@ -74,8 +125,49 @@ class DurabilityAlarmsCore {
74
125
  return count;
75
126
  }
76
127
  }
77
- _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = new WeakMap(), _DurabilityAlarmsCore_policy = new WeakMap(), _DurabilityAlarmsCore_emit = new WeakMap(), _DurabilityAlarmsCore_active = new WeakMap(), _DurabilityAlarmsCore_instances = new WeakSet(), _DurabilityAlarmsCore_runDue = async function _DurabilityAlarmsCore_runDue(now, info) {
78
- const due = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").storage.alarms.listDue(now, 100);
128
+ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = new WeakMap(), _DurabilityAlarmsCore_policy = new WeakMap(), _DurabilityAlarmsCore_lifecycle = new WeakMap(), _DurabilityAlarmsCore_emit = new WeakMap(), _DurabilityAlarmsCore_active = new WeakMap(), _DurabilityAlarmsCore_instances = new WeakSet(), _DurabilityAlarmsCore_trackedSource = function _DurabilityAlarmsCore_trackedSource() {
129
+ const sql = __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql;
130
+ return {
131
+ get: async (name) => {
132
+ const row = readAlarm(sql, name);
133
+ return row && alarmRecord(row);
134
+ },
135
+ list: async ({ limit, cursor, status, name }) => {
136
+ const page = listCreated(sql, alarmsTable, 'name', {
137
+ limit,
138
+ after: cursor,
139
+ status,
140
+ name,
141
+ });
142
+ const records = alarmRowSchema
143
+ .array()
144
+ .parse(page.rows)
145
+ .map(alarmRecord);
146
+ return page.next === undefined
147
+ ? { records }
148
+ : { records, cursor: page.next };
149
+ },
150
+ watch: (name, listener) => __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").watch(alarmsTable, name, (completed) => {
151
+ if (!completed) {
152
+ listener();
153
+ return;
154
+ }
155
+ listener({
156
+ id: name,
157
+ name,
158
+ generation: completed.generation_id,
159
+ createdAt: completed.created_at,
160
+ state: { status: 'completed', result: undefined },
161
+ });
162
+ }),
163
+ };
164
+ }, _DurabilityAlarmsCore_runDue = async function _DurabilityAlarmsCore_runDue(now, info) {
165
+ const due = alarmRowSchema.array().parse(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql
166
+ .exec(`SELECT * FROM durability_alarms
167
+ WHERE status = 'pending' AND next_attempt_at <= ?
168
+ ORDER BY next_attempt_at ASC
169
+ LIMIT 100`, now)
170
+ .toArray());
79
171
  const failures = [];
80
172
  await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").runConcurrent(due, async (row) => {
81
173
  try {
@@ -94,20 +186,23 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
94
186
  }
95
187
  const generation = crypto.randomUUID();
96
188
  const createdAt = Date.now();
97
- await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").transaction(async (transaction) => {
98
- await transaction.alarms.upsert({
99
- name,
100
- generation_id: generation,
101
- status: 'pending',
102
- scheduled_at: scheduledTime,
103
- next_attempt_at: scheduledTime,
104
- attempt: 0,
105
- last_error: null,
106
- last_error_name: null,
107
- created_at: createdAt,
108
- });
109
- await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").reconcile(transaction);
189
+ await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").transaction((sql) => {
190
+ sql.exec(`INSERT INTO durability_alarms
191
+ (name, generation_id, status, scheduled_at, next_attempt_at,
192
+ attempt, last_error, last_error_name, created_at)
193
+ VALUES (?, ?, 'pending', ?, ?, 0, NULL, NULL, ?)
194
+ ON CONFLICT(name) DO UPDATE SET
195
+ generation_id = excluded.generation_id,
196
+ status = excluded.status,
197
+ scheduled_at = excluded.scheduled_at,
198
+ next_attempt_at = excluded.next_attempt_at,
199
+ attempt = excluded.attempt,
200
+ last_error = excluded.last_error,
201
+ last_error_name = excluded.last_error_name,
202
+ created_at = excluded.created_at`, name, generation, scheduledTime, scheduledTime, createdAt);
110
203
  });
204
+ // A waiter on the replaced occurrence resolves now instead of at its timeout.
205
+ __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").notify(alarmsTable, name);
111
206
  __classPrivateFieldGet(this, _DurabilityAlarmsCore_emit, "f").call(this, {
112
207
  type: 'scheduled',
113
208
  entityKind: 'named_alarm',
@@ -126,7 +221,7 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
126
221
  const policy = __classPrivateFieldGet(this, _DurabilityAlarmsCore_policy, "f").call(this, row.name);
127
222
  const retryTimeouts = policy.method?.retryTimeouts ?? false;
128
223
  return __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").startExecution({
129
- kind: 'alarms',
224
+ table: alarmsTable,
130
225
  key: row.name,
131
226
  row,
132
227
  label: `named alarm "${row.name}"`,
@@ -152,9 +247,13 @@ _DurabilityAlarmsCore_engine = new WeakMap(), _DurabilityAlarmsCore_handlers = n
152
247
  platform,
153
248
  });
154
249
  },
155
- complete: async (_result, attempt) => {
250
+ complete: (_result, attempt) => {
156
251
  const timestamp = Date.now();
157
- const removed = await __classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").storage.alarms.remove(row.name, row.generation_id, attempt);
252
+ const removed = deleteAttempt(__classPrivateFieldGet(this, _DurabilityAlarmsCore_engine, "f").sql, alarmsTable, {
253
+ key: row.name,
254
+ generation: row.generation_id,
255
+ attempt,
256
+ });
158
257
  return removed ? timestamp : undefined;
159
258
  },
160
259
  isTerminal: (error) => isErrorInstance(error, DurableAlarmTimeoutError) && !retryTimeouts,
@@ -1,4 +1,4 @@
1
- import { type LifecycleHook } from './lifecycle.js';
1
+ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
2
2
  import { type DurabilityMigrationResult } from './migrations.js';
3
3
  import { type DurabilityMethodOptions, type ExecutionPolicyOptions } from './policy.js';
4
4
  import { type SchedulerAttachment } from './scheduler.js';
@@ -32,6 +32,10 @@ export type DurableHandler<Payload, Result> = (call: DurableCall<Payload>) => Re
32
32
  export type HandlerMap = Record<string, (...args: never[]) => unknown>;
33
33
  type HandlerPayload<Handler> = Handler extends (call: DurableCall<infer Payload>) => unknown ? Payload : never;
34
34
  type HandlerResult<Handler> = Handler extends (...args: never[]) => infer Result ? Awaited<Result> : never;
35
+ /** Result types of every operation, keyed by handler name. */
36
+ export type OperationResults<Handlers extends HandlerMap> = {
37
+ [Operation in Extract<keyof Handlers, string>]: HandlerResult<Handlers[Operation]>;
38
+ };
35
39
  type DurableOperationInput<Handler> = {
36
40
  /** Stable idempotency key used to deduplicate the operation. */
37
41
  id: string;
@@ -72,6 +76,26 @@ export type DurableOperationResult<Result> = {
72
76
  /** The handler's persisted return value. */
73
77
  result: Result;
74
78
  };
79
+ type OperationEvent = Extract<DurabilityLifecycleEvent, {
80
+ entityKind: 'operation';
81
+ }>;
82
+ type TypedOperationEvent<Operation extends string, Result> = OperationEvent extends infer Event ? Event extends {
83
+ outcome: 'completed';
84
+ } ? Omit<Event, 'operation' | 'result'> & {
85
+ operation: Operation;
86
+ result: Result;
87
+ } : Event extends object ? Omit<Event, 'operation'> & {
88
+ operation: Operation;
89
+ } : never : never;
90
+ /**
91
+ * A lifecycle event for one of this instance's operations. Completed events
92
+ * carry the handler's typed result.
93
+ */
94
+ export type DurabilityOperationEvent<Handlers extends HandlerMap> = {
95
+ [Operation in Extract<keyof Handlers, string>]: TypedOperationEvent<Operation, HandlerResult<Handlers[Operation]>>;
96
+ }[Extract<keyof Handlers, string>] | Extract<DurabilityLifecycleEvent, {
97
+ type: 'purged';
98
+ }>;
75
99
  /** Registers calls for one handler and reads their persisted results. */
76
100
  export type DurableOperation<Handler> = ((input: DurableOperationInput<Handler>) => Promise<void>) & {
77
101
  /** Reads the persisted state for an idempotency key. */
@@ -113,6 +137,11 @@ declare class DurabilityCore<Handlers extends HandlerMap> {
113
137
  static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): DurabilityMigrationResult;
114
138
  /** Processes due operations and re-arms the physical alarm. */
115
139
  alarm(info?: AlarmInvocationInfo): Promise<void>;
140
+ /**
141
+ * Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
142
+ * returns a function that detaches it.
143
+ */
144
+ lifecycle(hook: (event: DurabilityOperationEvent<Handlers>) => void | Promise<void>): () => void;
116
145
  /**
117
146
  * Destructively removes operation records created strictly before the
118
147
  * timestamp, regardless of status, and returns how many were removed.
@@ -150,6 +179,8 @@ type OperationMethods<Handlers extends HandlerMap> = {
150
179
  * ```
151
180
  */
152
181
  export type Durability<Handlers extends HandlerMap> = DurabilityCore<Handlers> & OperationMethods<Handlers>;
182
+ /** Any `Durability` instance, without the index signature of `Durability<HandlerMap>`. */
183
+ export type AnyDurability = DurabilityCore<HandlerMap>;
153
184
  export interface DurabilityConstructor {
154
185
  new <Handlers extends HandlerMap>(config: DurabilityConfig<Handlers>): Durability<Handlers>;
155
186
  migrate: typeof DurabilityCore.migrate;
@@ -9,17 +9,70 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
12
+ var _DurabilityCore_instances, _DurabilityCore_engine, _DurabilityCore_handlers, _DurabilityCore_policy, _DurabilityCore_lifecycle, _DurabilityCore_emit, _DurabilityCore_active, _DurabilityCore_executionStarts, _DurabilityCore_trackedSource, _DurabilityCore_runDue, _DurabilityCore_getResult, _DurabilityCore_run, _DurabilityCore_execute, _DurabilityCore_start;
13
+ import { z } from 'zod';
13
14
  import { DuplicateDurableCallError, DurableAttemptsExhaustedError, DurableAttemptTimeoutError, DurableResultSerializationError, isErrorInstance, NonRetryableError, reportFailure, } from './errors.js';
15
+ import { createLifecycleHooks, } from './lifecycle.js';
14
16
  import { durabilityOperationMigrations, migrate, } from './migrations.js';
15
17
  import { createPolicyResolver, methodOptionsSchema, } from './policy.js';
16
18
  import { engineFor, } from './scheduler.js';
17
19
  import { deserialize, serialize } from './serialization.js';
20
+ import { listCreated, updateAttempt } from './storage.js';
21
+ import { registerTrackedSource, } from './tracked-source.js';
22
+ const callRowSchema = z.object({
23
+ id: z.string(),
24
+ operation: z.string(),
25
+ payload: z.string(),
26
+ status: z.enum(['pending', 'completed', 'failed']),
27
+ result: z.string().nullable(),
28
+ attempt: z.number().int().nonnegative(),
29
+ next_attempt_at: z.number().int().nonnegative(),
30
+ last_error: z.string().nullable(),
31
+ last_error_name: z.string().nullable(),
32
+ completed_at: z.number().int().nonnegative().nullable(),
33
+ created_at: z.number().int().nonnegative(),
34
+ generation_id: z.string(),
35
+ });
36
+ const callsTable = { name: 'durability_calls', key: 'id' };
37
+ const readCall = (sql, id) => callRowSchema
38
+ .optional()
39
+ .parse(sql.exec('SELECT * FROM durability_calls WHERE id = ?', id).toArray()[0]);
18
40
  const assertOperation = (id, existingOperation, requestedOperation) => {
19
41
  if (existingOperation !== requestedOperation) {
20
42
  throw new DuplicateDurableCallError(id, existingOperation, requestedOperation);
21
43
  }
22
44
  };
45
+ const callState = (call) => {
46
+ if (call.status === 'pending') {
47
+ return {
48
+ status: 'pending',
49
+ attempt: call.attempt,
50
+ nextAttemptAt: call.next_attempt_at,
51
+ lastError: call.last_error,
52
+ };
53
+ }
54
+ if (call.status === 'failed') {
55
+ return {
56
+ status: 'failed',
57
+ attempt: call.attempt,
58
+ error: {
59
+ name: call.last_error_name ?? 'Error',
60
+ message: call.last_error ?? 'Durable operation failed',
61
+ },
62
+ };
63
+ }
64
+ if (call.result === null) {
65
+ throw new Error(`Completed durable call "${call.id}" has no result`);
66
+ }
67
+ return { status: 'completed', result: deserialize(call.result) };
68
+ };
69
+ const callRecord = (call) => ({
70
+ id: call.id,
71
+ name: call.operation,
72
+ generation: call.generation_id,
73
+ createdAt: call.created_at,
74
+ state: callState(call),
75
+ });
23
76
  const operationEntity = (call) => ({
24
77
  entityKind: 'operation',
25
78
  operation: call.operation,
@@ -32,6 +85,7 @@ class DurabilityCore {
32
85
  _DurabilityCore_engine.set(this, void 0);
33
86
  _DurabilityCore_handlers.set(this, void 0);
34
87
  _DurabilityCore_policy.set(this, void 0);
88
+ _DurabilityCore_lifecycle.set(this, void 0);
35
89
  _DurabilityCore_emit.set(this, void 0);
36
90
  _DurabilityCore_active.set(this, new Map());
37
91
  _DurabilityCore_executionStarts.set(this, new Map());
@@ -39,7 +93,8 @@ class DurabilityCore {
39
93
  __classPrivateFieldSet(this, _DurabilityCore_engine, engineFor(config), "f");
40
94
  __classPrivateFieldSet(this, _DurabilityCore_handlers, handlers, "f");
41
95
  __classPrivateFieldSet(this, _DurabilityCore_policy, createPolicyResolver(config, config.methods ?? {}, methodOptionsSchema), "f");
42
- __classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(config.onLifecycleEvent), "f");
96
+ __classPrivateFieldSet(this, _DurabilityCore_lifecycle, createLifecycleHooks((hook) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").emitter(hook), config.onLifecycleEvent), "f");
97
+ __classPrivateFieldSet(this, _DurabilityCore_emit, __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").emit, "f");
43
98
  const reserved = new Set(Object.getOwnPropertyNames(DurabilityCore.prototype));
44
99
  for (const operation of Object.keys(handlers)) {
45
100
  if (reserved.has(operation)) {
@@ -54,9 +109,10 @@ class DurabilityCore {
54
109
  }
55
110
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").migrateSchema('operations', durabilityOperationMigrations);
56
111
  __classPrivateFieldGet(this, _DurabilityCore_engine, "f").register({
57
- kind: 'calls',
112
+ table: callsTable,
58
113
  runDue: (now) => __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_runDue).call(this, now),
59
114
  });
115
+ registerTrackedSource(this, __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_trackedSource).call(this));
60
116
  }
61
117
  /** Applies or reverts the `durability_calls` schema; see {@link migrate}. */
62
118
  static migrate(context, target) {
@@ -66,12 +122,19 @@ class DurabilityCore {
66
122
  alarm(info) {
67
123
  return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").alarm(info);
68
124
  }
125
+ /**
126
+ * Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
127
+ * returns a function that detaches it.
128
+ */
129
+ lifecycle(hook) {
130
+ return __classPrivateFieldGet(this, _DurabilityCore_lifecycle, "f").add(hook);
131
+ }
69
132
  /**
70
133
  * Destructively removes operation records created strictly before the
71
134
  * timestamp, regardless of status, and returns how many were removed.
72
135
  */
73
136
  async purgeBefore(before) {
74
- const count = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").purge('calls', before, __classPrivateFieldGet(this, _DurabilityCore_active, "f"), 'Durable operation was purged');
137
+ const count = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").purge(callsTable, before, __classPrivateFieldGet(this, _DurabilityCore_active, "f"), 'Durable operation was purged');
75
138
  __classPrivateFieldGet(this, _DurabilityCore_emit, "f").call(this, {
76
139
  type: 'purged',
77
140
  entityKind: 'operation',
@@ -82,8 +145,37 @@ class DurabilityCore {
82
145
  return count;
83
146
  }
84
147
  }
85
- _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_runDue = async function _DurabilityCore_runDue(now) {
86
- const due = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.listDue(now, 100);
148
+ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap(), _DurabilityCore_policy = new WeakMap(), _DurabilityCore_lifecycle = new WeakMap(), _DurabilityCore_emit = new WeakMap(), _DurabilityCore_active = new WeakMap(), _DurabilityCore_executionStarts = new WeakMap(), _DurabilityCore_instances = new WeakSet(), _DurabilityCore_trackedSource = function _DurabilityCore_trackedSource() {
149
+ const sql = __classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql;
150
+ return {
151
+ get: async (id) => {
152
+ const call = readCall(sql, id);
153
+ return call && callRecord(call);
154
+ },
155
+ list: async ({ limit, cursor, status, name }) => {
156
+ const page = listCreated(sql, callsTable, 'operation', {
157
+ limit,
158
+ after: cursor,
159
+ status,
160
+ name,
161
+ });
162
+ const records = callRowSchema.array().parse(page.rows).map(callRecord);
163
+ return page.next === undefined
164
+ ? { records }
165
+ : { records, cursor: page.next };
166
+ },
167
+ watch: (id, listener) => __classPrivateFieldGet(this, _DurabilityCore_engine, "f").watch(callsTable, id, () => listener()),
168
+ };
169
+ }, _DurabilityCore_runDue = async function _DurabilityCore_runDue(now) {
170
+ const due = z
171
+ .object({ id: z.string() })
172
+ .array()
173
+ .parse(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql
174
+ .exec(`SELECT id FROM durability_calls
175
+ WHERE status = 'pending' AND next_attempt_at <= ?
176
+ ORDER BY next_attempt_at ASC
177
+ LIMIT 100`, now)
178
+ .toArray());
87
179
  await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").runConcurrent(due, async ({ id }) => {
88
180
  try {
89
181
  await __classPrivateFieldGet(this, _DurabilityCore_instances, "m", _DurabilityCore_execute).call(this, id);
@@ -93,62 +185,33 @@ _DurabilityCore_engine = new WeakMap(), _DurabilityCore_handlers = new WeakMap()
93
185
  }
94
186
  });
95
187
  }, _DurabilityCore_getResult = async function _DurabilityCore_getResult(operation, idempotencyKey) {
96
- const call = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.get(idempotencyKey);
188
+ const call = readCall(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, idempotencyKey);
97
189
  if (!call) {
98
190
  return { status: 'not_found' };
99
191
  }
100
192
  assertOperation(idempotencyKey, call.operation, operation);
101
- if (call.status === 'pending') {
102
- return {
103
- status: 'pending',
104
- attempt: call.attempt,
105
- nextAttemptAt: call.next_attempt_at,
106
- lastError: call.last_error,
107
- };
108
- }
109
- if (call.status === 'failed') {
110
- return {
111
- status: 'failed',
112
- attempt: call.attempt,
113
- error: {
114
- name: call.last_error_name ?? 'Error',
115
- message: call.last_error ?? 'Durable operation failed',
116
- },
117
- };
118
- }
119
- if (call.result === null) {
120
- throw new Error(`Completed durable call "${idempotencyKey}" has no result`);
121
- }
122
- return { status: 'completed', result: deserialize(call.result) };
193
+ return callState(call);
123
194
  }, _DurabilityCore_run = async function _DurabilityCore_run(input) {
124
195
  const payload = serialize(input.payload);
125
196
  const now = Date.now();
126
197
  const generation = crypto.randomUUID();
127
- let inserted = false;
128
- let winner;
129
- await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").transaction(async (transaction) => {
130
- inserted = await transaction.calls.insert({
131
- id: input.id,
132
- operation: input.operation,
133
- payload,
134
- status: 'pending',
135
- result: null,
136
- attempt: 0,
137
- next_attempt_at: now,
138
- last_error: null,
139
- last_error_name: null,
140
- completed_at: null,
141
- created_at: now,
142
- generation_id: generation,
143
- });
144
- winner = await transaction.calls.get(input.id);
145
- if (!winner) {
198
+ const { inserted, winner } = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").transaction((sql) => {
199
+ const created = sql
200
+ .exec(`INSERT INTO durability_calls
201
+ (id, operation, payload, status, attempt, next_attempt_at,
202
+ created_at, generation_id)
203
+ VALUES (?, ?, ?, 'pending', 0, ?, ?, ?)
204
+ ON CONFLICT(id) DO NOTHING
205
+ RETURNING id`, input.id, input.operation, payload, now, now, generation)
206
+ .toArray().length > 0;
207
+ const current = readCall(sql, input.id);
208
+ if (!current) {
146
209
  throw new Error(`Durable call "${input.id}" was not persisted`);
147
210
  }
148
- assertOperation(input.id, winner.operation, input.operation);
149
- await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").reconcile(transaction);
211
+ assertOperation(input.id, current.operation, input.operation);
212
+ return { inserted: created, winner: current };
150
213
  });
151
- if (!inserted || !winner) {
214
+ if (!inserted) {
152
215
  return;
153
216
  }
154
217
  __classPrivateFieldGet(this, _DurabilityCore_emit, "f").call(this, {
@@ -183,7 +246,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
183
246
  let permitTransferred = false;
184
247
  try {
185
248
  await previousStart;
186
- const call = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.get(id);
249
+ const call = readCall(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, id);
187
250
  if (!call || call.status !== 'pending') {
188
251
  return;
189
252
  }
@@ -211,7 +274,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
211
274
  const policy = __classPrivateFieldGet(this, _DurabilityCore_policy, "f").call(this, call.operation);
212
275
  const handler = __classPrivateFieldGet(this, _DurabilityCore_handlers, "f")[call.operation];
213
276
  return __classPrivateFieldGet(this, _DurabilityCore_engine, "f").startExecution({
214
- kind: 'calls',
277
+ table: callsTable,
215
278
  key: call.id,
216
279
  row: call,
217
280
  label: `operation "${call.operation}"`,
@@ -233,7 +296,7 @@ async function _DurabilityCore_execute(id, eagerPermit) {
233
296
  signal,
234
297
  });
235
298
  },
236
- complete: async (result, attempt) => {
299
+ complete: (result, attempt) => {
237
300
  let serialized;
238
301
  try {
239
302
  serialized = serialize(result);
@@ -242,13 +305,8 @@ async function _DurabilityCore_execute(id, eagerPermit) {
242
305
  throw new DurableResultSerializationError(call.operation, error);
243
306
  }
244
307
  const timestamp = Date.now();
245
- const updated = await __classPrivateFieldGet(this, _DurabilityCore_engine, "f").storage.calls.settle(call.id, call.generation_id, attempt, {
246
- status: 'completed',
247
- result: serialized,
248
- last_error: null,
249
- last_error_name: null,
250
- completed_at: timestamp,
251
- });
308
+ const updated = updateAttempt(__classPrivateFieldGet(this, _DurabilityCore_engine, "f").sql, callsTable, { key: call.id, generation: call.generation_id, attempt }, `status = 'completed', result = ?, last_error = NULL,
309
+ last_error_name = NULL, completed_at = ?`, serialized, timestamp);
252
310
  return updated ? timestamp : undefined;
253
311
  },
254
312
  isTerminal: (error) => isErrorInstance(error, DurableResultSerializationError),
package/dist/errors.d.ts CHANGED
@@ -67,6 +67,28 @@ export declare class FanoutTimeoutError extends Error {
67
67
  export declare class FanoutEnqueueError extends Error {
68
68
  constructor(message: string);
69
69
  }
70
+ /** A definite rejection before records were durably appended. */
71
+ export declare class LogAppendError extends Error {
72
+ constructor(message: string);
73
+ }
74
+ /**
75
+ * Thrown when a read starts below the retained window, so a consumer that
76
+ * falls further behind than retention learns it lost records instead of
77
+ * silently skipping them.
78
+ */
79
+ export declare class LogTruncatedError extends Error {
80
+ readonly requestedOffset: number;
81
+ readonly oldestOffset: number;
82
+ constructor(requestedOffset: number, oldestOffset: number);
83
+ }
84
+ /**
85
+ * Thrown when settling a lease that no longer exists, was already settled, or
86
+ * was reclaimed by another worker. A stale ack must fail loudly rather than
87
+ * advance a range someone else now owns.
88
+ */
89
+ export declare class LogLeaseError extends Error {
90
+ constructor(batchId: string);
91
+ }
70
92
  /** Error thrown when a sharding function returns an invalid shard key. */
71
93
  export declare class RoutingError extends Error {
72
94
  constructor(message: string);
package/dist/errors.js CHANGED
@@ -105,6 +105,37 @@ export class FanoutEnqueueError extends Error {
105
105
  this.name = 'FanoutEnqueueError';
106
106
  }
107
107
  }
108
+ /** A definite rejection before records were durably appended. */
109
+ export class LogAppendError extends Error {
110
+ constructor(message) {
111
+ super(message);
112
+ this.name = 'LogAppendError';
113
+ }
114
+ }
115
+ /**
116
+ * Thrown when a read starts below the retained window, so a consumer that
117
+ * falls further behind than retention learns it lost records instead of
118
+ * silently skipping them.
119
+ */
120
+ export class LogTruncatedError extends Error {
121
+ constructor(requestedOffset, oldestOffset) {
122
+ super(`Log offset ${requestedOffset} was trimmed; the oldest retained offset is ${oldestOffset}`);
123
+ this.requestedOffset = requestedOffset;
124
+ this.oldestOffset = oldestOffset;
125
+ this.name = 'LogTruncatedError';
126
+ }
127
+ }
128
+ /**
129
+ * Thrown when settling a lease that no longer exists, was already settled, or
130
+ * was reclaimed by another worker. A stale ack must fail loudly rather than
131
+ * advance a range someone else now owns.
132
+ */
133
+ export class LogLeaseError extends Error {
134
+ constructor(batchId) {
135
+ super(`Log lease "${batchId}" is not held`);
136
+ this.name = 'LogLeaseError';
137
+ }
138
+ }
108
139
  /** Error thrown when a sharding function returns an invalid shard key. */
109
140
  export class RoutingError extends Error {
110
141
  constructor(message) {
@@ -0,0 +1,8 @@
1
+ /**
2
+ * APIs that may change or be removed in a minor release. Pin an exact
3
+ * version of `durability` when depending on them.
4
+ *
5
+ * @packageDocumentation
6
+ */
7
+ export { DurabilityTracker, type DurabilityTrackerConfig, type TrackedHandle, type TrackedItem, type TrackedResult, type TrackedWaitOptions, type TrackerHandle, type TrackerPage, type TrackerQuery, type TrackerRecord, type TrackerRecordPage, } from './tracker.js';
8
+ export type { TrackedEntry, TrackedPage, TrackedQuery, TrackedRecord, TrackedResults, TrackedSource, TrackedState, TrackedStatus, } from './tracked-source.js';
@@ -0,0 +1,7 @@
1
+ /**
2
+ * APIs that may change or be removed in a minor release. Pin an exact
3
+ * version of `durability` when depending on them.
4
+ *
5
+ * @packageDocumentation
6
+ */
7
+ export { DurabilityTracker, } from './tracker.js';