@redocly/client-generator 0.3.7 → 0.4.0

package/eject-assets/generators/mock/faker.ts

@@ -0,0 +1,214 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "mock" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator mock --update`.
+// Builds the body value for a faker-mode mock factory: a tree of
+// `@faker-js/faker` call expressions that produce realistic — and, with a seed,
+// reproducible — data. Structurally mirrors `./sample.ts`'s `walk` (same
+// recursion + same visited-set cycle guard), but yields faker calls instead of a
+// static value. Nested refs are INLINED under the same cycle guard (never
+// `create<Ref>()` calls), so a cyclic schema terminates with `null` at the cycle
+// instead of recursing forever at runtime — exactly like the static path. The
+// factory signatures are identical to the static mode's, so a consumer can flip
+// `mockData` without touching call sites; `@faker-js/faker` becomes their
+// dev-dep while the real client stays dependency-free.
+
+import {
+  type DateType,
+  type NamedSchemaModel,
+  type ScalarKind,
+  type SchemaMetadata,
+  type SchemaModel,
+} from '@redocly/client-generator';
+import { codeLiteral } from '@redocly/client-generator/printers/typescript';
+
+import { splitIntersection } from './sample.ts';
+import { expr, isObjectValue, type MockEntry, type MockValue, objectValue } from './values.ts';
+
+/** The faker-call value for an IR schema. Refs resolve against `schemas`;
+ *  recursion is cut with a visited-set (`null` at the cycle). `dateType` mirrors
+ *  the sdk's `--date-type`: under `'Date'`, date fields stay `faker.date.recent()`
+ *  (a `Date`); otherwise they are stringified to match the `string`-typed sdk. */
+export function fakerExpression(
+  schema: SchemaModel,
+  schemas: NamedSchemaModel[],
+  opts: { dateType?: DateType } = {}
+): MockValue {
+  const byName = new Map(schemas.map((s) => [s.name, s.schema]));
+  const value = walk(schema, byName, new Set(), opts.dateType ?? 'string');
+  // A `CYCLE` that reaches the root has no container to absorb it (e.g. a
+  // self-referential union); fall back to null.
+  return value === CYCLE ? expr('null') : value;
+}
+
+/**
+ * Sentinel returned by `walk` when a `$ref` re-enters a name already on the stack.
+ * Containers turn it into the type-correct empty value for their position — an array
+ * to `[]`, a record to `{}`, an optional property to omission — mirroring `./sample.ts`
+ * so a recursive schema yields a faker tree that still satisfies its non-nullable type.
+ * Only a required, non-container self-reference (an uninhabitable schema) degrades to null.
+ */
+const CYCLE = Symbol('cycle');
+
+type WalkResult = MockValue | typeof CYCLE;
+
+function walk(
+  schema: SchemaModel,
+  byName: Map<string, SchemaModel>,
+  visiting: Set<string>,
+  dateType: DateType
+): WalkResult {
+  switch (schema.kind) {
+    case 'scalar':
+      return expr(scalarExpr(schema.scalar, schema.metadata, dateType));
+    case 'array': {
+      // A cyclic item type collapses the array to `[]` — itself a valid `T[]`.
+      const item = walk(schema.items, byName, visiting, dateType);
+      return item === CYCLE ? expr('[]') : multiple(item);
+    }
+    case 'object':
+      return objectValue(
+        schema.properties.flatMap((p): MockEntry[] => {
+          const value = walk(p.schema, byName, visiting, dateType);
+          // A cyclic optional property is omitted; a cyclic required property is
+          // uninhabitable, so null is the only stand-in.
+          if (value === CYCLE) return p.required ? [{ key: p.name, value: expr('null') }] : [];
+          return [{ key: p.name, value }];
+        })
+      );
+    case 'record': {
+      const value = walk(schema.value, byName, visiting, dateType);
+      return value === CYCLE ? expr('{}') : objectValue([{ key: 'key', value }]);
+    }
+    case 'enum':
+      return expr(
+        `faker.helpers.arrayElement([${schema.values.map((value) => codeLiteral(value)).join(', ')}] as const)`
+      );
+    case 'literal':
+      return expr(codeLiteral(schema.value));
+    case 'union': {
+      // First non-cyclic member; if every member cycles, propagate `CYCLE`.
+      for (const member of schema.members) {
+        const value = walk(member, byName, visiting, dateType);
+        if (value !== CYCLE) return value;
+      }
+      return schema.members.length > 0 ? CYCLE : expr('null');
+    }
+    case 'intersection': {
+      // Mirror the static sampler: object members merge into one synthetic object whose
+      // property conflicts resolve by SPECIFICITY (see `splitIntersection`); `unknown`
+      // members are constraint-only and dropped; with no object member, the first
+      // member's expression IS the value (a scalar-narrowing intersection).
+      const { merged, rest } = splitIntersection(schema.members, byName);
+      const parts = rest
+        .map((member) => walk(member, byName, visiting, dateType))
+        .filter((part): part is MockValue => part !== CYCLE);
+      if (merged) {
+        const value = walk(merged, byName, visiting, dateType);
+        const own = value !== CYCLE && isObjectValue(value) ? value.entries : [];
+        const folded = parts.filter(isObjectValue).flatMap((part) => part.entries);
+        return objectValue([...own, ...folded]);
+      }
+      const objects = parts.filter(isObjectValue);
+      if (objects.length > 0) {
+        return objectValue(objects.flatMap((part) => part.entries));
+      }
+      return parts[0] ?? objectValue([]);
+    }
+    case 'omit':
+      return omitExpr(schema.base, schema.keys, byName, visiting, dateType);
+    case 'ref': {
+      if (visiting.has(schema.name)) return CYCLE;
+      const target = byName.get(schema.name);
+      if (!target) return expr('null');
+      visiting.add(schema.name);
+      const result = walk(target, byName, visiting, dateType);
+      visiting.delete(schema.name);
+      return result;
+    }
+    case 'null':
+    case 'unknown':
+      return expr('null');
+  }
+}
+
+/** The faker call for a scalar, keyed by kind then `format`. A binary field has no
+ *  faker generator (its type is `Blob`), so it emits `new Blob([])` — the same
+ *  type-demanded expression the static path uses, taking precedence over any example. */
+function scalarExpr(
+  scalar: ScalarKind,
+  meta: SchemaMetadata | undefined,
+  dateType: DateType
+): string {
+  if (meta?.format === 'binary') return 'new Blob([])';
+  if (scalar === 'boolean') return 'faker.datatype.boolean()';
+  if (scalar === 'integer') return `faker.number.int(${boundsArg(meta)})`;
+  if (scalar === 'number') return `faker.number.float(${boundsArg(meta)})`;
+  switch (meta?.format) {
+    case 'email':
+      return 'faker.internet.email()';
+    case 'uuid':
+      return 'faker.string.uuid()';
+    case 'uri':
+    case 'url':
+      return 'faker.internet.url()';
+    case 'hostname':
+      return 'faker.internet.domainName()';
+    case 'ipv4':
+      return 'faker.internet.ipv4()';
+    case 'date-time':
+      return dateExpr(dateType, false);
+    case 'date':
+      return dateExpr(dateType, true);
+    default:
+      return 'faker.lorem.word()';
+  }
+}
+
+/** `faker.date.recent()` (under `dateType: 'Date'`); else its ISO string, sliced to
+ *  `YYYY-MM-DD` for a `date` so the wire shape matches the `string`-typed field. */
+function dateExpr(dateType: DateType, dateOnly: boolean): string {
+  if (dateType === 'Date') return 'faker.date.recent()';
+  const iso = 'faker.date.recent().toISOString()';
+  return dateOnly ? `${iso}.slice(0, 10)` : iso;
+}
+
+/** `{ min, max }` arg for a bounded numeric, or empty when neither bound is set. */
+function boundsArg(meta: SchemaMetadata | undefined): string {
+  const props = [
+    ...(meta?.minimum !== undefined ? [`min: ${meta.minimum}`] : []),
+    ...(meta?.maximum !== undefined ? [`max: ${meta.maximum}`] : []),
+  ];
+  return props.length > 0 ? `{ ${props.join(', ')} }` : '';
+}
+
+/** `faker.helpers.multiple(() => <item>, { count: 1 })` — one element keeps output small.
+ * An object-literal arrow body must be parenthesized (`() => ({ … })`), or the braces
+ * parse as a block. */
+function multiple(item: MockValue): MockValue {
+  const object = isObjectValue(item);
+  return {
+    kind: 'wrap',
+    before: `faker.helpers.multiple(() => ${object ? '(' : ''}`,
+    value: item,
+    after: `${object ? ')' : ''}, { count: 1 })`,
+  };
+}
+
+/** An `omit`: the base named schema's faker value minus the dropped keys. Resolves the
+ *  base via the schema set (cycle-guarded); a non-object base passes through unchanged. */
+function omitExpr(
+  base: string,
+  keys: string[],
+  byName: Map<string, SchemaModel>,
+  visiting: Set<string>,
+  dateType: DateType
+): WalkResult {
+  const target = byName.get(base);
+  if (!target) return expr('null');
+  const value = walk(target, byName, visiting, dateType);
+  // A cyclic or non-object base passes through unchanged (a container/root absorbs `CYCLE`).
+  if (value === CYCLE || !isObjectValue(value)) return value;
+  const drop = new Set(keys);
+  return objectValue(value.entries.filter((entry) => 'spread' in entry || !drop.has(entry.key)));
+}

package/eject-assets/generators/mock/index.ts

@@ -0,0 +1,35 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "mock" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator mock --update`.
+import type { Generator } from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { renderMockModule } from './render.ts';
+
+/**
+ * The mock generator: a standalone `<stem>.mocks.ts` module of MSW handlers and
+ * data factories baked from the spec. Imports `msw` (the consumer's dev-dep); the
+ * sdk client stays dependency-free. Output-mode-agnostic in v1 — one module beside
+ * the client. Emits nothing when there are no operations.
+ */
+export const mockGenerator: Generator = ({ model, output, banner, emit }) => {
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  const content = renderMockModule(model, {
+    sdkModule: `./${output.stem}.${emit.importExt ?? 'js'}`,
+    dateType: emit.dateType,
+    mockData: emit.mockData,
+    mockSeed: emit.mockSeed,
+  });
+  if (content === '') return [];
+  return [
+    { path: join(output.dir, `${output.stem}.mocks.ts`), content: `${header}\n\n${content}` },
+  ];
+};
+
+export default {
+  name: 'mock',
+  run: mockGenerator,
+  requires: ["typescript"],
+  requiresGenerator: '^0.4.0',
+};

package/eject-assets/generators/mock/render.ts

@@ -0,0 +1,282 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "mock" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator mock --update`.
+// Emits a `*.mocks.ts` module: a `create<Schema>(overrides?)` data factory per
+// named schema, an `<op>Handler(override?)` MSW request handler per operation
+// (its primary success response), and an aggregated `handlers` array. Response
+// data is sampled at codegen time (`sampleValue`) and printed as TypeScript
+// literals — source-text templates — so the generated module depends only on
+// `msw`; the real client stays zero-dependency.
+
+import {
+  allOperations,
+  type ApiModel,
+  type DateType,
+  type NamedSchemaModel,
+  type OperationModel,
+  type ResponseBodyModel,
+  type SchemaModel,
+} from '@redocly/client-generator';
+import {
+  codeLiteral,
+  isIdentifier,
+  pascalCase,
+} from '@redocly/client-generator/printers/typescript';
+import { isPlainObject } from '@redocly/openapi-core';
+
+import { fakerExpression } from './faker.ts';
+import { sampleValue, SampleExpression } from './sample.ts';
+import {
+  expr,
+  isObjectValue,
+  type MockValue,
+  objectValue,
+  renderMockValue,
+  spreadInto,
+} from './values.ts';
+
+const INDENT = '    ';
+
+export type MockOptions = {
+  /** Import specifier for the sdk entry the schema types live in. */
+  sdkModule: string;
+  /** Must match the sdk's `--date-type`: under `'Date'` the sampler bakes date
+   *  fields as `new Date(...)` so the mock data matches the `Date`-typed sdk. */
+  dateType?: DateType;
+  /**
+   * How factory/handler bodies produce data. `'static'` (default) inlines deterministic
+   * literals from the sampler (zero-dep, contract-faithful). `'faker'` emits
+   * `@faker-js/faker` calls for realistic data — reproducible when `mockSeed` is set —
+   * making `@faker-js/faker` the consumer's dev-dep. Factory signatures are identical
+   * across modes, so a consumer can flip this without changing call sites.
+   */
+  mockData?: 'static' | 'faker';
+  /** When set in `'faker'` mode, emit a top-level `faker.seed(<n>);` so runs reproduce. */
+  mockSeed?: number;
+};
+
+/** The body value for `schema` under the active data mode: a static literal tree
+ *  (`'static'`) or a tree of `@faker-js/faker` calls (`'faker'`). Both honor `dateType`
+ *  and the binary/Blob type demand; the faker path inlines refs with the same cycle
+ *  guard as the static sampler, so neither recurses forever on a cyclic schema. */
+function bodyValue(schema: SchemaModel, model: ApiModel, opts: MockOptions): MockValue {
+  return opts.mockData === 'faker'
+    ? fakerExpression(schema, model.schemas, { dateType: opts.dateType })
+    : literal(sampleValue(schema, model.schemas, { dateType: opts.dateType }));
+}
+
+/** Render the full `*.mocks.ts` source. `''` when the model has no operations. */
+export function renderMockModule(model: ApiModel, opts: MockOptions): string {
+  const operations = allOperations(model.services);
+  if (operations.length === 0) return '';
+  const blocks = [
+    ...schemaTypeImport(model, opts),
+    // Faker mode imports `faker` (the consumer's dev-dep) and, with a seed, pins it once
+    // at module top so every run reproduces. Static mode emits neither (stays zero-dep).
+    ...(opts.mockData === 'faker' && opts.mockSeed !== undefined
+      ? [`faker.seed(${opts.mockSeed});`]
+      : []),
+    ...model.schemas.map((s) => factoryFor(s, model, opts)),
+    ...operations.flatMap((op) => [
+      handlerFor(op, model, opts),
+      ...(op.errorResponses.length > 0 ? [errorHandlerFor(op, model, opts)] : []),
+    ]),
+    handlersArray(operations),
+  ];
+  const fakerImport = opts.mockData === 'faker' ? "import { faker } from '@faker-js/faker';\n" : '';
+  return `import { http, HttpResponse } from 'msw';\n${fakerImport}\n${blocks.join('\n\n')}`;
+}
+
+/**
+ * `import type { A, B, … } from '<sdkModule>';` — the named-schema types the factories
+ * reference (`create<Pascal>` returns/accepts `<Pascal>`). Sorted for stable output.
+ * Empty when the model has no named schemas (so no type import is emitted). Importing
+ * the schema types also shadows globals of the same name (e.g. an `Error` schema) so the
+ * factory return types resolve to the generated type, not `globalThis.Error`.
+ */
+function schemaTypeImport(model: ApiModel, opts: MockOptions): string[] {
+  if (model.schemas.length === 0) return [];
+  // Verbatim, not PascalCased: the sdk exports each schema type under its emitted name
+  // (`pet` stays `pet`), and the import must match it exactly.
+  const names = model.schemas.map((s) => s.name).sort();
+  return [`import type { ${names.join(', ')} } from ${JSON.stringify(opts.sdkModule)};`];
+}
+
+/**
+ * `export function create<Pascal>(overrides?: Partial<Name>): Name { return { …sampled, ...overrides }; }`.
+ * A schema whose sample is not an object literal (a scalar, enum, date, …) has nothing
+ * to spread into — `Partial<string>` is meaningless and would silently drop the argument —
+ * so its factory takes the FULL type and returns the override wholesale (`overrides ?? sample`).
+ */
+function factoryFor(named: NamedSchemaModel, model: ApiModel, opts: MockOptions): string {
+  const pascal = pascalCase(named.name);
+  const sampled = bodyValue(named.schema, model, opts);
+  // Type references use the sdk's verbatim export name; only the factory NAME is PascalCased.
+  const typeName = named.name;
+  const spreads = isObjectValue(sampled);
+  // Spreading `Partial<Union>` (the override type of a union schema) distributes into
+  // `Partial<A> | Partial<B>`, which widens any discriminant property (e.g. `category`)
+  // and defeats narrowing — TS can no longer place the literal in a single union member.
+  // The sampled object is already a complete, correct member, so re-assert the type.
+  const rendered = renderMockValue(spreads ? spreadInto(sampled, 'overrides') : sampled, INDENT);
+  const body = !spreads
+    ? `overrides ?? ${rendered}`
+    : named.schema.kind === 'union'
+      ? `${rendered} as ${typeName}`
+      : rendered;
+  const overridesType = spreads ? `Partial<${typeName}>` : typeName;
+  return [
+    `export function create${pascal}(overrides?: ${overridesType}): ${typeName} {`,
+    `${INDENT}return ${body};`,
+    '}',
+  ].join('\n');
+}
+
+/**
+ * The interpolation gate for values that land in emitted CODE positions (binding
+ * names, `http.<method>` member access). The pipeline sanitizes operation names
+ * before any emitter runs; this re-checks at the construction site so a hostile
+ * name can never become code even if that invariant regresses.
+ */
+function codeIdent(value: string): string {
+  if (!isIdentifier(value)) {
+    throw new Error(`Unsafe identifier in mock emission: ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/** `export const <op>Handler = (override?: <OverrideType>) => http.<method>('<path>', () => <response>);`. */
+function handlerFor(op: OperationModel, model: ApiModel, opts: MockOptions): string {
+  const override = overrideParam(op, model, opts);
+  const params = override ?? '';
+  const call = `http.${codeIdent(op.method)}(${JSON.stringify(mswPath(op.path))}, () => ${responseExpression(op, model, opts)})`;
+  return `export const ${codeIdent(op.name)}Handler = (${params}) => ${call};`;
+}
+
+/**
+ * `export const <op>ErrorHandler = (status: <StatusUnion>, body?: <BodyType>) =>
+ *    http.<method>("<mswPath>", () => HttpResponse.json(body ?? <staticSample>, { status }));`
+ *
+ * Opt-in (not added to `handlers`): `server.use(getPetErrorHandler(404))` overrides the
+ * happy path with an error. `<StatusUnion>` is the declared error statuses as literals
+ * (plus `number` when a `default` error is present, so any status is allowed). The static
+ * fallback samples the FIRST error response's schema.
+ */
+function errorHandlerFor(op: OperationModel, model: ApiModel, opts: MockOptions): string {
+  const first = op.errorResponses[0];
+  const sampled = renderMockValue(bodyValue(first.schema, model, opts), '');
+  const resolver = `() => HttpResponse.json(body ?? ${sampled}, { status })`;
+  const call = `http.${codeIdent(op.method)}(${JSON.stringify(mswPath(op.path))}, ${resolver})`;
+  return `export const ${codeIdent(op.name)}ErrorHandler = (status: ${errorStatusType(op)}, body?: ${errorBodyType(op)}) => ${call};`;
+}
+
+/**
+ * A union of the op's declared numeric error statuses (as literals); `number` is used in place
+ * of a literal whenever a `default` error or a `4XX`/`5XX` range is present, so any status is
+ * accepted. De-duped, since a multi-media-type error contributes the same status more than once.
+ */
+function errorStatusType(op: OperationModel): string {
+  const codes = [
+    ...new Set(
+      op.errorResponses.filter((r) => typeof r.status === 'number').map((r) => r.status as number)
+    ),
+  ];
+  const members: string[] = codes.map(String);
+  // A `default` error (or a range wildcard) means any status is valid — widen with `number`.
+  if (op.errorResponses.some((r) => typeof r.status !== 'number')) {
+    members.push('number');
+  }
+  return members.join(' | ');
+}
+
+/**
+ * The `body?` type: the union of the error responses' body types — `ref` bodies map to their
+ * named type, anything else to `unknown` (matching how the success handler types its override
+ * loosely). De-duped by printed name.
+ */
+function errorBodyType(op: OperationModel): string {
+  const names = new Set<string>();
+  let hasUnknown = false;
+  for (const r of op.errorResponses) {
+    if (r.schema.kind === 'ref') names.add(r.schema.name);
+    else hasUnknown = true;
+  }
+  const members = [...names];
+  if (hasUnknown || members.length === 0) members.push('unknown');
+  return members.join(' | ');
+}
+
+/**
+ * The handler's `override?` parameter, present only when the response consumes it.
+ * A `ref` success body forwards `override` to `create<Schema>(override)`, so its type
+ * mirrors the factory's parameter (`Partial<Schema>`, or the full type when the factory
+ * replaces wholesale — see `factoryFor`). An inline object body spreads `override`, typed
+ * `Record<string, unknown>`. A body-less or non-object inline response has nothing to
+ * override, so the handler takes no parameter.
+ */
+function overrideParam(op: OperationModel, model: ApiModel, opts: MockOptions): string | undefined {
+  const success = op.successResponses[0];
+  if (!success || success.schema.kind === 'unknown') return undefined;
+  if (success.schema.kind === 'ref') {
+    const typeName = success.schema.name;
+    const type = isObjectValue(bodyValue(success.schema, model, opts))
+      ? `Partial<${typeName}>`
+      : typeName;
+    return `override?: ${type}`;
+  }
+  if (!isObjectValue(bodyValue(success.schema, model, opts))) return undefined;
+  return 'override?: Record<string, unknown>';
+}
+
+/**
+ * The handler's response. A primary success body becomes `HttpResponse.json(…)`:
+ * a `ref` body calls its named `create<Schema>(override)` factory; an inline body
+ * is sampled and printed in place with `...override` spread in. A success with no
+ * usable body (an `unknown` schema, or no success response at all) becomes a
+ * body-less `new HttpResponse(null, { status })`. The status is the success
+ * response's declared code, or 200 when it's `default`/absent.
+ */
+function responseExpression(op: OperationModel, model: ApiModel, opts: MockOptions): string {
+  const success = op.successResponses[0];
+  const status = statusCode(success?.status);
+  if (!success || success.schema.kind === 'unknown') {
+    return `new HttpResponse(null, { status: ${status} })`;
+  }
+  const data =
+    success.schema.kind === 'ref'
+      ? `create${pascalCase(success.schema.name)}(override)`
+      : renderMockValue(spreadInto(bodyValue(success.schema, model, opts), 'override'), '');
+  // `HttpResponse.json(x)` already defaults to 200, so only pass `{ status }` when it differs.
+  const args = status === 200 ? data : `${data}, { status: ${status} }`;
+  return `HttpResponse.json(${args})`;
+}
+
+/** Numeric status for a response, mapping `default`/absent to 200. */
+function statusCode(status: ResponseBodyModel['status'] | undefined): number {
+  return typeof status === 'number' ? status : 200;
+}
+
+/** `export const handlers = [<op>Handler(), …];`. */
+function handlersArray(operations: OperationModel[]): string {
+  const elements = operations.map((op) => `${codeIdent(op.name)}Handler()`).join(', ');
+  return `export const handlers = [${elements}];`;
+}
+
+/** `/pets/{petId}` → `*​/pets/:petId` — MSW path with a wildcard origin and `:param` segments. */
+function mswPath(path: string): string {
+  return `*${path.replace(/\{([^{}]+)\}/g, ':$1')}`;
+}
+
+/** Recursively lift a sampled JS value into the render tree. Containers render
+ *  multiline; a `SampleExpression` carries pre-built source (`new Date(...)`). */
+function literal(value: unknown): MockValue {
+  if (value instanceof SampleExpression) return expr(value.code);
+  if (Array.isArray(value)) return { kind: 'array', items: value.map(literal) };
+  if (isPlainObject(value)) {
+    return objectValue(
+      Object.entries(value).map(([key, entryValue]) => ({ key, value: literal(entryValue) }))
+    );
+  }
+  return expr(codeLiteral(value));
+}