@redocly/client-generator 0.3.7 → 0.4.0

package/eject-assets/generators/python/pagination.ts

@@ -0,0 +1,128 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "python" 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 python --update`.
+// The `pagination` stage: `<ident>_pages` / `<ident>_items` iterator methods for
+// paginated operations, sync and async.
+
+import {
+  type DateType,
+  jsonSuccessSchema,
+  type OperationModel,
+  uniqueIdentifiers,
+} from '@redocly/client-generator';
+import type { PythonPrinter } from '@redocly/client-generator/printers/python';
+
+import { METHOD_ARG_SLOTS, naming, PY } from './naming.ts';
+import { pythonType } from './types.ts';
+
+/** `<ident>_pages` / `<ident>_items` iterator methods for a paginated operation. */
+export function writePaginationWrappers(
+  printer: PythonPrinter,
+  op: OperationModel,
+  ident: string,
+  isAsync: boolean,
+  itemType: string,
+  dateType: DateType
+): void {
+  const success = jsonSuccessSchema(op);
+  const pageType = success === undefined ? 'Any' : pythonType(success, dateType);
+  // The iterators take the same arguments as the operation itself, computed the same way,
+  // so a name the method moved aside (`id_2`) is the same name here — copying a call from
+  // one to the other has to keep working. Path values are substituted, not dropped.
+  const argNames = uniqueIdentifiers(
+    [...op.pathParams, ...op.queryParams].map((param) => param.name),
+    { style: 'snake', reserved: PY, taken: METHOD_ARG_SLOTS }
+  );
+  const pathArgs = op.pathParams.map((param, index) => ({ param, python: argNames[index] }));
+  const queryArgs = op.queryParams.map((param, index) => ({
+    param,
+    python: argNames[op.pathParams.length + index],
+  }));
+  const positional = pathArgs.map(
+    ({ param, python }) => `${python}: ${pythonType(param.schema, dateType)}`
+  );
+  const kwargs = [
+    ...queryArgs.map(({ param, python }) => {
+      const annotation = pythonType(param.schema, dateType);
+      const optional = annotation.startsWith('Optional[') ? annotation : `Optional[${annotation}]`;
+      return `${python}: ${optional} = None`;
+    }),
+    'headers: Optional[Dict[str, str]] = None',
+    'timeout: Optional[float] = None',
+    'retry: Optional[Dict[str, Any]] = None',
+  ];
+  const signature = ['self', ...positional, '*', ...kwargs].join(', ');
+  const iterType = isAsync ? 'AsyncIterator' : 'Iterator';
+  const pagesFn = isAsync ? 'aiter_pages' : 'iter_pages';
+  const itemsFn = isAsync ? 'aiter_items' : 'iter_items';
+
+  const writeCallClosure = () => {
+    printer.line('base: Dict[str, Any] = {}');
+    for (const { param, python } of queryArgs) {
+      printer.block(`if ${python} is not None:`, () => {
+        printer.line(`base[${naming.string(param.name)}] = encode(${python})`);
+      });
+    }
+    const prefix = isAsync ? 'async def' : 'def';
+    const awaitKw = isAsync ? 'await ' : '';
+    printer.block(`${prefix} _page(page_params: Dict[str, Any]) -> Tuple[Any, Any]:`, () => {
+      printer.line('auth_headers, auth_query = resolve_auth(op.get("security") or [], self._auth)');
+      const pathDict = pathArgs
+        .map(({ param, python }) => `${naming.string(param.name)}: ${python}`)
+        .join(', ');
+      printer.line(`url = build_url(self._server_url, op["path"], {${pathDict}})`);
+      printer.line(
+        `response = ${awaitKw}${isAsync ? 'send_async' : 'send'}(self._http, self._config, op, url, method=op["method"], ` +
+          'headers={**auth_headers, **(headers or {})}, params={**page_params, **auth_query}, ' +
+          'timeout=timeout, retry=retry)'
+      );
+      printer.block('if not response.is_success:', () => {
+        printer.line(
+          'raise ApiError(url, response.status_code, response.reason_phrase, _safe_json(response))'
+        );
+      });
+      printer.line('return _safe_json(response), response');
+    });
+  };
+
+  // pages: raw page JSON decoded into the page model per page.
+  if (isAsync) {
+    printer.block(`async def ${ident}_pages(${signature}) -> ${iterType}[${pageType}]:`, () => {
+      printer.line(`op = _OPERATIONS["${ident}"]`);
+      writeCallClosure();
+      printer.block(`async for page in ${pagesFn}(_page, op["pagination"], base):`, () => {
+        printer.line(pageType === 'Any' ? 'yield page' : `yield decode(${pageType}, page)`);
+      });
+    });
+    printer.blank();
+    printer.block(`async def ${ident}_items(${signature}) -> ${iterType}[${itemType}]:`, () => {
+      printer.line(`op = _OPERATIONS["${ident}"]`);
+      writeCallClosure();
+      printer.block(`async for item in ${itemsFn}(_page, op["pagination"], base):`, () => {
+        printer.line(itemType === 'Any' ? 'yield item' : `yield decode(${itemType}, item)`);
+      });
+    });
+  } else {
+    printer.block(`def ${ident}_pages(${signature}) -> ${iterType}[${pageType}]:`, () => {
+      printer.line(`op = _OPERATIONS["${ident}"]`);
+      writeCallClosure();
+      printer.line(
+        pageType === 'Any'
+          ? `return ${pagesFn}(_page, op["pagination"], base)`
+          : `return (decode(${pageType}, page) for page in ${pagesFn}(_page, op["pagination"], base))`
+      );
+    });
+    printer.blank();
+    printer.block(`def ${ident}_items(${signature}) -> ${iterType}[${itemType}]:`, () => {
+      printer.line(`op = _OPERATIONS["${ident}"]`);
+      writeCallClosure();
+      printer.line(
+        itemType === 'Any'
+          ? `return ${itemsFn}(_page, op["pagination"], base)`
+          : `return (decode(${itemType}, item) for item in ${itemsFn}(_page, op["pagination"], base))`
+      );
+    });
+  }
+  printer.blank();
+}

package/eject-assets/generators/python/types.ts

@@ -0,0 +1,54 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "python" 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 python --update`.
+// The `types` stage: schema → Python type annotation.
+
+import {
+  type DateType,
+  isNullable,
+  type SchemaModel,
+  unwrapNullable,
+} from '@redocly/client-generator';
+
+import { className, naming } from './naming.ts';
+
+/** The Python type annotation for a schema (anonymous complex shapes collapse to Any-ish). */
+export function pythonType(schema: SchemaModel, dateType: DateType = 'string'): string {
+  if (isNullable(schema)) {
+    return `Optional[${pythonType(unwrapNullable(schema), dateType)}]`;
+  }
+  switch (schema.kind) {
+    case 'scalar':
+      // `dateType: Date` annotates date/date-time as stdlib objects; `_decode.py`
+      // converts them from and to ISO strings on the wire.
+      if (dateType === 'Date' && schema.scalar === 'string') {
+        if (schema.metadata?.format === 'date-time') return 'datetime';
+        if (schema.metadata?.format === 'date') return 'date';
+      }
+      return { string: 'str', integer: 'int', number: 'float', boolean: 'bool' }[schema.scalar];
+    case 'array':
+      return `List[${pythonType(schema.items, dateType)}]`;
+    case 'record':
+      return `Dict[str, ${pythonType(schema.value, dateType)}]`;
+    case 'ref':
+      return className(schema.name);
+    case 'literal':
+      return `Literal[${naming.literal(schema.value)}]`;
+    case 'enum':
+      // Anonymous (inline) enums keep the wire scalar; only NAMED enums get classes.
+      return { string: 'str', integer: 'int', number: 'float', boolean: 'bool' }[schema.scalar];
+    case 'union':
+      return `Union[${schema.members.map((member) => pythonType(member, dateType)).join(', ')}]`;
+    case 'null':
+      return 'None';
+    case 'omit':
+      // Python has no Omit; the base class is the honest annotation (readOnly
+      // fields are server-managed and simply absent on requests).
+      return className(schema.base);
+    case 'object':
+    case 'intersection':
+    case 'unknown':
+      return 'Any';
+  }
+}

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

@@ -0,0 +1,37 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "swr" 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 swr --update`.
+import type { Generator } from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { renderSwrModule } from './render.ts';
+
+/**
+ * The swr generator: a standalone `<stem>.swr.ts` module of SWR hooks wrapping the
+ * sdk operation functions — `<op>Key` + `use<Op>` (`useSWR`) per query (GET/HEAD),
+ * `use<Op>` (`useSWRMutation`) per mutation. It imports the operation functions +
+ * their `<Op>Variables` types from the sdk entry (`./<stem>.js`), so it requires the
+ * `typescript` generator and targets its throw-mode operation functions. `swr`/`swr/mutation`
+ * are the consumer's peer; the sdk client stays dependency-free.
+ *
+ * Output-mode-agnostic: `./<stem>.js` resolves to the single-file client or the
+ * multi-file barrel at the output anchor either way. Emits nothing when there are
+ * no operations.
+ */
+export const swrGenerator: Generator = ({ model, output, banner, emit }) => {
+  const content = renderSwrModule(model, {
+    sdkModule: `./${output.stem}.${emit.importExt ?? 'js'}`,
+  });
+  if (content === '') return [];
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  return [{ path: join(output.dir, `${output.stem}.swr.ts`), content: `${header}\n\n${content}` }];
+};
+
+export default {
+  name: 'swr',
+  run: swrGenerator,
+  requires: ["typescript"],
+  errorModes: ["throw"],
+  requiresGenerator: '^0.4.0',
+};

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

@@ -0,0 +1,78 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "swr" 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 swr --update`.
+// Emits an idiomatic SWR module wrapping the sdk operation functions. Per query
+// operation (GET/HEAD) a `<op>Key(vars)` tuple factory + a `use<Op>(vars, init?)`
+// hook returning `useSWR(key, fetcher)`; per mutation (everything else) a
+// `use<Op>()` hook returning `useSWRMutation(key, (key, { arg }) => <op>(arg))`.
+// The fetcher forwards args per the configured args style (grouped `<op>(vars, init)`
+// or flat `<op>(vars.petId, …, init)`) via the shared `operationSignature`, so the
+// call type-checks against the generated sdk.
+// `swr`/`swr/mutation` are the consumer's peer; the sdk stays dependency-free.
+// Source-text templates throughout.
+
+import type { ApiModel, OperationModel } from '@redocly/client-generator';
+import {
+  hasInputs,
+  isQuery,
+  sdkCallText,
+  sdkNamedImportText,
+  variablesName,
+  wrappableOperations,
+} from '@redocly/client-generator/contracts/typescript';
+import { pascalCase } from '@redocly/client-generator/printers/typescript';
+
+export type SwrOptions = {
+  /** Import specifier for the sdk entry the operation functions/types live in. */
+  sdkModule: string;
+  /** How the sdk function takes its inputs — must match the generated client. */
+};
+
+/** Render the full SWR module source. `''` when there are no wrappable operations. */
+export function renderSwrModule(model: ApiModel, opts: SwrOptions): string {
+  const ops = wrappableOperations(model, 'swr');
+  if (ops.length === 0) return '';
+  const hasQuery = ops.some(isQuery);
+  const hasMutation = ops.some((op) => !isQuery(op));
+  const blocks = [
+    ...(hasQuery ? ['import useSWR from "swr";'] : []),
+    ...(hasMutation ? ['import useSWRMutation from "swr/mutation";'] : []),
+    sdkNamedImportText(ops, opts.sdkModule, hasQuery),
+    ...ops.flatMap((op) => (isQuery(op) ? queryBlocks(op) : [mutationBlock(op)])),
+  ];
+  return blocks.join('\n\n');
+}
+
+/** An exported `function use<Op>(<params>) { return <expr>; }` declaration. */
+function hookBlock(op: OperationModel, params: string, expr: string): string {
+  return `export function use${pascalCase(op.name)}(${params}) {\n    return ${expr};\n}`;
+}
+
+/** A query op's `<op>Key` factory + `use<Op>` hook calling `useSWR`. */
+function queryBlocks(op: OperationModel): string[] {
+  const inputs = hasInputs(op);
+  const keyParams = inputs ? `vars: ${variablesName(op)}` : '';
+  const keyElements = inputs
+    ? `[${JSON.stringify(op.name)}, vars]`
+    : `[${JSON.stringify(op.name)}]`;
+  const key = `export const ${op.name}Key = (${keyParams}) => ${keyElements} as const;`;
+  const keyCall = `${op.name}Key(${inputs ? 'vars' : ''})`;
+  const useSwr = `useSWR(${keyCall}, () => ${sdkCallText(op, 'vars', true)})`;
+  // The throw-only `envelope` option is excluded — cached data must stay the plain body.
+  const params = inputs
+    ? `vars: ${variablesName(op)}, init?: Omit<RequestOptions, "envelope">`
+    : 'init?: Omit<RequestOptions, "envelope">';
+  return [key, hookBlock(op, params, useSwr)];
+}
+
+/** A mutation op's `use<Op>` hook calling `useSWRMutation`. */
+function mutationBlock(op: OperationModel): string {
+  // `(_key: string, { arg }: { arg: <Op>Variables }) => <op>(…arg)` when the op has
+  // inputs; a no-arg `() => <op>()` when it has none (`arg` would be unused).
+  const trigger = hasInputs(op)
+    ? `(_key: string, { arg }: {\n        arg: ${variablesName(op)};\n    }) => ${sdkCallText(op, 'arg', false)}`
+    : `() => ${sdkCallText(op, 'arg', false)}`;
+  const useSwrMutation = `useSWRMutation(${JSON.stringify(op.name)}, ${trigger})`;
+  return hookBlock(op, '', useSwrMutation);
+}

package/eject-assets/generators/tanstack-query/index.ts

@@ -0,0 +1,48 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "tanstack-query" 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 tanstack-query --update`.
+import type { Generator } from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { renderTanstackModule } from './render.ts';
+
+/**
+ * The tanstack-query generator: a standalone `<stem>.tanstack.ts` module of
+ * TanStack Query v5 factories over the generated client — `<op>QueryKey`/`<op>Options`
+ * per query (GET/HEAD), `<op>InfiniteOptions` per paginated query, `<op>Mutation` per
+ * mutation, all built by `createQueryFactories(c)` (bindable to any client instance)
+ * with the module-level exports bound to the sdk's default `client`. It imports the
+ * `client` instance + the `<Op>Variables` types from the sdk entry (`./<stem>.js`), so
+ * it requires the `typescript` generator and its throw-mode client. The option helpers are
+ * imported from `@tanstack/<framework>-query` (the consumer's peer); the registry binds
+ * one framework per generator name, and the emitted body is byte-identical across them.
+ *
+ * Output-mode-agnostic: `./<stem>.js` resolves to the single-file client or the
+ * multi-file barrel at the output anchor either way. Emits nothing when there are
+ * no operations.
+ */
+export function tanstackQueryGenerator(framework: 'react' | 'vue' | 'svelte' | 'solid'): Generator {
+  return ({ model, output, banner, emit, pagination }) => {
+    const content = renderTanstackModule(model, {
+      argsStyle: emit.argsStyle ?? 'grouped',
+      sdkModule: `./${output.stem}.${emit.importExt ?? 'js'}`,
+      framework,
+      pagination,
+      queryKeyPrefix: emit.queryKeyPrefix,
+    });
+    if (content === '') return [];
+    const header = banner.map((line) => `// ${line}`).join('\n');
+    return [
+      { path: join(output.dir, `${output.stem}.tanstack.ts`), content: `${header}\n\n${content}` },
+    ];
+  };
+}
+
+export default {
+  name: 'tanstack-query',
+  run: tanstackQueryGenerator('react'),
+  requires: ["typescript"],
+  errorModes: ["throw"],
+  requiresGenerator: '^0.4.0',
+};