@gcmdev/faxios 0.2.1 → 0.2.2

package/src/lib/helpers/progressEventReducer.ts

@@ -11,7 +11,7 @@ export const progressEventReducer = (listener: (data: FaxiosProgressEvent) => vo
     if (!e || typeof (e as Record<string, unknown>).loaded !== "number") {
       return;
     }
-    const ev = e as { loaded: number; total?: number; lengthComputable?: boolean; };
+    const ev = e as { lengthComputable?: boolean; loaded: number; total?: number; };
     const rawLoaded = ev.loaded;
     const total = ev.lengthComputable ? ev.total : undefined;
     const loaded = total != null ? Math.min(rawLoaded, total) : rawLoaded;

package/src/lib/helpers/sanitizeHeaderValue.ts

@@ -36,7 +36,7 @@ const INVALID_UNICODE_HEADER_VALUE_CHARS = new RegExp("[\\u0000-\\u0008\\u000a-\
 const INVALID_BYTE_STRING_HEADER_VALUE_CHARS = new RegExp("[^\\u0009\\u0020-\\u007e\\u0080-\\u00ff]+", "g");
 
 // eslint-disable-next-line sonarjs/function-return-type
-function sanitizeValue(value: unknown, invalidChars: RegExp): string | Array<string> {
+function sanitizeValue(value: unknown, invalidChars: RegExp): Array<string> | string {
   if (utils.isArray(value)) {
     return (value as Array<unknown>).map(item => sanitizeValue(item, invalidChars) as string);
   }

package/src/lib/helpers/substitutePathParams.ts

@@ -1,13 +1,23 @@
+import FaxiosError from "../core/FaxiosError.js";
+
+// `.` and `..` (raw or percent-encoded) would become a dot segment that the URL parser resolves,
+// moving the request to another path.
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+
 /** Expects raw (unencoded) param values — applies encodeURIComponent here. */
 export function substitutePathParams(url: string, params: Record<string, unknown>): string {
   return url.replace(/\{([^{}]+)\}/g, (_match, key: string) => {
     if (!Object.prototype.hasOwnProperty.call(params, key)) {
-      throw new Error(`Path param "${key}" not found in pathParams`);
+      throw new FaxiosError(`Path param "${key}" not found in pathParams`, FaxiosError.ERR_BAD_OPTION_VALUE);
     }
     const val = params[key];
     if (val == null) {
-      throw new Error(`Path param "${key}" is null or undefined`);
+      throw new FaxiosError(`Path param "${key}" is null or undefined`, FaxiosError.ERR_BAD_OPTION_VALUE);
     }
-    return encodeURIComponent(String(val));
+    const str = String(val);
+    if (DOT_SEGMENT.test(str)) {
+      throw new FaxiosError(`Path param "${key}" must not be "." or ".." (or a percent-encoded form)`, FaxiosError.ERR_BAD_OPTION_VALUE);
+    }
+    return encodeURIComponent(str);
   });
 }

package/src/lib/helpers/throttle.ts

@@ -8,7 +8,7 @@ function throttle(fn: (...args: Array<unknown>) => void, freq: number): [(...arg
   let timestamp = 0;
   const threshold = 1000 / freq;
   let lastArgs: Array<unknown> | null = null;
-  let timer: ReturnType<typeof setTimeout> | null = null;
+  let timer: null | ReturnType<typeof setTimeout> = null;
 
   const invoke = (args: Array<unknown>, now: number = Date.now()) => {
     timestamp = now;

package/src/lib/helpers/toFormData.ts

@@ -2,7 +2,7 @@
 
 import FaxiosError from "../core/FaxiosError.js";
 // temporary hotfix to avoid circular references until FaxiosURLSearchParams is refactored
-import type { GenericFormData, SerializerVisitor, FormDataVisitorHelpers } from "../types.js";
+import type { FormDataVisitorHelpers, GenericFormData, SerializerVisitor } from "../types.js";
 import utils from "../utils.js";
 
 // Default nesting limit shared with the inverse transform (formDataToJSON) so
@@ -40,11 +40,11 @@ function removeBrackets(key: string): string {
  *
  * @returns {string} The path to the current key.
  */
-function renderKey(path: Array<string | number> | null | undefined, key: string | number, dots: unknown): string {
+function renderKey(path: Array<number | string> | null | undefined, key: number | string, dots: unknown): string {
   if (!path) return String(key);
   return path
     .concat(key)
-    .map(function each(token: string | number, i: number) {
+    .map(function each(token: number | string, i: number) {
       token = removeBrackets(String(token));
       return !dots && i ? "[" + token + "]" : token;
     })
@@ -100,13 +100,15 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     formData = new FormDataCtor();
   }
 
+  // Null-prototype destination: `visitor`, `maxDepth` and `Blob` are read below, and a polluted
+  // Object.prototype must not supply them.
   options = utils.toFlatObject(
     options,
-    {
+    Object.assign(Object.create(null) as Record<string, unknown>, {
       metaTokens: true,
       dots: false,
       indexes: false,
-    },
+    }),
     false,
     function defined(option: string, source: unknown) {
       return !utils.isUndefined((source as Record<string, unknown>)[option]);
@@ -201,7 +203,7 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
    *
    * @returns {boolean} return true to visit the each prop of the value recursively
    */
-  function defaultVisitor(this: GenericFormData, value: unknown, key: string | number, path: null | Array<string | number>, _helpers?: FormDataVisitorHelpers): boolean {
+  function defaultVisitor(this: GenericFormData, value: unknown, key: number | string, path: Array<number | string> | null, _helpers?: FormDataVisitorHelpers): boolean {
     let arr: unknown = value;
 
     if (utils.isReactNative(formData) && utils.isReactNativeBlob(value)) {
@@ -254,7 +256,7 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
     isVisitable,
   });
 
-  function build(value: unknown, path?: Array<string | number>, depth = 0): void {
+  function build(value: unknown, path?: Array<number | string>, depth = 0): void {
     if (utils.isUndefined(value)) return;
 
     throwIfMaxDepthExceeded(depth);
@@ -271,13 +273,13 @@ function toFormData(obj: unknown, formData?: GenericFormData | null, options?: R
         visitor.call(
           formData as GenericFormData,
           el,
-          utils.isString(key) ? (key as string).trim() : key as string | number,
+          utils.isString(key) ? (key as string).trim() : key as number | string,
           path ?? null,
           exposedHelpers
         );
 
       if (result === true) {
-        build(el, path ? path.concat(key as string | number) : [ key as string | number ], depth + 1);
+        build(el, path ? path.concat(key as number | string) : [ key as number | string ], depth + 1);
       }
     });
 

package/src/lib/helpers/trackStream.ts

@@ -1,11 +1,11 @@
 type ReadableStreamController = {
-  enqueue: (chunk: Uint8Array) => void;
   close: () => void;
+  enqueue: (chunk: Uint8Array) => void;
 };
 
 type ReadableStreamSource = {
-  pull?: (controller: ReadableStreamController) => Promise<void>;
   cancel?: (reason?: unknown) => Promise<unknown>;
+  pull?: (controller: ReadableStreamController) => Promise<void>;
 };
 
 type ReadableStreamInit = {
@@ -43,8 +43,8 @@ const readBytes = async function* (iterable: AsyncIterable<ByteChunk> | unknown,
 };
 
 type ReaderLike = {
-  read: () => Promise<{ done: boolean; value: ByteChunk; }>;
   cancel: () => Promise<void>;
+  read: () => Promise<{ done: boolean; value: ByteChunk; }>;
 };
 
 type StreamLike = {

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;
   }