@c9up/ream 0.1.3

package/dist/testing/RequestBuilder.js

@@ -0,0 +1,202 @@
+/** Assertion failure — plain Error so tests see a clean stack trace. */
+class ExpectationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExpectationError';
+    }
+}
+export class RequestBuilder {
+    #sender;
+    #method;
+    #path;
+    #headers = {};
+    #body = Buffer.alloc(0);
+    #cookies = {};
+    #authStrategy;
+    #pendingAuth = null;
+    #sent = null;
+    constructor(sender, method, path, authStrategy = null) {
+        this.#sender = sender;
+        this.#method = method;
+        this.#path = path;
+        this.#authStrategy = authStrategy;
+    }
+    headers(map) {
+        for (const [k, v] of Object.entries(map)) {
+            this.#headers[k.toLowerCase()] = v;
+        }
+        return this;
+    }
+    header(name, value) {
+        this.#headers[name.toLowerCase()] = value;
+        return this;
+    }
+    json(data) {
+        this.#body = Buffer.from(JSON.stringify(data), 'utf8');
+        this.#headers['content-type'] = 'application/json';
+        return this;
+    }
+    body(data, contentType) {
+        this.#body = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+        if (contentType)
+            this.#headers['content-type'] = contentType;
+        return this;
+    }
+    form(data) {
+        const pairs = Object.entries(data).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
+        this.#body = Buffer.from(pairs.join('&'), 'utf8');
+        this.#headers['content-type'] = 'application/x-www-form-urlencoded';
+        return this;
+    }
+    cookies(map) {
+        Object.assign(this.#cookies, map);
+        return this;
+    }
+    cookie(name, value) {
+        this.#cookies[name] = value;
+        return this;
+    }
+    /**
+     * Attach auth for a user. Uses the strategy passed to `client`'s `auth`
+     * option — Warden's session/JWT/API-key strategy decides the header/cookie
+     * shape. Without a strategy, throws at send time.
+     */
+    withAuth(subject) {
+        this.#pendingAuth = subject;
+        return this;
+    }
+    /** Shortcut for `withAuth({ id: userId })` — user is identified by id only. */
+    asUser(userId) {
+        this.#pendingAuth = { id: userId };
+        return this;
+    }
+    /** Fire the request (once) and return the raw response. Idempotent. */
+    send() {
+        if (this.#sent === null)
+            this.#sent = this.#execute();
+        return this.#sent;
+    }
+    async expectStatus(code) {
+        const res = await this.send();
+        if (res.status !== code) {
+            throw new ExpectationError(`Expected status ${code}, got ${res.status}. Body: ${capBody(res.body)}`);
+        }
+        return this;
+    }
+    async expectHeader(name, value) {
+        const res = await this.send();
+        const actual = res.headers[name.toLowerCase()];
+        if (actual === undefined) {
+            throw new ExpectationError(`Expected header ${name}, not present in response headers: ${Object.keys(res.headers).join(', ')}`);
+        }
+        if (value instanceof RegExp) {
+            if (!value.test(actual)) {
+                throw new ExpectationError(`Expected header ${name} to match ${value}, got "${actual}"`);
+            }
+        }
+        else if (actual !== value) {
+            throw new ExpectationError(`Expected header ${name} = "${value}", got "${actual}"`);
+        }
+        return this;
+    }
+    async expectCookie(name, value) {
+        const res = await this.send();
+        const setCookie = res.headers['set-cookie'];
+        if (!setCookie) {
+            throw new ExpectationError(`Expected cookie ${name}, but no Set-Cookie header was returned`);
+        }
+        const cookies = setCookie.split(/,(?=\s*\w+=)/);
+        const match = cookies.find((c) => c.trimStart().startsWith(`${name}=`));
+        if (!match) {
+            throw new ExpectationError(`Expected cookie ${name}, not found in: ${setCookie}`);
+        }
+        if (value === undefined)
+            return this;
+        const rawVal = match.split(';')[0]?.split('=')[1] ?? '';
+        if (value instanceof RegExp) {
+            if (!value.test(rawVal)) {
+                throw new ExpectationError(`Expected cookie ${name} to match ${value}, got "${rawVal}"`);
+            }
+        }
+        else if (rawVal !== value) {
+            throw new ExpectationError(`Expected cookie ${name} = "${value}", got "${rawVal}"`);
+        }
+        return this;
+    }
+    async expectJson(expected) {
+        const res = await this.send();
+        let actual;
+        try {
+            actual = res.json();
+        }
+        catch (err) {
+            throw new ExpectationError(`Expected JSON body, got non-JSON. Body: ${capBody(res.body)} (parse error: ${err instanceof Error ? err.message : String(err)})`);
+        }
+        if (!partialMatch(actual, expected)) {
+            throw new ExpectationError(`JSON partial match failed.\nExpected (partial): ${JSON.stringify(expected)}\nActual: ${capBody(JSON.stringify(actual))}`);
+        }
+        return this;
+    }
+    async #execute() {
+        // Resolve auth before sending.
+        if (this.#pendingAuth !== null) {
+            if (!this.#authStrategy) {
+                throw new Error('RequestBuilder: `withAuth()` / `asUser()` called but no AuthStrategy was provided via the client `auth` option.');
+            }
+            const authHeaders = await this.#authStrategy.headersFor(this.#pendingAuth);
+            for (const [k, v] of Object.entries(authHeaders)) {
+                this.#headers[k.toLowerCase()] = v;
+            }
+            if (this.#authStrategy.cookiesFor) {
+                const authCookies = await this.#authStrategy.cookiesFor(this.#pendingAuth);
+                Object.assign(this.#cookies, authCookies);
+            }
+            if (this.#pendingAuth.extraHeaders) {
+                for (const [k, v] of Object.entries(this.#pendingAuth.extraHeaders)) {
+                    this.#headers[k.toLowerCase()] = v;
+                }
+            }
+        }
+        // Serialise cookies into a single `Cookie:` header.
+        const cookieEntries = Object.entries(this.#cookies);
+        if (cookieEntries.length > 0) {
+            this.#headers.cookie = cookieEntries.map(([k, v]) => `${k}=${v}`).join('; ');
+        }
+        return this.#sender(this.#method, this.#path, {
+            headers: this.#headers,
+            body: this.#body,
+        });
+    }
+}
+function capBody(s, max = 512) {
+    return s.length <= max ? s : `${s.slice(0, max)}...[truncated]`;
+}
+/** Narrowing guard — a non-null, non-array object usable as a string map. */
+function isRecord(x) {
+    return typeof x === 'object' && x !== null && !Array.isArray(x);
+}
+/**
+ * Partial deep-match. For objects, every key in `expected` must match in
+ * `actual`. For arrays, every element in `expected` must match SOMEWHERE in
+ * `actual` (order-independent). Primitives compared by strict equality.
+ */
+export function partialMatch(actual, expected) {
+    if (expected === null || expected === undefined) {
+        return actual === expected;
+    }
+    if (typeof expected !== 'object')
+        return actual === expected;
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual))
+            return false;
+        return expected.every((want) => actual.some((have) => partialMatch(have, want)));
+    }
+    if (!isRecord(actual) || !isRecord(expected))
+        return false;
+    for (const key of Object.keys(expected)) {
+        if (!partialMatch(actual[key], expected[key]))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=RequestBuilder.js.map

package/dist/testing/RequestBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestBuilder.js","sourceRoot":"","sources":["../../src/testing/RequestBuilder.ts"],"names":[],"mappings":"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"}

package/dist/testing/TestClient.d.ts

@@ -0,0 +1,96 @@
+/**
+ * TestClient — supertest-like HTTP client for integration testing.
+ *
+ * Boots a Ream application on an ephemeral port and provides a fluent API
+ * for sending requests and asserting responses.
+ *
+ * Usage:
+ *   const client = new TestClient(createApp)
+ *   await client.boot()
+ *   const res = await client.get('/api/health')
+ *   expect(res.status).toBe(200)
+ *   await client.close()
+ *
+ * Or with the helper:
+ *   const client = await createTestClient(createApp)
+ *   const res = await client.post('/api/users').json({ name: 'Alice' }).send()
+ *   await client.close()
+ */
+import type { Dict } from '../types/helpers.js';
+import { type AuthStrategy, type HttpMethod, RequestBuilder } from './RequestBuilder.js';
+export interface TestResponse {
+    status: number;
+    headers: Dict;
+    body: string;
+    json<T = unknown>(): T;
+}
+export interface TestRequestBuilder {
+    /** Set a request header. */
+    header(name: string, value: string): TestRequestBuilder;
+    /** Set the request body as JSON. */
+    json(data: unknown): TestRequestBuilder;
+    /** Set a raw string body with optional content type. */
+    body(content: string, contentType?: string): TestRequestBuilder;
+    /** Set a cookie. */
+    cookie(name: string, value: string): TestRequestBuilder;
+    /** Send the request and return the response. */
+    send(): Promise<TestResponse>;
+}
+export declare class TestClient {
+    #private;
+    constructor(bootFn: (port: number) => Promise<{
+        port: number;
+        close: () => Promise<void> | void;
+    }>, options?: {
+        auth?: AuthStrategy;
+    });
+    /** Boot the application on a random port. */
+    boot(): Promise<void>;
+    /** Close the server. */
+    close(): Promise<void>;
+    /**
+     * Ephemeral port the booted server bound to. Useful for long-lived
+     * connections (SSE / WebSocket) that the fluent buffered request
+     * surface can't model — open them with `fetch` against
+     * `http://127.0.0.1:${client.port}/...`. Returns 0 before `boot()`.
+     */
+    get port(): number;
+    /** Set a default header for all requests. */
+    withHeader(name: string, value: string): this;
+    /** GET request. */
+    get(path: string): Promise<TestResponse>;
+    /** POST request. */
+    post(path: string): TestRequestBuilder;
+    /** PUT request. */
+    put(path: string): TestRequestBuilder;
+    /** PATCH request. */
+    patch(path: string): TestRequestBuilder;
+    /** DELETE request. */
+    delete(path: string): Promise<TestResponse>;
+    /**
+     * Build a request with the rich fluent surface: chained assertions
+     * (`expectStatus` / `expectJson` / `expectHeader` / `expectCookie`), auth
+     * injection (`withAuth` / `asUser`, needs the `auth` client option), and
+     * `form()`. The lower-level `request()` (below) stays for raw control.
+     */
+    fluent(method: HttpMethod, path: string): RequestBuilder;
+    /** Build a request with the low-level fluent API. */
+    request(method: string, path: string): TestRequestBuilder;
+}
+/** Create and boot a test client in one call. */
+export declare function createTestClient(bootFn: (port: number) => Promise<{
+    port: number;
+    close: () => Promise<void> | void;
+}>, options?: {
+    auth?: AuthStrategy;
+}): Promise<TestClient>;
+export { type AuthStrategy, type AuthSubject, type HttpMethod, type HttpSender, partialMatch, RequestBuilder, } from './RequestBuilder.js';
+/**
+ * Parse a raw HTTP response. Accepts the wire bytes (Buffer) or a UTF-8
+ * string for back-compat with older test callers. Chunked decoding runs on
+ * the Buffer to keep byte-counting honest — HTTP counts bytes (RFC 7230),
+ * not UTF-16 code units, so doing the work on a `.toString('utf8')` string
+ * silently truncated non-ASCII and binary responses.
+ */
+export declare function parseHttpResponse(raw: string | Buffer): TestResponse;
+//# sourceMappingURL=TestClient.d.ts.map

package/dist/testing/TestClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestClient.d.ts","sourceRoot":"","sources":["../../src/testing/TestClient.ts"],"names":[],"mappings":"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"}

package/dist/testing/TestClient.js

@@ -0,0 +1,263 @@
+/**
+ * TestClient — supertest-like HTTP client for integration testing.
+ *
+ * Boots a Ream application on an ephemeral port and provides a fluent API
+ * for sending requests and asserting responses.
+ *
+ * Usage:
+ *   const client = new TestClient(createApp)
+ *   await client.boot()
+ *   const res = await client.get('/api/health')
+ *   expect(res.status).toBe(200)
+ *   await client.close()
+ *
+ * Or with the helper:
+ *   const client = await createTestClient(createApp)
+ *   const res = await client.post('/api/users').json({ name: 'Alice' }).send()
+ *   await client.close()
+ */
+import { RequestBuilder, } from './RequestBuilder.js';
+export class TestClient {
+    #port = 0;
+    #headers = {};
+    #bootFn;
+    #auth;
+    constructor(bootFn, options = {}) {
+        this.#bootFn = bootFn;
+        this.#auth = options.auth ?? null;
+    }
+    #server = null;
+    /** Boot the application on a random port. */
+    async boot() {
+        this.#server = await this.#bootFn(0);
+        this.#port = this.#server.port;
+    }
+    /** Close the server. */
+    async close() {
+        if (this.#server) {
+            await this.#server.close();
+            this.#server = null;
+        }
+    }
+    /**
+     * Ephemeral port the booted server bound to. Useful for long-lived
+     * connections (SSE / WebSocket) that the fluent buffered request
+     * surface can't model — open them with `fetch` against
+     * `http://127.0.0.1:${client.port}/...`. Returns 0 before `boot()`.
+     */
+    get port() {
+        return this.#port;
+    }
+    /** Set a default header for all requests. */
+    withHeader(name, value) {
+        this.#headers[name.toLowerCase()] = value;
+        return this;
+    }
+    /** GET request. */
+    get(path) {
+        return this.request('GET', path).send();
+    }
+    /** POST request. */
+    post(path) {
+        return this.request('POST', path);
+    }
+    /** PUT request. */
+    put(path) {
+        return this.request('PUT', path);
+    }
+    /** PATCH request. */
+    patch(path) {
+        return this.request('PATCH', path);
+    }
+    /** DELETE request. */
+    delete(path) {
+        return this.request('DELETE', path).send();
+    }
+    /**
+     * Build a request with the rich fluent surface: chained assertions
+     * (`expectStatus` / `expectJson` / `expectHeader` / `expectCookie`), auth
+     * injection (`withAuth` / `asUser`, needs the `auth` client option), and
+     * `form()`. The lower-level `request()` (below) stays for raw control.
+     */
+    fluent(method, path) {
+        const sender = (m, p, init) => sendRequest(this.#port, m, p, { ...this.#headers, ...init.headers }, init.body.toString('utf8'));
+        return new RequestBuilder(sender, method, path, this.#auth);
+    }
+    /** Build a request with the low-level fluent API. */
+    request(method, path) {
+        const headers = { ...this.#headers };
+        let bodyContent = '';
+        const cookies = [];
+        const builder = {
+            header(name, value) {
+                headers[name.toLowerCase()] = value;
+                return builder;
+            },
+            json(data) {
+                bodyContent = JSON.stringify(data);
+                headers['content-type'] = 'application/json';
+                return builder;
+            },
+            body(content, contentType) {
+                bodyContent = content;
+                if (contentType)
+                    headers['content-type'] = contentType;
+                return builder;
+            },
+            cookie(name, value) {
+                cookies.push(`${name}=${value}`);
+                return builder;
+            },
+            send: async () => {
+                if (cookies.length > 0) {
+                    headers.cookie = cookies.join('; ');
+                }
+                return sendRequest(this.#port, method, path, headers, bodyContent);
+            },
+        };
+        return builder;
+    }
+}
+/** Create and boot a test client in one call. */
+export async function createTestClient(bootFn, options) {
+    const client = new TestClient(bootFn, options);
+    await client.boot();
+    return client;
+}
+export { partialMatch, RequestBuilder, } from './RequestBuilder.js';
+/** Send an HTTP request using raw TCP (no external dependencies). */
+async function sendRequest(port, method, path, headers, body) {
+    const { connect } = await import('node:net');
+    return new Promise((resolve, reject) => {
+        const socket = connect({ host: '127.0.0.1', port }, () => {
+            // Build HTTP/1.1 request
+            const headerLines = Object.entries(headers)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join('\r\n');
+            const contentLength = Buffer.byteLength(body, 'utf8');
+            let request = `${method} ${path} HTTP/1.1\r\n`;
+            request += `Host: localhost:${port}\r\n`;
+            request += `Connection: close\r\n`;
+            if (contentLength > 0) {
+                request += `Content-Length: ${contentLength}\r\n`;
+            }
+            if (headerLines) {
+                request += `${headerLines}\r\n`;
+            }
+            request += '\r\n';
+            request += body;
+            socket.write(request);
+        });
+        const chunks = [];
+        socket.on('data', (chunk) => chunks.push(chunk));
+        socket.on('end', () => {
+            // Keep the wire bytes as a Buffer through parseHttpResponse — chunked
+            // decoding has to count bytes (per RFC 7230), not UTF-16 code units.
+            // Converting to a string here used to truncate non-ASCII and binary
+            // chunked responses (é / emoji / images / PDF).
+            resolve(parseHttpResponse(Buffer.concat(chunks)));
+        });
+        socket.on('error', reject);
+        // Socket inactivity timeout. 5s was too tight for real e2e flows —
+        // signup hashes a password with argon2 (~50-200ms), then an INSERT
+        // crosses sqlite's WAL fsync, then JWT sign + serialize. Under
+        // cross-package CPU pressure (parallel helix workers, NAPI
+        // tokio runtimes) the cumulative latency exceeded 5s ~30% of runs
+        // and surfaced as flaky `bob accepts` / `non-member 403` failures
+        // in kitchen-sink's workspace.test.ts. 30s matches the helix
+        // `--timeout=60000` per-test budget without masking real hangs.
+        socket.setTimeout(30_000, () => {
+            socket.destroy();
+            reject(new Error('TestClient request timed out'));
+        });
+    });
+}
+/**
+ * Parse a raw HTTP response. Accepts the wire bytes (Buffer) or a UTF-8
+ * string for back-compat with older test callers. Chunked decoding runs on
+ * the Buffer to keep byte-counting honest — HTTP counts bytes (RFC 7230),
+ * not UTF-16 code units, so doing the work on a `.toString('utf8')` string
+ * silently truncated non-ASCII and binary responses.
+ */
+export function parseHttpResponse(raw) {
+    const buf = typeof raw === 'string' ? Buffer.from(raw, 'utf8') : raw;
+    const HEADER_TERM = Buffer.from('\r\n\r\n', 'ascii');
+    const headerEnd = buf.indexOf(HEADER_TERM);
+    if (headerEnd === -1) {
+        const body = buf.toString('utf8');
+        return { status: 0, headers: {}, body, json: () => JSON.parse(body) };
+    }
+    // HTTP headers are ASCII (RFC 7230 §3.2); decoding via 'ascii' is safe and
+    // makes any non-ASCII byte show as a question-mark, surfacing protocol bugs
+    // instead of silently smuggling them.
+    const headerSection = buf.subarray(0, headerEnd).toString('ascii');
+    let bodyBuffer = buf.subarray(headerEnd + HEADER_TERM.length);
+    const lines = headerSection.split('\r\n');
+    const statusLine = lines[0] ?? '';
+    const statusMatch = statusLine.match(/HTTP\/\d+\.\d+ (\d+)/);
+    const status = statusMatch ? Number.parseInt(statusMatch[1], 10) : 0;
+    const headers = {};
+    for (let i = 1; i < lines.length; i++) {
+        const colonIdx = lines[i].indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = lines[i].slice(0, colonIdx).trim().toLowerCase();
+        const value = lines[i].slice(colonIdx + 1).trim();
+        headers[key] = value;
+    }
+    // RFC 7230 §4.1: when Transfer-Encoding includes `chunked`, the message body
+    // is a sequence of `<size-hex>[;ext]\r\n<bytes>\r\n` chunks terminated by
+    // `0\r\n\r\n`. Decode on the Buffer so chunk sizes (bytes) match slice
+    // boundaries — character-counting corrupts é / emoji / binary payloads.
+    const transferEncoding = headers['transfer-encoding'] ?? '';
+    if (transferEncoding
+        .toLowerCase()
+        .split(',')
+        .map((s) => s.trim())
+        .includes('chunked')) {
+        bodyBuffer = decodeChunked(bodyBuffer);
+        delete headers['transfer-encoding'];
+    }
+    const body = bodyBuffer.toString('utf8');
+    return {
+        status,
+        headers,
+        body,
+        json() {
+            return JSON.parse(body);
+        },
+    };
+}
+/**
+ * Decode an HTTP/1.1 chunked-transfer body. Operates on a Buffer because
+ * chunk sizes are byte counts per RFC 7230 — character-counting silently
+ * corrupts non-ASCII / binary responses. Tolerant: stops at the first
+ * malformed chunk header rather than throwing — surfacing a partial body is
+ * more useful for a failing test assertion than swallowing the whole
+ * response.
+ */
+function decodeChunked(raw) {
+    const CRLF = Buffer.from('\r\n', 'ascii');
+    const out = [];
+    let i = 0;
+    while (i < raw.length) {
+        const lineEnd = raw.indexOf(CRLF, i);
+        if (lineEnd === -1)
+            break;
+        const sizeStr = raw.subarray(i, lineEnd).toString('ascii').split(';')[0]?.trim() ?? '';
+        const size = Number.parseInt(sizeStr, 16);
+        if (!Number.isFinite(size) || size < 0)
+            break;
+        i = lineEnd + CRLF.length;
+        if (size === 0)
+            break;
+        if (i + size > raw.length) {
+            out.push(raw.subarray(i));
+            break;
+        }
+        out.push(raw.subarray(i, i + size));
+        i += size + CRLF.length; // chunk + trailing \r\n
+    }
+    return Buffer.concat(out);
+}
+//# sourceMappingURL=TestClient.js.map

package/dist/testing/TestClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestClient.js","sourceRoot":"","sources":["../../src/testing/TestClient.ts"],"names":[],"mappings":"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"}

package/dist/types/helpers.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Type helpers — utility types for the Ream framework.
+ */
+/**
+ * Infer route parameters from a route pattern string.
+ *
+ * Usage:
+ *   type Params = InferRouteParams<'/users/:id/posts/:postId'>
+ *   // => { id: string; postId: string }
+ */
+export type InferRouteParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof InferRouteParams<`/${Rest}`>]: string;
+} : T extends `${string}:${infer Param}` ? {
+    [K in Param]: string;
+} : Record<string, never>;
+/** Accept a single value or an array. */
+export type OneOrMore<T> = T | T[];
+/** Create a nominal/opaque type from a base type. */
+export type Opaque<Base, Tag extends string> = Base & {
+    readonly __tag: Tag;
+};
+/** Unwrap an opaque type back to its base. */
+export type UnwrapOpaque<T> = T extends Opaque<infer Base, string> ? Base : T;
+/** Accept sync or async values. */
+export type AsyncOrSync<T> = T | Promise<T>;
+/** Constructor type. */
+export type Constructor<T = unknown, Args extends unknown[] = unknown[]> = new (...args: Args) => T;
+/** Abstract constructor type. */
+export type AbstractConstructor<T = unknown> = abstract new (...args: unknown[]) => T;
+/** Extract only function properties from a type. */
+export type ExtractFunctions<T, Ignore extends keyof T = never> = {
+    [K in Exclude<keyof T, Ignore>]: T[K] extends (...args: unknown[]) => unknown ? K : never;
+}[Exclude<keyof T, Ignore>];
+/** Prettify a type intersection for better IDE display. */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * String-keyed bag of values — the recurring HTTP-shaped objects:
+ * headers, cookies, query params, route params, env vars, form fields...
+ *
+ * Defaults to a string→string map (the most common case, and what
+ * `Record<string, string>` was being repeated for). Pass a value type
+ * explicitly when needed: `Dict<unknown>`, `Dict<number>`, ...
+ */
+export type Dict<V = string> = Record<string, V>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/types/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/types/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,KAAK,IAAI,MAAM,IAAI,EAAE,GAC/F;KAAG,CAAC,IAAI,KAAK,GAAG,MAAM,gBAAgB,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,MAAM;CAAE,GAC7D,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,KAAK,EAAE,GAClC;KAAG,CAAC,IAAI,KAAK,GAAG,MAAM;CAAE,GACxB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAE3B,yCAAyC;AACzC,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;AAElC,qDAAqD;AACrD,MAAM,MAAM,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS,MAAM,IAAI,IAAI,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAA;CAAE,CAAA;AAE7E,8CAA8C;AAC9C,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,CAAA;AAE7E,mCAAmC;AACnC,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAE3C,wBAAwB;AACxB,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,KAAK,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,CAAA;AAEnG,iCAAiC;AACjC,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;AAErF,oDAAoD;AACpD,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,CAAC,GAAG,KAAK,IAAI;KAC/D,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK;CAC1F,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;AAE3B,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA"}

package/dist/types/helpers.js

@@ -0,0 +1,5 @@
+/**
+ * Type helpers — utility types for the Ream framework.
+ */
+export {};
+//# sourceMappingURL=helpers.js.map

package/dist/types/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/types/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG"}