@speleodb/api 0.0.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,22 @@
+export { createApiClient } from "./runtime/request";
+export {
+  browserTransport,
+  fetchTransport,
+  xhrTransport,
+} from "./runtime/browser";
+export * from "./generated/operations";
+export * from "./generated/models";
+export type {
+  ApiBodyKind,
+  ApiClient,
+  ApiClientOptions,
+  ApiOperationMetadata,
+  ApiRequestOptions,
+  ApiResponse,
+  ApiResponseMetadata,
+  ApiTransport,
+  ApiTransportRequest,
+  ApiTransportResponse,
+  ApiUnexpectedResponse,
+  ApiUploadProgress,
+} from "./runtime/types";

package/src/runtime/browser.ts

@@ -0,0 +1,142 @@
+import { decodeResponse } from "./response";
+import type { ApiTransportRequest, ApiTransportResponse } from "./types";
+
+export async function fetchTransport(
+  request: ApiTransportRequest,
+): Promise<ApiTransportResponse> {
+  const init: RequestInit = {
+    method: request.method,
+    headers: request.headers,
+    signal: request.signal,
+    ...(request.body !== undefined ? { body: request.body } : {}),
+    ...(request.credentials !== undefined
+      ? { credentials: request.credentials }
+      : {}),
+    ...(request.redirect !== undefined ? { redirect: request.redirect } : {}),
+  };
+  if (request.cookiePolicy === "omit") init.credentials = "omit";
+  const response = await fetch(request.url, init);
+  if (request.responsePolicy === "status-first-json" && !response.ok) {
+    void response.body?.cancel().catch(() => {});
+  }
+  return decodeResponse(
+    request,
+    response.status,
+    response.headers,
+    () => response.text(),
+    () => response.blob(),
+  );
+}
+
+/** XHR is restricted to browser uploads that require progress events. */
+export function xhrTransport(
+  request: ApiTransportRequest,
+): Promise<ApiTransportResponse> {
+  if (request.redirect && request.redirect !== "follow") {
+    return Promise.reject(
+      new TypeError(
+        "XHR cannot enforce redirect refusal. Use the fetch transport.",
+      ),
+    );
+  }
+  if (request.cookiePolicy === "omit" || request.credentials === "omit") {
+    return Promise.reject(
+      new TypeError(
+        "XHR cannot omit same-origin cookies. Use the fetch transport.",
+      ),
+    );
+  }
+  return new Promise((resolve, reject) => {
+    request.signal.throwIfAborted();
+    const xhr = new XMLHttpRequest();
+    const abort = () => {
+      xhr.abort();
+      reject(request.signal.reason);
+    };
+    const cleanup = () => request.signal.removeEventListener("abort", abort);
+    xhr.open(request.method, request.url);
+    xhr.responseType = "arraybuffer";
+    xhr.timeout =
+      request.timeoutMs === null
+        ? 0
+        : Math.max(1, Math.ceil(request.timeoutMs));
+    xhr.withCredentials = request.credentials === "include";
+    request.headers.forEach((value, name) => xhr.setRequestHeader(name, value));
+    xhr.upload.onprogress = (event) => {
+      if (request.signal.aborted) return;
+      try {
+        request.onUploadProgress?.({
+          loaded: event.loaded,
+          lengthComputable: event.lengthComputable,
+          ...(event.lengthComputable ? { total: event.total } : {}),
+        });
+      } catch {
+        /* Observer failures cannot change HTTP ownership. */
+      }
+    };
+    xhr.upload.onload = () => {
+      if (request.signal.aborted) return;
+      try {
+        request.onUploadComplete?.();
+      } catch {
+        /* Observer only. */
+      }
+    };
+    xhr.onerror = () => {
+      cleanup();
+      reject(new TypeError("Network request failed."));
+    };
+    xhr.ontimeout = () => {
+      cleanup();
+      reject(new DOMException("Request timed out.", "TimeoutError"));
+    };
+    xhr.onabort = () => {
+      cleanup();
+      reject(
+        request.signal.reason ??
+          new DOMException("Request aborted.", "AbortError"),
+      );
+    };
+    xhr.onload = () => {
+      cleanup();
+      const headers = new Headers();
+      for (const line of xhr
+        .getAllResponseHeaders()
+        .trim()
+        .split(/[\r\n]+/)) {
+        const separator = line.indexOf(":");
+        if (separator > 0)
+          headers.append(
+            line.slice(0, separator).trim(),
+            line.slice(separator + 1).trim(),
+          );
+      }
+      const bytes = (xhr.response as ArrayBuffer | null) ?? new ArrayBuffer(0);
+      decodeResponse(
+        request,
+        xhr.status,
+        headers,
+        async () => new TextDecoder().decode(bytes),
+        async () =>
+          new Blob([bytes], {
+            type: headers.get("content-type") ?? "",
+          }),
+      ).then(resolve, reject);
+    };
+    request.signal.addEventListener("abort", abort, { once: true });
+    try {
+      xhr.send(request.body as XMLHttpRequestBodyInit | null | undefined);
+    } catch (error) {
+      cleanup();
+      reject(error);
+    }
+  });
+}
+
+export function browserTransport(
+  request: ApiTransportRequest,
+): Promise<ApiTransportResponse> {
+  return request.onUploadProgress || request.onUploadComplete
+    ? xhrTransport(request)
+    : fetchTransport(request);
+}

package/src/runtime/form-data.ts

@@ -0,0 +1,58 @@
+/** Web-native equivalent of Orval's generic union multipart serializer. */
+export function unionFormData(
+  body?: object,
+  nullAsEmpty: readonly string[] = [],
+): FormData {
+  const form = new FormData();
+  function append(name: string, value: unknown, item = false): void {
+    if (value === undefined) return;
+    if (value === null) {
+      if (item || !nullAsEmpty.includes(name))
+        throw new TypeError(
+          `Field ${name} cannot represent null in a form request.`,
+        );
+      form.append(name, "");
+      return;
+    }
+    if (value instanceof Blob) form.append(name, value);
+    else if (Array.isArray(value))
+      value.forEach((value: unknown) => append(name, value, true));
+    else
+      form.append(
+        name,
+        typeof value === "object" ? JSON.stringify(value) : String(value),
+      );
+  }
+  for (const [name, value] of Object.entries(body ?? {})) append(name, value);
+  return form;
+}
+
+/** Encode nested JSON fields and primitive unions without dropping numbers. */
+export function unionUrlEncoded(
+  body?: object,
+  nullAsEmpty: readonly string[] = [],
+): URLSearchParams {
+  const form = new URLSearchParams();
+  function append(name: string, value: unknown, item = false): void {
+    if (value === undefined) return;
+    if (value === null) {
+      if (item || !nullAsEmpty.includes(name))
+        throw new TypeError(
+          `Field ${name} cannot represent null in a form request.`,
+        );
+      form.append(name, "");
+      return;
+    }
+    if (value instanceof Blob)
+      throw new TypeError("Files require multipart/form-data.");
+    if (Array.isArray(value))
+      value.forEach((value: unknown) => append(name, value, true));
+    else
+      form.append(
+        name,
+        typeof value === "object" ? JSON.stringify(value) : String(value),
+      );
+  }
+  for (const [name, value] of Object.entries(body ?? {})) append(name, value);
+  return form;
+}

package/src/runtime/request.ts

@@ -0,0 +1,196 @@
+import { browserTransport } from "./browser";
+import { isDocumentedResponse } from "./response";
+import type {
+  ApiClient,
+  ApiClientOptions,
+  ApiRequestOptions,
+  ApiResponse,
+  ApiTransportRequest,
+  ApiTransportResponse,
+} from "./types";
+
+const MAX_TIMEOUT = 2_147_483_647;
+
+function checkedTimeout(value: number | null): number | null {
+  if (value === null) return null;
+  if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMEOUT) {
+    throw new RangeError(
+      "Request timeout must be a positive finite timer duration.",
+    );
+  }
+  return value;
+}
+
+/** Generated defaults precede caller entries, including differently cased names. */
+function mergedHeaders(...sources: (HeadersInit | undefined)[]): Headers {
+  const headers = new Headers();
+  for (const source of sources) {
+    if (!source) continue;
+    if (source instanceof Headers) {
+      source.forEach((value, name) => headers.set(name, value));
+    } else if (Symbol.iterator in source) {
+      for (const [name, value] of source as Iterable<
+        readonly [string, string]
+      >) {
+        headers.set(name, value);
+      }
+    } else {
+      for (const [name, value] of Object.entries(source))
+        headers.set(name, value);
+    }
+  }
+  return headers;
+}
+
+export function createApiClient(options: ApiClientOptions): ApiClient {
+  const base = new URL(options.baseUrl);
+  if (
+    !["http:", "https:"].includes(base.protocol) ||
+    base.username ||
+    base.password ||
+    base.pathname !== "/" ||
+    base.search ||
+    base.hash
+  ) {
+    throw new TypeError(
+      "API base URL must be an HTTP(S) origin without credentials, path, query, or fragment.",
+    );
+  }
+  return Object.freeze({
+    baseUrl: base.toString(),
+    transport: options.transport ?? browserTransport,
+    headers: options.headers,
+    timeoutMs: checkedTimeout(
+      options.timeoutMs === undefined ? 10_000 : options.timeoutMs,
+    ),
+    credentials: options.credentials,
+  });
+}
+
+function abortable<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", abort);
+        if (signal.aborted) reject(signal.reason);
+        else resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      },
+    );
+    // The admitted operation may abort synchronously before returning its promise.
+    // Attach both handlers before checking the signal so a late rejection is consumed.
+    if (signal.aborted) {
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason);
+    }
+  });
+}
+
+/** Orval's explicit two-argument signature makes client context available per call. */
+export async function apiRequest<
+  T extends ApiTransportResponse = ApiTransportResponse,
+>(url: string, options: ApiRequestOptions): Promise<ApiResponse<T>> {
+  if (!options?.client)
+    throw new TypeError("An ApiClient is required for every API operation.");
+  if (!options.operation)
+    throw new TypeError("Generated API operation metadata is required.");
+  const { client, operation } = options;
+  const timeoutMs = checkedTimeout(
+    options.timeoutMs === undefined ? client.timeoutMs : options.timeoutMs,
+  );
+  const startedAt = performance.now();
+  const controller = new AbortController();
+  const onAbort = () =>
+    controller.abort(
+      options.signal?.reason ??
+        new DOMException("Request aborted.", "AbortError"),
+    );
+  if (options.signal?.aborted) onAbort();
+  else options.signal?.addEventListener("abort", onAbort, { once: true });
+  const timer =
+    timeoutMs === null
+      ? undefined
+      : setTimeout(
+          () =>
+            controller.abort(
+              new DOMException("Request timed out.", "TimeoutError"),
+            ),
+          timeoutMs,
+        );
+  try {
+    controller.signal.throwIfAborted();
+    const response = await abortable(
+      (async () => {
+        const configuredHeaders =
+          typeof client.headers === "function"
+            ? await client.headers()
+            : client.headers;
+        controller.signal.throwIfAborted();
+        const headers = mergedHeaders(configuredHeaders, options.headers);
+        if (options.body instanceof FormData) headers.delete("content-type");
+        const target = new URL(url, client.baseUrl);
+        if (
+          target.origin !== new URL(client.baseUrl).origin ||
+          target.username ||
+          target.password
+        ) {
+          throw new TypeError(
+            "Generated API requests must remain on the configured API origin.",
+          );
+        }
+        const remaining =
+          timeoutMs === null
+            ? null
+            : timeoutMs - (performance.now() - startedAt);
+        if (remaining !== null && remaining <= 0)
+          throw new DOMException("Request timed out.", "TimeoutError");
+        const request: ApiTransportRequest = {
+          url: target.toString(),
+          method: options.method ?? "GET",
+          headers,
+          signal: controller.signal,
+          timeoutMs: remaining,
+          operation,
+          ...(options.body !== undefined ? { body: options.body } : {}),
+          ...((options.credentials ?? client.credentials) !== undefined
+            ? { credentials: options.credentials ?? client.credentials! }
+            : {}),
+          ...(options.redirect !== undefined
+            ? { redirect: options.redirect }
+            : {}),
+          ...(options.responsePolicy
+            ? { responsePolicy: options.responsePolicy }
+            : {}),
+          ...(options.cookiePolicy
+            ? { cookiePolicy: options.cookiePolicy }
+            : {}),
+          ...(options.onUploadProgress
+            ? { onUploadProgress: options.onUploadProgress }
+            : {}),
+          ...(options.onUploadComplete
+            ? { onUploadComplete: options.onUploadComplete }
+            : {}),
+        };
+        return client.transport(request);
+      })(),
+      controller.signal,
+    );
+    // Synchronous response decoding can occupy the event loop beyond the timer.
+    // Check the clock as well before publishing the result.
+    if (timeoutMs !== null && performance.now() - startedAt >= timeoutMs) {
+      controller.abort(new DOMException("Request timed out.", "TimeoutError"));
+    }
+    controller.signal.throwIfAborted();
+    return isDocumentedResponse(operation, response)
+      ? ({ ...response, kind: "documented" } as ApiResponse<T>)
+      : { ...response, kind: "unexpected" };
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+}

package/src/runtime/response.ts

@@ -0,0 +1,104 @@
+import type {
+  ApiOperationMetadata,
+  ApiResponseMetadata,
+  ApiTransportRequest,
+  ApiTransportResponse,
+} from "./types";
+
+export function responseMetadata(
+  operation: ApiOperationMetadata,
+  status: number,
+): ApiResponseMetadata | undefined {
+  return (
+    operation.responses[String(status)] ??
+    operation.responses[`${Math.floor(status / 100)}XX`] ??
+    operation.responses.default
+  );
+}
+
+function mediaType(headers: Headers): string {
+  return (headers.get("content-type") ?? "")
+    .split(";")[0]!
+    .trim()
+    .toLowerCase();
+}
+
+function matchingMediaType(
+  metadata: ApiResponseMetadata,
+  actual: string,
+): string | undefined {
+  if (metadata.content[actual]) return actual;
+  const range = `${actual.split("/")[0]}/*`;
+  if (metadata.content[range]) return range;
+  return metadata.content["*/*"] ? "*/*" : undefined;
+}
+
+export function isDocumentedResponse(
+  operation: ApiOperationMetadata,
+  response: ApiTransportResponse,
+): boolean {
+  if (response.unexpected) return false;
+  const metadata = responseMetadata(operation, response.status);
+  if (!metadata) return false;
+  const expected = Object.keys(metadata.content);
+  if (!expected.length) return response.data === undefined;
+  const contentType = mediaType(response.headers);
+  return matchingMediaType(metadata, contentType) !== undefined;
+}
+
+/** Status-first GIS denials must never wait for, decode, or reflect an error body. */
+export async function decodeResponse(
+  request: ApiTransportRequest,
+  status: number,
+  headers: Headers,
+  readText: () => Promise<string>,
+  readBlob: () => Promise<Blob>,
+): Promise<ApiTransportResponse> {
+  if (
+    request.responsePolicy === "status-first-json" &&
+    (status < 200 || status >= 300)
+  ) {
+    return { status, headers, data: null, unexpected: true };
+  }
+  if (request.method === "HEAD" || [204, 205, 304].includes(status)) {
+    return { status, headers, data: undefined };
+  }
+  const metadata = responseMetadata(request.operation, status);
+  const type = mediaType(headers);
+  const declaredType = metadata ? matchingMediaType(metadata, type) : undefined;
+  const declared = declaredType ? metadata?.content[declaredType] : undefined;
+  // Some declared JSON media, including application/geojson, have no +json suffix.
+  const isJson =
+    declared === "json" || /^application\/(?:[\w.-]+\+)?json$/.test(type);
+  if (request.responsePolicy === "status-first-json" && !isJson) {
+    throw new TypeError("The server did not return JSON.");
+  }
+  if (
+    declared === "blob" ||
+    (!isJson && !type.startsWith("text/") && type !== "" && declared !== "text")
+  ) {
+    return { status, headers, data: await readBlob() };
+  }
+  const text = await readText();
+  if (!text && metadata && Object.keys(metadata.content).length === 0) {
+    return { status, headers, data: undefined };
+  }
+  if (isJson) {
+    try {
+      return { status, headers, data: JSON.parse(text) as unknown };
+    } catch {
+      if (status >= 200 && status < 300)
+        throw new TypeError("The server returned invalid JSON.");
+      // Preserve error status without claiming the unparsed text is a declared DTO.
+      return { status, headers, data: text, unexpected: true };
+    }
+  }
+  return {
+    status,
+    headers,
+    data:
+      declared === "text" || type.startsWith("text/")
+        ? text
+        : text || undefined,
+  };
+}

package/src/runtime/types.ts

@@ -0,0 +1,86 @@
+export type ApiBodyKind = "json" | "text" | "blob";
+
+export interface ApiResponseMetadata {
+  content: Record<string, ApiBodyKind>;
+}
+
+/** Generated from the same OpenAPI document as the operation functions. */
+export interface ApiOperationMetadata {
+  operationId: string;
+  responses: Record<string, ApiResponseMetadata>;
+}
+
+export interface ApiUploadProgress {
+  loaded: number;
+  total?: number;
+  lengthComputable: boolean;
+}
+
+export interface ApiTransportRequest {
+  url: string;
+  method: string;
+  headers: Headers;
+  body?: BodyInit | null;
+  signal: AbortSignal;
+  /** Remaining overall deadline, including preparation; null disables the deadline. */
+  timeoutMs: number | null;
+  operation: ApiOperationMetadata;
+  credentials?: RequestCredentials;
+  redirect?: RequestRedirect;
+  responsePolicy?: "default" | "status-first-json";
+  cookiePolicy?: "omit";
+  onUploadProgress?: (progress: ApiUploadProgress) => void;
+  onUploadComplete?: () => void;
+}
+
+export interface ApiTransportResponse {
+  status: number;
+  data: unknown;
+  headers: Headers;
+  /** A transport preserved HTTP status without obtaining the declared body. */
+  unexpected?: boolean;
+}
+
+export type ApiTransport = (
+  request: ApiTransportRequest,
+) => Promise<ApiTransportResponse>;
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  transport?: ApiTransport;
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  /** Defaults to 10 seconds. null disables the deadline but retains cancellation. */
+  timeoutMs?: number | null;
+  credentials?: RequestCredentials;
+}
+
+export interface ApiClient {
+  readonly baseUrl: string;
+  readonly transport: ApiTransport;
+  readonly headers: ApiClientOptions["headers"];
+  readonly timeoutMs: number | null;
+  readonly credentials: RequestCredentials | undefined;
+}
+
+export type ApiRequestOptions = Pick<
+  RequestInit,
+  "method" | "headers" | "body" | "credentials" | "redirect"
+> & {
+  client?: ApiClient;
+  signal?: AbortSignal | null;
+  /** Overrides the client deadline; null explicitly disables it. */
+  timeoutMs?: number | null;
+  /** Supplied by generated code; consumers should not override this metadata. */
+  operation?: ApiOperationMetadata;
+  responsePolicy?: "default" | "status-first-json";
+  cookiePolicy?: "omit";
+  onUploadProgress?: (progress: ApiUploadProgress) => void;
+  onUploadComplete?: () => void;
+};
+
+export interface ApiUnexpectedResponse extends ApiTransportResponse {
+  kind: "unexpected";
+}
+
+export type ApiResponse<T extends ApiTransportResponse = ApiTransportResponse> =
+  (T & { kind: "documented" }) | ApiUnexpectedResponse;