@redocly/cli 2.47.0 → 2.48.0

package/lib/eject-assets/generators/typescript/type-guards.ts

@@ -0,0 +1,159 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "typescript" 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 typescript --update`.
+import type { DiscriminatorModel, NamedSchemaModel, SchemaModel } from '@redocly/client-generator';
+
+/**
+ * A discriminated union we can emit guards for, found while walking the schema
+ * tree. `label` is the guard's `value` parameter type — the union's name for a
+ * top-level union (`MenuItem`), the inline member union (`SuccessItem | ErrorItem`)
+ * for one nested inside another schema.
+ */
+type UnionSite = {
+  union: Extract<SchemaModel, { kind: 'union' }>;
+  label: string;
+};
+
+/** `is<Member>(value): value is <Member>` guards for every discriminated union (explicit or implicit). */
+export function renderTypeGuards(schemas: NamedSchemaModel[]): string {
+  const byName = new Map(schemas.map((s) => [s.name, s.schema] as const));
+  const blocks: string[] = [];
+  const emitted = new Set<string>();
+  for (const named of schemas) {
+    for (const site of collectUnionSites(named)) {
+      const discriminator =
+        site.union.discriminator ?? detectImplicitDiscriminator(site.union, byName);
+      if (!discriminator) continue;
+      const valuesByTarget = new Map<string, string[]>();
+      for (const entry of discriminator.mapping) {
+        if (!byName.has(entry.schemaName)) continue;
+        const existing = valuesByTarget.get(entry.schemaName);
+        if (existing) existing.push(entry.value);
+        else valuesByTarget.set(entry.schemaName, [entry.value]);
+      }
+      for (const [schemaName, values] of valuesByTarget) {
+        const guardName = `is${schemaName}`;
+        if (emitted.has(guardName)) continue;
+        emitted.add(guardName);
+        const access = `(value as Record<string, unknown>)[${JSON.stringify(discriminator.propertyName)}]`;
+        const check =
+          values.length === 1
+            ? `${access} === ${JSON.stringify(values[0])}`
+            : `([${values.map((value) => JSON.stringify(value)).join(', ')}] as readonly unknown[]).includes(${access})`;
+        blocks.push(
+          [
+            '/**',
+            ` * Narrow a \`${site.label}\` to \`${schemaName}\` via its \`${discriminator.propertyName}\` discriminant.`,
+            ' */',
+            `export function ${guardName}(value: ${site.label}): value is ${schemaName} {`,
+            `    return ${check};`,
+            '}',
+          ].join('\n')
+        );
+      }
+    }
+  }
+  return blocks.join('\n\n');
+}
+
+/**
+ * The discriminated-union sites reachable from a named schema, in a stable order:
+ * the schema itself (when it is a union), then any nested unions found by walking
+ * its tree. A top-level union keeps its name as the guard parameter; nested unions
+ * use their inline member union.
+ */
+function collectUnionSites(named: NamedSchemaModel): UnionSite[] {
+  const sites: UnionSite[] = [];
+  const root = named.schema;
+  if (root.kind === 'union') {
+    sites.push({ union: root, label: named.name });
+    for (const member of root.members) collectNestedSites(member, sites);
+  } else {
+    collectNestedSites(root, sites);
+  }
+  return sites;
+}
+
+/** Walk a schema subtree, recording each nested all-named-ref union as a site. */
+function collectNestedSites(schema: SchemaModel, sites: UnionSite[]): void {
+  switch (schema.kind) {
+    case 'union': {
+      const names = schema.members.map((m) => (m.kind === 'ref' ? m.name : undefined));
+      if (names.every((n): n is string => n !== undefined)) {
+        sites.push({ union: schema, label: names.join(' | ') });
+      }
+      for (const member of schema.members) collectNestedSites(member, sites);
+      break;
+    }
+    case 'array':
+      collectNestedSites(schema.items, sites);
+      break;
+    case 'record':
+      collectNestedSites(schema.value, sites);
+      break;
+    case 'object':
+      for (const prop of schema.properties) collectNestedSites(prop.schema, sites);
+      break;
+    case 'intersection':
+      for (const member of schema.members) collectNestedSites(member, sites);
+      break;
+    // scalar / literal / enum / ref / null / unknown / omit have no nested unions.
+  }
+}
+
+/**
+ * Detect an implicit discriminator: every member is a ref to a named schema,
+ * and they all pin one shared property to a distinct string literal. Returns
+ * `undefined` if no such property exists (so the union is left without guards).
+ */
+function detectImplicitDiscriminator(
+  union: Extract<SchemaModel, { kind: 'union' }>,
+  byName: Map<string, SchemaModel>
+): DiscriminatorModel | undefined {
+  const memberNames: string[] = [];
+  for (const member of union.members) {
+    if (member.kind !== 'ref') return undefined;
+    const target = byName.get(member.name);
+    if (!target) return undefined;
+    memberNames.push(member.name);
+  }
+  if (memberNames.length < 2) return undefined;
+
+  const literalsPerMember = memberNames.map((name) => literalPropsOf(byName.get(name)!));
+
+  for (const propName of Object.keys(literalsPerMember[0])) {
+    if (!literalsPerMember.every((props) => propName in props)) continue;
+    const values = literalsPerMember.map((props) => props[propName]);
+    if (!values.every((v): v is string => typeof v === 'string')) continue;
+    if (new Set(values).size !== values.length) continue;
+    return {
+      propertyName: propName,
+      mapping: memberNames.map((name, i) => ({
+        value: values[i] as string,
+        schemaName: name,
+      })),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Collect a schema's literal-valued properties (name → const value), descending
+ * through `intersection` members (the shape `allOf` produces). Only inline
+ * object/intersection members are inspected; nested refs are not resolved.
+ */
+function literalPropsOf(schema: SchemaModel): Record<string, string | number | boolean> {
+  const out: Record<string, string | number | boolean> = {};
+  const collect = (s: SchemaModel): void => {
+    if (s.kind === 'object') {
+      for (const prop of s.properties) {
+        if (prop.schema.kind === 'literal') out[prop.name] = prop.schema.value;
+      }
+    } else if (s.kind === 'intersection') {
+      for (const member of s.members) collect(member);
+    }
+  };
+  collect(schema);
+  return out;
+}

package/lib/eject-assets/generators/typescript/types.ts

@@ -0,0 +1,172 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "typescript" 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 typescript --update`.
+// TypeScript TYPES as source text: pure string logic over the IR, no
+// `typescript` import. Formatting contract: 4-space indent, double-quoted
+// literals, compound members parenthesized inside unions/intersections/arrays.
+
+import {
+  type DateType,
+  type NamedSchemaModel,
+  type PropertyModel,
+  type ScalarKind,
+  type SchemaMetadata,
+  type SchemaModel,
+} from '@redocly/client-generator';
+import {
+  escapeJsDoc,
+  isIdentifier,
+  jsdocText,
+  safeIdent,
+} from '@redocly/client-generator/printers/typescript';
+
+const INDENT = '    ';
+
+/** A JSDoc block (description + metadata tags) as indented lines, or [] when empty. */
+export function tsJsdoc(
+  text: string | undefined,
+  metadata: SchemaMetadata | undefined,
+  indent: string
+): string[] {
+  const body = jsdocText(text, metadata);
+  if (body === undefined) return [];
+  return [
+    `${indent}/**`,
+    ...escapeJsDoc(body)
+      .split('\n')
+      .map((line) => `${indent} * ${line}`.replace(/ +$/, '')),
+    `${indent} */`,
+  ];
+}
+
+function literalType(value: string | number | boolean): string {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+
+function scalarType(
+  kind: ScalarKind,
+  metadata: SchemaMetadata | undefined,
+  dateType: DateType
+): string {
+  switch (kind) {
+    case 'string':
+      if (metadata?.format === 'binary') return 'Blob';
+      if (
+        dateType === 'Date' &&
+        (metadata?.format === 'date-time' || metadata?.format === 'date')
+      ) {
+        return 'Date';
+      }
+      return 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+  }
+}
+
+/** True when the rendered type needs parentheses as an array element / intersection member. */
+function isCompound(schema: SchemaModel): boolean {
+  return (
+    schema.kind === 'union' ||
+    schema.kind === 'intersection' ||
+    (schema.kind === 'enum' && schema.values.length > 1)
+  );
+}
+
+/** The TypeScript type for an IR schema, rendered at `indent` (the containing line's indent). */
+export function tsType(schema: SchemaModel, dateType: DateType = 'string', indent = ''): string {
+  switch (schema.kind) {
+    case 'scalar':
+      return scalarType(schema.scalar, schema.metadata, dateType);
+    case 'ref':
+      return schema.name;
+    case 'literal':
+      return literalType(schema.value);
+    case 'enum':
+      return schema.values.map(literalType).join(' | ');
+    case 'null':
+      return 'null';
+    case 'unknown':
+      return 'unknown';
+    case 'array': {
+      const element = tsType(schema.items, dateType, indent);
+      return isCompound(schema.items) ? `(${element})[]` : `${element}[]`;
+    }
+    case 'record':
+      return `Record<string, ${tsType(schema.value, dateType, indent)}>`;
+    case 'object': {
+      if (schema.properties.length === 0) return '{}';
+      const inner = indent + INDENT;
+      const lines = schema.properties.flatMap((property) =>
+        propertyLines(property, dateType, inner)
+      );
+      return `{\n${lines.join('\n')}\n${indent}}`;
+    }
+    case 'union':
+      return schema.members
+        .map((member) => {
+          const rendered = tsType(member, dateType, indent);
+          return isCompound(member) ? `(${rendered})` : rendered;
+        })
+        .join(' | ');
+    case 'intersection':
+      return schema.members
+        .map((member) => {
+          const rendered = tsType(member, dateType, indent);
+          return isCompound(member) ? `(${rendered})` : rendered;
+        })
+        .join(' & ');
+    case 'omit':
+      return `Omit<${schema.base}, ${schema.keys.map((key) => JSON.stringify(key)).join(' | ')}>`;
+  }
+}
+
+function propertyLines(property: PropertyModel, dateType: DateType, indent: string): string[] {
+  const name = safeIdent(property.name);
+  const readonly = property.readOnly ? 'readonly ' : '';
+  const optional = property.required ? '' : '?';
+  const type = tsType(property.schema, dateType, indent);
+  return [
+    ...tsJsdoc(property.description, property.schema.metadata, indent),
+    `${indent}${readonly}${name}${optional}: ${type};`,
+  ];
+}
+
+/**
+ * For a named **string** enum whose values are all valid identifiers, the runtime
+ * companion `export const X = { a: "a", … } as const;` (cohabiting with the type).
+ */
+function enumConstLines(named: NamedSchemaModel): string[] {
+  const schema = named.schema;
+  if (schema.kind !== 'enum' || schema.scalar !== 'string') return [];
+  if (!schema.values.every((value) => typeof value === 'string' && isIdentifier(value))) return [];
+  return [
+    `export const ${named.name} = {`,
+    ...schema.values.map(
+      (value, index) =>
+        `${INDENT}${value}: ${JSON.stringify(value)}${index === schema.values.length - 1 ? '' : ','}`
+    ),
+    '} as const;',
+  ];
+}
+
+/** The model type aliases (with JSDoc and enum const companions), blank-line separated. */
+export function renderTypeAliases(
+  schemas: NamedSchemaModel[],
+  dateType: DateType = 'string'
+): string {
+  const blocks: string[] = [];
+  for (const named of schemas) {
+    const lines = [
+      ...tsJsdoc(named.schema.description ?? named.description, named.schema.metadata, ''),
+      `export type ${named.name} = ${tsType(named.schema, dateType)};`,
+    ];
+    blocks.push(lines.join('\n'));
+    const constCompanion = enumConstLines(named);
+    if (constCompanion.length > 0) blocks.push(constCompanion.join('\n'));
+  }
+  return blocks.join('\n\n');
+}

package/lib/eject-assets/generators/zod/index.ts

@@ -0,0 +1,32 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "zod" 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 zod --update`.
+import type { Generator } from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { renderZodModule } from './schemas.ts';
+
+/**
+ * The zod generator: a standalone `<stem>.zod.ts` module of Zod schemas (one
+ * `export const <Name>Schema` per IR named schema), plus runtime validation for
+ * the client — the `operationSchemas` request/response map and the `zodValidation`
+ * middleware (`use(zodValidation())`). The sdk client stays dependency-free —
+ * zod is the consumer's peer, and the module imports nothing from the client.
+ *
+ * Output-mode-agnostic: emits a single module beside the client regardless of
+ * how the sdk partitions its files. Emits nothing when the model has neither
+ * named schemas nor JSON operation bodies.
+ */
+export const zodGenerator: Generator = ({ model, output, banner }) => {
+  const content = renderZodModule(model);
+  if (content === '') return [];
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  return [{ path: join(output.dir, `${output.stem}.zod.ts`), content: `${header}\n\n${content}` }];
+};
+
+export default {
+  name: 'zod',
+  run: zodGenerator,
+  requiresGenerator: '^0.4.0',
+};