@zmdb/client 1.0.0-beta.1

package/src/errors/index.ts

@@ -0,0 +1,152 @@
+import type { ClientHeaders, ValidationIssue } from '../types.js';
+
+export interface ClientErrorInit {
+  readonly operationId?: string;
+  readonly cause?: unknown;
+}
+
+function operation(operationId: string | undefined): string {
+  return operationId === undefined ? 'Client request' : `Operation ${operationId}`;
+}
+
+export class ClientError extends Error {
+  readonly operationId: string | undefined;
+
+  constructor(message: string, init: ClientErrorInit = {}) {
+    super(message, init.cause === undefined ? undefined : { cause: init.cause });
+    this.name = 'ClientError';
+    this.operationId = init.operationId;
+  }
+}
+
+export class ClientRequestError extends ClientError {
+  constructor(message: string, init: ClientErrorInit = {}) {
+    super(message, init);
+    this.name = 'ClientRequestError';
+  }
+}
+
+export class AuthenticationError extends ClientError {
+  constructor(operationId: string, cause?: unknown) {
+    super(`Authentication failed for operation ${operationId}`, { operationId, cause });
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class MissingAuthenticationError extends AuthenticationError {
+  constructor(operationId: string) {
+    super(operationId);
+    this.name = 'MissingAuthenticationError';
+    this.message = `Operation ${operationId} requires an authentication provider`;
+  }
+}
+
+export class TransportError extends ClientError {
+  constructor(operationId: string | undefined, cause: unknown) {
+    super(
+      `${operation(operationId)} failed in the transport`,
+      operationId === undefined ? { cause } : { operationId, cause },
+    );
+    this.name = 'TransportError';
+  }
+}
+
+export class ClientTimeoutError extends ClientError {
+  readonly timeoutMs: number;
+
+  constructor(operationId: string, timeoutMs: number) {
+    super(`Operation ${operationId} timed out after ${String(timeoutMs)}ms`, { operationId });
+    this.name = 'ClientTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export class ResponseTooLargeError extends ClientError {
+  readonly status: number;
+  readonly limit: number;
+
+  constructor(operationId: string, status: number, limit: number) {
+    super(`Operation ${operationId} response status ${String(status)} exceeds the ${String(limit)} byte limit`, {
+      operationId,
+    });
+    this.name = 'ResponseTooLargeError';
+    this.status = status;
+    this.limit = limit;
+  }
+}
+
+export class UnexpectedStatusError extends ClientError {
+  readonly status: number;
+  readonly headers: ClientHeaders;
+  readonly bodySnippet: string;
+
+  constructor(operationId: string, status: number, headers: ClientHeaders, bodySnippet: string) {
+    const detail = bodySnippet.length === 0 ? '' : `: ${bodySnippet}`;
+    super(`Operation ${operationId} returned undocumented status ${String(status)}${detail}`, { operationId });
+    this.name = 'UnexpectedStatusError';
+    this.status = status;
+    this.headers = Object.freeze({ ...headers });
+    this.bodySnippet = bodySnippet;
+  }
+}
+
+export class UnexpectedContentTypeError extends ClientError {
+  readonly status: number;
+  readonly expected: readonly string[];
+  readonly received: string | undefined;
+
+  constructor(operationId: string, status: number, expected: readonly string[], received: string | undefined) {
+    super(
+      `Operation ${operationId} status ${String(status)} expected content type ${expected.join(' or ')}, ` +
+        `received ${received ?? 'none'}`,
+      { operationId },
+    );
+    this.name = 'UnexpectedContentTypeError';
+    this.status = status;
+    this.expected = Object.freeze([...expected]);
+    this.received = received;
+  }
+}
+
+export class ResponseDecodeError extends ClientError {
+  readonly status: number;
+  readonly bodySnippet: string;
+
+  constructor(operationId: string, status: number, bodySnippet: string, cause?: unknown) {
+    const detail = bodySnippet.length === 0 ? '' : `: ${bodySnippet}`;
+    super(`Operation ${operationId} could not decode status ${String(status)}${detail}`, { operationId, cause });
+    this.name = 'ResponseDecodeError';
+    this.status = status;
+    this.bodySnippet = bodySnippet;
+  }
+}
+
+export class ResponseValidationError extends ClientError {
+  readonly status: number;
+  readonly issues: readonly ValidationIssue[];
+
+  constructor(operationId: string, status: number, issues: readonly ValidationIssue[]) {
+    super(
+      `Operation ${operationId} status ${String(status)} failed response validation with ` +
+        `${String(issues.length)} issue(s)`,
+      { operationId },
+    );
+    this.name = 'ResponseValidationError';
+    this.status = status;
+    this.issues = Object.freeze(issues.map(issue => Object.freeze({ ...issue })));
+  }
+}
+
+export class ClientResponseError<Status extends number, Body, Headers = ClientHeaders> extends ClientError {
+  readonly status: Status;
+  readonly body: Body;
+  readonly headers: Headers;
+
+  constructor(operationId: string, status: Status, body: Body, headers: Headers) {
+    super(`Operation ${operationId} returned documented error status ${String(status)}`, { operationId });
+    this.name = 'ClientResponseError';
+    this.status = status;
+    this.body = body;
+    this.headers = headers;
+  }
+}

package/src/headers/index.ts

@@ -0,0 +1,57 @@
+import { ClientRequestError } from '../errors/index.js';
+import type { ClientHeaders } from '../types.js';
+
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const INVALID_VALUE = /[\0\r\n]/;
+
+export const TRANSPORT_OWNED_HEADERS: ReadonlySet<string> = new Set([
+  'connection',
+  'content-length',
+  'host',
+  'proxy-connection',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+]);
+
+export function normalizeClientHeaders(headers: ClientHeaders = {}): ClientHeaders {
+  const normalized: Record<string, string> = {};
+  for (const [sourceName, value] of Object.entries(headers)) {
+    if (!HEADER_NAME.test(sourceName)) {
+      throw new ClientRequestError(`Invalid HTTP header name ${JSON.stringify(sourceName)}`);
+    }
+    if (typeof value !== 'string' || INVALID_VALUE.test(value)) {
+      throw new ClientRequestError(`Invalid value for HTTP header ${sourceName.toLowerCase()}`);
+    }
+    const name = sourceName.toLowerCase();
+    const present = normalized[name];
+    if (present !== undefined && present !== value) {
+      throw new ClientRequestError(`Conflicting values for HTTP header ${name}`);
+    }
+    normalized[name] = value;
+  }
+  return Object.freeze(normalized);
+}
+
+export function mergeClientHeaders(...sources: readonly ClientHeaders[]): ClientHeaders {
+  const merged: Record<string, string> = {};
+  for (const source of sources) {
+    for (const [name, value] of Object.entries(normalizeClientHeaders(source))) {
+      const present = merged[name];
+      if (present !== undefined && present !== value) {
+        throw new ClientRequestError(`Conflicting values for HTTP header ${name}`);
+      }
+      merged[name] = value;
+    }
+  }
+  return Object.freeze(merged);
+}
+
+export function assertNoTransportOwnedHeaders(headers: ClientHeaders): void {
+  for (const name of Object.keys(headers)) {
+    if (TRANSPORT_OWNED_HEADERS.has(name.toLowerCase())) {
+      throw new ClientRequestError(`HTTP header ${name.toLowerCase()} is owned by the transport`);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export { DEFAULT_MAX_ERROR_BODY_BYTES, DEFAULT_MAX_RESPONSE_BYTES, prepareClientBody } from './body/index.js';
+export {
+  AuthenticationError,
+  ClientError,
+  ClientRequestError,
+  ClientResponseError,
+  ClientTimeoutError,
+  MissingAuthenticationError,
+  ResponseDecodeError,
+  ResponseTooLargeError,
+  ResponseValidationError,
+  TransportError,
+  UnexpectedContentTypeError,
+  UnexpectedStatusError,
+} from './errors/index.js';
+export { CLIENT_RUNTIME_ABI, createClientRuntime } from './runtime.js';
+export { createFetchTransport } from './transport/index.js';
+export { stringifyClientScalar, substituteClientPath } from './url/index.js';
+export type {
+  AuthenticationContext,
+  AuthenticationPatch,
+  AuthenticationProvider,
+  CallOptions,
+  ClientBody,
+  ClientBytes,
+  ClientHeaders,
+  ClientOperationResponse,
+  ClientOptions,
+  ClientQueryPair,
+  ClientRequest,
+  ClientResponse,
+  ClientResponseBody,
+  ClientRuntime,
+  ClientSecurityRequirement,
+  ClientSecurityScheme,
+  ClientTransport,
+  ClientVersionPlan,
+  DecodeResult,
+  GeneratedOperation,
+  PreparedClientRequest,
+  ValidationIssue,
+} from './types.js';