liaise 0.0.0 → 5.0.0

package/dist/built-in-middleware.d.ts

@@ -0,0 +1,232 @@
+import type { Middleware, RetryOptions } from './types.js';
+export type { RetryOptions, RetryInfo } from './types.js';
+/**
+ * Creates a middleware that retries failed requests with a real backoff
+ * policy: exponential (or linear, or custom) delay curves, full jitter,
+ * `Retry-After` support, a configurable retry predicate, and an observational
+ * `onRetry` hook.
+ *
+ * **How it works:**
+ *
+ * When the downstream chain (via `next()`) returns a result that `retryOn`
+ * accepts, this middleware waits out a delay and calls `next()` again —
+ * re-executing every middleware below it in the onion plus the core fetch.
+ * It keeps retrying until either the predicate rejects the result, or `max`
+ * attempts have been exhausted.
+ *
+ * **Delay:**
+ *
+ * The base delay comes from the configured curve (`baseDelay * 2^(attempt-1)`
+ * for `'exponential'`, `baseDelay * attempt` for `'linear'`, or a custom
+ * function of the attempt number), capped by `maxDelay`. Full jitter then
+ * applies: the actual delay is `Math.random() * computed`, per AWS's
+ * recommendation for de-synchronising a thundering herd. A `Retry-After`
+ * response header — when present and `respectRetryAfter` is not disabled —
+ * replaces the computed delay outright (still capped by `maxDelay`) and is
+ * honoured as-is, without jitter: a server telling you exactly when to come
+ * back should not be randomised.
+ *
+ * **Abortable sleep:**
+ *
+ * The backoff sleep watches `ctx.request.signal`, so a whole-operation
+ * `timeout` cannot be outlived by a long delay: the sleep resolves (rather
+ * than rejects) as soon as the signal aborts, and the loop proceeds straight
+ * to `next()`. With an already-aborted signal, the core fetch rejects
+ * immediately (no network call), and its existing abort classification does
+ * the rest — the result comes back with `kind: 'timeout'` for a deadline,
+ * `kind: 'abort'` for a cancellation or a dedupe supersede — instead of this
+ * middleware reporting a stale HTTP result for a request that was actually
+ * cancelled or timed out. The loop then exits on its own, since an abort is
+ * status 0 and the default `retryOn` only matches `status >= 500`.
+ *
+ * **What it does NOT retry by default:**
+ *
+ * - 4xx errors — caused by the request itself, not transient server issues.
+ * - 429 and network errors (status 0) — deliberately excluded from the
+ *   default so upgrading doesn't change behaviour under you; pass a custom
+ *   `retryOn` to opt in.
+ *
+ * **Retry count semantics:**
+ *
+ * `max` is the number of ADDITIONAL attempts after the initial one. So
+ * `retryMiddleware(2)` (or `{ max: 2 }`) means: 1 initial attempt + up to 2
+ * retries = 3 total calls to `next()` in the worst case.
+ *
+ * **Middleware position matters:**
+ *
+ * Because `next()` re-executes everything downstream, placing retry
+ * middleware BEFORE auth middleware means auth headers will be re-injected
+ * on each retry (good). Placing it AFTER means the same headers are reused
+ * (usually fine, but stale tokens won't be refreshed).
+ *
+ * @param options - Either a number (shorthand for `{ max: number }`, kept for
+ *   backwards compatibility) or a {@link RetryOptions} object. Defaults to 3.
+ * @returns A Middleware function that can be passed to `createApi` or
+ *   individual `Request` configs.
+ *
+ * @example
+ * ```ts
+ * // Retry up to 2 times on server errors (3 total attempts), numeric shorthand
+ * const api = createApi({
+ *   baseUrl: '/api',
+ *   requests: { getItems },
+ *   middleware: [retryMiddleware(2)],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Full policy: linear backoff, a higher cap, and progress reporting
+ * const api = createApi({
+ *   baseUrl: '/api',
+ *   requests: { getItems },
+ *   middleware: [retryMiddleware({
+ *     max: 5,
+ *     delay: 'linear',
+ *     baseDelay: 200,
+ *     maxDelay: 10_000,
+ *     onRetry: ({ attempt, max, delay }) => console.log(`retry ${attempt}/${max} in ${delay}ms`),
+ *   })],
+ * })
+ * ```
+ */
+export declare function retryMiddleware(options?: number | RetryOptions): Middleware;
+/**
+ * Middleware that logs the lifecycle of each API request to the console.
+ *
+ * **What it logs:**
+ *
+ * 1. A "request start" line when the request begins, showing the HTTP method,
+ *    the request name (e.g., 'getUser'), and the full URL.
+ *
+ * 2. A "request complete" line when the response arrives, showing:
+ *    - The request name
+ *    - Whether it succeeded ("OK") or failed ("ERROR" + status code)
+ *    - The elapsed time in milliseconds
+ *
+ * **Timing:**
+ *
+ * Uses `Date.now()` instead of `performance.now()` for maximum runtime
+ * compatibility. `performance.now()` is not available in all environments
+ * (e.g., some edge runtimes, older Node.js versions), while `Date.now()`
+ * works everywhere. The millisecond precision of `Date.now()` is more than
+ * sufficient for HTTP request timing.
+ *
+ * **Output format examples:**
+ *
+ * ```
+ * [liaise] → GET getItems /api/items
+ * [liaise] ← getItems OK (142ms)
+ *
+ * [liaise] → POST createUser /api/users
+ * [liaise] ← createUser ERROR 422 (89ms)
+ * ```
+ *
+ * **Usage note:**
+ *
+ * This middleware is intended for development and debugging. In production,
+ * you may want to replace it with a custom middleware that sends telemetry
+ * to your observability platform instead of logging to the console.
+ *
+ * @example
+ * ```ts
+ * import { logMiddleware } from 'liaise/middleware'
+ *
+ * const api = createApi({
+ *   baseUrl: '/api',
+ *   requests: { getItems, createUser },
+ *   middleware: [logMiddleware],
+ * })
+ * ```
+ */
+export declare const logMiddleware: Middleware;
+export type CacheMiddleware = Middleware & {
+    clear(): void;
+};
+/**
+ * Creates a middleware that caches successful responses in memory, keyed by
+ * request name and params. Identical calls within the TTL window are served
+ * from cache without hitting the network.
+ *
+ * **Cache key:**
+ *
+ * The key is `ctx.requestName` plus `stableKey(ctx.request.params)` — a
+ * content-based key (see `src/utils/stable-key.ts`): object keys sorted,
+ * `undefined` members dropped, `Date` by its ISO string, `Map`, `Set` and
+ * typed arrays by their entries. It is derived from the original params
+ * object, not the processed URL.
+ *
+ * A call whose params cannot be keyed soundly — a BigInt, an `ArrayBuffer`,
+ * `Blob`, `FormData` or `URLSearchParams`, a circular structure, or an object
+ * with no enumerable state, at any depth — is never cached and never served
+ * from cache. Declining is always safe; serving one caller the response to a
+ * different payload never is. A raw string keys fine and is cached normally.
+ *
+ * **What is cached:**
+ *
+ * Only successful results are stored. If the response has an error (4xx, 5xx,
+ * network error, or GraphQL error), the result is not cached and the next call
+ * will hit the network again.
+ *
+ * The full `Result` object is cached, including `response` (headers, status)
+ * and `retry`. Calling `retry()` on a cached result re-enters the middleware
+ * chain — if the TTL is still valid it returns the cached value; if expired,
+ * it makes a fresh network call. To force a network call on a specific
+ * invocation, use `skipMiddleware: [myCache]` in the call options.
+ *
+ * **Isolation:**
+ *
+ * Each call to `cacheMiddleware()` creates an independent store. Two separate
+ * instances on two different endpoints never share entries, regardless of
+ * request name or params shape.
+ *
+ * **Eviction:**
+ *
+ * When the store reaches `maxSize`, the oldest entry by insertion time is
+ * evicted before the new one is added. Expired entries are removed on access
+ * rather than on a background timer.
+ *
+ * **Debugging:**
+ *
+ * Set `debug: true` to log cache hits and misses to the console:
+ * ```
+ * [liaise cache] HIT  getUser {"id":"42"}
+ * [liaise cache] MISS getUser {"id":"42"}
+ * ```
+ *
+ * @param options.ttl - Time-to-live in milliseconds. Defaults to 5 minutes.
+ * @param options.maxSize - Maximum number of entries. Defaults to 50.
+ * @param options.debug - Log hits and misses to console. Defaults to false.
+ * @returns A middleware function with an attached `clear()` method.
+ *
+ * @example
+ * ```ts
+ * import { cacheMiddleware } from 'liaise/middleware'
+ *
+ * const getUserCache = cacheMiddleware({ ttl: 5 * 60_000, maxSize: 100 })
+ *
+ * const getUser = new Request<{ id: string }, User>({
+ *   method: 'GET',
+ *   path: '/users/:id',
+ *   middleware: [getUserCache],
+ * })
+ *
+ * // Force a network call for a single invocation:
+ * const { data } = await api.getUser({ id: '42' }, { skipMiddleware: [getUserCache] })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Clear all cached entries on logout so the next user gets fresh data:
+ * const getUserCache = cacheMiddleware({ ttl: 5 * 60_000 })
+ *
+ * function onLogout() {
+ *   getUserCache.clear()
+ * }
+ * ```
+ */
+export declare function cacheMiddleware(options?: {
+    ttl?: number;
+    maxSize?: number;
+    debug?: boolean;
+}): CacheMiddleware;

package/dist/built-in-middleware.js

@@ -0,0 +1,127 @@
+import { CacheStore } from './utils/cache.js';
+import { stableKey } from './utils/stable-key.js';
+function sleep(ms, signal) {
+    return new Promise(resolve => {
+        if (signal?.aborted)
+            return resolve();
+        const cleanup = () => { signal?.removeEventListener('abort', onAbort); };
+        const onAbort = () => { clearTimeout(timer); cleanup(); resolve(); };
+        const timer = setTimeout(() => { cleanup(); resolve(); }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const when = Date.parse(trimmed);
+    if (Number.isNaN(when))
+        return null;
+    return Math.max(0, when - Date.now());
+}
+export function retryMiddleware(options = 3) {
+    const o = typeof options === 'number' ? { max: options } : options;
+    const max = o.max ?? 3;
+    const curve = o.delay ?? 'exponential';
+    const baseDelay = typeof o.baseDelay === 'number' && !Number.isNaN(o.baseDelay) ? o.baseDelay : 250;
+    const maxDelay = typeof o.maxDelay === 'number' && !Number.isNaN(o.maxDelay) ? o.maxDelay : 30000;
+    const jitter = o.jitter ?? true;
+    const respectRetryAfter = o.respectRetryAfter ?? true;
+    const retryOn = o.retryOn ?? ((r) => (r.error?.status ?? 0) >= 500);
+    const shouldRetry = (r, attempt) => {
+        try {
+            return retryOn(r, attempt);
+        }
+        catch {
+            return false;
+        }
+    };
+    const computeDelay = (attempt) => {
+        const fallback = baseDelay * 2 ** (attempt - 1);
+        if (typeof curve === 'function') {
+            let computed;
+            try {
+                computed = curve(attempt);
+            }
+            catch {
+                return fallback;
+            }
+            if (!Number.isFinite(computed))
+                return fallback;
+            return Math.max(0, computed);
+        }
+        return curve === 'linear' ? baseDelay * attempt : fallback;
+    };
+    return async (ctx, next) => {
+        let result = await next();
+        let attempt = 0;
+        while (shouldRetry(result, attempt + 1)) {
+            if (attempt >= max)
+                break;
+            attempt++;
+            const header = respectRetryAfter ? parseRetryAfter(result.response?.headers.get('retry-after') ?? null) : null;
+            let delay = Math.min(header ?? computeDelay(attempt), maxDelay);
+            if (!Number.isFinite(delay) || delay < 0)
+                delay = 0;
+            if (header === null && jitter)
+                delay = Math.random() * delay;
+            if (o.onRetry) {
+                const info = { attempt, max, delay, result };
+                try {
+                    o.onRetry(info);
+                }
+                catch { }
+            }
+            await sleep(delay, ctx.request.signal);
+            result = await next();
+        }
+        return result;
+    };
+}
+export const logMiddleware = async (ctx, next) => {
+    const start = Date.now();
+    console.log(`[liaise] → ${ctx.request.method} ${ctx.requestName} ${ctx.request.url}`);
+    const result = await next();
+    const duration = Date.now() - start;
+    if (result.error) {
+        console.log(`[liaise] ← ${ctx.requestName} ERROR ${result.error.status} (${duration}ms)`);
+    }
+    else {
+        console.log(`[liaise] ← ${ctx.requestName} OK (${duration}ms)`);
+    }
+    return result;
+};
+export function cacheMiddleware(options) {
+    const store = new CacheStore({
+        ttl: options?.ttl ?? 5 * 60000,
+        maxSize: options?.maxSize ?? 50,
+    });
+    const debug = options?.debug ?? false;
+    const mw = async (ctx, next) => {
+        const paramsStr = stableKey(ctx.request.params);
+        if (paramsStr === null)
+            return next();
+        const key = `${ctx.requestName}|${paramsStr}`;
+        const cached = store.get(key);
+        if (cached !== null) {
+            if (debug)
+                console.log(`[liaise cache] HIT  ${ctx.requestName} ${paramsStr}`);
+            return cached;
+        }
+        if (debug)
+            console.log(`[liaise cache] MISS ${ctx.requestName} ${paramsStr}`);
+        const result = await next();
+        if (!result.error) {
+            store.set(key, result);
+        }
+        return result;
+    };
+    const fn = mw;
+    fn.clear = () => store.clear();
+    return fn;
+}

package/dist/create-api.d.ts

@@ -0,0 +1,120 @@
+import { Request } from './request.js';
+import type { ApiConfig, CallOptions, Result } from './types.js';
+/**
+ * Extracts the TParams type from a Request instance.
+ *
+ * Given `Request<{ id: string }, User>`, this resolves to `{ id: string }`.
+ * Used internally by the Api mapped type to infer method parameter types.
+ *
+ * @typeParam R - A Request instance (or anything — returns `never` for non-Request types).
+ */
+type ExtractParams<R> = R extends Request<infer P, any> ? P : never;
+/**
+ * Extracts the TResponse type from a Request instance.
+ *
+ * Given `Request<{ id: string }, User>`, this resolves to `User`.
+ * Used internally by the Api mapped type to infer method return types.
+ *
+ * @typeParam R - A Request instance (or anything — returns `never` for non-Request types).
+ */
+type ExtractResponse<R> = R extends Request<any, infer Res> ? Res : never;
+/**
+ * Defines the signature of a generated API method.
+ *
+ * The key trick here is the conditional type: when TParams is
+ * `Record<string, never>` (an empty object — meaning the endpoint takes no
+ * params), the `params` argument becomes optional. This allows callers to
+ * write `api.health()` instead of `api.health({})`.
+ *
+ * The condition `Record<string, never> extends TParams` works because:
+ * - When TParams IS Record<string, never>, the condition is true → optional params
+ * - When TParams has required keys (e.g., { id: string }), Record<string, never>
+ *   does NOT extend it → required params
+ *
+ * @typeParam TParams - The params type for this endpoint.
+ * @typeParam TResponse - The response type for this endpoint.
+ */
+type ApiMethod<TParams extends object, TResponse> = Record<string, never> extends TParams ? (params?: TParams, options?: CallOptions) => Promise<Result<TResponse>> : (params: TParams, options?: CallOptions) => Promise<Result<TResponse>>;
+/**
+ * The typed API object returned by createApi.
+ *
+ * This is a mapped type that transforms a record of Request instances into
+ * a record of callable methods. Each key from the `requests` config becomes
+ * a method with fully typed params and response.
+ *
+ * @example
+ * ```ts
+ * // Given:
+ * const requests = {
+ *   getUser: new Request<{ id: string }, User>({ ... }),
+ *   listUsers: new Request<Record<string, never>, User[]>({ ... }),
+ * }
+ *
+ * // Api<typeof requests> resolves to:
+ * {
+ *   getUser: (params: { id: string }, options?: CallOptions) => Promise<Result<User>>
+ *   listUsers: (params?: Record<string, never>, options?: CallOptions) => Promise<Result<User[]>>
+ * }
+ * ```
+ *
+ * @typeParam TRequests - The record of Request instances from the config.
+ */
+type Api<TRequests extends Record<string, Request<any, any>>> = {
+    [K in keyof TRequests]: ApiMethod<ExtractParams<TRequests[K]>, ExtractResponse<TRequests[K]>>;
+};
+/**
+ * Creates a typed API client from a set of Request definitions.
+ *
+ * This is the primary entry point of the liaise library. It takes a configuration
+ * object containing a base URL, request definitions, optional global middleware,
+ * default headers, and an error callback, and returns an object where each request
+ * key becomes a callable, fully-typed method.
+ *
+ * **How it works internally:**
+ *
+ * For each Request in the `requests` record, createApi generates a method that:
+ * 1. Builds the URL from baseUrl + path template + params (path param substitution)
+ * 2. Merges headers from three layers (global < per-request < per-call)
+ * 3. Serializes the body (JSON for plain objects, passthrough for FormData/Blob/etc.)
+ * 4. Computes the effective abort signal (includes dedupe tracking if enabled)
+ * 5. Composes the middleware chain (global → per-request → per-call, minus skipped)
+ * 6. Executes the chain, with the core fetch as the innermost layer
+ * 7. Fires the onError callback if the final result has an error
+ *
+ * **Dedupe integration:**
+ *
+ * A single DedupeTracker instance is created per createApi call. When a Request
+ * has `dedupe: true`, the abort signal is routed through the tracker before being
+ * passed to fetch. This means that firing a new request for the same endpoint
+ * automatically cancels any previous in-flight request — perfect for
+ * search-as-you-type, paginated lists, or rapidly changing filters.
+ *
+ * **Error handling philosophy:**
+ *
+ * The library never throws — every outcome is expressed as a Result<T>.
+ * - HTTP errors (4xx, 5xx) → Result with error, response, and retry
+ * - Network errors → Result with error (status 0), null response, and retry
+ * - Synchronous errors (e.g., TypeError from query string serialization) → same
+ *
+ * @typeParam TRequests - Record of Request instances. Keys become method names,
+ *   and the Request's TParams/TResponse generics become the method's signature.
+ *
+ * @param config - API configuration with baseUrl, requests, middleware, headers, onError.
+ * @returns A typed object where each request key is a callable method.
+ *
+ * @example
+ * ```ts
+ * const api = createApi({
+ *   baseUrl: '/api',
+ *   requests: { getUser, listUsers, createUser },
+ *   middleware: [authMiddleware, logMiddleware],
+ *   headers: { 'X-App-Version': '2.0.0' },
+ *   onError: (error) => Sentry.captureException(error),
+ * })
+ *
+ * // Fully typed: params and response inferred from Request generics
+ * const { data, error, retry } = await api.getUser({ id: '42' })
+ * ```
+ */
+export declare function createApi<TRequests extends Record<string, Request<any, any>>>(config: ApiConfig<TRequests>): Api<TRequests>;
+export {};