@wats/graph 0.4.0-beta.0 → 0.5.0-beta

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/README.md CHANGED
@@ -16,7 +16,7 @@ import { GraphClient, createFetchTransport, sendMessage } from "@wats/graph";
16
16
 
17
17
  const graph = new GraphClient({
18
18
  accessToken: process.env.WATS_ACCESS_TOKEN ?? "",
19
- apiVersion: "v25.0",
19
+ apiVersion: "v27.0",
20
20
  transport: createFetchTransport()
21
21
  });
22
22
 
@@ -1,9 +1,16 @@
1
1
  export interface RateLimiter {
2
2
  /**
3
3
  * Wait until `cost` tokens are available, then deduct them. Resolves once
4
- * the request is admitted; never rejects unless the injected sleep does.
4
+ * the request is admitted; never rejects unless the injected sleep does,
5
+ * or an `AbortSignal` is provided and aborts before admission.
6
+ *
7
+ * The optional `signal` is backwards compatible: callers using the legacy
8
+ * `acquire(cost?)` signature are unaffected. A real `AbortSignal` racing
9
+ * the wait rejects promptly with the signal's reason and consumes no
10
+ * token. Non-AbortSignal inputs fail closed with a TypeError rather than
11
+ * silently dropping cancellation.
5
12
  */
6
- acquire(cost?: number): Promise<void>;
13
+ acquire(cost?: number, signal?: AbortSignal): Promise<void>;
7
14
  /**
8
15
  * Non-blocking admission check. Refills the bucket to the current virtual
9
16
  * time, then if `cost` tokens are available deducts them and returns true;
@@ -27,6 +27,7 @@ export function createTokenBucketRateLimiter(options) {
27
27
  throw new Error("CreateTokenBucketRateLimiterOptions: sleep must be a function.");
28
28
  }
29
29
  const now = options.now ?? (() => Date.now());
30
+ const usesDefaultSleep = options.sleep === undefined;
30
31
  const sleep = options.sleep ?? defaultSleep;
31
32
  let tokens = capacity;
32
33
  let lastRefillMs = now();
@@ -49,9 +50,20 @@ export function createTokenBucketRateLimiter(options) {
49
50
  }
50
51
  }
51
52
  return {
52
- async acquire(cost) {
53
+ async acquire(cost, signal) {
53
54
  const c = assertCost(cost);
55
+ if (signal !== undefined) {
56
+ if (signal === null || !(signal instanceof AbortSignal)) {
57
+ throw new TypeError("RateLimiter.acquire: signal must be an AbortSignal or undefined.");
58
+ }
59
+ if (signal.aborted) {
60
+ throw signal.reason instanceof Error ? signal.reason : new Error("RateLimiter acquire aborted by caller.");
61
+ }
62
+ }
54
63
  for (;; ) {
64
+ if (signal?.aborted) {
65
+ throw signal.reason instanceof Error ? signal.reason : new Error("RateLimiter acquire aborted by caller.");
66
+ }
55
67
  refill();
56
68
  if (tokens >= c) {
57
69
  tokens -= c;
@@ -59,7 +71,29 @@ export function createTokenBucketRateLimiter(options) {
59
71
  }
60
72
  const deficit = c - tokens;
61
73
  const waitMs = deficit / refillPerSecond * 1000;
62
- await sleep(Math.max(0, waitMs));
74
+ if (signal === undefined) {
75
+ await sleep(Math.max(0, waitMs));
76
+ continue;
77
+ }
78
+ let onAbort;
79
+ let timer;
80
+ const aborted = new Promise((_resolve, reject) => {
81
+ onAbort = () => {
82
+ reject(signal.reason instanceof Error ? signal.reason : new Error("RateLimiter acquire aborted by caller."));
83
+ };
84
+ signal.addEventListener("abort", onAbort, { once: true });
85
+ });
86
+ try {
87
+ const waiting = usesDefaultSleep ? new Promise((resolve) => {
88
+ timer = setTimeout(resolve, Math.max(0, waitMs));
89
+ }) : sleep(Math.max(0, waitMs));
90
+ await Promise.race([waiting, aborted]);
91
+ } finally {
92
+ if (timer !== undefined)
93
+ clearTimeout(timer);
94
+ if (onAbort !== undefined)
95
+ signal.removeEventListener("abort", onAbort);
96
+ }
63
97
  }
64
98
  },
65
99
  tryAcquire(cost) {
@@ -20,16 +20,27 @@ export interface ReliableTransportOptions extends Partial<TransportRetryPolicy>
20
20
  * the historical behavior: POST is retried only on 429 (the rate-limit
21
21
  * exception), never on 5xx or network errors.
22
22
  *
23
+ * A no-response POST failure (connection reset, socket closed mid-upload,
24
+ * read timeout) is ambiguous: the server may have received and applied the
25
+ * request before the response was lost. An Idempotency-Key header on its
26
+ * own proves nothing — the client sets it, the server has no obligation to
27
+ * honor it unless the endpoint documents verified remote idempotency. The
28
+ * retry modes below opt into retry only when you have independently verified
29
+ * the endpoint is idempotent or dedupes by Idempotency-Key server-side. The
30
+ * key is a necessary, not sufficient, condition; it never overrides the
31
+ * default "never".
32
+ *
23
33
  * - "network-only": additionally retry a POST whose request threw a
24
34
  * GraphNetworkError BEFORE any response arrived, but only when the request
25
- * carries an Idempotency-Key header (case-insensitive). A pre-response
26
- * network failure is the one POST failure shape that cannot have been
27
- * processed by the server, so an idempotency key makes the retry safe.
28
- * POST 5xx is still not retried — the server may have side-effected.
35
+ * carries an Idempotency-Key header (case-insensitive). This is the least
36
+ * ambiguous POST failure shape, but still not exactly-once: the server may
37
+ * have applied the first send and lost the response. The retry is safe only
38
+ * if the endpoint dedupes by the key you supplied. POST 5xx is not retried —
39
+ * the server began processing and may have side-effected.
29
40
  * - "always": additionally retry POST on 5xx. Requires server-side
30
41
  * idempotency for the endpoint; a 5xx after the server began processing
31
- * can otherwise duplicate a send. Use only for endpoints you have
32
- * verified are idempotent or dedupe by Idempotency-Key.
42
+ * can otherwise duplicate a send. Use only for endpoints you have verified
43
+ * are idempotent or dedupe by Idempotency-Key.
33
44
  */
34
45
  readonly retryPosts?: RetryPostMode;
35
46
  readonly rateLimiter?: RateLimiter;
@@ -38,7 +38,7 @@ function resolvePolicy(options) {
38
38
  if (options?.rateLimiter !== undefined) {
39
39
  const rl = options.rateLimiter;
40
40
  if (rl === null || typeof rl !== "object" || typeof rl.acquire !== "function") {
41
- throw new Error("ReliableTransportOptions: rateLimiter must be an object with an acquire(cost?) => Promise<void> method.");
41
+ throw new Error("ReliableTransportOptions: rateLimiter must be an object with an acquire(cost?, signal?) => Promise<void> method.");
42
42
  }
43
43
  if (typeof rl.tryAcquire !== "function") {
44
44
  throw new Error("ReliableTransportOptions: rateLimiter must also implement tryAcquire(cost?) => boolean.");
@@ -170,6 +170,25 @@ async function sleepWithAbort(sleep, delayMs, signal) {
170
170
  signal.removeEventListener("abort", onAbort);
171
171
  }
172
172
  }
173
+ async function acquireWithAbort(limiter, signal) {
174
+ let onAbort;
175
+ const aborted = new Promise((_resolve, reject) => {
176
+ onAbort = () => {
177
+ reject(signal.reason instanceof Error ? signal.reason : new GraphNetworkError("Transport request aborted by caller."));
178
+ };
179
+ if (signal.aborted) {
180
+ onAbort();
181
+ } else {
182
+ signal.addEventListener("abort", onAbort, { once: true });
183
+ }
184
+ });
185
+ try {
186
+ await Promise.race([limiter.acquire(undefined, signal), aborted]);
187
+ } finally {
188
+ if (onAbort !== undefined)
189
+ signal.removeEventListener("abort", onAbort);
190
+ }
191
+ }
173
192
  export function createReliableTransport(inner, options) {
174
193
  if (inner === null || typeof inner !== "object" || typeof inner.request !== "function") {
175
194
  throw new Error("ReliableTransportOptions: inner transport must implement request().");
@@ -182,8 +201,13 @@ export function createReliableTransport(inner, options) {
182
201
  for (;; ) {
183
202
  throwIfAborted(opts?.signal);
184
203
  if (policy.rateLimiter !== undefined) {
185
- await policy.rateLimiter.acquire();
204
+ if (opts?.signal !== undefined) {
205
+ await acquireWithAbort(policy.rateLimiter, opts.signal);
206
+ } else {
207
+ await policy.rateLimiter.acquire();
208
+ }
186
209
  }
210
+ throwIfAborted(opts?.signal);
187
211
  attempt += 1;
188
212
  const composedSignal = composeSignal(opts?.signal, policy.timeoutMs);
189
213
  const attemptOpts = composedSignal !== undefined ? { signal: composedSignal } : undefined;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@wats/graph",
3
3
  "description": "Graph client, transport, endpoints, errors, pagination.",
4
- "version": "0.4.0-beta.0",
4
+ "version": "0.5.0-beta",
5
5
  "private": false,
6
6
  "license": "MIT",
7
7
  "type": "module",
@@ -86,7 +86,7 @@
86
86
  "wats"
87
87
  ],
88
88
  "dependencies": {
89
- "@wats/crypto": "^0.4.0-beta.0",
90
- "@wats/internal-utils": "^0.4.0-beta.0"
89
+ "@wats/crypto": "^0.5.0-beta",
90
+ "@wats/internal-utils": "^0.5.0-beta"
91
91
  }
92
92
  }