@gcmdev/faxios 0.2.1 → 0.2.3

package/src/lib/helpers/validator.ts

@@ -5,7 +5,7 @@ import { VERSION } from "../env/data.js";
 
 export type ValidatorFn = (value: unknown, opt?: string, opts?: unknown) => boolean | string;
 
-const validators: Record<string, ValidatorFn | undefined> = {};
+const validators: Record<string, undefined | ValidatorFn> = {};
 
 [ "object", "boolean", "number", "function", "string", "symbol" ].forEach((type, i) => {
   validators[type] = function validator(thing: unknown): boolean | string {
@@ -24,7 +24,7 @@ const deprecatedWarnings: Record<string, boolean | undefined> = {};
  *
  * @returns {function}
  */
-(validators as Record<string, unknown>)["transitional"] = function transitional(validator: ValidatorFn | false | undefined, version?: string, message?: string): ValidatorFn {
+(validators as Record<string, unknown>)["transitional"] = function transitional(validator: false | undefined | ValidatorFn, version?: string, message?: string): ValidatorFn {
   function formatMessage(opt: string, desc: string): string {
     return (
       "[Faxios v" +
@@ -80,7 +80,7 @@ const deprecatedWarnings: Record<string, boolean | undefined> = {};
  * @returns {object}
  */
 
-function assertOptions(options: unknown, schema: Record<string, ValidatorFn | undefined>, allowUnknown: boolean): void {
+function assertOptions(options: unknown, schema: Record<string, undefined | ValidatorFn>, allowUnknown: boolean): void {
   if (typeof options !== "object") {
     throw new FaxiosError("options must be an object", FaxiosError.ERR_BAD_OPTION_VALUE);
   }

package/src/lib/platform.ts

@@ -3,13 +3,13 @@
 import FaxiosURLSearchParams from "./helpers/FaxiosURLSearchParams.js";
 
 const _globalThis = globalThis as {
-  window?: { location?: { href?: string; }; };
+  Blob?: new (...args: Array<unknown>) => object;
   document?: unknown;
+  FormData?: new () => object;
   navigator?: { product?: string; userAgent?: string; };
-  WorkerGlobalScope?: unknown;
   self?: { importScripts?: unknown; };
-  FormData?: new () => object;
-  Blob?: new (...args: Array<unknown>) => object;
+  window?: { location?: { href?: string; }; };
+  WorkerGlobalScope?: unknown;
 };
 
 const hasBrowserEnv = typeof _globalThis.window !== "undefined" && typeof _globalThis.document !== "undefined";

package/src/lib/plugins/authBearer.ts

@@ -13,10 +13,6 @@ import { definePlugin } from "./definePlugin.js";
 export type AuthBearerCapability = { auth: { getToken: () => Promise<string>; }; };
 
 export type AuthBearerOptions = {
-  /** Replace a header the request already has. Default `false`: an explicit header is kept. */
-  overwrite?: boolean;
-  /** Put before the token, separated by a space. Default `"Bearer"`; `""` sends the bare token. */
-  scheme?: string;
   /** The header to set. Default `"Authorization"`. */
   header?: string;
   /**
@@ -24,6 +20,10 @@ export type AuthBearerOptions = {
    * with an absolute `baseURL`, only its origin; otherwise only relative request URLs.
    */
   origins?: Array<string>;
+  /** Replace a header the request already has. Default `false`: an explicit header is kept. */
+  overwrite?: boolean;
+  /** Put before the token, separated by a space. Default `"Bearer"`; `""` sends the bare token. */
+  scheme?: string;
 };
 
 // A header name is a token (RFC 9110 §5.6.2).
@@ -31,7 +31,7 @@ const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
 // A bare origin, optionally with a trailing slash. A path would look like a narrower limit than
 // the origin the token is really sent to.
-function originOf(value: unknown): string | null {
+function originOf(value: unknown): null | string {
   if (typeof value !== "string") return null;
   try {
     const { origin } = new URL(value);
@@ -56,7 +56,7 @@ const own = <T extends object, K extends keyof T>(source: T, key: K): T[K] | und
 // that leaves the page (`//host`, `/\host`) is told apart from one that stays on it.
 const SAME_ORIGIN = "https://same-origin.invalid";
 
-function resolvedOrigin(url: string, base: string | undefined): string | null {
+function resolvedOrigin(url: string, base: string | undefined): null | string {
   try {
     return new URL(url, base).origin;
   }
@@ -72,7 +72,7 @@ function pageHref(): string | undefined {
   return undefined;
 }
 
-function sendsTokenTo(config: InternalFaxiosRequestConfig, origins: ReadonlyArray<string> | null): boolean {
+function sendsTokenTo(config: InternalFaxiosRequestConfig, origins: null | ReadonlyArray<string>): boolean {
   const baseURL = own(config, "baseURL");
   const url = buildFullPath(baseURL, own(config, "url"), own(config, "allowAbsoluteUrls"), config);
   if (origins) {
@@ -91,8 +91,12 @@ function sendsTokenTo(config: InternalFaxiosRequestConfig, origins: ReadonlyArra
  * can ask for a token too. A header the request already has is kept unless `overwrite` is set.
  * The token goes only to the `baseURL` origin when `baseURL` is absolute, otherwise only to
  * relative request URLs; `origins` replaces that rule.
+ *
+ * When `getToken` gives anything other than a non-empty string (`null`, `undefined`, `""`, a
+ * number, an object), the request is sent without the header, so a signed-out state never sends
+ * `Bearer null`. The parameter type stays `string`: the guard is for JavaScript callers and casts.
  */
-export function authBearer(getToken: () => string | Promise<string>, options: AuthBearerOptions = {}): FaxiosPlugin<{ provides: AuthBearerCapability; }> {
+export function authBearer(getToken: () => Promise<string> | string, options: AuthBearerOptions = {}): FaxiosPlugin<{ provides: AuthBearerCapability; }> {
   if (typeof getToken !== "function") {
     throw new FaxiosError("authBearer: getToken must be a function", FaxiosError.ERR_BAD_OPTION_VALUE);
   }
@@ -112,7 +116,8 @@ export function authBearer(getToken: () => string | Promise<string>, options: Au
     provides: { auth },
     middleware: async (ctx, next) => {
       if ((!overwrite && ctx.config.headers.has(header)) || !sendsTokenTo(ctx.config, origins)) return next(ctx);
-      const token = await auth.getToken();
+      const token: unknown = await auth.getToken();
+      if (typeof token !== "string" || token === "") return next(ctx);
       // On a copy: middleware that calls next() again (retry installed before this plugin) comes
       // back through here without the header, so every try asks for a fresh token.
       const headers = new FaxiosHeaders(ctx.config.headers).set(header, scheme ? `${scheme} ${token}` : token, true);

package/src/lib/plugins/definePlugin.ts

@@ -19,15 +19,15 @@ type RequiredCapabilities<TCapabilities, TProvides> = [keyof TProvides] extends
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- `{}`: no capabilities or options, as in FaxiosContext
 export function definePlugin<TProvides = {}, TOptions = {}, TCapabilities = TProvides>(plugin: {
+  middleware: FaxiosMiddleware<TOptions, TCapabilities>;
   name: string;
   // The middleware reads the capabilities it provides from ctx too, so they must have the types
   // its context declares. NoInfer: TProvides is inferred from the value alone.
   provides?: TProvides & NoInfer<Pick<TCapabilities, keyof TProvides & keyof TCapabilities>>;
-  middleware: FaxiosMiddleware<TOptions, TCapabilities>;
 }): FaxiosPlugin<{
-  requires: RequiredCapabilities<TCapabilities, TProvides>;
-  provides: Slot<TProvides>;
   options: Slot<TOptions>;
+  provides: Slot<TProvides>;
+  requires: RequiredCapabilities<TCapabilities, TProvides>;
 }> {
   // Only the types change: use() reads the fields at install time, as it does for any plugin.
   return plugin as never;

package/src/lib/plugins/retry.ts

@@ -55,37 +55,36 @@ function assertRetryOptions(value: unknown, config?: InternalFaxiosRequestConfig
 export type RetryOptions = {
   /** Total tries, counting the first request. Default 3. */
   attempts?: number;
-  /**
-   * Whether the try that just failed should be retried. `attempt` counts from 1.
-   * Default: network errors, timeouts and the `statuses`; never a cancellation. A custom `retryOn`
-   * replaces that whole predicate, so `statuses` is ignored when both are set. retryOn decides
-   * only within `methods`; to retry POST, list it in `methods`.
-   */
-  retryOn?: (error: unknown, attempt: number) => boolean;
-  /**
-   * Response statuses the default predicate retries. Default 408, 429, 500, 502, 503 and 504.
-   * Ignored when `retryOn` is set.
-   */
-  statuses?: ReadonlyArray<number>;
   /**
    * Milliseconds to wait before the next try, or a function of the try that failed. Default 100ms,
    * doubling. Capped at `maxDelay`, then jittered. A 429 or 503 with a `Retry-After` header waits
    * that long instead, unless `respectRetryAfter` is `false`.
    */
-  delay?: number | ((attempt: number, error: unknown) => number);
-  /** The most the computed backoff waits, in milliseconds. Default 30 000. Doesn't apply to `Retry-After`. */
-  maxDelay?: number;
+  delay?: ((attempt: number, error: unknown) => number) | number;
   /**
    * `"full"` (default) waits a random time between 0 and the capped backoff, so clients that failed
    * together don't retry together; `"none"` waits the capped backoff. Doesn't apply to `Retry-After`.
    */
   jitter?: "full" | "none";
+  /** The most the computed backoff waits, in milliseconds. Default 30 000. Doesn't apply to `Retry-After`. */
+  maxDelay?: number;
   /**
    * The longest `Retry-After` (seconds or an HTTP date, on a 429 or 503) to wait, in milliseconds.
    * Default 300 000 (5 minutes). A longer one rejects with the response's error instead of retrying.
    * Ignored when `respectRetryAfter` is `false`.
    */
   maxRetryAfter?: number;
+  /**
+   * HTTP methods that may be retried, in any case. Default: GET, HEAD, OPTIONS, PUT, DELETE and
+   * QUERY. POST and PATCH aren't idempotent, so add them only if your API dedupes repeats. A request
+   * whose method isn't listed is never retried, whatever `retryOn` or `statuses` say.
+   */
+  methods?: ReadonlyArray<Method>;
+  /**
+   * Called before each wait with the error, the try that failed and the wait in milliseconds. If it
+   * throws, the request rejects with that error and stops retrying.
+   */
+  onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
   /**
    * Whether a 429 or 503's `Retry-After` header sets the wait. Default `true`. With `false`, every
    * retry waits the computed backoff and `maxRetryAfter` doesn't apply; which requests retry doesn't
@@ -93,20 +92,21 @@ export type RetryOptions = {
    */
   respectRetryAfter?: boolean;
   /**
-   * Called before each wait with the error, the try that failed and the wait in milliseconds. If it
-   * throws, the request rejects with that error and stops retrying.
+   * Whether the try that just failed should be retried. `attempt` counts from 1.
+   * Default: network errors, timeouts and the `statuses`; never a cancellation. A custom `retryOn`
+   * replaces that whole predicate, so `statuses` is ignored when both are set. retryOn decides
+   * only within `methods`; to retry POST, list it in `methods`.
    */
-  onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+  retryOn?: (error: unknown, attempt: number) => boolean;
   /**
-   * HTTP methods that may be retried, in any case. Default: GET, HEAD, OPTIONS, PUT, DELETE and
-   * QUERY. POST and PATCH aren't idempotent, so add them only if your API dedupes repeats. A request
-   * whose method isn't listed is never retried, whatever `retryOn` or `statuses` say.
+   * Response statuses the default predicate retries. Default 408, 429, 500, 502, 503 and 504.
+   * Ignored when `retryOn` is set.
    */
-  methods?: ReadonlyArray<Method>;
+  statuses?: ReadonlyArray<number>;
 };
 
 /** Per-request override: `false` turns retries off, an object overrides the plugin's options. */
-export type RetryRequestOptions = { retry?: RetryOptions | false; };
+export type RetryRequestOptions = { retry?: false | RetryOptions; };
 
 function retryByDefault(error: unknown, statuses: ReadonlyArray<number>): boolean {
   if (isCancel(error) || !(error instanceof FaxiosError)) return false;
@@ -164,13 +164,13 @@ function retriesMethod(config: InternalFaxiosRequestConfig, perRequest: RetryOpt
 
 type Policy = {
   attempts: number;
-  retryOn: (error: unknown, attempt: number) => boolean;
-  delay: number | ((attempt: number, error: unknown) => number);
-  maxDelay: number;
+  delay: ((attempt: number, error: unknown) => number) | number;
   jitter: "full" | "none";
+  maxDelay: number;
   maxRetryAfter: number;
-  respectRetryAfter: boolean;
   onRetry: ((error: unknown, attempt: number, delayMs: number) => void) | undefined;
+  respectRetryAfter: boolean;
+  retryOn: (error: unknown, attempt: number) => boolean;
 };
 
 // Per field, request first: no merged object, and only own properties count.

package/src/lib/plugins/timing.ts

@@ -11,17 +11,17 @@ import { definePlugin } from "./definePlugin.js";
  * headers or body, so an event is safe to log.
  */
 export type TimingEvent = {
-  /** The request method, upper-cased (`"GET"`). */
-  method: string;
-  /** The full request URL without its query string and fragment. */
-  url: string;
   /**
    * The try number from `retry`: each try's when installed after it, the final try's when
    * installed before it. Absent without `retry`.
    */
   attempt?: number;
   durationMs: number;
-} & ({ status: number; error?: undefined; } | { status?: undefined; error: unknown; });
+  /** The request method, upper-cased (`"GET"`). */
+  method: string;
+  /** The full request URL without its query string and fragment. */
+  url: string;
+} & ({ error: unknown; status?: undefined; } | { error?: undefined; status: number; });
 
 const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
 

package/src/lib/types/standard-schema.ts

@@ -13,12 +13,12 @@ export interface StandardSchemaV1<Input = unknown, Output = Input> {
 
 export declare namespace StandardSchemaV1 {
   interface Props<Input = unknown, Output = Input> {
-    readonly version: 1;
-    readonly vendor: string;
     readonly types?: Types<Input, Output>;
     readonly validate: (
       value: unknown
-    ) => Result<Output> | Promise<Result<Output>>;
+    ) => Promise<Result<Output>> | Result<Output>;
+    readonly vendor: string;
+    readonly version: 1;
   }
 
   interface Types<Input = unknown, Output = Input> {
@@ -26,11 +26,11 @@ export declare namespace StandardSchemaV1 {
     readonly output: Output;
   }
 
-  type Result<Output> = SuccessResult<Output> | FailureResult;
+  type Result<Output> = FailureResult | SuccessResult<Output>;
 
   interface SuccessResult<Output> {
-    readonly value: Output;
     readonly issues?: undefined;
+    readonly value: Output;
   }
 
   interface FailureResult {
@@ -40,7 +40,7 @@ export declare namespace StandardSchemaV1 {
   interface Issue {
     readonly message: string;
     readonly path?:
-      | ReadonlyArray<PropertyKey | PathSegment>
+      | ReadonlyArray<PathSegment | PropertyKey>
       | undefined;
   }