durability 3.0.1 → 4.1.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.
package/dist/errors.js CHANGED
@@ -76,6 +76,13 @@ export class DuplicateDurableCallError extends Error {
76
76
  this.name = 'DuplicateDurableCallError';
77
77
  }
78
78
  }
79
+ /** Thrown when an idempotency key is reused for the same operation with a different payload. */
80
+ export class DuplicateDurablePayloadError extends Error {
81
+ constructor(id, operation) {
82
+ super(`Durable call "${id}" for operation "${operation}" was registered with a different payload`);
83
+ this.name = 'DuplicateDurablePayloadError';
84
+ }
85
+ }
79
86
  /**
80
87
  * Error thrown when a fanout delivery is settled twice.
81
88
  *
@@ -105,6 +112,37 @@ export class FanoutEnqueueError extends Error {
105
112
  this.name = 'FanoutEnqueueError';
106
113
  }
107
114
  }
115
+ /** A definite rejection before records were durably appended. */
116
+ export class LogAppendError extends Error {
117
+ constructor(message) {
118
+ super(message);
119
+ this.name = 'LogAppendError';
120
+ }
121
+ }
122
+ /**
123
+ * Thrown when a read starts below the retained window, so a consumer that
124
+ * falls further behind than retention learns it lost records instead of
125
+ * silently skipping them.
126
+ */
127
+ export class LogTruncatedError extends Error {
128
+ constructor(requestedOffset, oldestOffset) {
129
+ super(`Log offset ${requestedOffset} was trimmed; the oldest retained offset is ${oldestOffset}`);
130
+ this.requestedOffset = requestedOffset;
131
+ this.oldestOffset = oldestOffset;
132
+ this.name = 'LogTruncatedError';
133
+ }
134
+ }
135
+ /**
136
+ * Thrown when settling a lease that no longer exists, was already settled, or
137
+ * was reclaimed by another worker. A stale ack must fail loudly rather than
138
+ * advance a range someone else now owns.
139
+ */
140
+ export class LogLeaseError extends Error {
141
+ constructor(batchId) {
142
+ super(`Log lease "${batchId}" is not held`);
143
+ this.name = 'LogLeaseError';
144
+ }
145
+ }
108
146
  /** Error thrown when a sharding function returns an invalid shard key. */
109
147
  export class RoutingError extends Error {
110
148
  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';
package/dist/fanout.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { LifecycleHook } from './lifecycle.js';
1
+ import { type DurabilityLifecycleEvent, type LifecycleHook } from './lifecycle.js';
2
2
  import { RoutingLoad, type EnqueueResult, type LoadSnapshot } from './load.js';
3
3
  import type { MessageWrite } from './stored-message.js';
4
4
  import { type ExecutionPolicyOptions } from './policy.js';
@@ -23,10 +23,17 @@ export type DurabilityFanoutMessage<Body = unknown> = {
23
23
  };
24
24
  export type FanoutTarget<Body> = ExecutionPolicyOptions & ({
25
25
  deliver(messages: DurabilityFanoutMessage<Body>[]): unknown | Promise<unknown>;
26
+ /**
27
+ * Acks every message the consumer leaves unsettled when `deliver`
28
+ * returns without throwing, in one transaction instead of one call
29
+ * per message. Explicit `retry()` and `deadLetter()` still apply.
30
+ */
31
+ ackOnReturn?: boolean;
26
32
  storage?: never;
27
33
  } | {
28
34
  storage: MessageWrite<Body>;
29
35
  deliver?: never;
36
+ ackOnReturn?: never;
30
37
  });
31
38
  export type FanoutEnqueueOptions = {
32
39
  /** Omit for all static targets. Redrive specifies only the failed target. */
@@ -35,11 +42,22 @@ export type FanoutEnqueueOptions = {
35
42
  export type DurabilityFanoutConfig<Body> = SchedulerAttachment & ExecutionPolicyOptions & {
36
43
  targets: Record<string, FanoutTarget<Body>>;
37
44
  routing?: RoutingLoad;
38
- /** Receives terminal failures. Without it, terminal work is retained. */
45
+ /** Receives terminal failures. Without it, terminal deliveries are dropped. */
39
46
  dlq?: MessageWrite<Body>;
40
47
  maxBatchSize?: number;
48
+ /**
49
+ * Holds first deliveries for up to this many milliseconds so messages
50
+ * arriving together share a batch. Defaults to 0 (deliver immediately).
51
+ */
52
+ batchDelayMs?: number;
41
53
  onLifecycleEvent?: LifecycleHook;
42
54
  };
55
+ /** A lifecycle event for one of this instance's deliveries. */
56
+ export type DurabilityFanoutEvent = Extract<DurabilityLifecycleEvent, {
57
+ entityKind: 'fanout_delivery';
58
+ }> | Extract<DurabilityLifecycleEvent, {
59
+ type: 'purged';
60
+ }>;
43
61
  /**
44
62
  * A composable DO capability: durable, independent delivery to static named
45
63
  * targets. Share a scheduler with operations/alarms on the same object.
@@ -50,6 +68,11 @@ export declare class DurabilityFanout<Body = unknown> {
50
68
  constructor(config: DurabilityFanoutConfig<Body>);
51
69
  static migrate(context: Pick<DurableObjectState, 'storage'>, target?: string | null): import("./migrations.js").DurabilityMigrationResult;
52
70
  alarm(info?: AlarmInvocationInfo): Promise<void>;
71
+ /**
72
+ * Attaches a best-effort lifecycle hook alongside `onLifecycleEvent` and
73
+ * returns a function that detaches it.
74
+ */
75
+ lifecycle(hook: (event: DurabilityFanoutEvent) => void | Promise<void>): () => void;
53
76
  load(): Promise<LoadSnapshot>;
54
77
  /**
55
78
  * Atomically accepts the whole batch, including its frozen target set.