@gcmdev/faxios 0.2.0 → 0.2.2

package/src/lib/helpers/trackStream.ts

@@ -0,0 +1,123 @@
+type ReadableStreamController = {
+  close: () => void;
+  enqueue: (chunk: Uint8Array) => void;
+};
+
+type ReadableStreamSource = {
+  cancel?: (reason?: unknown) => Promise<unknown>;
+  pull?: (controller: ReadableStreamController) => Promise<void>;
+};
+
+type ReadableStreamInit = {
+  highWaterMark?: number;
+};
+
+type ReadableStreamCtor = new (source: ReadableStreamSource, init?: ReadableStreamInit) => unknown;
+
+const ReadableStreamGlobal = (globalThis as Record<string, unknown>)["ReadableStream"] as ReadableStreamCtor | undefined;
+
+type ByteChunk = { byteLength: number; slice: (start: number, end?: number) => ByteChunk; };
+
+const streamChunk = function* (chunk: ByteChunk, chunkSize?: number): Generator<ByteChunk> {
+  const len = chunk.byteLength;
+
+  if (!chunkSize || len < chunkSize) {
+    yield chunk;
+    return;
+  }
+
+  let pos = 0;
+  let end: number;
+
+  while (pos < len) {
+    end = pos + chunkSize;
+    yield chunk.slice(pos, end);
+    pos = end;
+  }
+};
+
+const readBytes = async function* (iterable: AsyncIterable<ByteChunk> | unknown, chunkSize?: number): AsyncGenerator<ByteChunk> {
+  for await (const chunk of readStream(iterable)) {
+    yield* streamChunk(chunk, chunkSize);
+  }
+};
+
+type ReaderLike = {
+  cancel: () => Promise<void>;
+  read: () => Promise<{ done: boolean; value: ByteChunk; }>;
+};
+
+type StreamLike = {
+  [Symbol.asyncIterator]?: () => AsyncIterator<ByteChunk>;
+  getReader?: () => ReaderLike;
+};
+
+const readStream = async function* (stream: unknown): AsyncGenerator<ByteChunk> {
+  const s = stream as StreamLike;
+  if (s[Symbol.asyncIterator]) {
+    yield* s as AsyncIterable<ByteChunk>;
+    return;
+  }
+
+  const reader = s.getReader!();
+  try {
+    for (;;) {
+      // eslint-disable-next-line no-await-in-loop
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      yield value;
+    }
+  }
+  finally {
+    await reader.cancel();
+  }
+};
+
+export const trackStream = (stream: unknown, chunkSize: number | undefined, onProgress?: ((bytes: number) => void) | null, onFinish?: ((err?: unknown) => void) | null): unknown => {
+  const iterator = readBytes(stream, chunkSize);
+
+  let bytes = 0;
+  let done = false;
+  const _onFinish = (e?: unknown): void => {
+    if (!done) {
+      done = true;
+      onFinish && onFinish(e);
+    }
+  };
+
+  return new ReadableStreamGlobal!(
+    {
+      async pull(controller: ReadableStreamController) {
+        try {
+          const { done: iterDone, value } = await iterator.next();
+
+          if (iterDone) {
+            _onFinish();
+            controller.close();
+            return;
+          }
+
+          const len = value.byteLength;
+          if (onProgress) {
+            const loadedBytes = (bytes += len);
+            onProgress(loadedBytes);
+          }
+          controller.enqueue(new Uint8Array(value as unknown as ArrayBuffer));
+        }
+        catch (err) {
+          _onFinish(err);
+          throw err;
+        }
+      },
+      async cancel(reason?: unknown) {
+        _onFinish(reason);
+        return iterator.return(undefined);
+      },
+    },
+    {
+      highWaterMark: 2,
+    }
+  );
+};

package/src/lib/helpers/validator.ts

@@ -0,0 +1,114 @@
+"use strict";
+
+import FaxiosError from "../core/FaxiosError.js";
+import { VERSION } from "../env/data.js";
+
+export type ValidatorFn = (value: unknown, opt?: string, opts?: unknown) => boolean | string;
+
+const validators: Record<string, undefined | ValidatorFn> = {};
+
+[ "object", "boolean", "number", "function", "string", "symbol" ].forEach((type, i) => {
+  validators[type] = function validator(thing: unknown): boolean | string {
+    return typeof thing === type || "a" + (i < 1 ? "n " : " ") + type;
+  };
+});
+
+const deprecatedWarnings: Record<string, boolean | undefined> = {};
+
+/**
+ * Transitional option validator
+ *
+ * @param {function|boolean?} validator - set to false if the transitional option has been removed
+ * @param {string?} version - deprecated version / removed since version
+ * @param {string?} message - some message with additional info
+ *
+ * @returns {function}
+ */
+(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" +
+      VERSION +
+      "] Transitional option '" +
+      opt +
+      "'" +
+      desc +
+      (message ? ". " + message : "")
+    );
+  }
+
+  return (value: unknown, opt?: string, opts?: unknown): boolean | string => {
+    if (validator === false) {
+      throw new FaxiosError(
+        formatMessage(opt ?? "", " has been removed" + (version ? " in " + version : "")),
+        FaxiosError.ERR_DEPRECATED
+      );
+    }
+
+    if (version && opt && !deprecatedWarnings[opt]) {
+      deprecatedWarnings[opt] = true;
+
+      // eslint-disable-next-line no-console
+      console.warn(
+        formatMessage(
+          opt,
+          " has been deprecated since v" + version + " and will be removed in the near future"
+        )
+      );
+    }
+
+    return validator ? validator(value, opt, opts) : true;
+  };
+};
+
+(validators as Record<string, unknown>)["spelling"] = function spelling(correctSpelling: string): ValidatorFn {
+  return (_value: unknown, opt?: string): boolean | string => {
+
+    // eslint-disable-next-line no-console
+    console.warn(`${opt ?? ""} is likely a misspelling of ${correctSpelling}`);
+    return true;
+  };
+};
+
+/**
+ * Assert object's properties type
+ *
+ * @param {object} options
+ * @param {object} schema
+ * @param {boolean?} allowUnknown
+ *
+ * @returns {object}
+ */
+
+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);
+  }
+  const keys = Object.keys(options as object);
+  let i = keys.length;
+  while (i-- > 0) {
+    const opt = keys[i]!;
+    // Use hasOwnProperty so a polluted Object.prototype.<opt> cannot supply
+    // a non-function validator and cause a TypeError.
+    const validator = Object.prototype.hasOwnProperty.call(schema, opt) ? schema[opt] : undefined;
+    if (validator) {
+      const value = (options as Record<string, unknown>)[opt];
+      const result = value === undefined || validator(value, opt, options);
+      if (result !== true) {
+        throw new FaxiosError(
+          "option " + opt + " must be " + result,
+          FaxiosError.ERR_BAD_OPTION_VALUE
+        );
+      }
+      continue;
+    }
+    if (allowUnknown !== true) {
+      throw new FaxiosError("Unknown option " + opt, FaxiosError.ERR_BAD_OPTION);
+    }
+  }
+}
+
+export default {
+  assertOptions,
+  validators,
+};

package/src/lib/platform.ts

@@ -0,0 +1,44 @@
+"use strict";
+
+import FaxiosURLSearchParams from "./helpers/FaxiosURLSearchParams.js";
+
+const _globalThis = globalThis as {
+  Blob?: new (...args: Array<unknown>) => object;
+  document?: unknown;
+  FormData?: new () => object;
+  navigator?: { product?: string; userAgent?: string; };
+  self?: { importScripts?: unknown; };
+  window?: { location?: { href?: string; }; };
+  WorkerGlobalScope?: unknown;
+};
+
+const hasBrowserEnv = typeof _globalThis.window !== "undefined" && typeof _globalThis.document !== "undefined";
+
+const _navigator = typeof _globalThis.navigator === "object" ? _globalThis.navigator : undefined;
+
+const hasStandardBrowserEnv =
+  hasBrowserEnv &&
+  (!_navigator || [ "ReactNative", "NativeScript", "NS" ].indexOf(_navigator.product ?? "") < 0);
+
+const hasStandardBrowserWebWorkerEnv = (() => (
+  typeof _globalThis.WorkerGlobalScope !== "undefined" &&
+    _globalThis.self instanceof (_globalThis.WorkerGlobalScope as new (...args: Array<unknown>) => unknown) &&
+    typeof _globalThis.self?.importScripts === "function"
+))();
+
+const origin = (hasBrowserEnv && _globalThis.window?.location?.href) || "http://localhost";
+
+export default {
+  isBrowser: true,
+  classes: {
+    URLSearchParams: typeof URLSearchParams !== "undefined" ? URLSearchParams : FaxiosURLSearchParams,
+    FormData: _globalThis.FormData !== undefined ? _globalThis.FormData : null,
+    Blob: _globalThis.Blob !== undefined ? _globalThis.Blob : null,
+  },
+  protocols: [ "http", "https", "file", "blob", "url", "data" ],
+  hasBrowserEnv,
+  hasStandardBrowserEnv,
+  hasStandardBrowserWebWorkerEnv,
+  navigator: _navigator,
+  origin,
+};

package/src/lib/plugins/attempt.ts

@@ -0,0 +1,3 @@
+// Shared only by the built-in plugins; not exported from any entry point. retry writes the number
+// of the try it is about to make under this key of ctx.state, and timing reads it.
+export const RETRY_ATTEMPT: unique symbol = Symbol("faxios.retry.attempt");

package/src/lib/plugins/authBearer.ts

@@ -0,0 +1,129 @@
+// @ts-self-types="./authBearer.d.ts" — required for Deno: maps built .js to adjacent .d.ts in dist/
+
+import buildFullPath from "../core/buildFullPath.js";
+import FaxiosError from "../core/FaxiosError.js";
+import FaxiosHeaders from "../core/FaxiosHeaders.js";
+import isAbsoluteURL from "../helpers/isAbsoluteURL.js";
+import validator from "../helpers/validator.js";
+import type { FaxiosPlugin, InternalFaxiosRequestConfig } from "../types.js";
+import utils from "../utils.js";
+import { definePlugin } from "./definePlugin.js";
+
+/** What `authBearer` provides to plugins installed after it. */
+export type AuthBearerCapability = { auth: { getToken: () => Promise<string>; }; };
+
+export type AuthBearerOptions = {
+  /** The header to set. Default `"Authorization"`. */
+  header?: string;
+  /**
+   * The origins (`"https://api.example.com"`) that get the token, replacing the default rule:
+   * 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).
+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): null | string {
+  if (typeof value !== "string") return null;
+  try {
+    const { origin } = new URL(value);
+    return origin !== "null" && (value === origin || value === `${origin}/`) ? origin : null;
+  }
+  catch {
+    return null;
+  }
+}
+
+const optionsSchema = {
+  overwrite: validator.validators["boolean"],
+  scheme: (value: unknown) => (typeof value === "string" && !/[\r\n]/.test(value)) || "a string without line breaks",
+  header: (value: unknown) => (typeof value === "string" && TOKEN.test(value)) || "a header name",
+  origins: (value: unknown) => (Array.isArray(value) && value.every(o => originOf(o) !== null)) || "an array of origins such as \"https://api.example.com\"",
+};
+
+const own = <T extends object, K extends keyof T>(source: T, key: K): T[K] | undefined =>
+  (utils.hasOwnProp(source, key) ? source[key] : undefined);
+
+// Resolves a relative URL the way a page would, without ever matching a real origin, so a URL
+// 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): null | string {
+  try {
+    return new URL(url, base).origin;
+  }
+  catch {
+    return null;
+  }
+}
+
+// A relative URL goes to the page's origin, which only a browser has.
+function pageHref(): string | undefined {
+  const location: unknown = "location" in globalThis ? globalThis.location : undefined;
+  if (location && typeof location === "object" && "href" in location && typeof location.href === "string") return location.href;
+  return undefined;
+}
+
+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) {
+    const origin = resolvedOrigin(url, isAbsoluteURL(url) ? undefined : pageHref());
+    return origin !== null && origins.includes(origin);
+  }
+  if (typeof baseURL === "string" && isAbsoluteURL(baseURL)) {
+    return resolvedOrigin(url, baseURL) === resolvedOrigin(baseURL, undefined);
+  }
+  return !isAbsoluteURL(url) && resolvedOrigin(url, SAME_ORIGIN) === SAME_ORIGIN;
+}
+
+/**
+ * Sets `Authorization: Bearer <token>` on requests to the API it guards, asking `getToken` each
+ * time, and provides the `auth` capability so later plugins (for example a token-refresh plugin)
+ * 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: () => 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);
+  }
+  // Callers without TypeScript can pass anything.
+  const given: unknown = options;
+  if (given === null || typeof given !== "object") {
+    throw new FaxiosError("authBearer options must be an object", FaxiosError.ERR_BAD_OPTION_VALUE);
+  }
+  validator.assertOptions(options, optionsSchema, false);
+  const overwrite = own(options, "overwrite") ?? false;
+  const scheme = own(options, "scheme") ?? "Bearer";
+  const header = own(options, "header") ?? "Authorization";
+  const origins = own(options, "origins")?.map(o => originOf(o)!) ?? null;
+  const auth = { getToken: async () => getToken() };
+  return definePlugin({
+    name: "authBearer",
+    provides: { auth },
+    middleware: async (ctx, next) => {
+      if ((!overwrite && ctx.config.headers.has(header)) || !sendsTokenTo(ctx.config, origins)) return next(ctx);
+      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);
+      const config = { ...ctx.config };
+      config.headers = headers;
+      return next({ ...ctx, config });
+    },
+  });
+}

package/src/lib/plugins/definePlugin.ts

@@ -0,0 +1,34 @@
+// @ts-self-types="./definePlugin.d.ts" — required for Deno: maps built .js to adjacent .d.ts in dist/
+// The `@gcmdev/faxios/plugins` entry point. The built-in plugins have their own subpaths.
+
+import type { FaxiosMiddleware, FaxiosPlugin } from "../types.js";
+
+// An empty capability or option map adds nothing, so it's the `unknown` an absent slot is.
+type Slot<T> = [keyof T] extends [never] ? unknown : T;
+
+// The middleware's capabilities are what it requires plus what it provides itself.
+type RequiredCapabilities<TCapabilities, TProvides> = [keyof TProvides] extends [never]
+  ? Slot<TCapabilities>
+  : Slot<{ [K in keyof TCapabilities as K extends keyof TProvides ? never : K]: TCapabilities[K]; }>;
+
+/**
+ * Builds a plugin for `use()` and infers its `FaxiosPlugin` slots from the object: `provides` from
+ * the `provides` value, `options` and `requires` from the context type the middleware annotates
+ * (`ctx: FaxiosContext<Options, Capabilities>`). Capabilities the plugin provides itself don't
+ * count as required. Returns the same object.
+ */
+// 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>>;
+}): FaxiosPlugin<{
+  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;
+}