dixous 0.1.1 → 0.2.0

package/src/index.ts

@@ -1,132 +1,50 @@
-import { defaultResponseMethods, type DefaultResponseMethods } from "./response-methods.ts";
+import { ConcurrentNextError, UnexpectedResponseError } from "./errors.ts";
+import { defaultOperationApi } from "./response-methods.ts";
 import type {
-  ClientOptions,
-  Context,
-  ContextKey,
-  Dixous,
-  Extension,
-  ExtensionClientOptions,
-  ExtensionDefinition,
-  ExtensionMeta,
-  ExtensionMethods,
-  ExtensionRequestOptions,
-  Fetcher,
-  FetchResponse,
-  Middleware,
-  NoClientOptionOverrides,
-  NoRequestInitOverrides,
-  RequestContext,
-  RequestOptions,
-  ResponseMethods,
+  AnyExtension, ApplyExtensionApi, ApplyExtensionOptions, CoreOptions, CreateOptions,
+  DefaultOperationApi, Dixous as DixousClient, Extension,
+  ExtensionDefinition, OperationContext, RequestContext, RequestInput,
+  MatchedOperation, RequestMiddleware, RequestOptions, ReservedOperationKey,
 } from "./types.ts";
 
-export { SchemaValidationError } from "./response-methods.ts";
-export type { DefaultResponseMethods, InferOutput } from "./response-methods.ts";
-
+export { ConcurrentNextError, ResponseValidationError, UnexpectedResponseError } from "./errors.ts";
+export type { InferOutput, StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1 } from "./standard-schema.ts";
 export type {
-  BaseClientOptions,
-  ClientOptions,
-  Context,
-  ContextKey,
-  Dixous,
-  Extension,
-  Fetcher,
-  FetchResponse,
-  Middleware,
-  Next,
-  RequestContext,
-  RequestOptions,
+  AnyExtension, CoreOptions, CreateOptions, DefaultOperationApi, Extension,
+  ExtensionDefinition, Match, MatchedOperation, MatchResult, Next, OperationContext,
+  RequestContext, RequestInput, RequestMiddleware, RequestOperation, RequestOptions,
+  ReservedOperationKey, StatusHandlers,
 } from "./types.ts";
 
-export function createContextKey<T>(): ContextKey<T> {
-  return Symbol() as ContextKey<T>;
-}
-
-function createContext(): Context {
-  const values = new Map<symbol, unknown>();
-  return {
-    get<T>(key: ContextKey<T>) {
-      return values.get(key) as T | undefined;
-    },
-    set<T>(key: ContextKey<T>, value: T) {
-      values.set(key, value);
-    },
-  };
-}
-
-export function defineExtension<const Methods extends ResponseMethods = {}>(
-  extension: ExtensionDefinition<{}, {}, Methods>,
-): Extension<{}, {}, Methods>;
-export function defineExtension<
-  RequestExtra extends object & NoRequestInitOverrides = {},
-  ClientExtra extends object & NoClientOptionOverrides = {},
->(): <const Methods extends ResponseMethods = {}>(
-  extension: ExtensionDefinition<RequestExtra, ClientExtra, Methods>,
-) => Extension<RequestExtra, ClientExtra, Methods>;
-export function defineExtension(extension?: object): unknown {
-  // Extension metadata is a type-only brand; composition uses the captured values.
-  return extension === undefined ? (definition: object) => definition : extension;
-}
-
-export class HttpError extends Error {
-  readonly request: Request;
-  readonly response: Response;
-  readonly status: number;
-
-  constructor(request: Request, response: Response) {
-    super(`HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`);
-    this.name = "HttpError";
-    this.request = request;
-    this.response = response;
-    this.status = response.status;
-  }
-}
-
-function snapshotClient(options: ClientOptions = {}): Readonly<ClientOptions> {
-  const client = { ...options };
-  if (client.baseUrl !== undefined) client.baseUrl = client.baseUrl.toString();
-  if (client.headers !== undefined) client.headers = new Headers(client.headers);
-  return Object.freeze(client);
+export function defineExtension<const OperationApi extends object = {}>(
+  definition: ExtensionDefinition<{}, OperationApi>,
+): Extension<{}, OperationApi>;
+export function defineExtension<Options extends object>(): <const OperationApi extends object = {}>(
+  definition: ExtensionDefinition<Options, OperationApi>,
+) => Extension<Options, OperationApi>;
+export function defineExtension(definition?: object): unknown {
+  return definition === undefined ? (entry: object) => entry : definition;
 }
 
-function snapshotOptions(options: RequestOptions = {}): Readonly<RequestOptions> {
-  const snapshot = { ...options };
-  if (snapshot.headers !== undefined) snapshot.headers = new Headers(snapshot.headers);
-  return Object.freeze(snapshot);
-}
-
-function createTemplate(
-  input: string | URL | Request,
-  options: Readonly<RequestOptions>,
-  client: Readonly<ClientOptions>,
-): Request {
-  const headers = new Headers(client.headers);
-  if (input instanceof Request) {
-    input.headers.forEach((value, name) => headers.set(name, value));
+function mergeHeaders(...sources: (HeadersInit | undefined)[]): Headers {
+  const headers = new Headers();
+  for (const source of sources) {
+    if (source !== undefined) new Headers(source).forEach((value, name) => headers.set(name, value));
   }
-  if (options.headers !== undefined) {
-    new Headers(options.headers).forEach((value, name) => headers.set(name, value));
-  }
-  const source = !(input instanceof Request) && client.baseUrl !== undefined
-    ? new URL(input.toString(), client.baseUrl)
-    : input;
-  return new Request(source, { ...options, headers });
+  return headers;
 }
 
 function runMiddleware(
-  middleware: readonly Middleware[],
+  middleware: readonly RequestMiddleware[],
   context: RequestContext,
-  fetchImpl: typeof globalThis.fetch,
+  transport: typeof globalThis.fetch,
 ): Promise<Response> {
   async function dispatch(index: number): Promise<Response> {
     const current = middleware[index];
-    if (current === undefined) return fetchImpl(context.request.clone());
-
-    // Each middleware invocation owns its guard. Sequential retries re-enter
-    // the downstream chain with the same context and new downstream guards.
+    if (current === undefined) return transport(context.request);
     let running = false;
     return current(context, async () => {
-      if (running) throw new Error("Overlapping next() calls are not allowed");
+      if (running) throw new ConcurrentNextError();
       running = true;
       try {
         return await dispatch(index + 1);
@@ -138,82 +56,94 @@ function runMiddleware(
   return dispatch(0);
 }
 
-function createFetchResponse(
-  template: Request,
-  options: Readonly<RequestOptions>,
-  client: Readonly<ClientOptions>,
-  middleware: readonly Middleware[],
-  fetchImpl: typeof globalThis.fetch,
-): FetchResponse {
-  let execution: Promise<Response> | undefined;
-  return () => {
-    // Defer execution until after storing the promise, including when a
-    // synchronous middleware re-enters its operation's FetchResponse.
-    execution ??= Promise.resolve().then(async () => {
-      const context: RequestContext = {
-        request: template.clone(),
-        options,
-        client,
-        state: createContext(),
-      };
-      const response = await runMiddleware(middleware, context, fetchImpl);
-      if (!response.ok) throw new HttpError(context.request, response);
-      return response;
+type Configuration = CoreOptions & RequestOptions & { readonly extensions?: readonly AnyExtension[] };
+
+const reservedOperationKeys = ["response", "then"] as const satisfies readonly ReservedOperationKey[];
+
+function createOperation(
+  context: RequestContext,
+  execute: () => Promise<Response>,
+  extensions: readonly AnyExtension[],
+) {
+  const build = (response: () => Promise<Response>): MatchedOperation<{}> => {
+    const scoped: OperationContext = Object.create(context, {
+      response: { value: response, enumerable: true },
+      execute: { value: execute, enumerable: true },
+      api: { value: (matched: Response) => build(async () => matched), enumerable: true },
+    });
+    const operation = Object.assign(Object.create(null), defaultOperationApi(scoped));
+    for (const extension of extensions) {
+      const contribution = extension.operation?.(scoped);
+      if (contribution !== undefined) {
+        for (const key of reservedOperationKeys) {
+          if (key in contribution) throw new TypeError(`Extension operation cannot replace ${key}`);
+        }
+        Object.assign(operation, contribution);
+      }
+    }
+    return Object.defineProperties(operation, {
+      response: { value: execute, enumerable: true },
+      then: { value: undefined },
     });
-    return execution;
   };
+  return build(async () => {
+    const response = await execute();
+    if (!response.ok) throw new UnexpectedResponseError(context.request, response);
+    return response;
+  });
 }
 
-export function createDixous<
-  const Extensions extends readonly ExtensionMeta[] = [],
->(options?: {
-  extensions?: Extensions;
-  fetch?: typeof globalThis.fetch;
-}): Dixous<
-  ExtensionRequestOptions<Extensions>,
-  ExtensionClientOptions<Extensions>,
-  DefaultResponseMethods & ExtensionMethods<Extensions>
-> {
-  const fetchImpl = options?.fetch ?? globalThis.fetch;
-  const middleware: Middleware[] = [];
-  const methods = new Map<string, ResponseMethods[string]>(Object.entries(defaultResponseMethods));
-
-  for (const entry of options?.extensions ?? []) {
-    // Contributions are erased only inside the kernel; the public signature
-    // intersects their exact types when constructing the resulting client.
-    const extension = entry as Extension<{}, {}, ResponseMethods>;
-    if (extension.request !== undefined) middleware.push(extension.request);
-    for (const [name, factory] of Object.entries(extension.methods ?? {})) {
-      if (methods.has(name)) throw new Error(`Duplicate response method: ${name}`);
-      methods.set(name, factory);
-    }
-  }
+function createClient(parent: Configuration = {}, supplied: Configuration = {}): DixousClient {
+  const { extensions: inherited = [], ...defaults } = parent;
+  const { extensions: appended = [], ...overrides } = supplied;
+  const configuration = Object.freeze({
+    ...defaults,
+    ...overrides,
+    ...(overrides.baseUrl !== undefined ? { baseUrl: overrides.baseUrl.toString() } : {}),
+    headers: mergeHeaders(defaults.headers, overrides.headers),
+    // Capture contributions so later mutations cannot alter an immutable client.
+    extensions: Object.freeze([...inherited, ...appended].map(entry => Object.freeze({ ...entry }))),
+  });
+  const { extensions, ...clientOptions } = configuration;
+  const middleware = extensions.flatMap(entry => entry.request ? [entry.request] : []);
+  const transport = configuration.fetch ?? globalThis.fetch;
+
+  return Object.freeze({
+    create(options?: Configuration) { return createClient(configuration, options); },
+    request(input: RequestInput, suppliedOptions: RequestOptions = {}) {
+      const options = Object.freeze({
+        ...clientOptions,
+        ...suppliedOptions,
+        headers: mergeHeaders(
+          configuration.headers,
+          input instanceof Request ? input.headers : undefined,
+          suppliedOptions.headers,
+        ),
+      });
+      const source = !(input instanceof Request) && configuration.baseUrl !== undefined
+        ? new URL(input.toString(), configuration.baseUrl)
+        : input;
+      const request = new Request(source, options);
+      let execution: Promise<Response> | undefined;
+      const execute = () => {
+        // Store the promise before middleware can synchronously re-enter execute().
+        execution ??= Promise.resolve().then(() => runMiddleware(middleware, context, transport));
+        return execution;
+      };
+      const context: RequestContext = { input, request, options };
+      Object.defineProperties(context, { input: { writable: false }, options: { writable: false } });
+      return createOperation(context, execute, extensions);
+    },
+  }) as DixousClient;
+}
 
-  function configured(clientOptions?: ClientOptions): Fetcher<{}, ResponseMethods> {
-    const client = snapshotClient(clientOptions);
-    return {
-      fetch(input, requestOptions) {
-        const snapshot = snapshotOptions(requestOptions);
-        const template = createTemplate(input, snapshot, client);
-        const pending: Record<string, (...args: never[]) => Promise<unknown>> =
-          Object.create(null);
-        for (const [name, factory] of methods) {
-          pending[name] = (...args) => {
-            const fetchResponse = createFetchResponse(
-              template, snapshot, client, middleware, fetchImpl,
-            );
-            // Factories and method work are lazy too, and run once per call.
-            return factory(fetchResponse)(...args);
-          };
-        }
-        return Object.freeze(pending);
-      },
-    };
-  }
+export interface Dixous<Options extends object = {}, OperationApi extends object = DefaultOperationApi>
+  extends DixousClient<Options, OperationApi> {}
 
-  return Object.assign(configured, { fetch: configured().fetch }) as Dixous<
-    ExtensionRequestOptions<Extensions>,
-    ExtensionClientOptions<Extensions>,
-    DefaultResponseMethods & ExtensionMethods<Extensions>
-  >;
-}
+export const Dixous: {
+  create<const Extensions extends readonly AnyExtension[] = []>(
+    options?: CreateOptions<{}, Extensions>,
+  ): Dixous<ApplyExtensionOptions<{}, Extensions>, ApplyExtensionApi<DefaultOperationApi, Extensions>>;
+} = Object.freeze({
+  create: createClient.bind(undefined, {}) as DixousClient["create"],
+});

package/src/response-methods.ts

@@ -1,36 +1,25 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { FetchResponse, ResponseMethods } from "./types.ts";
+import { ResponseValidationError, UnexpectedResponseError } from "./errors.ts";
+import type { InferOutput, StandardSchemaV1 } from "./standard-schema.ts";
+import type { DefaultOperationApi, MatchResult, OperationContext, StatusHandlers } from "./types.ts";
 
-export type InferOutput<Schema extends StandardSchemaV1> =
-  StandardSchemaV1.InferOutput<Schema>;
-
-export class SchemaValidationError extends Error {
-  readonly issues: readonly StandardSchemaV1.Issue[];
-
-  constructor(issues: readonly StandardSchemaV1.Issue[]) {
-    super("Response failed schema validation");
-    this.name = "SchemaValidationError";
-    this.issues = issues;
-  }
-}
-
-// Built-ins use the same per-operation factories as extension methods.
-export const defaultResponseMethods = {
-  json: (fetchResponse: FetchResponse) =>
-    async <Schema extends StandardSchemaV1>(schema: Schema): Promise<InferOutput<Schema>> => {
-      const response = await fetchResponse();
+export function defaultOperationApi(operation: OperationContext): DefaultOperationApi {
+  return {
+    async json<Schema extends StandardSchemaV1>(schema: Schema): Promise<InferOutput<Schema>> {
+      const response = await operation.response();
       const result = await schema["~standard"].validate(await response.json());
-      if (result.issues) throw new SchemaValidationError(result.issues);
+      if (result.issues !== undefined) {
+        throw new ResponseValidationError(operation.request, response, result.issues);
+      }
       return result.value as InferOutput<Schema>;
     },
-  text: (fetchResponse: FetchResponse) => async (): Promise<string> =>
-    (await fetchResponse()).text(),
-  blob: (fetchResponse: FetchResponse) => async (): Promise<Blob> =>
-    (await fetchResponse()).blob(),
-  arrayBuffer: (fetchResponse: FetchResponse) => async (): Promise<ArrayBuffer> =>
-    (await fetchResponse()).arrayBuffer(),
-  response: (fetchResponse: FetchResponse) => (): Promise<Response> =>
-    fetchResponse(),
-} satisfies ResponseMethods;
-
-export type DefaultResponseMethods = typeof defaultResponseMethods;
+    async text() { return (await operation.response()).text(); },
+    async blob() { return (await operation.response()).blob(); },
+    async arrayBuffer() { return (await operation.response()).arrayBuffer(); },
+    async match<Handlers extends StatusHandlers<{}>>(handlers: Handlers): Promise<MatchResult<Handlers>> {
+      const response = await operation.execute();
+      const handler = handlers[response.status];
+      if (handler === undefined) throw new UnexpectedResponseError(operation.request, response);
+      return (await handler(operation.api(response))) as MatchResult<Handlers>;
+    },
+  };
+}

package/src/standard-schema.ts

@@ -0,0 +1,51 @@
+/**
+ * Standard Schema v1 types, vendored from @standard-schema/spec 1.1.0.
+ * https://standardschema.dev/schema
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2024 Colin McDonnell
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) =>
+      StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    };
+  };
+}
+
+export type StandardSchemaResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: readonly StandardSchemaIssue[] };
+
+export interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[];
+}
+
+export type InferOutput<Schema extends StandardSchemaV1> =
+  NonNullable<Schema["~standard"]["types"]>["output"];