@zenera/faker 1.1.21 → 1.1.23

package/dist/paging.d.ts

@@ -3,8 +3,10 @@ import type { ParamSpec } from './spec.ts';
 export type PagingStyle = 'cursor' | 'offset';
 export interface Paging {
     style: PagingStyle;
-    /** the query parameter that turns the page */
+    /** the parameter that turns the page */
     param: string;
+    /** where the parameter lives: 'body' when in request body, absent when in query */
+    paramIn?: 'query' | 'body';
     /** the page-size parameter, when the operation takes one */
     size?: string;
     /** the response property carrying the token for the page after this one */
@@ -25,7 +27,7 @@ export interface Paging {
  * a one-shot list — so a control that turns the page *and* a property that says
  * where the next one is are both required.
  */
-export declare function pagingOf(params: readonly ParamSpec[], schema: Schema | undefined): Paging | undefined;
+export declare function pagingOf(params: readonly ParamSpec[], schema: Schema | undefined, bodySchema?: Schema | undefined): Paging | undefined;
 /**
  * The paging an actual request reveals, for a document that declared none.
  *
@@ -35,7 +37,7 @@ export declare function pagingOf(params: readonly ParamSpec[], schema: Schema |
  * evidence even when the document is silent, and silence is exactly the case
  * nothing else here can catch.
  */
-export declare function pagingSeen(params: readonly ParamSpec[], schema: Schema | undefined, query: Iterable<[string, string]>): Paging | undefined;
+export declare function pagingSeen(params: readonly ParamSpec[], schema: Schema | undefined, query: Iterable<[string, string]>, body?: unknown): Paging | undefined;
 /** The token a body offers for the next page, or nothing when it offers none. */
 export declare function tokenOf(value: unknown, paging: Paging): string | undefined;
 /**
@@ -48,4 +50,30 @@ export declare function tokenOf(value: unknown, paging: Paging): string | undefi
  * obvious. Where the schema leaves no room, this changes nothing and says so.
  */
 export declare function cutLoop(value: unknown, paging: Paging, sent: string): boolean;
+/**
+ * Terminates pagination unconditionally on a response object: nullifies or deletes
+ * the next token if allowed, or empties items if the token is required non-nullable.
+ */
+export declare function cutPaging(value: unknown, paging: Paging): boolean;
+/** Sets the items array to empty and sets more to false. */
+export declare function emptyItems(value: unknown, paging: Paging): boolean;
+/** Retrieves the sent pagination token from query parameters or request body. */
+export declare function getSentToken(query: URLSearchParams, body: unknown, paging: Paging): string | undefined;
+/** Decodes the 1-based page index from base64 JSON token `{"p": n}` if present. */
+export declare function parsePageFromToken(token: string, style?: PagingStyle): number | undefined;
+export interface PaginationCutResult {
+    cut: boolean;
+    reason: string;
+}
+/**
+ * Tracks active pagination streams to bound iterations and prevent infinite loops.
+ *
+ * Randomly bounds pagination to 1-10 pages by default, intercepts cycle loops and
+ * echoed tokens, and empties responses when clients loop past the end.
+ */
+export declare class PaginationLimiter {
+    #private;
+    constructor(maxPages?: number | (() => number), maxEntries?: number);
+    process(operationKey: string, streamKey: string, sent: string | undefined, value: unknown, paging: Paging): PaginationCutResult | undefined;
+}
 //# sourceMappingURL=paging.d.ts.map

package/dist/paging.js

@@ -1,3 +1,4 @@
+import { randomInt } from 'node:crypto';
 import { properties } from "./schema.js";
 const squash = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
 const CURSOR_PARAMS = new Set([
@@ -73,13 +74,22 @@ const ITEMS_PROPS = new Set([
  * a one-shot list — so a control that turns the page *and* a property that says
  * where the next one is are both required.
  */
-export function pagingOf(params, schema) {
+export function pagingOf(params, schema, bodySchema) {
     if (!schema) {
         return undefined;
     }
     const query = params.filter((p) => p.in === 'query');
-    const cursor = query.find((p) => CURSOR_PARAMS.has(squash(p.name)));
-    const offset = query.find((p) => OFFSET_PARAMS.has(squash(p.name)) && numeric(p.schema));
+    const queryCursor = query.find((p) => CURSOR_PARAMS.has(squash(p.name)));
+    const queryOffset = query.find((p) => OFFSET_PARAMS.has(squash(p.name)) && numeric(p.schema));
+    let bodyCursor;
+    let bodyOffset;
+    if (!queryCursor && !queryOffset && bodySchema) {
+        const bodyProps = properties(bodySchema);
+        bodyCursor = bodyProps.find((p) => CURSOR_PARAMS.has(squash(p.name)));
+        bodyOffset = bodyProps.find((p) => OFFSET_PARAMS.has(squash(p.name)) && numeric(p.schema));
+    }
+    const cursor = queryCursor ?? bodyCursor;
+    const offset = queryOffset ?? bodyOffset;
     const param = cursor ?? offset;
     if (!param) {
         return undefined;
@@ -90,10 +100,16 @@ export function pagingOf(params, schema) {
     if (!next && !more) {
         return undefined;
     }
+    const isBody = Boolean(!queryCursor && !queryOffset && (bodyCursor || bodyOffset));
+    const size = query.find((p) => SIZE_PARAMS.has(squash(p.name)))?.name ??
+        (bodySchema
+            ? properties(bodySchema).find((p) => SIZE_PARAMS.has(squash(p.name)))?.name
+            : undefined);
     return {
         style: cursor ? 'cursor' : 'offset',
         param: param.name,
-        size: query.find((p) => SIZE_PARAMS.has(squash(p.name)))?.name,
+        ...(isBody ? { paramIn: 'body' } : {}),
+        size,
         next: next?.name,
         nextNullable: next ? nullable(next.schema) : undefined,
         nextRequired: next?.required,
@@ -110,7 +126,7 @@ export function pagingOf(params, schema) {
  * evidence even when the document is silent, and silence is exactly the case
  * nothing else here can catch.
  */
-export function pagingSeen(params, schema, query) {
+export function pagingSeen(params, schema, query, body) {
     const declared = new Set(params.map((p) => p.name));
     const extra = [];
     for (const [name, value] of query) {
@@ -119,7 +135,31 @@ export function pagingSeen(params, schema, query) {
             extra.push({ name, in: 'query', required: false, schema: guess(value) });
         }
     }
-    return extra.length === 0 ? undefined : pagingOf([...params, ...extra], schema);
+    if (extra.length > 0) {
+        const detected = pagingOf([...params, ...extra], schema);
+        if (detected) {
+            return detected;
+        }
+    }
+    if (isObject(body)) {
+        for (const [name, value] of Object.entries(body)) {
+            if (value !== null && value !== undefined && value !== '') {
+                if (CURSOR_PARAMS.has(squash(name)) || OFFSET_PARAMS.has(squash(name))) {
+                    const syntheticBody = {
+                        type: 'object',
+                        properties: {
+                            [name]: guess(typeof value === 'string' ? value : JSON.stringify(value)),
+                        },
+                    };
+                    const detected = pagingOf(params, schema, syntheticBody);
+                    if (detected) {
+                        return detected;
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
 }
 /** The token a body offers for the next page, or nothing when it offers none. */
 export function tokenOf(value, paging) {
@@ -165,6 +205,274 @@ export function cutLoop(value, paging, sent) {
     }
     return true;
 }
+/**
+ * Terminates pagination unconditionally on a response object: nullifies or deletes
+ * the next token if allowed, or empties items if the token is required non-nullable.
+ */
+export function cutPaging(value, paging) {
+    let cut = false;
+    if (paging.next) {
+        const holder = holderOf(value, paging.next);
+        if (holder) {
+            if (paging.nextNullable) {
+                holder[paging.next] = null;
+                cut = true;
+            }
+            else if (!paging.nextRequired) {
+                delete holder[paging.next];
+                cut = true;
+            }
+            else if (paging.items) {
+                const itemsHolder = holderOf(value, paging.items);
+                if (itemsHolder && Array.isArray(itemsHolder[paging.items])) {
+                    itemsHolder[paging.items] = [];
+                    cut = true;
+                }
+            }
+        }
+    }
+    if (paging.more) {
+        const moreHolder = holderOf(value, paging.more);
+        if (moreHolder) {
+            moreHolder[paging.more] = false;
+            cut = true;
+        }
+    }
+    return cut;
+}
+/** Sets the items array to empty and sets more to false. */
+export function emptyItems(value, paging) {
+    let cut = false;
+    if (paging.items) {
+        const itemsHolder = holderOf(value, paging.items);
+        if (itemsHolder && Array.isArray(itemsHolder[paging.items])) {
+            itemsHolder[paging.items] = [];
+            cut = true;
+        }
+    }
+    if (paging.next) {
+        const holder = holderOf(value, paging.next);
+        if (holder) {
+            if (paging.nextNullable) {
+                holder[paging.next] = null;
+                cut = true;
+            }
+            else if (!paging.nextRequired) {
+                delete holder[paging.next];
+                cut = true;
+            }
+        }
+    }
+    if (paging.more) {
+        const moreHolder = holderOf(value, paging.more);
+        if (moreHolder) {
+            moreHolder[paging.more] = false;
+            cut = true;
+        }
+    }
+    return cut;
+}
+/** Retrieves the sent pagination token from query parameters or request body. */
+export function getSentToken(query, body, paging) {
+    if (paging.paramIn === 'body' && isObject(body)) {
+        const val = body[paging.param];
+        if (val !== undefined && val !== null && val !== '') {
+            return typeof val === 'object' ? JSON.stringify(val) : String(val);
+        }
+    }
+    const qVal = query.get(paging.param);
+    if (qVal !== null && qVal !== '') {
+        return qVal;
+    }
+    if (isObject(body)) {
+        const val = body[paging.param];
+        if (val !== undefined && val !== null && val !== '') {
+            return typeof val === 'object' ? JSON.stringify(val) : String(val);
+        }
+        if (paging.next) {
+            const nextVal = body[paging.next];
+            if (nextVal !== undefined && nextVal !== null && nextVal !== '') {
+                return typeof nextVal === 'object' ? JSON.stringify(nextVal) : String(nextVal);
+            }
+        }
+    }
+    return undefined;
+}
+/** Decodes the 1-based page index from base64 JSON token `{"p": n}` if present. */
+export function parsePageFromToken(token, style = 'cursor') {
+    if (style !== 'cursor') {
+        return undefined;
+    }
+    try {
+        const decoded = Buffer.from(token, 'base64').toString('utf8');
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed?.p === 'number')
+            return parsed.p;
+        if (typeof parsed?.page === 'number')
+            return parsed.page;
+    }
+    catch {
+        // Not base64 JSON
+    }
+    return undefined;
+}
+/**
+ * Tracks active pagination streams to bound iterations and prevent infinite loops.
+ *
+ * Randomly bounds pagination to 1-10 pages by default, intercepts cycle loops and
+ * echoed tokens, and empties responses when clients loop past the end.
+ */
+export class PaginationLimiter {
+    #tokens = new Map();
+    #maxPagesFactory;
+    #maxEntries;
+    constructor(maxPages = () => randomInt(1, 11), maxEntries = 5000) {
+        this.#maxPagesFactory = typeof maxPages === 'function' ? maxPages : () => maxPages;
+        this.#maxEntries = maxEntries;
+    }
+    process(operationKey, streamKey, sent, value, paging) {
+        this.#prune();
+        const nextToken = tokenOf(value, paging);
+        // Case 1: First page (no cursor sent)
+        if (sent === undefined) {
+            const maxPages = Math.max(1, this.#maxPagesFactory());
+            if (maxPages === 1) {
+                if (nextToken !== undefined) {
+                    cutPaging(value, paging);
+                    return { cut: true, reason: 'cut pagination at max pages (1)' };
+                }
+                return undefined;
+            }
+            if (nextToken !== undefined) {
+                this.#tokens.set(nextToken, {
+                    operationKey,
+                    page: 2,
+                    maxPages,
+                    seenTokens: new Set([nextToken]),
+                    streamKey,
+                    createdAt: Date.now(),
+                });
+            }
+            return undefined;
+        }
+        // Case 2: Cursor was sent
+        const state = this.#tokens.get(sent);
+        // Subcase 2A: Re-requesting an already-terminated token
+        if (state?.terminated) {
+            emptyItems(value, paging);
+            return {
+                cut: true,
+                reason: `cut pagination at max pages (${state.maxPages})`,
+            };
+        }
+        // Subcase 2B: Echo loop (server returned the exact token that was sent)
+        if (nextToken !== undefined && nextToken === sent) {
+            const didCut = cutLoop(value, paging, sent);
+            if (state) {
+                state.terminated = true;
+            }
+            if (didCut) {
+                return { cut: true, reason: 'cut a looping page token' };
+            }
+            // Where the schema leaves no room to null or delete, leave alone
+            return undefined;
+        }
+        // Subcase 2C: Cycle loop (server returned a token seen earlier in this stream)
+        if (state && nextToken !== undefined && state.seenTokens.has(nextToken)) {
+            cutPaging(value, paging);
+            state.terminated = true;
+            return { cut: true, reason: 'cut a cycling page token' };
+        }
+        // Subcase 2D: Tracked stream reached maxPages
+        if (state) {
+            if (state.page >= state.maxPages) {
+                cutPaging(value, paging);
+                state.terminated = true;
+                if (nextToken !== undefined) {
+                    this.#tokens.set(nextToken, {
+                        operationKey,
+                        page: state.page + 1,
+                        maxPages: state.maxPages,
+                        seenTokens: state.seenTokens,
+                        streamKey,
+                        terminated: true,
+                        createdAt: Date.now(),
+                    });
+                }
+                return {
+                    cut: true,
+                    reason: `cut pagination at max pages (${state.maxPages})`,
+                };
+            }
+            // Not yet at maxPages: advance to next page
+            if (nextToken !== undefined) {
+                state.seenTokens.add(nextToken);
+                this.#tokens.set(nextToken, {
+                    operationKey,
+                    page: state.page + 1,
+                    maxPages: state.maxPages,
+                    seenTokens: state.seenTokens,
+                    streamKey,
+                    createdAt: Date.now(),
+                });
+            }
+            return undefined;
+        }
+        // Subcase 2E: Untracked token (first time seen)
+        const decodedPage = parsePageFromToken(sent, paging.style);
+        if (decodedPage !== undefined) {
+            const maxPages = Math.max(decodedPage, this.#maxPagesFactory());
+            if (decodedPage >= maxPages) {
+                cutPaging(value, paging);
+                return {
+                    cut: true,
+                    reason: `cut pagination at max pages (${maxPages})`,
+                };
+            }
+            if (nextToken !== undefined) {
+                this.#tokens.set(nextToken, {
+                    operationKey,
+                    page: decodedPage + 1,
+                    maxPages,
+                    seenTokens: new Set([sent, nextToken]),
+                    streamKey,
+                    createdAt: Date.now(),
+                });
+            }
+            return undefined;
+        }
+        // Untracked arbitrary string token (e.g. 'page-1' in server.test.ts)
+        const maxPages = Math.max(2, this.#maxPagesFactory());
+        if (nextToken !== undefined) {
+            this.#tokens.set(nextToken, {
+                operationKey,
+                page: 2,
+                maxPages,
+                seenTokens: new Set([sent, nextToken]),
+                streamKey,
+                createdAt: Date.now(),
+            });
+        }
+        return undefined;
+    }
+    #prune() {
+        const now = Date.now();
+        for (const [token, entry] of this.#tokens) {
+            if (now - entry.createdAt > 10 * 60 * 1000) {
+                this.#tokens.delete(token);
+            }
+        }
+        while (this.#tokens.size > this.#maxEntries) {
+            const first = this.#tokens.keys().next().value;
+            if (first !== undefined) {
+                this.#tokens.delete(first);
+            }
+            else {
+                break;
+            }
+        }
+    }
+}
 /** The nearest object carrying `name`; a real body nests its envelope. */
 function holderOf(value, name) {
     const seen = new Set();
@@ -202,6 +510,7 @@ const numeric = (schema) => types(schema).some((t) => t === 'integer' || t === '
 const boolish = (schema) => types(schema).includes('boolean');
 const listish = (schema) => types(schema).includes('array') || schema.items !== undefined;
 const nullable = (schema) => types(schema).includes('null');
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 /** An undeclared parameter has only its value to be typed by. */
 const guess = (value) => ({
     type: /^-?\d+$/.test(value) ? 'integer' : 'string',

package/dist/probe.js

@@ -178,15 +178,26 @@ function text(schema, variant) {
 // mistake being looked for, and a still seed makes it a fixed point — visible
 // on the second page here instead of on somebody's client.
 // ---------------------------------------------------------------------------
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 /** The first page: an ordinary probe with the paging control taken back off. */
 export function walkStart(operation, paging) {
     const input = probesFor(operation)[0];
+    if (paging.paramIn === 'body') {
+        const body = isObject(input.body) ? { ...input.body } : {};
+        delete body[paging.param];
+        return { ...input, body };
+    }
     const query = { ...input.query };
     delete query[paging.param];
     return { ...input, query };
 }
 /** The same request again, asking for whatever the last answer pointed at. */
 export function nextPage(previous, paging, token) {
+    if (paging.paramIn === 'body') {
+        const body = isObject(previous.body) ? { ...previous.body } : {};
+        body[paging.param] = token;
+        return { ...previous, body };
+    }
     return { ...previous, query: { ...previous.query, [paging.param]: token } };
 }
 // ---------------------------------------------------------------------------

package/dist/prompt.d.ts

@@ -1,3 +1,4 @@
+import type { GeneratorInput } from './envelope.ts';
 import { type Operation } from './spec.ts';
 export declare const SYSTEM: string;
 export declare function brief(operation: Operation): string;
@@ -8,4 +9,17 @@ export declare function brief(operation: Operation): string;
  */
 export declare function instruction(operation: Operation): string;
 export declare function retry(diagnostics: readonly string[]): string;
+export interface ExampleRequest {
+    input: GeneratorInput;
+    output?: unknown;
+}
+export interface RegenerationPromptContext {
+    operation: Operation;
+    currentSource: string;
+    failingInput: GeneratorInput;
+    fault: string;
+    stderr?: string;
+    examples?: readonly ExampleRequest[];
+}
+export declare function regenerationInstruction(ctx: RegenerationPromptContext): string;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.js

@@ -39,8 +39,9 @@ export const SYSTEM = [
     '   this generically, by looking the names up at run time. Do the same for a',
     '   query parameter where it plainly describes the content rather than',
     '   controlling the call. A paging control — a cursor, page, offset or',
-    '   page-size parameter — is never content and must not be copied into the',
-    '   body; see PAGINATION below where the operation has one.',
+    '   page-size parameter (whether in query or request body) — is never content',
+    '   and must not be copied into the body; see PAGINATION below where the',
+    '   operation has one.',
     '3. Every required property must be present. Optional ones may be omitted',
     '   sometimes; that is what makes a mock useful.',
     '4. Values must suit their names, not just their types. Use `faker` for anything',
@@ -91,11 +92,12 @@ function pagination(paging) {
     const advance = paging.style === 'cursor'
         ? 'the base64 of a small JSON object holding the next page index, such as {"p": 2}'
         : "the offset of the next page — this page's offset plus its size";
+    const where = paging.paramIn === 'body' ? 'In the request `body`, ' : '';
     const lines = [
         'PAGINATION',
-        `  This operation is paged. \`${paging.param}\` asks for a page;`,
+        `  This operation is paged. ${where}\`${paging.param}\` asks for a page;`,
         '  absent or empty means the first one.',
-        '  - Fabricate three pages in total and no more.',
+        '  - Fabricate a random number of pages between 1 and 10 in total and no more.',
     ];
     if (paging.next) {
         lines.push(`  - \`${paging.next}\` carries the token for the page after this one.`, `    Build it out of \`${paging.param}\`:`, `    ${advance}.`, '  - Never build it out of `seed`. Unpinned, the seed changes on every', '    request; pinned, it is a function of the query. A token made from it', '    either wanders or never changes.', '  - It must strictly advance. Answering with the token you were given is', '    the one failure that matters: a client following it loops forever.');
@@ -127,7 +129,7 @@ function last(paging) {
         .join(' and ');
     return [
         `  - The schema requires \`${paging.next}\` on every page, so the last page`,
-        `    ends the list the other way: ${otherwise || 'an empty page'}.`,
+        `    ends the list the other way: ${otherwise || 'an empty page'} (e.g. \`${paging.items || 'results'}\` as an empty list \`[]\`).`,
     ];
 }
 /**
@@ -149,5 +151,36 @@ export function retry(diagnostics) {
         ...diagnostics,
     ].join('\n');
 }
+export function regenerationInstruction(ctx) {
+    const { operation, currentSource, failingInput, fault, stderr, examples } = ctx;
+    const lines = [
+        brief(operation),
+        '',
+        'Embed the response schema in the file as a literal and validate against it.',
+        '',
+        'CURRENT GENERATOR CODE:',
+        '```python',
+        currentSource.trim(),
+        '```',
+        '',
+        'THE GENERATOR FAILED ON THIS REQUEST:',
+        'Input:',
+        json(failingInput),
+        '',
+        `Fault: ${fault}`,
+    ];
+    if (stderr && stderr.trim()) {
+        lines.push('', 'Stderr / Traceback:', '```', stderr.trim(), '```');
+    }
+    if (examples && examples.length > 0) {
+        lines.push('', 'PREVIOUS SUCCESSFUL REQUESTS (use as examples):');
+        for (let i = 0; i < examples.length; i++) {
+            const ex = examples[i];
+            lines.push(`Example ${i + 1}:`, 'Input:', json(ex.input), 'Output produced:', json(ex.output), '');
+        }
+    }
+    lines.push('TASK:', 'Fix the generator code so that it handles the failing request without error, produces valid output that matches the schema, and continues to produce valid output for the previous example requests.', 'ANSWER WITH THE COMPLETE REVISED PYTHON FILE AND NOTHING ELSE. No explanation, no markdown fence.');
+    return lines.join('\n');
+}
 const json = (value) => JSON.stringify(value, null, 1);
 //# sourceMappingURL=prompt.js.map

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { type Server } from 'node:http';
 import type { Box } from './box.ts';
 import { type Cache } from './cache.ts';
+import { RegenerationLimiter, RequestHistory } from './logger.ts';
+import { PaginationLimiter } from './paging.ts';
 import type { Router } from './router.ts';
 import { type Checks } from './validate.ts';
 export interface ServerOptions {
@@ -12,6 +14,12 @@ export interface ServerOptions {
     seed?: number;
     maxBody?: number;
     onRequest?: (line: string) => void;
+    requestsDir?: string;
+    regenLimit?: number;
+    history?: RequestHistory;
+    limiter?: RegenerationLimiter;
+    maxPages?: number | (() => number);
+    paginationLimiter?: PaginationLimiter;
 }
 export interface Listening {
     server: Server;