liaise 0.0.0 → 5.0.0

package/dist/create-api.js

@@ -0,0 +1,370 @@
+import { ApiError, createSuccessResult, createErrorResult, createNetworkErrorResult } from './result.js';
+import { composeMiddleware } from './middleware.js';
+import { buildUrl, joinUrl, FragmentError } from './utils/path-params.js';
+import { serializeBody } from './utils/serialize.js';
+import { DedupeTracker } from './utils/dedupe.js';
+import { ShareTracker, isAbandoned } from './utils/share.js';
+import { mergeHeaders } from './utils/headers.js';
+import { abortKind, propagatesReason } from './utils/abort-kind.js';
+import { anySignal } from './utils/any-signal.js';
+import { operationBudget, perCallerBudget } from './utils/budget.js';
+import { stableKey } from './utils/stable-key.js';
+import { createBackstop } from './utils/backstop.js';
+import { isSpecialBody } from './utils/special-body.js';
+import { runSchema } from './utils/validate.js';
+const EMPTY_JSON_BODY = Symbol('liaise.emptyJsonBody');
+async function parseResponse(response, responseType = 'json') {
+    switch (responseType) {
+        case 'text':
+            return response.text();
+        case 'blob':
+            return response.blob();
+        case 'arrayBuffer':
+            return response.arrayBuffer();
+        case 'formData':
+            return response.formData();
+        case 'none':
+            try {
+                await response.body?.cancel();
+            }
+            catch {
+            }
+            return undefined;
+        case 'json':
+        default: {
+            const text = await response.text();
+            return text ? JSON.parse(text) : EMPTY_JSON_BODY;
+        }
+    }
+}
+function resolveRequestUrl(baseUrl, request, params) {
+    const asQuery = request.shouldSerializeAsQuery;
+    const paramsIsSpecialBody = isSpecialBody(params);
+    const { url, remaining } = buildUrl(baseUrl, request.config.path, paramsIsSpecialBody ? {} : params, asQuery);
+    return { url, remaining, asQuery, paramsIsSpecialBody };
+}
+function urlForError(baseUrl, request, params) {
+    try {
+        return resolveRequestUrl(baseUrl, request, params).url;
+    }
+    catch (err) {
+        if (err instanceof FragmentError)
+            return err.resolvedUrl;
+        return joinUrl(baseUrl, request.config.path);
+    }
+}
+function syntheticResult(reason, signal, fallbackKind, method, url, params, retry) {
+    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, url, params }
+    });
+    return createNetworkErrorResult(error, retry);
+}
+function isEmptyHeaders(init) {
+    if (init === undefined)
+        return true;
+    if (init instanceof Headers) {
+        let empty = true;
+        init.forEach(() => { empty = false; });
+        return empty;
+    }
+    if (Array.isArray(init))
+        return init.length === 0;
+    return Object.keys(init).length === 0;
+}
+export function createApi(config) {
+    const { baseUrl, requests, middleware: globalMiddleware = [], headers: globalHeaders, onError } = config;
+    const fireOnError = (error) => {
+        if (error.kind === 'abort')
+            return;
+        if (!onError)
+            return;
+        try {
+            onError(error);
+        }
+        catch {
+        }
+    };
+    const dedupeTracker = new DedupeTracker();
+    const shareTracker = new ShareTracker();
+    for (const [name, request] of Object.entries(requests)) {
+        if (request.config.share && request.config.dedupe) {
+            throw new Error(`Request "${name}" sets both share and dedupe. They are opposites — ` +
+                `dedupe cancels the previous call, share joins it. Pick one.`);
+        }
+    }
+    const api = {};
+    for (const [name, request] of Object.entries(requests)) {
+        api[name] = (params = {}, options = {}) => {
+            function buildFailedResult(reason, signal, fallbackKind, url) {
+                return syntheticResult(reason, signal, fallbackKind, request.config.method, url ?? urlForError(baseUrl, request, params), params, retry);
+            }
+            function failedResult(reason, signal, fallbackKind) {
+                const result = buildFailedResult(reason, signal, fallbackKind);
+                fireOnError(result.error);
+                return result;
+            }
+            const execute = (sharedSignal, onSettled) => {
+                try {
+                    const allMiddleware = [
+                        ...globalMiddleware,
+                        ...(request.config.middleware ?? []),
+                        ...(options.middleware ?? [])
+                    ];
+                    const operation = operationBudget(options.timeout, request.config.timeout, options.signal, sharedSignal !== undefined);
+                    const callerSignal = sharedSignal
+                        ? anySignal([sharedSignal, operation])
+                        : operation;
+                    let dedupeController;
+                    const core = async (ctx) => {
+                        try {
+                            if (sharedSignal && ctx.request.signal !== sharedSignal) {
+                                ctx.request.signal = anySignal([ctx.request.signal, sharedSignal]);
+                            }
+                            if (request.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 fetchInit = {
+                                method: ctx.request.method,
+                                headers: ctx.request.headers,
+                                signal: ctx.request.signal
+                            };
+                            if (ctx.request.body !== null && ctx.request.body !== undefined) {
+                                fetchInit.body = ctx.request.body;
+                            }
+                            const response = await fetch(ctx.request.url, fetchInit);
+                            if (!response.ok) {
+                                let body;
+                                try {
+                                    const errorResponseType = request.config.responseType === 'none' ? 'json' : request.config.responseType;
+                                    body = await parseResponse(response, errorResponseType);
+                                    if (body === EMPTY_JSON_BODY)
+                                        body = 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: ctx.request.method, url: ctx.request.url, params }
+                                        });
+                                        return createNetworkErrorResult(error, retry);
+                                    }
+                                    body = null;
+                                }
+                                const error = new ApiError({
+                                    status: response.status,
+                                    kind: 'http',
+                                    statusText: response.statusText,
+                                    body,
+                                    headers: response.headers,
+                                    request: { method: ctx.request.method, url: ctx.request.url, params }
+                                });
+                                return createErrorResult(error, response, retry);
+                            }
+                            let data;
+                            try {
+                                data = await parseResponse(response, request.config.responseType);
+                            }
+                            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: ctx.request.method, url: ctx.request.url, params }
+                                    });
+                                    return createNetworkErrorResult(error, retry);
+                                }
+                                const error = new ApiError({
+                                    kind: 'parse',
+                                    status: response.status,
+                                    statusText: response.statusText,
+                                    body: parseErr,
+                                    headers: response.headers,
+                                    request: { method: ctx.request.method, url: ctx.request.url, params }
+                                });
+                                return createErrorResult(error, response, retry);
+                            }
+                            if (data === EMPTY_JSON_BODY) {
+                                const error = new ApiError({
+                                    kind: 'parse',
+                                    status: response.status,
+                                    statusText: response.statusText,
+                                    body: '',
+                                    headers: response.headers,
+                                    request: { method: ctx.request.method, url: ctx.request.url, params }
+                                });
+                                return createErrorResult(error, response, retry);
+                            }
+                            if (request.config.schema) {
+                                let outcome;
+                                try {
+                                    outcome = await runSchema(request.config.schema, data);
+                                }
+                                catch (validatorErr) {
+                                    const error = new ApiError({
+                                        kind: 'parse',
+                                        status: response.status,
+                                        statusText: response.statusText,
+                                        body: validatorErr,
+                                        headers: response.headers,
+                                        request: { method: ctx.request.method, url: ctx.request.url, params }
+                                    });
+                                    return createErrorResult(error, response, retry);
+                                }
+                                if (!outcome.ok) {
+                                    const error = new ApiError({
+                                        kind: 'parse',
+                                        status: response.status,
+                                        statusText: response.statusText,
+                                        body: outcome.issues,
+                                        headers: response.headers,
+                                        request: { method: ctx.request.method, url: ctx.request.url, params }
+                                    });
+                                    return createErrorResult(error, response, retry);
+                                }
+                                data = outcome.value;
+                            }
+                            return createSuccessResult(data, response, retry);
+                        }
+                        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: ctx.request.method, url: ctx.request.url, params }
+                            });
+                            return createNetworkErrorResult(error, retry);
+                        }
+                    };
+                    const { url, remaining, asQuery, paramsIsSpecialBody } = resolveRequestUrl(baseUrl, request, params);
+                    const headers = mergeHeaders(globalHeaders, request.config.headers, options.headers);
+                    let body = null;
+                    if (!asQuery) {
+                        const toSerialize = paramsIsSpecialBody ? params : remaining;
+                        if (paramsIsSpecialBody || Object.keys(remaining).length > 0) {
+                            const serialized = serializeBody(toSerialize);
+                            body = serialized.body;
+                            if (serialized.contentType && !headers.has('Content-Type')) {
+                                headers.set('Content-Type', serialized.contentType);
+                            }
+                        }
+                    }
+                    const context = {
+                        request: {
+                            method: request.config.method,
+                            url,
+                            path: request.config.path,
+                            params,
+                            headers,
+                            body,
+                            signal: callerSignal
+                        },
+                        requestName: name
+                    };
+                    const backstop = createBackstop(signal => buildFailedResult(signal.reason, signal, 'abort', context.request.url));
+                    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', context.request.url));
+                    }
+                    catch (err) {
+                        resultPromise = Promise.resolve(buildFailedResult(err, context.request.signal, 'middleware', context.request.url));
+                    }
+                    return backstop.follow(resultPromise, (result, preempted) => {
+                        if (typeof onSettled === 'function') {
+                            try {
+                                onSettled();
+                            }
+                            catch { }
+                        }
+                        if (request.config.dedupe && dedupeController) {
+                            if (preempted)
+                                dedupeController.abort();
+                            dedupeTracker.clear(name, dedupeController);
+                        }
+                        const abandoned = sharedSignal?.aborted === true && isAbandoned(sharedSignal.reason);
+                        if (result.error && !abandoned)
+                            fireOnError(result.error);
+                        return result;
+                    }, (err) => failedResult(err, undefined, 'abort'));
+                }
+                catch (err) {
+                    return Promise.resolve(failedResult(err, undefined, 'network'));
+                }
+            };
+            function retry() {
+                return execute();
+            }
+            try {
+                const key = request.config.share === true &&
+                    isEmptyHeaders(options.headers) &&
+                    (options.middleware === undefined || options.middleware.length === 0)
+                    ? stableKey(params)
+                    : null;
+                if (key === null)
+                    return execute();
+                const shareKey = `${name}|${key}`;
+                const perCaller = perCallerBudget(options.timeout, options.signal);
+                const { promise, release, hasSettled } = shareTracker.acquire(shareKey, (signal, markSettled) => execute(signal, markSettled));
+                if (!perCaller)
+                    return promise.then(r => r, (err) => failedResult(err, undefined, 'network'));
+                return new Promise(resolve => {
+                    let done = false;
+                    const finish = (r) => {
+                        if (done)
+                            return;
+                        done = true;
+                        perCaller.removeEventListener('abort', onAbort);
+                        resolve(r);
+                    };
+                    promise.then(r => finish(r), (err) => {
+                        if (done)
+                            return;
+                        finish(failedResult(err, undefined, 'network'));
+                    });
+                    const onAbort = () => {
+                        release();
+                        const result = buildFailedResult(perCaller.reason, perCaller, 'abort');
+                        if (!hasSettled())
+                            fireOnError(result.error);
+                        finish(result);
+                    };
+                    if (perCaller.aborted)
+                        onAbort();
+                    else
+                        perCaller.addEventListener('abort', onAbort, { once: true });
+                });
+            }
+            catch (err) {
+                return Promise.resolve(failedResult(err, undefined, 'network'));
+            }
+        };
+    }
+    return api;
+}

package/dist/define-request.d.ts

@@ -0,0 +1,251 @@
+import { Request } from './request.js';
+import type { RequestConfig, ResponseType, StandardSchemaV1, InferOutput } from './types.js';
+/**
+ * The characters a path token name may contain.
+ *
+ * This list is not arbitrary and must not be "simplified": it mirrors
+ * `buildUrl`'s substitution pattern, `:${key}(?=[^a-zA-Z0-9_]|$)`
+ * (src/utils/path-params.ts). If the two ever disagree, the types describe a
+ * URL the runtime does not build.
+ */
+type WordChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '_';
+/**
+ * Consumes the leading word characters of `S` — a token name — and stops at the
+ * first character that is not one, exactly where `buildUrl`'s lookahead stops.
+ *
+ * Character-at-a-time rather than splitting on '/', because a token does not
+ * have to end at a slash: `/users/:id.json` substitutes `:id` and leaves
+ * `.json`, and `/search/:q?x=1` substitutes `:q`.
+ */
+type TakeName<S extends string, Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? C extends WordChar ? TakeName<Rest, `${Acc}${C}`> : Acc : Acc;
+/**
+ * The params a path template requires, as `{ token: string | number }`.
+ *
+ * `string | number` because `buildUrl` does `encodeURIComponent(String(value))`
+ * — a numeric id is as valid as a string one. An object is rejected, which is
+ * right: `String({})` is `"[object Object]"`, a silently wrong URL.
+ *
+ * A path with no tokens gives `{}`, and `Record<string, never> extends {}`
+ * holds, so `ApiMethod`'s optional-params branch still fires and `api.health()`
+ * stays callable with no arguments.
+ *
+ * A token must BEGIN a path segment, mirroring `buildUrl`'s Phase 1b
+ * (src/utils/path-params.ts, search "A token must BEGIN a path segment"):
+ * matching is anchored to `/:` rather than a bare `:`, so a colon that appears
+ * mid-segment — a Google-style custom method like `/v1/documents:batchGet`,
+ * or a time like `/events/at/12:30` — is never mistaken for a token. Both of
+ * those paths parse to `{}`, not `{ batchGet: ... }` or `{ '30': ... }`.
+ *
+ * A missing leading slash is normalised before anchoring. `buildUrl` requires a
+ * token to sit at index 0 of a `split('/')` segment, which means "preceded by
+ * `/`, **or at the very start of the string**" — and segment 0 always starts at
+ * index 0. Prepending `/` when it is absent makes this type's `/:` requirement
+ * exactly equivalent to that condition, and is a no-op for a path that already
+ * has one.
+ *
+ * 4.1.0 shipped the anchor without the normalisation and so under-inferred a
+ * path whose token *starts the string*: `':id'` inferred nothing while the
+ * request still demanded `id`, failing at runtime. A path like `'users/:id'`
+ * was never affected — it contains a literal `/:`.
+ *
+ * Exported for `tests/types.test-d.ts`. Not re-exported from `src/index.ts`, so
+ * it is not public API — see index.ts's note on what is deliberately withheld.
+ */
+type Anchored<P extends string> = P extends `${string}/:${infer Tail}` ? TakeName<Tail> extends infer Name extends string ? Name extends '' ? Anchored<Tail> : {
+    [K in Name]: string | number;
+} & (Tail extends `${Name}${infer Rest}` ? Anchored<Rest> : {}) : {} : {};
+export type PathParams<P extends string> = Anchored<P extends `/${string}` ? P : `/${P}`>;
+/**
+ * Flattens an intersection into a single object type.
+ *
+ * Presentational, but load-bearing for the feature's value: without it, hovering
+ * an endpoint in an editor shows `PathParams<'/orgs/:org/repos'> & { page?:
+ * number }` instead of `{ org: string | number; page?: number }`.
+ */
+export type Id<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Rejects `responseType: 'none'` when `TResponse` is a real type.
+ *
+ * `'none'` means the endpoint sends no body on success and `data` is
+ * `undefined` at runtime. Declaring a response type alongside it is a
+ * contradiction that was, until now, only a documented convention.
+ *
+ * Fires only on the LITERAL `'none'`. A config whose `responseType` is the
+ * widened `ResponseType | undefined` — a `RequestConfig`-typed variable, or a
+ * spread of one — infers as the whole union, which is not `'none'`, and passes
+ * through untouched. That matters: constraining the config parameter directly
+ * rejects both of those legitimate forms, which is exactly the permissiveness
+ * problem recorded in `ResponseType`'s JSDoc in types.ts.
+ *
+ * The other side of "literal only" is `TResponse`, not `TRT`: the check is
+ * `undefined extends TResponse`, so any `TResponse` that ADMITS `undefined` —
+ * `User | undefined`, `any`, `unknown` — satisfies the guard and is not
+ * rejected, same as the exact type `undefined`. Only a `TResponse` that
+ * excludes `undefined` entirely trips it.
+ *
+ * The failure branch uses a non-colliding marker property, `__emptyBodyMismatch`,
+ * rather than reusing `responseType`. Reusing `responseType` collapses that
+ * property's type to `never` via intersection with the existing `responseType?:
+ * TRT`, which TypeScript then reports as a per-property mismatch on unrelated
+ * fields like `method`, never mentioning the message. `__emptyBodyMismatch`
+ * collides with nothing a real config has, so TypeScript instead reports it as
+ * a missing required property, and the sentence rides along in that message.
+ */
+type EmptyBodyGuard<TRT, TResponse> = [
+    TRT
+] extends ['none'] ? undefined extends TResponse ? unknown : {
+    __emptyBodyMismatch: 'declare TResponse as undefined when responseType is none';
+} : unknown;
+/**
+ * Rejects a `path` literal containing a URL fragment.
+ *
+ * `fetch` never transmits a fragment, so one in a request path cannot do
+ * anything the caller intended — and before 4.2.1 it silently ate the query
+ * string as well. 4.2.1 made `buildUrl` refuse it at runtime, which left the
+ * type accepting what the runtime rejects: `defineRequest()({ path:
+ * '/docs#section' })` compiled, and then failed on every call. That divergence
+ * is the defect this library exists to prevent (§2.4 closed the same gap in the
+ * other direction), so the guard closes it at the call site.
+ *
+ * **Fires only on a literal.** `string extends `${string}#${string}`` is false,
+ * so a `RequestConfig`-typed variable, a spread of one, or any path computed at
+ * runtime still compiles. That permissiveness is not an oversight — it is the
+ * constraint that sank the 3.1.0 guard attempt, and `EmptyBodyGuard` carries it
+ * for the same reason. A config assembled at runtime cannot be checked at
+ * compile time, and refusing it would make the factory unusable for that shape.
+ *
+ * `new Request` gets no equivalent: it takes no path literal, so there is
+ * nothing for a guard to read. That is the asymmetry §3.4 already accepted, and
+ * it is why the factory exists at all.
+ *
+ * The marker property follows `EmptyBodyGuard`'s reasoning exactly — reusing
+ * `path` would intersect to `never` and make TypeScript report a mismatch on
+ * unrelated fields, never showing the sentence. `__fragmentInPath` collides
+ * with nothing a real config has, so it is reported as a missing required
+ * property and the message rides along.
+ */
+type FragmentGuard<TPath> = TPath extends `${string}#${string}` ? {
+    __fragmentInPath: 'a URL fragment is never sent to the server — remove the # and everything after it';
+} : unknown;
+/**
+ * The response type a schema supplies, or `unknown` when it supplies none.
+ *
+ * "Supplies none" covers two cases that must be treated identically: `TSchema`
+ * is literally `undefined` (no `schema` was written), and `TSchema` is present
+ * but its OUTPUT is `unknown` or `any` (a widened `StandardSchemaV1<unknown>`,
+ * which is what a bare `RequestConfig`-typed variable's `schema` field infers
+ * as — see `SchemaConflictGuard`). Both collapse to `unknown` here, which is
+ * what lets `SchemaConflictGuard` and `defineRequest`'s return type ask the
+ * SAME question ("did a schema meaningfully narrow the response?") and get the
+ * same answer. They used to ask it separately and disagreed: the guard read
+ * the schema's OUTPUT (`unknown extends InferOutput<TSchema>`) while the
+ * return type read `TSchema`'s presence directly (`[TSchema] extends
+ * [undefined]`), so a widened config passed the guard (its output read as "not
+ * given") but the return type's presence check still saw `TSchema` and took
+ * the `InferOutput` branch, producing `unknown` — silently discarding an
+ * explicit `TResponse`. One shared rule, asked once.
+ */
+type SchemaOut<TSchema> = [TSchema] extends [undefined] ? unknown : InferOutput<TSchema>;
+/**
+ * Refuses a schema and an explicit response type together.
+ *
+ * Two sources of truth that can disagree is a mistake, and this project makes a
+ * contradiction unrepresentable rather than picking a winner silently — the same
+ * reasoning as the `share` + `dedupe` throw and the empty-body guard.
+ *
+ * It fires even when the two AGREE, because the failure it prevents is temporal:
+ * the schema changes, the explicit type is now wrong, and nothing reports it
+ * because it was never being read.
+ *
+ * `unknown extends TResponse` is true only when no explicit argument was given,
+ * which is what makes "was one supplied?" answerable at all. `any` satisfies it
+ * too and counts as "not given" — acceptable, since `defineRequest<any>()` is
+ * already opting out of everything.
+ *
+ * The "was a schema given?" side reads `SchemaOut<TSchema>` — the schema's
+ * OUTPUT — rather than asking whether `TSchema` itself is `undefined`, and the
+ * config field feeding it is `Omit<RequestConfig, 'schema'> & { schema?:
+ * TSchema }` rather than `RequestConfig & { schema?: TSchema }`. Both changes
+ * exist for the same reason: `RequestConfig` already declares `schema?:
+ * StandardSchemaV1<unknown>` (for `new Request`), so a config typed as plain
+ * `RequestConfig` — or a spread of one — structurally carries that field
+ * whether or not a schema was actually written. Left in the intersection, that
+ * field becomes a second, competing inference source for `TSchema`, and —
+ * only when `TSchema` also appears inside a conditional in the SAME parameter,
+ * which is what a "was one given?" guard requires — TypeScript stops
+ * decomposing a non-literal argument (a bare `RequestConfig`-typed variable)
+ * property by property and falls back to `TSchema`'s default instead, which
+ * then disagrees with the very shape it just failed to read. `Omit` removes
+ * the competing source; reading the OUTPUT instead of `TSchema` itself
+ * survives whatever that source infers anyway, because an unknown-output
+ * schema (the widened `StandardSchemaV1<unknown>`, same as a plain
+ * `undefined`) reads as "not given" right alongside the real absence.
+ *
+ * A schema carrying no type information — an OUTPUT of `unknown` or `any` —
+ * is treated as no schema at all: the explicit response type is HONOURED, and
+ * no conflict is raised. `defineRequest<User>()({ ..., schema:
+ * looselyTypedSchema })` compiles and its `data` is `User`, not `unknown`.
+ * This is not a gap being tolerated; it is what makes a widened
+ * `RequestConfig`-typed config work at all — a spread of one carries exactly
+ * `schema?: StandardSchemaV1<unknown>`, inherited from `RequestConfig` itself,
+ * and a schema written directly can be just as loosely typed. A schema that
+ * DOES carry type information — a concrete `Output` — supplies the response
+ * type instead (see `defineRequest`'s return-type expression), and an
+ * explicit type alongside THAT is the conflict this guard exists to catch.
+ *
+ * This falls out of `SchemaOut` for free, and only BECAUSE the guard and
+ * `defineRequest`'s return type read it identically. That took two attempts:
+ * moving the guard onto `SchemaOut` (the OUTPUT paragraph above) fixed the
+ * guard's own over-rejection of widened configs, but the return type was left
+ * reading `[TSchema] extends [undefined]` directly — the schema's PRESENCE,
+ * not its output — so a widened config now passed the guard while the return
+ * type still discarded its `TResponse`. Same mistake as the original
+ * over-rejection, just relocated: two formulas answering one question. Both
+ * disappeared once both sites read `SchemaOut`. Do not let them drift apart
+ * again: change `SchemaConflictGuard` and `defineRequest`'s return-type
+ * expression together, and reverify against `tests/types.test-d.ts`'s
+ * widened-config assertions, which check the resulting `data` type via
+ * `createApi` rather than merely that the call compiles — editing one site
+ * without the other, unverified, is exactly how this regressed.
+ */
+type SchemaConflictGuard<TSchema, TResponse> = unknown extends SchemaOut<TSchema> ? unknown : unknown extends TResponse ? unknown : {
+    __schemaSuppliesTheType: 'omit the explicit response type when passing a schema';
+};
+/**
+ * Declares an endpoint, inferring its path parameters from the `path` literal.
+ *
+ * Curried because TypeScript has no partial type-argument inference: supplying
+ * `TResponse` and the config in ONE call makes `TPath` fall back to its
+ * constraint, `PathParams<string>` resolve to `{}`, and `{}` accepts anything —
+ * the feature disappears with no error anywhere, which is precisely how the
+ * 3.1.0 guard attempt failed. Two calls keep the response type explicit and the
+ * path inferred.
+ *
+ * `TExtra` is for params the path does not name — query or body fields.
+ *
+ * Returns an ordinary `Request`, so `createApi` needs no knowledge of this
+ * function: its `ExtractParams`/`ExtractResponse` already match structurally.
+ * `new Request(...)` remains and is not deprecated; this is a second way to
+ * construct, which is what makes it additive.
+ *
+ * @example
+ * ```ts
+ * const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
+ * const listRepos = defineRequest<Repo[], { page?: number }>()({
+ *   method: 'GET',
+ *   path: '/orgs/:org/repos',
+ * })
+ *
+ * api.getUser({ id: '42' })               // ✓
+ * api.getUser({ userId: '42' })           // ✗ compile error
+ * api.listRepos({ org: 'acme', page: 2 }) // ✓
+ * ```
+ */
+export declare function defineRequest<TResponse = unknown, TExtra extends object = {}>(): <TPath extends string, TRT extends ResponseType | undefined, TSchema extends StandardSchemaV1<any> | undefined = undefined>(config: Omit<RequestConfig, "schema"> & {
+    path: TPath;
+    responseType?: TRT;
+    schema?: TSchema;
+} & EmptyBodyGuard<TRT, TResponse> & SchemaConflictGuard<TSchema, TResponse> & FragmentGuard<TPath>) => Request<Id<PathParams<TPath> & TExtra>, unknown extends SchemaOut<TSchema> ? TResponse : SchemaOut<TSchema>>;
+export {};

package/dist/define-request.js

@@ -0,0 +1,4 @@
+import { Request } from './request.js';
+export function defineRequest() {
+    return (config) => new Request(config);
+}

package/dist/graphql.d.ts

@@ -0,0 +1,30 @@
+import type { CallOptions, Result, GraphQLBaseConfig, OperationConfig } from './types.js';
+export declare class Operation<TVariables extends object, TData> {
+    readonly config: OperationConfig;
+    readonly _variables: TVariables;
+    readonly _data: TData;
+    constructor(config: OperationConfig);
+}
+export declare const gql: (strings: TemplateStringsArray, ...values: unknown[]) => string;
+type GraphQLMethod<TVariables extends object, TData> = Record<string, never> extends TVariables ? (variables?: TVariables, options?: CallOptions) => Promise<Result<TData>> : (variables: TVariables, options?: CallOptions) => Promise<Result<TData>>;
+type FlatClient<TOperations> = {
+    [K in keyof TOperations]: TOperations[K] extends Operation<infer V, infer D> ? GraphQLMethod<V, D> : never;
+};
+type SplitClient<TQ, TM> = (TQ extends Record<string, Operation<any, any>> ? {
+    query: FlatClient<TQ>;
+} : {}) & (TM extends Record<string, Operation<any, any>> ? {
+    mutation: FlatClient<TM>;
+} : {});
+type WithOperations<T> = GraphQLBaseConfig & {
+    operations: T;
+    queries?: never;
+    mutations?: never;
+};
+type WithSplit<TQ, TM> = GraphQLBaseConfig & {
+    operations?: never;
+    queries?: TQ;
+    mutations?: TM;
+};
+export declare function createGraphQL<T extends Record<string, Operation<any, any>>>(config: WithOperations<T>): FlatClient<T>;
+export declare function createGraphQL<TQ extends Record<string, Operation<any, any>>, TM extends Record<string, Operation<any, any>>>(config: WithSplit<TQ, TM>): SplitClient<TQ, TM>;
+export {};