liaise 0.0.0 → 5.0.0

package/dist/graphql.js

@@ -0,0 +1,272 @@
+import { ApiError, createSuccessResult, createErrorResult, createNetworkErrorResult } from './result.js';
+import { composeMiddleware } from './middleware.js';
+import { DedupeTracker } from './utils/dedupe.js';
+import { mergeHeaders } from './utils/headers.js';
+import { abortKind, propagatesReason } from './utils/abort-kind.js';
+import { resolveBudget } from './utils/budget.js';
+import { createBackstop } from './utils/backstop.js';
+import { runSchema } from './utils/validate.js';
+export class Operation {
+    constructor(config) {
+        this.config = config;
+    }
+}
+export const gql = (strings, ...values) => String.raw({ raw: strings }, ...values);
+export function createGraphQL(config) {
+    const { endpoint, middleware: globalMiddleware = [], headers: globalHeaders, onError, } = config;
+    const dedupeTracker = new DedupeTracker();
+    const fireOnError = (error) => {
+        if (error.kind === 'abort')
+            return;
+        if (!onError)
+            return;
+        try {
+            onError(error);
+        }
+        catch {
+        }
+    };
+    function buildMethod(name, operation) {
+        return (variables = {}, options = {}) => {
+            const execute = () => {
+                function buildFailedResult(reason, signal, fallbackKind) {
+                    const isOurCancellation = signal?.aborted === true &&
+                        (fallbackKind !== 'middleware' || propagatesReason(reason, signal.reason));
+                    const kind = isOurCancellation ? (abortKind(signal.reason) ?? 'abort') : fallbackKind;
+                    const error = new ApiError({
+                        kind,
+                        status: 0,
+                        statusText: '',
+                        body: reason,
+                        headers: new Headers(),
+                        request: { method: 'POST', url: endpoint, params: variables },
+                    });
+                    return createNetworkErrorResult(error, execute);
+                }
+                try {
+                    const allMiddleware = [
+                        ...globalMiddleware,
+                        ...(operation.config.middleware ?? []),
+                        ...(options.middleware ?? []),
+                    ];
+                    const budget = resolveBudget(options.timeout, operation.config.timeout, options.signal, false);
+                    const callerSignal = budget.operation;
+                    let dedupeController;
+                    const core = async (ctx) => {
+                        try {
+                            if (operation.config.dedupe && !dedupeController) {
+                                const tracked = dedupeTracker.track(name, ctx.request.signal ?? callerSignal);
+                                dedupeController = tracked.controller;
+                                ctx.request.signal = tracked.signal;
+                                backstop.watch(tracked.controller.signal);
+                            }
+                            const response = await fetch(ctx.request.url, {
+                                method: 'POST',
+                                headers: ctx.request.headers,
+                                body: ctx.request.body,
+                                signal: ctx.request.signal,
+                            });
+                            if (!response.ok) {
+                                let body;
+                                try {
+                                    const text = await response.text();
+                                    body = text ? JSON.parse(text) : null;
+                                }
+                                catch (parseErr) {
+                                    const signal = ctx.request.signal;
+                                    if (signal?.aborted === true) {
+                                        const error = new ApiError({
+                                            status: 0,
+                                            kind: abortKind(signal.reason) ?? 'abort',
+                                            statusText: '',
+                                            body: parseErr,
+                                            headers: new Headers(),
+                                            request: { method: 'POST', url: ctx.request.url, params: variables },
+                                        });
+                                        return createNetworkErrorResult(error, execute);
+                                    }
+                                    body = null;
+                                }
+                                const error = new ApiError({
+                                    status: response.status,
+                                    kind: 'http',
+                                    statusText: response.statusText,
+                                    body,
+                                    headers: response.headers,
+                                    request: { method: 'POST', url: ctx.request.url, params: variables },
+                                });
+                                return createErrorResult(error, response, execute);
+                            }
+                            const text = await response.text();
+                            let gqlBody;
+                            try {
+                                gqlBody = text
+                                    ? JSON.parse(text)
+                                    : null;
+                            }
+                            catch (parseErr) {
+                                const error = new ApiError({
+                                    kind: 'parse',
+                                    status: response.status,
+                                    statusText: response.statusText,
+                                    body: parseErr,
+                                    headers: response.headers,
+                                    request: { method: 'POST', url: ctx.request.url, params: variables },
+                                });
+                                return createErrorResult(error, response, execute);
+                            }
+                            if (gqlBody?.errors?.length) {
+                                const error = new ApiError({
+                                    status: response.status,
+                                    kind: 'http',
+                                    statusText: 'GraphQL Error',
+                                    body: gqlBody.errors,
+                                    headers: response.headers,
+                                    request: { method: 'POST', url: ctx.request.url, params: variables },
+                                    partialData: gqlBody.data ?? undefined,
+                                });
+                                return createErrorResult(error, response, execute);
+                            }
+                            if (gqlBody?.data == null) {
+                                const error = new ApiError({
+                                    kind: 'parse',
+                                    status: response.status,
+                                    statusText: response.statusText,
+                                    body: text,
+                                    headers: response.headers,
+                                    request: { method: 'POST', url: ctx.request.url, params: variables },
+                                });
+                                return createErrorResult(error, response, execute);
+                            }
+                            if (operation.config.schema) {
+                                let outcome;
+                                try {
+                                    outcome = await runSchema(operation.config.schema, gqlBody.data);
+                                }
+                                catch (validatorErr) {
+                                    const error = new ApiError({
+                                        kind: 'parse',
+                                        status: response.status,
+                                        statusText: response.statusText,
+                                        body: validatorErr,
+                                        headers: response.headers,
+                                        request: { method: 'POST', url: ctx.request.url, params: variables }
+                                    });
+                                    return createErrorResult(error, response, execute);
+                                }
+                                if (!outcome.ok) {
+                                    const error = new ApiError({
+                                        kind: 'parse',
+                                        status: response.status,
+                                        statusText: response.statusText,
+                                        body: outcome.issues,
+                                        headers: response.headers,
+                                        request: { method: 'POST', url: ctx.request.url, params: variables }
+                                    });
+                                    return createErrorResult(error, response, execute);
+                                }
+                                return createSuccessResult(outcome.value, response, execute);
+                            }
+                            return createSuccessResult(gqlBody.data, response, execute);
+                        }
+                        catch (err) {
+                            const signal = ctx.request.signal;
+                            const kind = signal?.aborted === true
+                                ? (abortKind(signal.reason) ?? 'abort')
+                                : (abortKind(err) ?? 'network');
+                            const error = new ApiError({
+                                status: 0,
+                                kind,
+                                statusText: '',
+                                body: err,
+                                headers: new Headers(),
+                                request: { method: 'POST', url: ctx.request.url, params: variables },
+                            });
+                            return createNetworkErrorResult(error, execute);
+                        }
+                    };
+                    const headers = mergeHeaders(globalHeaders, operation.config.headers, options.headers);
+                    if (!headers.has('Content-Type')) {
+                        headers.set('Content-Type', 'application/json');
+                    }
+                    const body = JSON.stringify({ query: operation.config.operation, variables });
+                    const context = {
+                        request: {
+                            method: 'POST',
+                            url: endpoint,
+                            path: endpoint,
+                            params: variables,
+                            headers,
+                            body,
+                            signal: callerSignal,
+                        },
+                        requestName: name,
+                    };
+                    const backstop = createBackstop(signal => buildFailedResult(signal.reason, signal, 'abort'));
+                    backstop.watch(callerSignal);
+                    const composed = composeMiddleware(allMiddleware, backstop.guard(core), options.skipMiddleware ?? []);
+                    let resultPromise;
+                    try {
+                        resultPromise = composed(context).catch((err) => buildFailedResult(err, context.request.signal, 'middleware'));
+                    }
+                    catch (err) {
+                        resultPromise = Promise.resolve(buildFailedResult(err, context.request.signal, 'middleware'));
+                    }
+                    return backstop.follow(resultPromise, (result, preempted) => {
+                        if (operation.config.dedupe && dedupeController) {
+                            if (preempted)
+                                dedupeController.abort();
+                            dedupeTracker.clear(name, dedupeController);
+                        }
+                        if (result.error)
+                            fireOnError(result.error);
+                        return result;
+                    }, (err) => {
+                        const result = buildFailedResult(err, undefined, 'abort');
+                        fireOnError(result.error);
+                        return result;
+                    });
+                }
+                catch (err) {
+                    const error = new ApiError({
+                        status: 0,
+                        kind: 'network',
+                        statusText: '',
+                        body: err,
+                        headers: new Headers(),
+                        request: { method: 'POST', url: endpoint, params: variables },
+                    });
+                    fireOnError(error);
+                    return Promise.resolve(createNetworkErrorResult(error, execute));
+                }
+            };
+            return execute();
+        };
+    }
+    const allOperations = {
+        ...(config.operations ?? {}),
+        ...(config.queries ?? {}),
+        ...(config.mutations ?? {}),
+    };
+    const flatMethods = {};
+    for (const [name, operation] of Object.entries(allOperations)) {
+        flatMethods[name] = buildMethod(name, operation);
+    }
+    if (config.operations) {
+        return flatMethods;
+    }
+    const result = {};
+    if (config.queries) {
+        result.query = {};
+        for (const name of Object.keys(config.queries)) {
+            result.query[name] = flatMethods[name];
+        }
+    }
+    if (config.mutations) {
+        result.mutation = {};
+        for (const name of Object.keys(config.mutations)) {
+            result.mutation[name] = flatMethods[name];
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/** Factory that wires Request definitions into a typed, callable API object. */
+export { createApi } from './create-api.js';
+/** Typed request definition — one instance per API endpoint. */
+export { Request } from './request.js';
+/** Typed factory — infers path params from the `path` literal. */
+export { defineRequest } from './define-request.js';
+/** Walks a paginated endpoint, yielding one Result per page. */
+export { paginate } from './paginate.js';
+/** Options for `paginate` — `next`, `maxPages`, and any CallOptions. */
+export type { PaginateOptions } from './paginate.js';
+/** Structured error with status, body, headers, and request context. */
+export { ApiError } from './result.js';
+export type { RequestConfig, ApiConfig, CallOptions, Result, SuccessResult, ErrorResult, Middleware, MiddlewareContext, MiddlewareNext, ApiErrorKind, StandardSchemaV1, InferOutput, StandardIssue } from './types.js';
+/** Factory and primitives for building a typed GraphQL client. */
+export { createGraphQL, Operation, gql } from './graphql.js';
+export type { GraphQLError, OperationConfig, GraphQLBaseConfig } from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createApi } from './create-api.js';
+export { Request } from './request.js';
+export { defineRequest } from './define-request.js';
+export { paginate } from './paginate.js';
+export { ApiError } from './result.js';
+export { createGraphQL, Operation, gql } from './graphql.js';

package/dist/middleware.d.ts

@@ -0,0 +1,77 @@
+import type { Middleware, MiddlewareContext, Result } from './types.js';
+/**
+ * Signature for the "core" function — the innermost layer of the onion.
+ *
+ * This is the function that actually performs the HTTP fetch. It receives
+ * the fully-prepared {@link MiddlewareContext} (with all middleware
+ * modifications applied) and returns a {@link Result}.
+ *
+ * The core function is NOT a middleware — it does not receive a `next`
+ * parameter because there is nothing after it. It is the terminal point
+ * of the middleware chain.
+ *
+ * @param context - The middleware context containing the prepared request.
+ * @returns A promise resolving to the Result of the HTTP call.
+ */
+export type CoreFn = (context: MiddlewareContext) => Promise<Result<unknown>>;
+/**
+ * Composes an array of middleware into a single executable function using
+ * the onion model.
+ *
+ * **How it works:**
+ *
+ * Given middleware `[A, B, C]` and a core function, calling the composed
+ * function produces this execution order:
+ *
+ * ```
+ * A "before" logic
+ *   B "before" logic
+ *     C "before" logic
+ *       core(context) ← actual fetch happens here
+ *     C "after" logic
+ *   B "after" logic
+ * A "after" logic
+ * ```
+ *
+ * **Skip filtering:**
+ *
+ * The `skip` parameter accepts an array of middleware references. Before
+ * composing, any middleware whose reference (===) matches an entry in `skip`
+ * is removed from the chain. This enables per-call overrides like:
+ *
+ * ```ts
+ * api.getUser({ id: '1' }, { skipMiddleware: [cacheMiddleware] })
+ * ```
+ *
+ * **No double-call guard:**
+ *
+ * Unlike some middleware engines (e.g., Koa), this implementation does NOT
+ * prevent a middleware from calling `next()` more than once. This is
+ * intentional — retry middleware needs to call `next()` sequentially in a
+ * loop to re-execute the downstream chain. Each `next()` call creates a
+ * fresh traversal from the current position onward.
+ *
+ * @param middleware - Array of middleware functions to compose. Order matters:
+ *   the first middleware in the array is the outermost layer (runs first on
+ *   the way "in" and last on the way "out").
+ * @param core - The innermost function that performs the actual HTTP fetch.
+ *   This is called when the last middleware in the chain calls `next()`.
+ * @param skip - Optional array of middleware references to exclude from the
+ *   chain. Comparison is by reference identity (===), not by value.
+ * @returns A function that takes a {@link MiddlewareContext} and returns a
+ *   `Promise<Result<unknown>>`. This is the fully composed pipeline ready
+ *   to be executed.
+ *
+ * @example
+ * ```ts
+ * // Compose global + per-request middleware with a fetch core
+ * const pipeline = composeMiddleware(
+ *   [authMiddleware, logMiddleware, cacheMiddleware],
+ *   fetchCore,
+ *   [cacheMiddleware], // skip cache for this call
+ * )
+ *
+ * const result = await pipeline(context)
+ * ```
+ */
+export declare function composeMiddleware(middleware: Middleware[], core: CoreFn, skip?: Middleware[]): (context: MiddlewareContext) => Promise<Result<unknown>>;

package/dist/middleware.js

@@ -0,0 +1,12 @@
+export function composeMiddleware(middleware, core, skip = []) {
+    const active = middleware.filter(mw => !skip.includes(mw));
+    return (context) => {
+        const dispatch = (i) => {
+            if (i >= active.length)
+                return core(context);
+            const mw = active[i];
+            return mw(context, () => dispatch(i + 1));
+        };
+        return dispatch(0);
+    };
+}

package/dist/paginate.d.ts

@@ -0,0 +1,71 @@
+import type { CallOptions, Result, SuccessResult } from './types.js';
+/**
+ * How to continue, and when to stop.
+ *
+ * @typeParam TParams - The endpoint's params type.
+ * @typeParam TResponse - The endpoint's success data type.
+ */
+export interface PaginateOptions<TParams extends object, TResponse> extends CallOptions {
+    /**
+     * Builds the params for the next page, or returns nullish to stop.
+     *
+     * Returns **params**, not a cursor. A cursor would leave this function
+     * deciding where to put it — `cursor`? `page_token`? `after`? — which is a
+     * convention, and a config option per API in existence is what `buildUrl`'s
+     * refusal to guess a nested-query-string format already rejected.
+     *
+     * The previous params arrive as the second argument so the common case is a
+     * spread:
+     *
+     * ```ts
+     * next: (page, prev) => page.data.cursor
+     *   ? { ...prev, cursor: page.data.cursor }
+     *   : undefined
+     * ```
+     *
+     * Only ever called with a page that succeeded — an error page has no data to
+     * read a cursor from, and ends the walk.
+     *
+     * It is the caller's own function, invoked inside their own `for await`, so a
+     * throw here propagates to them with their own stack rather than becoming a
+     * `Result`. That is not a hole in "never throws": that rule is about request
+     * failures, and this is a bug in the caller's callback. Converting it would
+     * need an error kind that fits nothing, and would hide the stack that
+     * identifies it.
+     */
+    next: (page: SuccessResult<TResponse>, params: TParams) => TParams | undefined | null;
+    /**
+     * The most pages to fetch. Omitted means unbounded.
+     *
+     * There is no default, deliberately: this library cannot justify a number —
+     * why 1000 and not 100? — and a silent truncation at an invented ceiling is
+     * indistinguishable from "no more pages", which is a worse failure than the
+     * runaway it would prevent.
+     *
+     * `0` means zero pages, not "unset". A caller who needs to know they hit the
+     * cap counts pages themselves; they are already writing the loop body.
+     */
+    maxPages?: number;
+}
+/**
+ * Walks a paginated endpoint, yielding one `Result` per page.
+ *
+ * @example
+ * ```ts
+ * for await (const page of paginate(api.listItems, { limit: 50 }, {
+ *   next: (p, prev) => p.data.cursor ? { ...prev, cursor: p.data.cursor } : undefined,
+ * })) {
+ *   if (page.error) break
+ *   render(page.data.items)
+ * }
+ * ```
+ *
+ * Yields `Result`s rather than unwrapping them, because that is the shape every
+ * other entry point returns — a paging loop should not invent a second
+ * convention for failure.
+ *
+ * @param endpoint - Any `createApi` method, or any function of that shape.
+ * @param params - The params for the first page.
+ * @param options - `next`, plus any `CallOptions` to apply to every request.
+ */
+export declare function paginate<TParams extends object, TResponse>(endpoint: (params: TParams, options?: CallOptions) => Promise<Result<TResponse>>, params: TParams, options: PaginateOptions<TParams, TResponse>): AsyncGenerator<Result<TResponse>, void, undefined>;

package/dist/paginate.js

@@ -0,0 +1,15 @@
+export async function* paginate(endpoint, params, options) {
+    const { next, maxPages, ...callOptions } = options;
+    let current = params;
+    let fetched = 0;
+    while (current !== undefined && current !== null) {
+        if (maxPages !== undefined && fetched >= maxPages)
+            return;
+        const page = await endpoint(current, callOptions);
+        fetched++;
+        yield page;
+        if (page.error !== null)
+            return;
+        current = next(page, current);
+    }
+}

package/dist/request.d.ts

@@ -0,0 +1,136 @@
+import type { RequestConfig } from './types.js';
+/**
+ * Typed request definition. One instance per API endpoint.
+ *
+ * The `Request` class is a **typed config container** — it does **not** execute
+ * HTTP requests. Execution is handled by the API client returned from `createApi`.
+ * This class stores the "recipe" for how a particular endpoint should be called:
+ * which HTTP method, what path template, which middleware to apply, what headers
+ * to include, and how to serialize parameters.
+ *
+ * The two type parameters are the key to the library's type safety:
+ * - `TParams` describes what the caller must pass when invoking this endpoint.
+ * - `TResponse` describes what the caller receives back on success.
+ *
+ * When passed to `createApi`, these generics flow through to produce a fully
+ * typed API method: `api.getUser({ id: '42' })` → `Promise<Result<User>>`.
+ *
+ * @typeParam TParams - The shape of the params object the caller must provide.
+ *   This includes both path parameters (e.g., `:id` segments) and any query
+ *   string or body parameters. Path params are extracted and substituted
+ *   automatically; the rest are serialized according to the method or `bodyAs`.
+ *
+ * @typeParam TResponse - The shape of the successful response data. This
+ *   becomes the type of `result.data` when the API call succeeds.
+ *
+ * @example
+ * ```ts
+ * // Define a GET endpoint that takes an `id` path param and returns a User
+ * const getUser = new Request<{ id: string }, User>({
+ *   method: 'GET',
+ *   path: '/users/:id',
+ * })
+ *
+ * // Define a POST endpoint with middleware and custom headers
+ * const createUser = new Request<{ name: string; email: string }, User>({
+ *   method: 'POST',
+ *   path: '/users',
+ *   middleware: [validationMiddleware],
+ *   headers: { 'X-Idempotency-Key': crypto.randomUUID() },
+ * })
+ *
+ * // Define a DELETE endpoint that sends a JSON body (overriding the default
+ * // query string behavior for DELETE)
+ * const bulkDelete = new Request<{ ids: string[] }, { deleted: number }>({
+ *   method: 'DELETE',
+ *   path: '/items',
+ *   bodyAs: 'body',
+ * })
+ * ```
+ */
+export declare class Request<TParams extends object, TResponse> {
+    /**
+     * The immutable configuration for this endpoint.
+     *
+     * Contains the HTTP method, URL path template, optional middleware,
+     * headers, response parsing strategy, deduplication flag, and body
+     * serialization override.
+     *
+     * This property is `readonly` because request definitions are meant to be
+     * created once and reused — they describe an endpoint, not a single call.
+     * Per-call customization (extra headers, abort signals, etc.) is handled
+     * via `CallOptions` at invocation time, not by mutating this config.
+     *
+     * @see {@link RequestConfig} for the full shape of the config object.
+     */
+    readonly config: RequestConfig;
+    /**
+     * Phantom fields — never assigned, never read at runtime.
+     *
+     * Without them the class body never references TParams or TResponse, so
+     * TypeScript treats every instantiation as structurally identical and
+     * `Request<{ id }, User>` silently accepts a `Request<{ slug }, Post>`.
+     *
+     * `declare` emits no property, so this costs zero runtime bytes.
+     * `Operation` in graphql.ts uses the same technique.
+     */
+    readonly _params: TParams;
+    readonly _response: TResponse;
+    /**
+     * Creates a new Request instance with the given endpoint configuration.
+     *
+     * The constructor simply stores the config — no validation or side effects.
+     * The config is used later by `createApi` when the endpoint is actually called.
+     *
+     * @param config - The endpoint configuration describing the HTTP method,
+     *   path template, middleware, headers, and serialization behavior.
+     *
+     * @example
+     * ```ts
+     * const listItems = new Request<{ page: number; limit: number }, Item[]>({
+     *   method: 'GET',
+     *   path: '/items',
+     *   dedupe: true, // auto-cancel previous in-flight request
+     * })
+     * ```
+     */
+    constructor(config: RequestConfig);
+    /**
+     * Determines whether this request's params should be serialized as a URL
+     * query string (as opposed to a JSON request body).
+     *
+     * The logic follows standard REST conventions with an escape hatch:
+     *
+     * 1. If `bodyAs` is explicitly set on the config, that takes precedence:
+     *    - `bodyAs: 'query'` → always serialize as query string (even for POST)
+     *    - `bodyAs: 'body'`  → always serialize as request body (even for GET/DELETE)
+     *
+     * 2. If `bodyAs` is not set, fall back to the HTTP method convention:
+     *    - `GET` / `DELETE` → params go to query string (returns `true`)
+     *    - `POST` / `PUT` / `PATCH` → params go to request body (returns `false`)
+     *
+     * This getter is used by the fetch layer in `createApi` to decide how to
+     * pass the caller's params to the `buildUrl` utility and whether to set
+     * a `body` on the fetch `RequestInit`.
+     *
+     * @returns `true` if params should be appended to the URL as a query string,
+     *   `false` if params should be sent as a JSON request body.
+     *
+     * @example
+     * ```ts
+     * const get = new Request<{ page: number }, unknown>({ method: 'GET', path: '/items' })
+     * get.shouldSerializeAsQuery // → true (GET defaults to query)
+     *
+     * const post = new Request<{ name: string }, unknown>({ method: 'POST', path: '/items' })
+     * post.shouldSerializeAsQuery // → false (POST defaults to body)
+     *
+     * const deleteWithBody = new Request<{ ids: string[] }, unknown>({
+     *   method: 'DELETE',
+     *   path: '/items',
+     *   bodyAs: 'body',
+     * })
+     * deleteWithBody.shouldSerializeAsQuery // → false (bodyAs overrides DELETE default)
+     * ```
+     */
+    get shouldSerializeAsQuery(): boolean;
+}

package/dist/request.js

@@ -0,0 +1,12 @@
+const QUERY_METHODS = new Set(['GET', 'DELETE']);
+export class Request {
+    constructor(config) {
+        this.config = config;
+    }
+    get shouldSerializeAsQuery() {
+        if (this.config.bodyAs) {
+            return this.config.bodyAs === 'query';
+        }
+        return QUERY_METHODS.has(this.config.method);
+    }
+}