arthron 1.2.0 → 2.1.0

package/dist/plugins.d.cts

@@ -1,2 +1,138 @@
-import { S as UploadProgressEvent, a as logging, c as bearerAuth, i as retry, l as BearerAuthOptions, n as timeout, o as LogEvent, r as TimeoutOptions, s as LoggingOptions, t as uploadProgress, x as RetryOptions } from "./index-C3lylSNd.cjs";
-export { type BearerAuthOptions, type LogEvent, type LoggingOptions, type RetryOptions, type TimeoutOptions, type UploadProgressEvent, bearerAuth, logging, retry, timeout, uploadProgress };
+import { f as RetryOptions, m as UploadProgressEvent, p as TimeoutOptions, r as Plugin } from "./shared.cjs";
+//#region src/plugins/bearer-auth/bearer-auth.types.d.ts
+type BearerAuthOptions = {
+  /**
+   * The origins the token may go to, as a list of URLs of which only the
+   * origin counts, so your `baseURL` works as is: `tokenOrigins: [API]`. A
+   * request anywhere else — a CDN, a URL taken from a response body — is
+   * sent without the token.
+   */
+  tokenOrigins: readonly string[];
+  /**
+   * Returns the current access token; called on every attempt. `null`,
+   * `undefined` or `""` sends no `authorization` header.
+   */
+  accessTokenFn: () => string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Refreshes the session after a 401, so the next `accessTokenFn()`
+   * returns the new token; the call is then redone once.
+   * Concurrent 401s share one refresh, and a call whose token was already
+   * replaced retries without one. Throw when the refresh fails — every waiting call
+   * rejects with that error. A request it starts through the same client
+   * before its first `await` goes out as with `meta: { bearerAuth: false }`
+   * (no token, no refresh on its 401); one started after an `await` needs
+   * that meta itself, or its 401 would wait for the refresh it is part of.
+   * Without `refreshFn`, or for a `ReadableStream` body (already read, so it
+   * cannot be resent), a 401 is thrown as is.
+   */
+  refreshFn?: () => Promise<void>;
+};
+//#endregion
+//#region src/plugins/bearer-auth/bearer-auth.d.ts
+/**
+ * Bearer-token auth. A request interceptor sets `authorization: Bearer
+ * <token>` on every attempt to `tokenOrigins`; with `refreshFn`, a middleware turns a
+ * 401 into one refresh and one more try. Concurrent 401s share the refresh
+ * (with refresh-token rotation, parallel refreshes revoke each other), and a
+ * call whose token was replaced meanwhile just retries. A call opts out with
+ * `meta: { bearerAuth: false }`.
+ */
+export declare function bearerAuth(options: BearerAuthOptions): Plugin;
+//#endregion
+//#region src/plugins/logging/logging.types.d.ts
+/**
+ * One step of a call, as `logging({ onEvent })` receives it. `url` is the
+ * request URL with its query and userinfo removed — the value
+ * `ArthronError.toJSON()` calls `url`. `duration` is in ms, retries
+ * included.
+ */
+type LogEvent = {
+  phase: "start";
+  method: string;
+  url: string;
+} | {
+  phase: "success";
+  method: string;
+  url: string;
+  status: number;
+  duration: number;
+} | {
+  phase: "error";
+  method: string;
+  url: string;
+  /** HTTP status for an ArthronError (0 = network); undefined for anything else. */
+  status: number | undefined;
+  duration: number;
+  error: unknown;
+};
+type LoggingOptions = {
+  /** Default `true`. The library never reads `NODE_ENV` — pass `isDev` yourself. */
+  enabled?: boolean;
+  logger?: Pick<Console, "log" | "error">;
+  /** Receive structured events instead of the default console lines. */
+  onEvent?: (event: LogEvent) => void;
+  /**
+   * Default `false`. `true` reports a call that timed out before its response
+   * arrived — a `TimeoutError`, from `timeout()` or `AbortSignal.timeout()` —
+   * as an error event, `status` undefined. A timeout while the body is read
+   * rejects that read instead: the call has already logged its success.
+   * Other cancellations are never reported.
+   */
+  timeouts?: boolean;
+};
+//#endregion
+//#region src/plugins/logging/logging.d.ts
+/**
+ * One event when a request starts, one when it settles, with status and
+ * elapsed time. Wraps the whole call, so retries are included in the time.
+ * Default output is a console line per event; pass `onEvent` to get the
+ * structured event instead. Cancellations are not reported, timeouts only
+ * with `timeouts: true`.
+ */
+export declare function logging(options?: LoggingOptions): Plugin;
+//#endregion
+//#region src/plugins/retry/retry.d.ts
+/**
+ * Retry on network errors and the configured statuses by calling `next`
+ * again — the whole attempt (request interceptors included) is re-run.
+ * Only `ArthronError` is considered; cancellation and plugin bugs pass through.
+ * A call can turn it off or override its options with `meta.retry`.
+ */
+export declare function retry(options?: RetryOptions): Plugin;
+//#endregion
+//#region src/plugins/timeout/timeout.d.ts
+/**
+ * Abort the request when it takes longer than `ms` — counted from the start
+ * of the attempt until the body has been fully read, so a server that sends
+ * headers and then stalls still trips it. `timeout({ idle })` instead aborts
+ * once no data has arrived for that long, and never cuts off a stream that
+ * keeps flowing; `timeout({ total, idle })` does both. Rejects with a
+ * `TimeoutError` (a `DOMException`, like `AbortSignal.timeout()` would give);
+ * it is not an `ArthronError`, so error interceptors and `retry` leave it
+ * alone.
+ *
+ * A call can lift the deadlines or change them with `meta.timeout`.
+ *
+ * Deadlines are timers on an AbortController — not `AbortSignal.timeout`,
+ * since the idle one restarts — joined to the caller's signal with
+ * `AbortSignal.any`.
+ */
+export declare function timeout(ms: number): Plugin;
+export declare function timeout(options: TimeoutOptions): Plugin;
+//#endregion
+//#region src/plugins/upload-progress/upload-progress.d.ts
+/**
+ * Does nothing by itself — only a call that passes `meta.uploadProgress`
+ * reports upload progress. On such a call it changes how that one attempt
+ * is sent: over XMLHttpRequest in a browser, with a counted body in Node.
+ * Every other call, on this client too, goes out exactly as before.
+ *
+ * Progress needs the runtime's own fetch: with a client `fetchFn`, another
+ * plugin's fetchFn, or a runtime that is neither (Deno, Bun, Cloudflare
+ * Workers, a service worker), the call is sent as usual without progress.
+ * Put it last in `plugins`: the call's signal carries a throwing callback's
+ * error, and an interceptor after it that replaces the signal would cut it.
+ */
+export declare function uploadProgress(): Plugin;
+//#endregion
+export type { BearerAuthOptions, LogEvent, LoggingOptions, RetryOptions, TimeoutOptions, UploadProgressEvent };

package/dist/plugins.d.mts

@@ -1,2 +1,138 @@
-import { S as UploadProgressEvent, a as logging, c as bearerAuth, i as retry, l as BearerAuthOptions, n as timeout, o as LogEvent, r as TimeoutOptions, s as LoggingOptions, t as uploadProgress, x as RetryOptions } from "./index-C3lylSNd.mjs";
-export { type BearerAuthOptions, type LogEvent, type LoggingOptions, type RetryOptions, type TimeoutOptions, type UploadProgressEvent, bearerAuth, logging, retry, timeout, uploadProgress };
+import { f as RetryOptions, m as UploadProgressEvent, p as TimeoutOptions, r as Plugin } from "./shared.mjs";
+//#region src/plugins/bearer-auth/bearer-auth.types.d.ts
+type BearerAuthOptions = {
+  /**
+   * The origins the token may go to, as a list of URLs of which only the
+   * origin counts, so your `baseURL` works as is: `tokenOrigins: [API]`. A
+   * request anywhere else — a CDN, a URL taken from a response body — is
+   * sent without the token.
+   */
+  tokenOrigins: readonly string[];
+  /**
+   * Returns the current access token; called on every attempt. `null`,
+   * `undefined` or `""` sends no `authorization` header.
+   */
+  accessTokenFn: () => string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Refreshes the session after a 401, so the next `accessTokenFn()`
+   * returns the new token; the call is then redone once.
+   * Concurrent 401s share one refresh, and a call whose token was already
+   * replaced retries without one. Throw when the refresh fails — every waiting call
+   * rejects with that error. A request it starts through the same client
+   * before its first `await` goes out as with `meta: { bearerAuth: false }`
+   * (no token, no refresh on its 401); one started after an `await` needs
+   * that meta itself, or its 401 would wait for the refresh it is part of.
+   * Without `refreshFn`, or for a `ReadableStream` body (already read, so it
+   * cannot be resent), a 401 is thrown as is.
+   */
+  refreshFn?: () => Promise<void>;
+};
+//#endregion
+//#region src/plugins/bearer-auth/bearer-auth.d.ts
+/**
+ * Bearer-token auth. A request interceptor sets `authorization: Bearer
+ * <token>` on every attempt to `tokenOrigins`; with `refreshFn`, a middleware turns a
+ * 401 into one refresh and one more try. Concurrent 401s share the refresh
+ * (with refresh-token rotation, parallel refreshes revoke each other), and a
+ * call whose token was replaced meanwhile just retries. A call opts out with
+ * `meta: { bearerAuth: false }`.
+ */
+export declare function bearerAuth(options: BearerAuthOptions): Plugin;
+//#endregion
+//#region src/plugins/logging/logging.types.d.ts
+/**
+ * One step of a call, as `logging({ onEvent })` receives it. `url` is the
+ * request URL with its query and userinfo removed — the value
+ * `ArthronError.toJSON()` calls `url`. `duration` is in ms, retries
+ * included.
+ */
+type LogEvent = {
+  phase: "start";
+  method: string;
+  url: string;
+} | {
+  phase: "success";
+  method: string;
+  url: string;
+  status: number;
+  duration: number;
+} | {
+  phase: "error";
+  method: string;
+  url: string;
+  /** HTTP status for an ArthronError (0 = network); undefined for anything else. */
+  status: number | undefined;
+  duration: number;
+  error: unknown;
+};
+type LoggingOptions = {
+  /** Default `true`. The library never reads `NODE_ENV` — pass `isDev` yourself. */
+  enabled?: boolean;
+  logger?: Pick<Console, "log" | "error">;
+  /** Receive structured events instead of the default console lines. */
+  onEvent?: (event: LogEvent) => void;
+  /**
+   * Default `false`. `true` reports a call that timed out before its response
+   * arrived — a `TimeoutError`, from `timeout()` or `AbortSignal.timeout()` —
+   * as an error event, `status` undefined. A timeout while the body is read
+   * rejects that read instead: the call has already logged its success.
+   * Other cancellations are never reported.
+   */
+  timeouts?: boolean;
+};
+//#endregion
+//#region src/plugins/logging/logging.d.ts
+/**
+ * One event when a request starts, one when it settles, with status and
+ * elapsed time. Wraps the whole call, so retries are included in the time.
+ * Default output is a console line per event; pass `onEvent` to get the
+ * structured event instead. Cancellations are not reported, timeouts only
+ * with `timeouts: true`.
+ */
+export declare function logging(options?: LoggingOptions): Plugin;
+//#endregion
+//#region src/plugins/retry/retry.d.ts
+/**
+ * Retry on network errors and the configured statuses by calling `next`
+ * again — the whole attempt (request interceptors included) is re-run.
+ * Only `ArthronError` is considered; cancellation and plugin bugs pass through.
+ * A call can turn it off or override its options with `meta.retry`.
+ */
+export declare function retry(options?: RetryOptions): Plugin;
+//#endregion
+//#region src/plugins/timeout/timeout.d.ts
+/**
+ * Abort the request when it takes longer than `ms` — counted from the start
+ * of the attempt until the body has been fully read, so a server that sends
+ * headers and then stalls still trips it. `timeout({ idle })` instead aborts
+ * once no data has arrived for that long, and never cuts off a stream that
+ * keeps flowing; `timeout({ total, idle })` does both. Rejects with a
+ * `TimeoutError` (a `DOMException`, like `AbortSignal.timeout()` would give);
+ * it is not an `ArthronError`, so error interceptors and `retry` leave it
+ * alone.
+ *
+ * A call can lift the deadlines or change them with `meta.timeout`.
+ *
+ * Deadlines are timers on an AbortController — not `AbortSignal.timeout`,
+ * since the idle one restarts — joined to the caller's signal with
+ * `AbortSignal.any`.
+ */
+export declare function timeout(ms: number): Plugin;
+export declare function timeout(options: TimeoutOptions): Plugin;
+//#endregion
+//#region src/plugins/upload-progress/upload-progress.d.ts
+/**
+ * Does nothing by itself — only a call that passes `meta.uploadProgress`
+ * reports upload progress. On such a call it changes how that one attempt
+ * is sent: over XMLHttpRequest in a browser, with a counted body in Node.
+ * Every other call, on this client too, goes out exactly as before.
+ *
+ * Progress needs the runtime's own fetch: with a client `fetchFn`, another
+ * plugin's fetchFn, or a runtime that is neither (Deno, Bun, Cloudflare
+ * Workers, a service worker), the call is sent as usual without progress.
+ * Put it last in `plugins`: the call's signal carries a throwing callback's
+ * error, and an interceptor after it that replaces the signal would cut it.
+ */
+export declare function uploadProgress(): Plugin;
+//#endregion
+export type { BearerAuthOptions, LogEvent, LoggingOptions, RetryOptions, TimeoutOptions, UploadProgressEvent };