@wylan24/mockgen 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wylan24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# mockgen
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/wylan24/mockgen/actions/workflows/ci.yml/badge.svg)](https://github.com/wylan24/mockgen/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@wylan24/mockgen?include_prereleases)](https://www.npmjs.com/package/@wylan24/mockgen)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Turn an OpenAPI spec — or just a folder of sample JSON responses — into a running mock server with realistic, stable fake data. One command.
+
+```bash
+npx @wylan24/mockgen serve ./openapi.yaml
+npx @wylan24/mockgen serve ./samples/
+```
+
+You get a server on `localhost:4010` that returns schema-valid, human-looking data, returns the same data across restarts, and can be tweaked without writing code.
+
+> **Status:** alpha (0.x). It works and is tested against 57 real-world APIs, but options may still change before 1.0. [Feedback and bug reports](https://github.com/wylan24/mockgen/issues/new/choose) are very welcome.
+
+## Install
+
+Requires Node 22.19 or later. Run it without installing:
+
+```bash
+npx @wylan24/mockgen serve ./openapi.yaml
+```
+
+Or add it to a project, for scripts and tests:
+
+```bash
+npm install --save-dev @wylan24/mockgen
+npx mockgen serve ./openapi.yaml
+```
+
+## Why
+
+- **Realistic data.** Field names drive the data: `email`, `avatarUrl`, `createdAt`, `price`, `city` all look like the real thing, and a record's name, username and email match each other.
+- **Deterministic.** Same spec + seed → byte-identical responses, so screenshots and tests stay stable. `GET /users/42` always returns the same user, with `id: 42`.
+- **Valid.** Responses honor `enum`, `min`/`max`, `pattern`, `minLength`, `minItems`, `uniqueItems`, `oneOf`/`anyOf`/`allOf`, nullable, and use your spec's `example` values when present.
+- **Zero config.** CORS on, request log in the terminal, hot reload when the spec changes.
+
+## Usage
+
+```bash
+mockgen serve <spec|dir>             # Start a mock server (hot-reloads on change)
+mockgen generate <spec|dir> [route]  # Print generated responses, e.g. "GET /users/1"
+mockgen validate <spec|dir>          # Generate every response and check it against its schema
+mockgen infer <dir> [-o openapi.yaml]  # Write the schema inferred from samples as OpenAPI 3.1
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `-p, --port` | `4010` | Port to listen on |
+| `-H, --host` | `127.0.0.1` | Host to bind |
+| `-s, --seed` | `1` | Seed for generated data |
+| `-d, --delay` | `0` | Delay every response, e.g. `300ms` |
+| `-r, --records` | `50` | Records in every list endpoint's collection |
+| `--no-watch` | | Disable hot reload |
+| `-o, --out` | stdout | `infer` output file (`.yaml` or `.json`) |
+
+### Simulating errors and latency
+
+Per request, with a header or a query parameter:
+
+```bash
+curl -H 'X-Mock-Status: 404' localhost:4010/users/1   # the spec's 404 response
+curl 'localhost:4010/users/1?__status=503'            # undocumented codes work too
+curl -H 'X-Mock-Delay: 1500' localhost:4010/users     # slow this one down
+```
+
+### Lists and pagination
+
+Every list endpoint — a bare array of objects, or an object wrapping one (`data`, `items`, `results`, …) — is a window onto a stable collection of 50 records (`--records`):
+
+```bash
+curl 'localhost:4010/users?page=2&limit=20'   # also per_page, pageSize, offset/skip
+curl 'localhost:4010/users?cursor=bzoyMA'     # any cursor mockgen handed out works
+```
+
+- Integer ids are sequential (`1…50`), so page 2 of 10 is ids 11–20, every time.
+- When the spec also has `GET /users/{id}`, each list item is the same record that route returns.
+- Wrapper fields are filled by name, including nested ones like `meta.pagination`: `total`, `page`, `perPage`, `totalPages`, `hasMore`, `next`/`prev` (page number, URL or cursor, and `null` on the last page).
+- Responses carry `X-Total-Count` and a `Link` header with `next`/`prev`.
+
+A page past the end is empty, even if the schema sets `minItems`.
+
+### In tests
+
+```ts
+import { createMockServer } from '@wylan24/mockgen';
+
+const mock = await createMockServer({ spec: './openapi.yaml', seed: 1 });
+const url = await mock.listen(0); // random free port
+// ... run tests against url ...
+await mock.close();
+```
+
+## Supported input
+
+### OpenAPI specs
+
+- OpenAPI 3.0 and 3.1, YAML or JSON, with local and multi-file `$ref`s (circular refs are fine).
+- Swagger 2.0 is not supported; convert it with [swagger2openapi](https://github.com/Mermade/oas-kit) first.
+
+### A folder of sample responses
+
+No spec yet? Drop real responses into a folder, named after their route. mockgen infers a schema from them and generates fresh data in the same shape.
+
+| File | Route |
+| --- | --- |
+| `GET.users.json` | `GET /users` → 200 |
+| `GET.users.[id].json` or `users/GET.[id].json` | `GET /users/{id}` (folders are path segments; `{id}` works too) |
+| `GET.users.[id].404.json` | the 404 response, served with `X-Mock-Status: 404` |
+| `GET.users.[id]~alice.json` | another sample for the same response |
+| `POST.users.json` | `POST /users` → 201 |
+| `DELETE.users.[id].json` (empty file) | `DELETE /users/{id}` → 204, no body |
+
+Every sample for a route is merged: keys missing from some samples become optional, `null` values make a field nullable, ISO dates, emails, URLs and UUIDs are detected, and a few short values repeated often (`role: admin | member | viewer`) become an enum. See [examples/samples](examples/samples).
+
+When you're ready for a real spec, `mockgen infer ./samples -o openapi.yaml` writes the inferred schema out so you can edit it.
+
+## Roadmap to 1.0
+
+- [x] OpenAPI 3.0/3.1 loader with multi-file `$ref`s
+- [x] Deterministic, field-name-aware data generation honoring schema constraints
+- [x] Mock server: CORS, request log, status/latency simulation, hot reload
+- [x] Sample-response input (folder of JSON files → inferred schema) and `mockgen infer`
+- [x] List/detail consistency (`/users/{id}` returns the user from `/users`) and pagination
+- [x] Spec corpus of 50+ real-world APIs in CI: every spec loads, and every generated response validates apart from documented spec bugs
+- [ ] Stateful CRUD, `mock.config.ts` overrides, Docker image
+
+## Quality: the spec corpus
+
+mockgen is tested against 57 real-world OpenAPI specs (Stripe, GitHub, Twilio, Box, Jira, DocuSign, Plaid, Petstore variants and more from [APIs.guru](https://apis.guru)), pinned to commits in [corpus/specs.json](corpus/specs.json). Every spec must load, and every generated response is validated against its schema with Ajv.
+
+```bash
+npm run corpus:fetch        # download the specs once (~60 MB, cached in corpus/.cache)
+npm run corpus              # load + generate + validate everything
+npm run corpus -- stripe    # just one spec
+npm run corpus:explain -- linode "GET /linode/instances" 200   # why a response fails
+```
+
+Validation follows OpenAPI semantics: 3.0 `nullable`, boolean exclusive bounds, `writeOnly` fields absent from responses, and `discriminator` choosing the `oneOf` branch.
+
+Every spec's GET routes must also serve in under 20 ms at p95.
+
+Some real specs contain schemas no value can satisfy (the same schema twice in a `oneOf`, `allOf: [string, null]`, contradictory enums). [corpus/baseline.json](corpus/baseline.json) lists each one with the reason. CI runs `npm run corpus -- --strict`, which fails if any spec gets worse than its baseline or any failure isn't a documented spec bug.
+
+## Development
+
+Requires Node 22.19+.
+
+```bash
+npm install
+npm test
+npm run serve:example     # builds, then serves examples/petstore.yaml
+npm run smoke             # pack, install into an empty project, run the CLI and library
+```
+
+Snapshot tests in [test/snapshot.test.ts](test/snapshot.test.ts) pin generated output byte for byte, and CI runs them on macOS, Linux and Windows. If you change generation on purpose, review the diff and update with `npx vitest run -u`.
+
+### Releasing
+
+Bump `version` in `package.json`, commit, then push a matching tag:
+
+```bash
+git tag v0.1.0-alpha.1 && git push origin v0.1.0-alpha.1
+```
+
+The [release workflow](.github/workflows/release.yml) reruns the tests, smoke test and strict corpus gate, publishes to npm with provenance (pre-releases under the `next` dist-tag), and creates the GitHub release. It needs an `NPM_TOKEN` repository secret, or the workflow set up as a trusted publisher on npmjs.com.
+
+## Contributing
+
+Bug reports, specs that mockgen gets wrong, and pull requests are all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get set up, and the [Code of Conduct](CODE_OF_CONDUCT.md). Ask questions in [Discussions](https://github.com/wylan24/mockgen/discussions). Report security problems privately, as described in [SECURITY.md](SECURITY.md).
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed in each release.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs, styleText } from 'node:util';
+import { generate } from './generate.js';
+import { loadSource } from './load.js';
+import { formatOpenApi, loadSamples } from './samples.js';
+import { createMockServer, respond } from './server.js';
+import { ResponseValidator } from './validate.js';
+const HELP = `mockgen — turn an OpenAPI spec or a folder of sample responses into a running mock server
+
+Usage
+  mockgen serve <spec|dir>             Start a mock server (hot-reloads on change)
+  mockgen generate <spec|dir> [route]  Print generated responses, e.g. "GET /users/1"
+  mockgen validate <spec|dir>          Load the input and generate every response
+  mockgen infer <dir> [-o file]        Write the schema inferred from samples as OpenAPI 3.1
+
+Sample folders: name files after the route, e.g. GET.users.json, users/GET.[id].json,
+GET.users.[id].404.json. Folders become path segments; [id] or {id} is a path param.
+
+Options
+  -p, --port <n>      Port to listen on (default 4010)
+  -H, --host <host>   Host to bind (default 127.0.0.1)
+  -s, --seed <n>      Seed for generated data (default 1)
+  -d, --delay <ms>    Delay every response, e.g. 300 or 300ms
+  -r, --records <n>   Records per list endpoint, paged with ?page=&limit= (default 50)
+  -o, --out <file>    infer: write here instead of stdout (.yaml or .json)
+      --no-watch      Disable hot reload
+  -h, --help          Show this help
+  -v, --version       Show the version
+
+Per request
+  X-Mock-Status: 404  (or ?__status=404)   Return that status instead of the success response
+  X-Mock-Delay: 500   (or ?__delay=500)    Delay this response
+  ?page=2&limit=20, ?offset=40, ?cursor=…  Page through list endpoints
+`;
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        allowNegative: true,
+        options: {
+            port: { type: 'string', short: 'p', default: '4010' },
+            host: { type: 'string', short: 'H', default: '127.0.0.1' },
+            seed: { type: 'string', short: 's', default: '1' },
+            delay: { type: 'string', short: 'd', default: '0' },
+            out: { type: 'string', short: 'o' },
+            records: { type: 'string', short: 'r', default: '50' },
+            watch: { type: 'boolean', default: true },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    if (values.version)
+        return console.log(await version());
+    const [command, spec, ...rest] = positionals;
+    if (values.help || !command)
+        return console.log(HELP);
+    if (!spec)
+        fail(`Missing <spec>. Try: mockgen ${command} ./openapi.yaml`);
+    const seed = int(values.seed, '--seed');
+    switch (command) {
+        case 'serve':
+            return serve(spec, { port: int(values.port, '--port'), host: values.host, seed, delay: int(values.delay.replace(/ms$/, ''), '--delay'), watch: values.watch, records: int(values.records, '--records') });
+        case 'generate':
+            return generateCmd(spec, rest.join(' '), seed, int(values.records, '--records'));
+        case 'validate':
+            return validate(spec, seed);
+        case 'infer':
+            return infer(spec, values.out);
+        default:
+            fail(`Unknown command "${command}". Run mockgen --help.`);
+    }
+}
+async function serve(spec, opts) {
+    const started = performance.now();
+    const model = await loadSource(spec);
+    printWarnings(model);
+    const mock = createMockServer({ model, seed: opts.seed, delay: opts.delay, records: opts.records, log: (line) => console.log(styleText('dim', line)) });
+    const url = await mock.listen(opts.port, opts.host).catch((err) => {
+        if (err.code === 'EADDRINUSE')
+            fail(`Port ${opts.port} is already in use on ${opts.host}. Pick another with --port ${opts.port + 1}, or --port 0 for any free port.`);
+        if (err.code === 'EACCES')
+            fail(`No permission to use port ${opts.port} on ${opts.host}. Ports below 1024 usually need admin rights; try --port 4010.`);
+        throw err;
+    });
+    // Watch before announcing "ready": a script that edits the spec as soon as it sees
+    // that line would otherwise race the watcher and its edit could be missed.
+    if (opts.watch)
+        watchSources(model, async () => {
+            try {
+                const next = await loadSource(spec);
+                mock.setModel(next);
+                printWarnings(next);
+                console.log(`${styleText('green', '↻')} Reloaded ${next.routes.length} routes`);
+                return next;
+            }
+            catch (err) {
+                console.error(styleText('red', `✖ Reload failed, still serving the previous version:\n  ${err.message}`));
+                return undefined;
+            }
+        });
+    console.log(`\n${styleText('bold', model.title)} ${styleText('dim', model.version)}`);
+    for (const r of model.routes)
+        console.log(`  ${styleText('cyan', r.method.padEnd(7))} ${url}${model.basePath}${r.path}`);
+    console.log(`\n${styleText('green', '✔')} Mock server ready at ${styleText('bold', url)} in ${Math.round(performance.now() - started)}ms (seed ${opts.seed})\n`);
+    const shutdown = () => mock.close().then(() => process.exit(0));
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}
+/**
+ * Watch every local file of the spec and reload on change, debounced.
+ *
+ * Watchers are re-created after every reload, failed ones included: on Linux and macOS
+ * a watcher follows the file, not its name, so an editor's save (write a temp file,
+ * rename it over the original) leaves the old watcher on a file that no longer exists.
+ */
+function watchSources(model, reload) {
+    let watchers = [];
+    let files = model.sources;
+    let timer;
+    let retry;
+    const onChange = () => {
+        clearTimeout(timer);
+        timer = setTimeout(async () => {
+            files = (await reload())?.sources ?? files;
+            watch();
+        }, 100);
+    };
+    const watch = () => {
+        watchers.forEach((w) => w.close());
+        watchers = [];
+        clearTimeout(retry);
+        let missing = false;
+        for (const file of files) {
+            try {
+                watchers.push(fs.watch(file, { recursive: fs.statSync(file).isDirectory() }, onChange));
+            }
+            catch {
+                missing = true; // e.g. mid-save, between delete and rename
+            }
+        }
+        if (missing)
+            retry = setTimeout(watch, 200);
+    };
+    watch();
+}
+async function generateCmd(spec, route, seed, records) {
+    const model = await loadSource(spec);
+    if (route) {
+        const [method = 'GET', p = '/'] = route.includes(' ') ? route.split(/\s+/) : ['GET', route];
+        const [pathname = '/', query] = p.split('?');
+        const result = respond(model, { method: method.toUpperCase(), path: pathname, query, seed, records });
+        if (result.status >= 400 && !model.routes.some((r) => r.pattern.test(pathname)))
+            fail(result.body.message);
+        return console.log(JSON.stringify(result.body, null, 2));
+    }
+    const out = {};
+    for (const r of model.routes) {
+        const res = r.responses.find((x) => x.status >= 200 && x.status < 300) ?? r.responses[0];
+        out[`${r.method} ${r.path}`] = res?.hasExample ? res.example : generate(res?.schema, { seed, key: `${r.method} ${r.path} ${res?.status}` });
+    }
+    console.log(JSON.stringify(out, null, 2));
+}
+async function infer(dir, out) {
+    if (!(await fs.promises.stat(dir).catch(() => undefined))?.isDirectory())
+        fail(`infer expects a folder of sample responses, got "${dir}"`);
+    const model = await loadSamples(dir);
+    printWarnings(model);
+    const text = formatOpenApi(model, out);
+    if (!out)
+        return process.stdout.write(text);
+    await fs.promises.writeFile(out, text);
+    console.error(`${styleText('green', '✔')} Wrote ${model.routes.length} routes to ${out}`);
+}
+async function validate(spec, seed) {
+    const model = await loadSource(spec);
+    printWarnings(model);
+    const validator = new ResponseValidator(model.openapi);
+    let responses = 0;
+    let skipped = 0;
+    const invalid = [];
+    for (const r of model.routes) {
+        for (const res of r.responses) {
+            if (!res.schema || res.hasExample)
+                continue;
+            const label = `${r.method} ${r.path} ${res.status}`;
+            const value = generate(res.schema, { seed, key: label });
+            try {
+                const result = validator.validate(res.schema, value);
+                if (!result.valid)
+                    invalid.push(`${label}: ${result.errors}`);
+                responses++;
+            }
+            catch {
+                skipped++; // The schema itself can't be compiled (e.g. a non-JavaScript regex).
+            }
+        }
+    }
+    for (const line of invalid)
+        console.error(styleText('red', `✖ ${line}`));
+    const summary = `${model.title}: ${model.routes.length} routes, ${responses - invalid.length}/${responses} generated responses valid${skipped ? `, ${skipped} schemas not checkable` : ''}, ${model.warnings.length} warnings`;
+    if (invalid.length)
+        fail(summary);
+    console.log(`${styleText('green', '✔')} ${summary}`);
+}
+function printWarnings(model) {
+    for (const w of model.warnings)
+        console.warn(styleText('yellow', `⚠ ${w}`));
+}
+function int(value, flag) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0)
+        fail(`${flag} must be a non-negative integer, got "${value}"`);
+    return n;
+}
+async function version() {
+    const pkg = JSON.parse(await fs.promises.readFile(path.join(import.meta.dirname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+}
+function fail(message) {
+    console.error(styleText('red', `✖ ${message}`));
+    process.exit(1);
+}
+main(process.argv.slice(2)).catch((err) => fail(err.message));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { parseArgs, styleText } from 'node:util';\nimport { generate } from './generate.js';\nimport type { MockModel } from './model.js';\nimport { loadSource } from './load.js';\nimport { formatOpenApi, loadSamples } from './samples.js';\nimport { createMockServer, respond } from './server.js';\nimport { ResponseValidator } from './validate.js';\n\nconst HELP = `mockgen — turn an OpenAPI spec or a folder of sample responses into a running mock server\n\nUsage\n  mockgen serve <spec|dir>             Start a mock server (hot-reloads on change)\n  mockgen generate <spec|dir> [route]  Print generated responses, e.g. \"GET /users/1\"\n  mockgen validate <spec|dir>          Load the input and generate every response\n  mockgen infer <dir> [-o file]        Write the schema inferred from samples as OpenAPI 3.1\n\nSample folders: name files after the route, e.g. GET.users.json, users/GET.[id].json,\nGET.users.[id].404.json. Folders become path segments; [id] or {id} is a path param.\n\nOptions\n  -p, --port <n>      Port to listen on (default 4010)\n  -H, --host <host>   Host to bind (default 127.0.0.1)\n  -s, --seed <n>      Seed for generated data (default 1)\n  -d, --delay <ms>    Delay every response, e.g. 300 or 300ms\n  -r, --records <n>   Records per list endpoint, paged with ?page=&limit= (default 50)\n  -o, --out <file>    infer: write here instead of stdout (.yaml or .json)\n      --no-watch      Disable hot reload\n  -h, --help          Show this help\n  -v, --version       Show the version\n\nPer request\n  X-Mock-Status: 404  (or ?__status=404)   Return that status instead of the success response\n  X-Mock-Delay: 500   (or ?__delay=500)    Delay this response\n  ?page=2&limit=20, ?offset=40, ?cursor=…  Page through list endpoints\n`;\n\nasync function main(argv: string[]) {\n  const { values, positionals } = parseArgs({\n    args: argv,\n    allowPositionals: true,\n    allowNegative: true,\n    options: {\n      port: { type: 'string', short: 'p', default: '4010' },\n      host: { type: 'string', short: 'H', default: '127.0.0.1' },\n      seed: { type: 'string', short: 's', default: '1' },\n      delay: { type: 'string', short: 'd', default: '0' },\n      out: { type: 'string', short: 'o' },\n      records: { type: 'string', short: 'r', default: '50' },\n      watch: { type: 'boolean', default: true },\n      help: { type: 'boolean', short: 'h' },\n      version: { type: 'boolean', short: 'v' },\n    },\n  });\n\n  if (values.version) return console.log(await version());\n  const [command, spec, ...rest] = positionals;\n  if (values.help || !command) return console.log(HELP);\n  if (!spec) fail(`Missing <spec>. Try: mockgen ${command} ./openapi.yaml`);\n\n  const seed = int(values.seed, '--seed');\n  switch (command) {\n    case 'serve':\n      return serve(spec, { port: int(values.port, '--port'), host: values.host, seed, delay: int(values.delay.replace(/ms$/, ''), '--delay'), watch: values.watch, records: int(values.records, '--records') });\n    case 'generate':\n      return generateCmd(spec, rest.join(' '), seed, int(values.records, '--records'));\n    case 'validate':\n      return validate(spec, seed);\n    case 'infer':\n      return infer(spec, values.out);\n    default:\n      fail(`Unknown command \"${command}\". Run mockgen --help.`);\n  }\n}\n\nasync function serve(spec: string, opts: { port: number; host: string; seed: number; delay: number; watch: boolean; records: number }) {\n  const started = performance.now();\n  const model = await loadSource(spec);\n  printWarnings(model);\n  const mock = createMockServer({ model, seed: opts.seed, delay: opts.delay, records: opts.records, log: (line) => console.log(styleText('dim', line)) });\n  const url = await mock.listen(opts.port, opts.host).catch((err: NodeJS.ErrnoException) => {\n    if (err.code === 'EADDRINUSE') fail(`Port ${opts.port} is already in use on ${opts.host}. Pick another with --port ${opts.port + 1}, or --port 0 for any free port.`);\n    if (err.code === 'EACCES') fail(`No permission to use port ${opts.port} on ${opts.host}. Ports below 1024 usually need admin rights; try --port 4010.`);\n    throw err;\n  });\n\n  // Watch before announcing \"ready\": a script that edits the spec as soon as it sees\n  // that line would otherwise race the watcher and its edit could be missed.\n  if (opts.watch) watchSources(model, async () => {\n    try {\n      const next = await loadSource(spec);\n      mock.setModel(next);\n      printWarnings(next);\n      console.log(`${styleText('green', '↻')} Reloaded ${next.routes.length} routes`);\n      return next;\n    } catch (err) {\n      console.error(styleText('red', `✖ Reload failed, still serving the previous version:\\n  ${(err as Error).message}`));\n      return undefined;\n    }\n  });\n\n  console.log(`\\n${styleText('bold', model.title)} ${styleText('dim', model.version)}`);\n  for (const r of model.routes) console.log(`  ${styleText('cyan', r.method.padEnd(7))} ${url}${model.basePath}${r.path}`);\n  console.log(`\\n${styleText('green', '✔')} Mock server ready at ${styleText('bold', url)} in ${Math.round(performance.now() - started)}ms (seed ${opts.seed})\\n`);\n\n  const shutdown = () => mock.close().then(() => process.exit(0));\n  process.once('SIGINT', shutdown);\n  process.once('SIGTERM', shutdown);\n}\n\n/**\n * Watch every local file of the spec and reload on change, debounced.\n *\n * Watchers are re-created after every reload, failed ones included: on Linux and macOS\n * a watcher follows the file, not its name, so an editor's save (write a temp file,\n * rename it over the original) leaves the old watcher on a file that no longer exists.\n */\nfunction watchSources(model: MockModel, reload: () => Promise<MockModel | undefined>) {\n  let watchers: fs.FSWatcher[] = [];\n  let files = model.sources;\n  let timer: NodeJS.Timeout | undefined;\n  let retry: NodeJS.Timeout | undefined;\n  const onChange = () => {\n    clearTimeout(timer);\n    timer = setTimeout(async () => {\n      files = (await reload())?.sources ?? files;\n      watch();\n    }, 100);\n  };\n  const watch = () => {\n    watchers.forEach((w) => w.close());\n    watchers = [];\n    clearTimeout(retry);\n    let missing = false;\n    for (const file of files) {\n      try {\n        watchers.push(fs.watch(file, { recursive: fs.statSync(file).isDirectory() }, onChange));\n      } catch {\n        missing = true; // e.g. mid-save, between delete and rename\n      }\n    }\n    if (missing) retry = setTimeout(watch, 200);\n  };\n  watch();\n}\n\nasync function generateCmd(spec: string, route: string, seed: number, records: number) {\n  const model = await loadSource(spec);\n  if (route) {\n    const [method = 'GET', p = '/'] = route.includes(' ') ? route.split(/\\s+/) : ['GET', route];\n    const [pathname = '/', query] = p.split('?');\n    const result = respond(model, { method: method.toUpperCase(), path: pathname, query, seed, records });\n    if (result.status >= 400 && !model.routes.some((r) => r.pattern.test(pathname))) fail((result.body as any).message);\n    return console.log(JSON.stringify(result.body, null, 2));\n  }\n  const out: Record<string, unknown> = {};\n  for (const r of model.routes) {\n    const res = r.responses.find((x) => x.status >= 200 && x.status < 300) ?? r.responses[0];\n    out[`${r.method} ${r.path}`] = res?.hasExample ? res.example : generate(res?.schema, { seed, key: `${r.method} ${r.path} ${res?.status}` });\n  }\n  console.log(JSON.stringify(out, null, 2));\n}\n\nasync function infer(dir: string, out: string | undefined) {\n  if (!(await fs.promises.stat(dir).catch(() => undefined))?.isDirectory()) fail(`infer expects a folder of sample responses, got \"${dir}\"`);\n  const model = await loadSamples(dir);\n  printWarnings(model);\n  const text = formatOpenApi(model, out);\n  if (!out) return process.stdout.write(text);\n  await fs.promises.writeFile(out, text);\n  console.error(`${styleText('green', '✔')} Wrote ${model.routes.length} routes to ${out}`);\n}\n\nasync function validate(spec: string, seed: number) {\n  const model = await loadSource(spec);\n  printWarnings(model);\n  const validator = new ResponseValidator(model.openapi);\n  let responses = 0;\n  let skipped = 0;\n  const invalid: string[] = [];\n  for (const r of model.routes) {\n    for (const res of r.responses) {\n      if (!res.schema || res.hasExample) continue;\n      const label = `${r.method} ${r.path} ${res.status}`;\n      const value = generate(res.schema, { seed, key: label });\n      try {\n        const result = validator.validate(res.schema, value);\n        if (!result.valid) invalid.push(`${label}: ${result.errors}`);\n        responses++;\n      } catch {\n        skipped++; // The schema itself can't be compiled (e.g. a non-JavaScript regex).\n      }\n    }\n  }\n  for (const line of invalid) console.error(styleText('red', `✖ ${line}`));\n  const summary = `${model.title}: ${model.routes.length} routes, ${responses - invalid.length}/${responses} generated responses valid${skipped ? `, ${skipped} schemas not checkable` : ''}, ${model.warnings.length} warnings`;\n  if (invalid.length) fail(summary);\n  console.log(`${styleText('green', '✔')} ${summary}`);\n}\n\nfunction printWarnings(model: MockModel) {\n  for (const w of model.warnings) console.warn(styleText('yellow', `⚠ ${w}`));\n}\n\nfunction int(value: string, flag: string): number {\n  const n = Number(value);\n  if (!Number.isInteger(n) || n < 0) fail(`${flag} must be a non-negative integer, got \"${value}\"`);\n  return n;\n}\n\nasync function version(): Promise<string> {\n  const pkg = JSON.parse(await fs.promises.readFile(path.join(import.meta.dirname, '..', 'package.json'), 'utf8'));\n  return pkg.version;\n}\n\nfunction fail(message: string): never {\n  console.error(styleText('red', `✖ ${message}`));\n  process.exit(1);\n}\n\nmain(process.argv.slice(2)).catch((err) => fail(err.message));\n"]}

package/dist/collections.d.ts

@@ -0,0 +1,45 @@
+import type { MockRoute, Schema } from './model.js';
+export interface ListShape {
+    /** Property holding the records; undefined when the response is a bare array. */
+    key?: string;
+    arraySchema: Schema;
+    itemSchema: Schema;
+}
+/** Recognize a list response: a bare array of objects, or an object wrapping one. */
+export declare function findListShape(schema: Schema | undefined): ListShape | undefined;
+/** The `GET /users/{id}` route for list route `GET /users`, if the spec has one. */
+export declare function findDetailRoute(routes: MockRoute[], list: MockRoute): MockRoute | undefined;
+export interface PageWindow {
+    offset: number;
+    limit: number;
+    /** 1-based. */
+    page: number;
+    total: number;
+}
+/** Work out which slice of the collection a request asks for. */
+export declare function readPage(query: URLSearchParams, arraySchema: Schema, total: number, defaultLimit?: number): PageWindow;
+export interface BuildPageInput {
+    /** The list response's schema. */
+    schema: Schema;
+    /** Concrete request path, used to seed records and build next/prev links. */
+    requestPath: string;
+    query: URLSearchParams;
+    origin?: string;
+    seed?: number;
+    shape: ListShape;
+    /** Generated response body; for wrapped lists, its metadata is filled in place. */
+    body: unknown;
+    total: number;
+    /** Name of the id property that links items to the detail route. */
+    idKey?: string;
+    /** Detail response for an id, used to make list items agree with `GET /x/{id}`. */
+    detail?: (id: unknown) => Record<string, unknown> | undefined;
+    /** The detail route's schema; fields it shares with the item need no re-check. */
+    detailSchema?: Schema;
+}
+export declare function buildPage(input: BuildPageInput): {
+    body: unknown;
+    headers: Record<string, string>;
+};
+/** Opaque-looking cursors that are really offsets, so any cursor we hand out works. */
+export declare function encodeCursor(offset: number): string;