typed-openapi 1.5.0 → 2.0.0

package/dist/types-DsI2d-HE.d.ts

@@ -0,0 +1,244 @@
+import * as openapi3_ts_oas31 from 'openapi3-ts/oas31';
+import { OpenAPIObject, ReferenceObject, OperationObject, SchemaObject } from 'openapi3-ts/oas31';
+import { SchemaObject as SchemaObject$1 } from 'openapi3-ts/oas30';
+
+declare class Box<T extends AnyBoxDef = AnyBoxDef> {
+    definition: T;
+    type: T["type"];
+    value: T["value"];
+    params: T["params"];
+    schema: T["schema"];
+    ctx: T["ctx"];
+    constructor(definition: T);
+    toJSON(): {
+        type: T["type"];
+        value: T["value"];
+    };
+    toString(): string;
+    recompute(callback: OpenapiSchemaConvertContext["onBox"]): Box<AnyBoxDef>;
+    static fromJSON(json: string): Box<any>;
+    static isBox(box: unknown): box is Box<AnyBoxDef>;
+    static isUnion(box: Box<AnyBoxDef>): box is Box<BoxUnion>;
+    static isIntersection(box: Box<AnyBoxDef>): box is Box<BoxIntersection>;
+    static isArray(box: Box<AnyBoxDef>): box is Box<BoxArray>;
+    static isOptional(box: Box<AnyBoxDef>): box is Box<BoxOptional>;
+    static isReference(box: Box<AnyBoxDef>): box is Box<BoxRef>;
+    static isKeyword(box: Box<AnyBoxDef>): box is Box<BoxKeyword>;
+    static isObject(box: Box<AnyBoxDef>): box is Box<BoxObject>;
+    static isLiteral(box: Box<AnyBoxDef>): box is Box<BoxLiteral>;
+}
+
+type RefInfo = {
+    /**
+     * The (potentially autocorrected) ref
+     * @example "#/components/schemas/MySchema"
+     */
+    ref: string;
+    /**
+     * The name of the ref
+     * @example "MySchema"
+     * */
+    name: string;
+    normalized: string;
+    kind: "schemas" | "responses" | "parameters" | "requestBodies" | "headers";
+};
+declare const createRefResolver: (doc: OpenAPIObject, factory: GenericFactory, nameTransform?: NameTransformOptions) => {
+    get: <T = LibSchemaObject>(ref: string) => NonNullable<T>;
+    unwrap: <T extends ReferenceObject | {}>(component: T) => Exclude<T, ReferenceObject>;
+    getInfosByRef: (ref: string) => RefInfo;
+    infos: Map<string, RefInfo>;
+    /**
+     * Get the schemas in the order they should be generated, depending on their dependencies
+     * so that a schema is generated before the ones that depend on it
+     */
+    getOrderedSchemas: () => [schema: Box<AnyBoxDef>, infos: RefInfo][];
+    directDependencies: Map<string, Set<string>>;
+    transitiveDependencies: Map<string, Set<string>>;
+};
+interface RefResolver extends ReturnType<typeof createRefResolver> {
+}
+
+declare const mapOpenApiEndpoints: (doc: OpenAPIObject, options?: {
+    nameTransform?: NameTransformOptions;
+}) => {
+    doc: OpenAPIObject;
+    refs: {
+        get: <T = LibSchemaObject>(ref: string) => NonNullable<T>;
+        unwrap: <T extends openapi3_ts_oas31.ReferenceObject | {}>(component: T) => Exclude<T, openapi3_ts_oas31.ReferenceObject>;
+        getInfosByRef: (ref: string) => RefInfo;
+        infos: Map<string, RefInfo>;
+        getOrderedSchemas: () => [schema: Box<AnyBoxDef>, infos: RefInfo][];
+        directDependencies: Map<string, Set<string>>;
+        transitiveDependencies: Map<string, Set<string>>;
+    };
+    endpointList: Endpoint<DefaultEndpoint>[];
+    factory: {
+        union: (types: StringOrBox[]) => string;
+        intersection: (types: StringOrBox[]) => string;
+        array: (type: StringOrBox) => string;
+        optional: (type: StringOrBox) => string;
+        reference: (name: string, typeArgs: StringOrBox[] | undefined) => string;
+        literal: (value: StringOrBox) => string;
+        string: () => "string";
+        number: () => "number";
+        boolean: () => "boolean";
+        unknown: () => "unknown";
+        any: () => "any";
+        never: () => "never";
+        object: (props: Record<string, StringOrBox>) => string;
+    };
+};
+type MutationMethod = "post" | "put" | "patch" | "delete";
+type Method = "get" | "head" | "options" | MutationMethod;
+type EndpointParameters = {
+    body?: Box<BoxRef>;
+    query?: Box<BoxRef> | Record<string, AnyBox>;
+    header?: Box<BoxRef> | Record<string, AnyBox>;
+    path?: Box<BoxRef> | Record<string, AnyBox>;
+};
+type RequestFormat = "json" | "form-data" | "form-url" | "binary" | "text";
+type DefaultEndpoint = {
+    parameters?: EndpointParameters | undefined;
+    response: AnyBox;
+    responses?: Record<string, AnyBox>;
+    responseHeaders?: Record<string, AnyBox>;
+};
+type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
+    operation: OperationObject;
+    method: Method;
+    path: string;
+    parameters?: TConfig["parameters"];
+    requestFormat: RequestFormat;
+    meta: {
+        alias: string;
+        hasParameters: boolean;
+        areParametersRequired: boolean;
+    };
+    response: TConfig["response"];
+    responses?: TConfig["responses"];
+    responseHeaders?: TConfig["responseHeaders"];
+};
+
+type LibSchemaObject = SchemaObject & SchemaObject$1;
+type BoxDefinition = {
+    type: string;
+    params: unknown;
+    value: string;
+};
+type BoxParams = string | BoxDefinition;
+type WithSchema = {
+    schema: LibSchemaObject | ReferenceObject | undefined;
+    ctx: OpenapiSchemaConvertContext;
+};
+type BoxUnion = WithSchema & {
+    type: "union";
+    params: {
+        types: Array<BoxParams>;
+    };
+    value: string;
+};
+type BoxIntersection = WithSchema & {
+    type: "intersection";
+    params: {
+        types: Array<BoxParams>;
+    };
+    value: string;
+};
+type BoxArray = WithSchema & {
+    type: "array";
+    params: {
+        type: BoxParams;
+    };
+    value: string;
+};
+type BoxOptional = WithSchema & {
+    type: "optional";
+    params: {
+        type: BoxParams;
+    };
+    value: string;
+};
+type BoxRef = WithSchema & {
+    type: "ref";
+    params: {
+        name: string;
+        generics?: BoxParams[] | undefined;
+    };
+    value: string;
+};
+type BoxLiteral = WithSchema & {
+    type: "literal";
+    params: {};
+    value: string;
+};
+type BoxKeyword = WithSchema & {
+    type: "keyword";
+    params: {
+        name: string;
+    };
+    value: string;
+};
+type BoxObject = WithSchema & {
+    type: "object";
+    params: {
+        props: Record<string, BoxParams>;
+    };
+    value: string;
+};
+type AnyBoxDef = BoxUnion | BoxIntersection | BoxArray | BoxOptional | BoxRef | BoxLiteral | BoxKeyword | BoxObject;
+type AnyBox = Box<AnyBoxDef>;
+type OpenapiSchemaConvertArgs = {
+    schema: SchemaObject | ReferenceObject;
+    ctx: OpenapiSchemaConvertContext;
+    meta?: {} | undefined;
+};
+type FactoryCreator = (schema: SchemaObject | ReferenceObject, ctx: OpenapiSchemaConvertContext) => GenericFactory;
+type NameTransformOptions = {
+    transformSchemaName?: (name: string) => string;
+    transformEndpointName?: (endpoint: {
+        alias: string;
+        operation: OperationObject;
+        method: Method;
+        path: string;
+    }) => string;
+};
+type OpenapiSchemaConvertContext = {
+    factory: FactoryCreator | GenericFactory;
+    refs: RefResolver;
+    onBox?: (box: Box<AnyBoxDef>) => Box<AnyBoxDef>;
+    nameTransform?: NameTransformOptions;
+};
+type StringOrBox = string | Box<AnyBoxDef>;
+type BoxFactory = {
+    union: (types: Array<StringOrBox>) => Box<BoxUnion>;
+    intersection: (types: Array<StringOrBox>) => Box<BoxIntersection>;
+    array: (type: StringOrBox) => Box<BoxArray>;
+    object: (props: Record<string, StringOrBox>) => Box<BoxObject>;
+    optional: (type: StringOrBox) => Box<BoxOptional>;
+    reference: (name: string, generics?: Array<StringOrBox> | undefined) => Box<BoxRef>;
+    literal: (value: StringOrBox) => Box<BoxLiteral>;
+    string: () => Box<BoxKeyword>;
+    number: () => Box<BoxKeyword>;
+    boolean: () => Box<BoxKeyword>;
+    unknown: () => Box<BoxKeyword>;
+    any: () => Box<BoxKeyword>;
+    never: () => Box<BoxKeyword>;
+};
+type GenericFactory = {
+    callback?: OpenapiSchemaConvertContext["onBox"];
+    union: (types: Array<StringOrBox>) => string;
+    intersection: (types: Array<StringOrBox>) => string;
+    array: (type: StringOrBox) => string;
+    object: (props: Record<string, StringOrBox>) => string;
+    optional: (type: StringOrBox) => string;
+    reference: (name: string, generics?: Array<StringOrBox> | undefined) => string;
+    literal: (value: StringOrBox) => string;
+    string: () => string;
+    number: () => string;
+    boolean: () => string;
+    unknown: () => string;
+    any: () => string;
+    never: () => string;
+};
+
+export { type AnyBoxDef as A, type BoxFactory as B, type EndpointParameters as E, type FactoryCreator as F, type GenericFactory as G, type LibSchemaObject as L, type Method as M, type NameTransformOptions as N, type OpenapiSchemaConvertContext as O, type RefInfo as R, type StringOrBox as S, type WithSchema as W, type OpenapiSchemaConvertArgs as a, Box as b, type Endpoint as c, createRefResolver as d, type RefResolver as e, type BoxDefinition as f, type BoxParams as g, type BoxUnion as h, type BoxIntersection as i, type BoxArray as j, type BoxOptional as k, type BoxRef as l, mapOpenApiEndpoints as m, type BoxLiteral as n, type BoxKeyword as o, type BoxObject as p, type AnyBox as q };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "typed-openapi",
   "type": "module",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
-    "./node": "./dist/node.export.js"
+    "./node": "./dist/node.export.js",
+    "./pretty": "./dist/pretty.export.js"
   },
   "bin": {
     "typed-openapi": "bin.js"
@@ -29,8 +30,10 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.4",
+    "@tanstack/react-query": "5.85.0",
     "@types/node": "^22.15.17",
     "@types/prettier": "3.0.0",
+    "msw": "2.10.5",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
@@ -63,6 +66,9 @@
     "dev": "tsup --watch",
     "build": "tsup",
     "test": "vitest",
+    "generate:runtime": "node bin.js ./tests/samples/petstore.yaml --output ./tmp/generated-client.ts --tanstack generated-tanstack.ts",
+    "test:runtime:run": "vitest run tests/integration-runtime-msw.test.ts",
+    "test:runtime": "pnpm run generate:runtime && pnpm run test:runtime:run",
     "fmt": "prettier --write src",
     "typecheck": "tsc -b ./tsconfig.build.json"
   }

package/src/cli.ts

@@ -1,5 +1,4 @@
 import { cac } from "cac";
-
 import { readFileSync } from "fs";
 import { generateClientFiles } from "./generate-client-files.ts";
 import { allowedRuntimes } from "./generator.ts";
@@ -11,16 +10,22 @@ cli
   .command("<input>", "Generate")
   .option("-o, --output <path>", "Output path for the api client ts file (defaults to `<input>.<runtime>.ts`)")
   .option(
-    "-r, --runtime <name>",
+    "-r, --runtime <n>",
     `Runtime to use for validation; defaults to \`none\`; available: ${allowedRuntimes.toString()}`,
     { default: "none" },
   )
   .option("--schemas-only", "Only generate schemas, skipping client generation (defaults to false)", { default: false })
+  .option("--include-client", "Include API client types and implementation (defaults to true)", { default: true })
+  .option(
+    "--success-status-codes <codes>",
+    "Comma-separated list of success status codes (defaults to 2xx and 3xx ranges)",
+  )
+  .option("--error-status-codes <codes>", "Comma-separated list of error status codes (defaults to 4xx and 5xx ranges)")
   .option(
     "--tanstack [name]",
     "Generate tanstack client, defaults to false, can optionally specify a name for the generated file",
   )
-  .action(async (input, _options) => {
+  .action(async (input: string, _options: any) => {
     return generateClientFiles(input, _options);
   });
 

package/src/generate-client-files.ts

@@ -3,10 +3,17 @@ import type { OpenAPIObject } from "openapi3-ts/oas31";
 import { basename, join, dirname } from "pathe";
 import { type } from "arktype";
 import { mkdir, writeFile } from "fs/promises";
-import { allowedRuntimes, generateFile } from "./generator.ts";
+import {
+  allowedRuntimes,
+  generateFile,
+  DEFAULT_SUCCESS_STATUS_CODES,
+  DEFAULT_ERROR_STATUS_CODES,
+  type GeneratorOptions,
+} from "./generator.ts";
 import { mapOpenApiEndpoints } from "./map-openapi-endpoints.ts";
 import { generateTanstackQueryFile } from "./tanstack-query.generator.ts";
 import { prettify } from "./format.ts";
+import type { NameTransformOptions } from "./types.ts";
 
 const cwd = process.cwd();
 const now = new Date();
@@ -24,21 +31,46 @@ export const optionsSchema = type({
   runtime: allowedRuntimes,
   tanstack: "boolean | string",
   schemasOnly: "boolean",
+  "includeClient?": "boolean | 'true' | 'false'",
+  "successStatusCodes?": "string",
+  "errorStatusCodes?": "string",
 });
 
-export async function generateClientFiles(input: string, options: typeof optionsSchema.infer) {
+type GenerateClientFilesOptions = typeof optionsSchema.infer & {
+  nameTransform?: NameTransformOptions;
+};
+
+export async function generateClientFiles(input: string, options: GenerateClientFilesOptions) {
   const openApiDoc = (await SwaggerParser.bundle(input)) as OpenAPIObject;
 
-  const ctx = mapOpenApiEndpoints(openApiDoc);
+  const ctx = mapOpenApiEndpoints(openApiDoc, options);
   console.log(`Found ${ctx.endpointList.length} endpoints`);
 
-  const content = await prettify(
-    generateFile({
-      ...ctx,
-      runtime: options.runtime,
-      schemasOnly: options.schemasOnly,
-    }),
-  );
+  // Parse success status codes if provided
+  const successStatusCodes = options.successStatusCodes
+    ? (options.successStatusCodes.split(",").map((code) => parseInt(code.trim(), 10)) as readonly number[])
+    : undefined;
+
+  // Parse error status codes if provided
+  const errorStatusCodes = options.errorStatusCodes
+    ? (options.errorStatusCodes.split(",").map((code) => parseInt(code.trim(), 10)) as readonly number[])
+    : undefined;
+
+  // Convert string boolean to actual boolean
+  const includeClient =
+    options.includeClient === "false" ? false : options.includeClient === "true" ? true : options.includeClient;
+
+  const generatorOptions: GeneratorOptions = {
+    ...ctx,
+    runtime: options.runtime,
+    schemasOnly: options.schemasOnly,
+    nameTransform: options.nameTransform,
+    includeClient: includeClient ?? true,
+    successStatusCodes: successStatusCodes ?? DEFAULT_SUCCESS_STATUS_CODES,
+    errorStatusCodes: errorStatusCodes ?? DEFAULT_ERROR_STATUS_CODES,
+  };
+
+  const content = await prettify(generateFile(generatorOptions));
   const outputPath = join(
     cwd,
     options.output ?? input + `.${options.runtime === "none" ? "client" : options.runtime}.ts`,
@@ -50,7 +82,7 @@ export async function generateClientFiles(input: string, options: typeof options
 
   if (options.tanstack) {
     const tanstackContent = await generateTanstackQueryFile({
-      ...ctx,
+      ...generatorOptions,
       relativeApiClientPath: "./" + basename(outputPath),
     });
     const tanstackOutputPath = join(