@databehave/server 0.1.0

package/dist/openapi/auto-schema.js

@@ -0,0 +1,232 @@
+import { translateOasToIR } from './translate.js';
+/** Single-shot guard for the `schema.locale` no-op soft warn. */
+let localeWarned = false;
+/** Knobs accepted on the `schema:` JSONC object (alongside `enabled`). */
+const KNOWN_SCHEMA_KEYS = new Set([
+    'enabled',
+    'seed',
+    'locale',
+    'arrayCount',
+]);
+/**
+ * Friendly install-hint emitted when `config.schema.enabled === true`
+ * but the `@databehave/schema` peer is not installed. Verbatim from
+ * the brief — names the package, the field, the file, all three
+ * install commands, the README anchor, and the opt-out instruction.
+ */
+export const INSTALL_HINT = '[@databehave/server] Auto-schema mode is enabled in databehave.jsonc\n' +
+    '("schema": { "enabled": true } is set), but the data-generation engine is not installed.\n' +
+    '\n' +
+    '  npm i @databehave/schema\n' +
+    '  # or: pnpm add @databehave/schema\n' +
+    '  # or: yarn add @databehave/schema\n' +
+    '\n' +
+    'This enables realistic, seeded mock data derived from your OpenAPI\n' +
+    'document. See: https://github.com/ochairo/databehave/blob/main/packages/server/docs/openapi/auto-schema.md#missing-install-error\n' +
+    '\n' +
+    'To keep the default zero-dep placeholder mode instead, set\n' +
+    '"schema": { "enabled": false } or remove the "schema" field from databehave.jsonc.';
+/**
+ * Validate the raw JSONC `schema:` value and normalise to the
+ * resolved shape. The value MUST be an object with an explicit
+ * `enabled: boolean`. The boolean shorthand (`schema: true` /
+ * `schema: false`) was removed — callers receive a migration
+ * error pointing at the new shape. Returns `null` when
+ * `enabled === false` so the caller can short-circuit auto-mode.
+ * Unknown keys throw with a message pointing at the offending key.
+ */
+export const normaliseSchemaConfig = (raw) => {
+    if (typeof raw === 'boolean') {
+        throw new Error('@databehave/server/config: "schema" must be an object like ' +
+            '{ "enabled": true }; the boolean shorthand was removed (got ' +
+            JSON.stringify(raw) +
+            ')');
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('@databehave/server/config: "schema" must be an object like ' +
+            '{ "enabled": true } (got ' +
+            (raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw) +
+            ')');
+    }
+    const obj = raw;
+    for (const k of Object.keys(obj)) {
+        if (!KNOWN_SCHEMA_KEYS.has(k)) {
+            throw new Error(`@databehave/server/config: unknown key in "schema": ${JSON.stringify(k)} ` +
+                `(valid keys: ${[...KNOWN_SCHEMA_KEYS].join(', ')})`);
+        }
+    }
+    if (typeof obj.enabled !== 'boolean') {
+        throw new Error('@databehave/server/config: "schema.enabled" must be a boolean ' +
+            `(got ${obj.enabled === undefined ? 'undefined' : JSON.stringify(obj.enabled)})`);
+    }
+    if (obj.enabled === false)
+        return null;
+    let seed = 'stable';
+    if (obj.seed !== undefined) {
+        if (typeof obj.seed === 'number' ||
+            obj.seed === 'stable' ||
+            obj.seed === 'random') {
+            seed = obj.seed;
+        }
+        else {
+            throw new Error('@databehave/server/config: "schema.seed" must be a number, "stable", or "random" ' +
+                `(got ${JSON.stringify(obj.seed)})`);
+        }
+    }
+    const out = { seed };
+    if (obj.locale !== undefined) {
+        if (typeof obj.locale !== 'string') {
+            throw new Error('@databehave/server/config: "schema.locale" must be a string');
+        }
+        out.locale = obj.locale;
+        if (!localeWarned) {
+            localeWarned = true;
+            console.warn(`[@databehave/server] schema.locale (${JSON.stringify(obj.locale)}) is currently parsed but not consumed by the data-generation engine; the value will be ignored.`);
+        }
+    }
+    if (obj.arrayCount !== undefined) {
+        if (typeof obj.arrayCount !== 'number' || !Number.isFinite(obj.arrayCount) || obj.arrayCount < 0) {
+            throw new Error('@databehave/server/config: "schema.arrayCount" must be a non-negative number');
+        }
+        out.arrayCount = obj.arrayCount;
+    }
+    return out;
+};
+/**
+ * Load the optional peer `@databehave/schema` package. On
+ * "Cannot find module" failures the native Node error is suppressed
+ * and replaced with the friendly install hint above. Other errors
+ * (e.g. broken install) re-throw verbatim — those are real bugs.
+ */
+export const loadSchemaModule = async () => {
+    try {
+        return await import('@databehave/schema');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const code = err?.code;
+        if (code === 'ERR_MODULE_NOT_FOUND' ||
+            code === 'MODULE_NOT_FOUND' ||
+            msg.includes('Cannot find module') ||
+            msg.includes('Cannot find package')) {
+            // Suppress the native error — users see only the friendly
+            // template. Wrapping `cause: err` would re-leak the native
+            // text into Node's default stack-printer; intentionally drop it.
+            throw new Error(INSTALL_HINT);
+        }
+        throw err;
+    }
+};
+const SUPPORTED_METHODS = new Set([
+    'get',
+    'post',
+    'put',
+    'delete',
+    'patch',
+]);
+/** Convert OAS `/users/{id}` → `/users/:id`. */
+const oasPathToInternal = (oasPath) => oasPath
+    .split('/')
+    .map((seg) => (seg.startsWith('{') && seg.endsWith('}') ? `:${seg.slice(1, -1)}` : seg))
+    .join('/');
+/**
+ * FNV-1a 32-bit hash. Tiny, zero-dep, stable across machines —
+ * exactly what the per-request `seed: 'stable'` derivation needs.
+ *
+ * Input format: `${METHOD} ${endpointPath}|${sortedQuery}|${sortedPathParams}`,
+ * where sorted means lex-sorted keys joined by `&` as `key=value`.
+ *
+ * Example input  → output (uint32):
+ *   `GET /users/:id|page=2|id=42` → 0x9b1ed8c5
+ */
+export const hashSeed = (input) => {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h >>> 0;
+};
+const sortedJoin = (record) => Object.keys(record)
+    .sort()
+    .map((k) => `${k}=${record[k]}`)
+    .join('&');
+const deriveSeed = (cfg, method, endpointPath, req) => {
+    if (typeof cfg.seed === 'number')
+        return cfg.seed >>> 0;
+    if (cfg.seed === 'random') {
+        return (Math.random() * 0xffffffff) >>> 0;
+    }
+    // 'stable': hash of `${METHOD} ${endpointPath}|${sortedQuery}|${sortedParams}`
+    const key = `${method} ${endpointPath}|${sortedJoin(req.query)}|${sortedJoin(req.params)}`;
+    return hashSeed(key);
+};
+/**
+ * Find the response schema node that the OAS-only generator would
+ * pick: prefer 200, then the smallest declared 2xx, mirroring
+ * `register.ts`. 204 → no body (signal via `null`).
+ */
+const pickResponseSchema = (responses) => {
+    const twoXx = Object.keys(responses)
+        .map((s) => Number.parseInt(s, 10))
+        .filter((n) => Number.isFinite(n) && n >= 200 && n < 300)
+        .sort((a, b) => (a === 200 ? -1 : b === 200 ? 1 : a - b));
+    const status = twoXx[0];
+    if (status === undefined)
+        return null;
+    if (status === 204)
+        return 'no-body';
+    const schema = responses[String(status)]?.content?.['application/json']?.schema;
+    if (!schema || typeof schema !== 'object')
+        return null;
+    return { schema, status };
+};
+/**
+ * Build a route-key → handler map for every OAS path/method whose
+ * response carries a usable JSON schema and is NOT already covered
+ * by hand-written `endpoints`. Each handler is closed over the
+ * cached schema module and pre-translated IR.
+ *
+ * `declaredKeys` is the set of route keys the user already declared
+ * via `endpoints`; auto-mode skips those so hand-written routes
+ * always win.
+ */
+export const buildAutoSchemaRoutes = async (doc, cfg, schemaModule, declaredKeys) => {
+    const out = new Map();
+    const paths = doc.paths;
+    if (!paths)
+        return out;
+    for (const [oasPath, methods] of Object.entries(paths)) {
+        if (oasPath === '/')
+            continue;
+        const kitPath = oasPathToInternal(oasPath);
+        for (const [methodName, op] of Object.entries(methods)) {
+            const method = methodName.toLowerCase();
+            if (!SUPPORTED_METHODS.has(method))
+                continue;
+            const key = `${method.toUpperCase()} ${kitPath}`;
+            if (declaredKeys.has(key))
+                continue;
+            const responses = op.responses;
+            if (!responses)
+                continue;
+            const picked = pickResponseSchema(responses);
+            if (picked === null || picked === 'no-body')
+                continue;
+            // Translation throws at server-creation on unsupported keywords —
+            // FAIL LOUD, never silently fall through to the placeholder
+            // generator (the user opted in to auto-schema; downgrading
+            // would produce confusing mixed output).
+            const ir = await translateOasToIR(picked.schema, doc);
+            const upperMethod = method.toUpperCase();
+            const handler = (req) => {
+                const seed = deriveSeed(cfg, upperMethod, kitPath, req);
+                const value = schemaModule.mock(ir, { seed });
+                return { json: value };
+            };
+            out.set(key, handler);
+        }
+    }
+    return out;
+};
+//# sourceMappingURL=auto-schema.js.map

package/dist/openapi/auto-schema.js.map

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

package/dist/openapi/generate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-server, zero-dep mock-data generator for OpenAPI-driven mocks.
+ *
+ *   OpenAPI node → generateFromOasSchema() → deterministic JSON value
+ *
+ * `@databehave/server` runs standalone for OAS-only consumers — this
+ * file is the entire mock-body engine and pulls no DSL dependency at
+ * runtime. Output is deterministic placeholder data so tests can pin
+ * exact values (`"string"`, `0`, `false`, …) and OAS gaps surface
+ * loudly via `onWalkError` in `register.ts`.
+ *
+ * Single file. No external imports. Sibling-relative only.
+ */
+import type { OasDoc, OasNode } from './walker.js';
+/** Reserved for a future seeded mode (brief item #11). Currently ignored. */
+export interface GenerateOptions {
+    readonly seed?: number;
+}
+export declare const generateFromOasSchema: (node: OasNode, doc?: OasDoc, _opts?: GenerateOptions, seen?: Set<string>) => unknown;
+//# sourceMappingURL=generate.d.ts.map

package/dist/openapi/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/openapi/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAElD,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAsDD,eAAO,MAAM,qBAAqB,GAChC,MAAM,OAAO,EACb,MAAK,MAAW,EAEhB,QAAO,eAAoB,EAC3B,OAAM,GAAG,CAAC,MAAM,CAAqB,KACpC,OAqEF,CAAA"}

package/dist/openapi/generate.js

@@ -0,0 +1,121 @@
+const FORMAT_STRINGS = {
+    date: '2024-01-01',
+    'date-time': '2024-01-01T00:00:00Z',
+    email: 'user@example.com',
+    uuid: '00000000-0000-4000-8000-000000000000',
+    uri: 'https://example.com/',
+};
+const KNOWN_TYPES = new Set([
+    'string',
+    'integer',
+    'number',
+    'boolean',
+    'array',
+    'object',
+    'null',
+]);
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const resolveRef = (doc, ref) => {
+    if (!ref.startsWith('#/')) {
+        throw new Error(`@databehave/server/openapi: remote $ref not supported by OAS-only generator: ${ref}`);
+    }
+    const m = /^#\/components\/schemas\/(.+)$/.exec(ref);
+    if (!m) {
+        throw new Error(`@databehave/server/openapi: unsupported $ref: ${ref}`);
+    }
+    const name = decodeURIComponent(m[1]);
+    const target = doc.components?.schemas?.[name];
+    if (!target) {
+        throw new Error(`@databehave/server/openapi: $ref not found: ${ref}`);
+    }
+    return target;
+};
+/**
+ * Pick the concrete (non-`null`) type when OAS 3.1 declares
+ * `["string","null"]`. OAS 3.0 `nullable: true` is treated the same
+ * way: the generator never emits `null` from a nullable widening —
+ * callers that want explicit `null` use `examples` or `enum`.
+ */
+const pickType = (node) => {
+    if (Array.isArray(node.type)) {
+        return node.type.find((t) => t !== 'null');
+    }
+    return node.type;
+};
+export const generateFromOasSchema = (node, doc = {}, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_opts = {}, seen = new Set()) => {
+    const ex = node.example;
+    if (ex !== undefined)
+        return ex;
+    const examples = node.examples;
+    if (Array.isArray(examples) && examples.length > 0)
+        return examples[0];
+    if (Array.isArray(node.enum) && node.enum.length > 0)
+        return node.enum[0];
+    if (node.const !== undefined)
+        return node.const;
+    if (node.$ref) {
+        if (seen.has(node.$ref))
+            return {};
+        const next = new Set(seen);
+        next.add(node.$ref);
+        return generateFromOasSchema(resolveRef(doc, node.$ref), doc, _opts, next);
+    }
+    if (Array.isArray(node.allOf) && node.allOf.length > 0) {
+        let merged = {};
+        for (const branch of node.allOf) {
+            const v = generateFromOasSchema(branch, doc, _opts, seen);
+            if (isPlainObject(v))
+                merged = { ...merged, ...v };
+            else
+                return v;
+        }
+        return merged;
+    }
+    if (Array.isArray(node.oneOf) && node.oneOf.length > 0) {
+        return generateFromOasSchema(node.oneOf[0], doc, _opts, seen);
+    }
+    if (Array.isArray(node.anyOf) && node.anyOf.length > 0) {
+        return generateFromOasSchema(node.anyOf[0], doc, _opts, seen);
+    }
+    let t = pickType(node);
+    if (!t && node.properties)
+        t = 'object';
+    if (!t && node.items !== undefined)
+        t = 'array';
+    if (!t)
+        return {};
+    if (typeof t === 'string' && !KNOWN_TYPES.has(t)) {
+        throw new Error(`@databehave/server/openapi: unsupported OpenAPI node: ${JSON.stringify(node)}`);
+    }
+    if (t === 'null')
+        return null;
+    if (t === 'string') {
+        if (node.format && FORMAT_STRINGS[node.format]) {
+            return FORMAT_STRINGS[node.format];
+        }
+        return 'string';
+    }
+    if (t === 'integer' || t === 'number') {
+        return typeof node.minimum === 'number' ? node.minimum : 0;
+    }
+    if (t === 'boolean')
+        return false;
+    if (t === 'array') {
+        const itemNode = node.items ?? {};
+        const count = typeof node.minItems === 'number' && node.minItems > 0 ? node.minItems : 1;
+        const out = [];
+        for (let i = 0; i < count; i += 1) {
+            out.push(generateFromOasSchema(itemNode, doc, _opts, seen));
+        }
+        return out;
+    }
+    // object
+    const out = {};
+    for (const [k, v] of Object.entries(node.properties ?? {})) {
+        out[k] = generateFromOasSchema(v, doc, _opts, seen);
+    }
+    return out;
+};
+//# sourceMappingURL=generate.js.map

package/dist/openapi/generate.js.map

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

package/dist/openapi/loader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parse a JSON OpenAPI document.
+ *
+ * Consumers hand `@databehave/server` the raw text — how they obtained it
+ * (`fs.readFile`, `fetch`, bundler `?raw` import) is up to them.
+ *
+ * `@databehave/server` is JSON-only. Convert YAML up-front
+ * (`yq -o=json spec.yaml > spec.json`) and pass the JSON bytes through.
+ */
+import type { OasDoc } from './walker.js';
+/**
+ * Parse a JSON OpenAPI document.
+ *
+ * `sourcePath` is optional metadata used only to enrich error messages
+ * and to refuse YAML inputs by extension with an actionable hint.
+ */
+export declare const parseOpenApi: (text: string, sourcePath?: string) => OasDoc;
+//# sourceMappingURL=loader.d.ts.map

package/dist/openapi/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/openapi/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,aAAa,MAAM,KAAG,MAoBhE,CAAA"}

package/dist/openapi/loader.js

@@ -0,0 +1,25 @@
+/**
+ * Parse a JSON OpenAPI document.
+ *
+ * `sourcePath` is optional metadata used only to enrich error messages
+ * and to refuse YAML inputs by extension with an actionable hint.
+ */
+export const parseOpenApi = (text, sourcePath) => {
+    // Strip a leading UTF-8 BOM (U+FEFF) if present — common when the
+    // OAS document was authored in Windows tooling or saved as
+    // "UTF-8 with BOM". Without this, the very first `JSON.parse`
+    // throws "Unexpected token" with no actionable hint.
+    const stripped = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    if (sourcePath !== undefined && /\.ya?ml$/i.test(sourcePath)) {
+        throw new Error('JSON-only spec loader. Convert YAML first: yq -o=json <file>.yaml > <file>.json');
+    }
+    const where = sourcePath !== undefined ? ` at ${sourcePath}` : '';
+    try {
+        return JSON.parse(stripped);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`@databehave/server/openapi: failed to parse JSON OpenAPI document${where}: ${msg}`);
+    }
+};
+//# sourceMappingURL=loader.js.map

package/dist/openapi/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/openapi/loader.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,UAAmB,EAAU,EAAE;IACxE,kEAAkE;IAClE,2DAA2D;IAC3D,8DAA8D;IAC9D,qDAAqD;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACrE,IAAI,UAAU,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACjE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAW,CAAA;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC5D,MAAM,IAAI,KAAK,CACb,oEAAoE,KAAK,KAAK,GAAG,EAAE,CACpF,CAAA;IACH,CAAC;AACH,CAAC,CAAA"}

package/dist/openapi/register.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Build a route table of `Handler`s from an OpenAPI document.
+ *
+ * The walker visits every `paths.*.<method>` entry. For each that
+ * has a non-empty 200 response schema, a deterministic mock body is
+ * generated once at boot (so OAS gaps surface at boot, not on the
+ * first request) and the handler re-serves it per request.
+ *
+ * Determinism: the OAS-only generator emits structural placeholder
+ * values, so same schema → same body. Per-request seeding (path /
+ * query params) is reserved for a future seeded mode (brief #11)
+ * and currently has no effect on the body.
+ *
+ * Endpoints without a usable schema get a tiny stub: `{}` for GET,
+ * `{ success: true, message: null }` for mutating methods.
+ *
+ * Pure: this module never reads files or talks to the HTTP layer. It produces
+ * plain `Handler` callables that @databehave/server registers like any
+ * hand-written route.
+ */
+import type { Handler, Method, RouteKey } from '../types.js';
+import type { OasDoc } from './walker.js';
+export interface OpenApiRoutesOptions {
+    /** Route keys (`'METHOD /path'`) the OAS walker must NOT register. */
+    readonly skip?: ReadonlySet<RouteKey>;
+    /** Optional callback for walker failures. Defaults to silent stub fallback. */
+    readonly onWalkError?: (method: Method, routePath: string, err: unknown) => void;
+    /**
+     * Optional callback fired when the OAS declares a response with an
+     * empty / permissive schema (`schema: {}`). Per JSON Schema this
+     * matches any value, so we still serve a deterministic stub — but
+     * the caller usually wants to surface it so the spec gap is fixed.
+     */
+    readonly onEmptySchema?: (method: Method, routePath: string, status: number) => void;
+}
+/**
+ * Build a per-route per-status JSON body generator map from the OAS
+ * `responses` table. Used by mock-mode to synthesize an error body
+ * from the schema declared for that status code.
+ *
+ * Each generator is deterministic: same `(routeKey, status)` always
+ * yields the same body. Routes with `:param` segments are matched
+ * by exact path key only — runtime path-param substitution is the
+ * caller's responsibility.
+ *
+ * `onWalkError` mirrors `buildOpenApiRoutes` so spec gaps in error
+ * responses surface the same way as gaps in success responses.
+ */
+export declare const buildOpenApiResponseGenerators: (doc: OasDoc, options?: {
+    onWalkError?: OpenApiRoutesOptions["onWalkError"];
+}) => Map<RouteKey, Map<number, () => unknown>>;
+/**
+ * Produce a `Map<RouteKey, Handler>` covering every OAS
+ * `paths.<p>.<m>` not in `skip`. Failing schemas fall back to the
+ * stub body and report via `onWalkError` (default: ignore).
+ */
+export declare const buildOpenApiRoutes: (doc: OasDoc, options?: OpenApiRoutesOptions) => Map<RouteKey, Handler>;
+//# sourceMappingURL=register.d.ts.map

package/dist/openapi/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/openapi/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAG5D,OAAO,KAAK,EAAE,MAAM,EAAW,MAAM,aAAa,CAAA;AAwClD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAA;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,KACT,IAAI,CAAA;IACT;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,KACX,IAAI,CAAA;CACV;AAmBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,8BAA8B,GACzC,KAAK,MAAM,EACX,UAAS;IAAE,WAAW,CAAC,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAA;CAAO,KAClE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,CA+C1C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,KAAK,MAAM,EACX,UAAS,oBAAyB,KACjC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAuDvB,CAAA"}