typed-openapi 0.1.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "typed-openapi",
+  "type": "module",
+  "version": "0.1.1",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "bin": {
+    "typed-openapi": "bin.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astahmer/typed-openapi.git"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "@changesets/cli": "^2.26.2",
+    "@dprint/formatter": "^0.2.0",
+    "@dprint/typescript": "^0.85.1",
+    "@sinclair/typebox-codegen": "^0.8.5",
+    "arktype": "1.0.18-alpha",
+    "cac": "^6.7.14",
+    "dprint": "^0.40.2",
+    "openapi3-ts": "^4.1.2",
+    "pastable": "^2.2.1",
+    "pathe": "^1.1.1",
+    "ts-pattern": "^5.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.4.5",
+    "tsup": "^7.1.0",
+    "typescript": "^5.1.6",
+    "vite-node": "^0.33.0",
+    "vitest": "^0.33.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "cli",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node ./dist/cli.cjs",
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/asserts.ts

@@ -0,0 +1,7 @@
+import type { SchemaObject } from "openapi3-ts/oas31";
+
+export type SingleType = Exclude<SchemaObject["type"], any[] | undefined>;
+export const isPrimitiveType = (type: unknown): type is PrimitiveType => primitiveTypeList.includes(type as any);
+
+const primitiveTypeList = ["string", "number", "integer", "boolean", "null"] as const;
+export type PrimitiveType = (typeof primitiveTypeList)[number];

package/src/box-factory.ts

@@ -0,0 +1,52 @@
+import type { ReferenceObject, SchemaObject } from "openapi3-ts/oas31";
+import { Box } from "./box";
+import { AnyBoxDef, BoxFactory, OpenapiSchemaConvertContext, StringOrBox } from "./types";
+
+export const unwrap = (param: StringOrBox) => (typeof param === "string" ? param : param.value);
+export const createFactory = <T extends OpenapiSchemaConvertContext["factory"]>(f: T) => f;
+
+/**
+ * Create a box-factory using your schema provider and automatically add the input schema to each box.
+ */
+export const createBoxFactory = (schema: SchemaObject | ReferenceObject, ctx: OpenapiSchemaConvertContext) => {
+  const f = typeof ctx.factory === "function" ? ctx.factory(schema, ctx) : ctx.factory;
+  const callback = <T extends AnyBoxDef>(box: Box<T>) => {
+    if (f.callback) {
+      box = f.callback(box) as Box<T>;
+    }
+
+    if (ctx?.onBox) {
+      box = ctx.onBox?.(box) as Box<T>;
+    }
+
+    return box;
+  };
+
+  const box: BoxFactory = {
+    union: (types) => callback(new Box({ ctx, schema, type: "union", params: { types }, value: f.union(types) })),
+    intersection: (types) =>
+      callback(new Box({ ctx, schema, type: "intersection", params: { types }, value: f.intersection(types) })),
+    array: (type) => callback(new Box({ ctx, schema, type: "array", params: { type }, value: f.array(type) })),
+    optional: (type) => callback(new Box({ ctx, schema, type: "optional", params: { type }, value: f.optional(type) })),
+    reference: (name, generics) =>
+      callback(
+        new Box({
+          ctx,
+          schema,
+          type: "ref",
+          params: generics ? { name, generics } : { name },
+          value: f.reference(name, generics),
+        }),
+      ),
+    literal: (value) => callback(new Box({ ctx, schema, type: "literal", params: {}, value: f.literal(value) })),
+    string: () => callback(new Box({ ctx, schema, type: "keyword", params: { name: "string" }, value: f.string() })),
+    number: () => callback(new Box({ ctx, schema, type: "keyword", params: { name: "number" }, value: f.number() })),
+    boolean: () => callback(new Box({ ctx, schema, type: "keyword", params: { name: "boolean" }, value: f.boolean() })),
+    unknown: () => callback(new Box({ ctx, schema, type: "keyword", params: { name: "unknown" }, value: f.unknown() })),
+    any: () => callback(new Box({ ctx, schema, type: "keyword", params: { name: "any" }, value: f.any() })),
+    never: () => callback(new Box({ ctx, schema, type: "keyword", params: { name: "never" }, value: f.never() })),
+    object: (props) => callback(new Box({ ctx, schema, type: "object", params: { props }, value: f.object(props) })),
+  };
+
+  return box;
+};

package/src/box.ts

@@ -0,0 +1,84 @@
+import { SchemaObject } from "openapi3-ts/oas31";
+import { openApiSchemaToTs } from "./openapi-schema-to-ts";
+import {
+  AnyBoxDef,
+  BoxArray,
+  BoxIntersection,
+  BoxKeyword,
+  BoxLiteral,
+  BoxObject,
+  BoxOptional,
+  BoxRef,
+  BoxUnion,
+  OpenapiSchemaConvertContext,
+} from "./types";
+
+// TODO rename SchemaBox
+export class Box<T extends AnyBoxDef = AnyBoxDef> {
+  type: T["type"];
+  value: T["value"];
+  params: T["params"];
+  schema: T["schema"];
+  ctx: T["ctx"];
+
+  constructor(public definition: T) {
+    this.definition = definition;
+    this.type = definition.type;
+    this.value = definition.value;
+    this.params = definition.params;
+    this.schema = definition.schema;
+    this.ctx = definition.ctx;
+  }
+
+  toJSON() {
+    return { type: this.type, value: this.value };
+  }
+
+  toString() {
+    return JSON.stringify(this.toJSON(), null, 2);
+  }
+
+  recompute(callback: OpenapiSchemaConvertContext["onBox"]) {
+    return openApiSchemaToTs({ schema: this.schema as SchemaObject, ctx: { ...this.ctx, onBox: callback! } });
+  }
+
+  static fromJSON(json: string) {
+    return new Box(JSON.parse(json));
+  }
+
+  static isBox(box: unknown): box is Box<AnyBoxDef> {
+    return box instanceof Box;
+  }
+
+  static isUnion(box: Box<AnyBoxDef>): box is Box<BoxUnion> {
+    return box.type === "union";
+  }
+
+  static isIntersection(box: Box<AnyBoxDef>): box is Box<BoxIntersection> {
+    return box.type === "intersection";
+  }
+
+  static isArray(box: Box<AnyBoxDef>): box is Box<BoxArray> {
+    return box.type === "array";
+  }
+
+  static isOptional(box: Box<AnyBoxDef>): box is Box<BoxOptional> {
+    return box.type === "optional";
+  }
+
+  static isReference(box: Box<AnyBoxDef>): box is Box<BoxRef> {
+    return box.type === "ref";
+  }
+
+  static isKeyword(box: Box<AnyBoxDef>): box is Box<BoxKeyword> {
+    return box.type === "keyword";
+  }
+
+  static isObject(box: Box<AnyBoxDef>): box is Box<BoxObject> {
+    return box.type === "object";
+  }
+
+  static isLiteral(box: Box<AnyBoxDef>): box is Box<BoxLiteral> {
+    return box.type === "literal";
+  }
+}

package/src/cli.ts

@@ -0,0 +1,47 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { cac } from "cac";
+import type { OpenAPIObject } from "openapi3-ts/oas31";
+import { join } from "pathe";
+import { type } from "arktype";
+
+import { writeFile } from "fs/promises";
+// @ts-expect-error
+import { name, version } from "../package.json";
+import { allowedRuntimes, generateFile } from "./generator";
+import { mapOpenApiEndpoints } from "./map-openapi-endpoints";
+
+const cwd = process.cwd();
+const cli = cac(name);
+const now = new Date();
+
+const optionsSchema = type({ "output?": "string", runtime: allowedRuntimes });
+
+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>",
+    `Runtime to use for validation; defaults to \`none\`; available: ${allowedRuntimes.definition}`,
+    { default: "none" },
+  )
+  .action(async (input, _options) => {
+    const options = optionsSchema.assert(_options);
+    const openApiDoc = (await SwaggerParser.bundle(input)) as OpenAPIObject;
+
+    const ctx = mapOpenApiEndpoints(openApiDoc);
+    console.log(`Found ${ctx.endpointList.length} endpoints`);
+
+    const content = generateFile({ ...ctx, runtime: options.runtime });
+    const output = join(
+      cwd,
+      options.output ?? input + `.${options.runtime === "none" ? "client" : options.runtime}.ts`,
+    );
+
+    console.log("Generating...", output);
+    await writeFile(output, content);
+    console.log(`Done in ${new Date().getTime() - now.getTime()}ms !`);
+  });
+
+cli.help();
+cli.version(version);
+cli.parse();

package/src/format.ts

@@ -0,0 +1,12 @@
+import { createFromBuffer, GlobalConfiguration } from "@dprint/formatter";
+import * as fs from "fs";
+import { join } from "path";
+
+const tsPluginPath = join(__dirname, "..", "node_modules", "@dprint", "typescript", "plugin.wasm");
+const buffer = fs.readFileSync(tsPluginPath);
+const formatter = createFromBuffer(buffer);
+
+formatter.setConfig({ lineWidth: 120, indentWidth: 2 }, {});
+
+export const prettify = (code: string, options?: GlobalConfiguration) =>
+  formatter.formatText("code.ts", code, options as any);

package/src/generator.ts

@@ -0,0 +1,305 @@
+import { capitalize, groupBy } from "pastable/server";
+import { Box } from "./box";
+import { prettify } from "./format";
+import { mapOpenApiEndpoints } from "./map-openapi-endpoints";
+import { AnyBox, BoxRef } from "./types";
+import * as Codegen from "@sinclair/typebox-codegen";
+import { match } from "ts-pattern";
+import { type } from "arktype";
+import { wrapWithQuotesIfNeeded } from "./string-utils";
+
+type GeneratorOptions = ReturnType<typeof mapOpenApiEndpoints> & {
+  runtime?: "none" | keyof typeof runtimeValidationGenerator;
+};
+type GeneratorContext = Required<GeneratorOptions>;
+
+export const allowedRuntimes = type("'none' | 'arktype' | 'io-ts' | 'typebox' | 'valibot' | 'yup' | 'zod'");
+
+// TODO validate response schemas in sample fetch ApiClient
+// also, check that we can easily retrieve the response schema from the Fetcher
+
+const runtimeValidationGenerator = {
+  arktype: Codegen.ModelToArkType.Generate,
+  "io-ts": Codegen.ModelToIoTs.Generate,
+  typebox: Codegen.ModelToTypeBox.Generate,
+  valibot: Codegen.ModelToValibot.Generate,
+  yup: Codegen.ModelToYup.Generate,
+  zod: Codegen.ModelToZod.Generate,
+};
+
+const inferByRuntime = {
+  none: (input: string) => input,
+  arktype: (input: string) => `${input}["infer"]`,
+  "io-ts": (input: string) => `t.TypeOf<${input}>`,
+  typebox: (input: string) => `Static<${input}>`,
+  valibot: (input: string) => `v.Output<${input}>`,
+  yup: (input: string) => `y.InferType<${input}>`,
+  zod: (input: string) => `z.infer<${input}>`,
+};
+
+const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as const;
+const methodsRegex = new RegExp(`(?:${methods.join("|")})_`);
+const endpointExport = new RegExp(`export (?:type|const) (?:${methodsRegex.source})`);
+
+const replacerByRuntime = {
+  yup: (line: string) =>
+    line
+      .replace(/y\.InferType<\s*?typeof (.*?)\s*?>/g, "typeof $1")
+      .replace(new RegExp(`(${endpointExport.source})` + new RegExp(/(.*? )(y\.object)(\()/).source, "g"), "$1$2("),
+  zod: (line: string) =>
+    line
+      .replace(/z\.infer<\s*?typeof (.*?)\s*?>/g, "typeof $1")
+      .replace(new RegExp(`(${endpointExport.source})` + new RegExp(/(.*? )(z\.object)(\()/).source, "g"), "$1$2("),
+};
+
+export const generateFile = (options: GeneratorOptions) => {
+  const ctx = { ...options, runtime: options.runtime ?? "none" } as GeneratorContext;
+
+  const schemaList = generateSchemaList(ctx);
+  const endpointSchemaList = generateEndpointSchemaList(ctx);
+  const apiClient = generateApiClient(ctx);
+
+  const transform =
+    ctx.runtime === "none"
+      ? (file: string) => file
+      : (file: string) => {
+          const model = Codegen.TypeScriptToModel.Generate(file);
+          const transformer = runtimeValidationGenerator[ctx.runtime as Exclude<typeof ctx.runtime, "none">];
+          // tmp fix for typebox, there's currently a "// todo" only with Codegen.ModelToTypeBox.Generate
+          // https://github.com/sinclairzx81/typebox-codegen/blob/44d44d55932371b69f349331b1c8a60f5d760d9e/src/model/model-to-typebox.ts#L31
+          const generated = ctx.runtime === "typebox" ? Codegen.TypeScriptToTypeBox.Generate(file) : transformer(model);
+
+          let converted = "";
+          const match = generated.match(/(const __ENDPOINTS_START__ =)([\s\S]*?)(export type __ENDPOINTS_END__)/);
+          const content = match?.[2];
+
+          if (content && ctx.runtime in replacerByRuntime) {
+            const before = generated.slice(0, generated.indexOf("export type __ENDPOINTS_START"));
+            converted =
+              before +
+              replacerByRuntime[ctx.runtime as keyof typeof replacerByRuntime](
+                content.slice(content.indexOf("export")),
+              );
+          } else {
+            converted = generated;
+          }
+
+          return converted;
+        };
+
+  const file = `
+  ${transform(schemaList + endpointSchemaList)}
+  ${apiClient}
+  `;
+
+  return prettify(file);
+};
+
+const generateSchemaList = ({ refs }: GeneratorContext) => {
+  let file = `
+  export namespace Schemas {
+    // <Schemas>
+  `;
+  refs.getOrderedSchemas().forEach(([schema, infos]) => {
+    if (!infos?.name) return;
+    if (infos.kind !== "schemas") return;
+
+    file += `export type ${infos.normalized} = ${schema.value}\n`;
+  });
+
+  return (
+    file +
+    `
+    // </Schemas>
+    }
+  `
+  );
+};
+
+const parameterObjectToString = (parameters: Box<BoxRef> | Record<string, AnyBox>) => {
+  if (parameters instanceof Box) return parameters.value;
+
+  let str = "{";
+  for (const [key, box] of Object.entries(parameters)) {
+    str += `${wrapWithQuotesIfNeeded(key)}: ${box.value},\n`;
+  }
+  return str + "}";
+};
+const generateEndpointSchemaList = (ctx: GeneratorContext) => {
+  let file = `
+  export namespace Endpoints {
+  // <Endpoints>
+  ${ctx.runtime === "none" ? "" : "type __ENDPOINTS_START__ = {}"}
+  `;
+  ctx.endpointList.map((endpoint) => {
+    const parameters = endpoint.parameters ?? {};
+    file += `export type ${endpoint.meta.alias} = {
+      method: "${endpoint.method.toUpperCase()}",
+      path: "${endpoint.path}",
+      ${
+        endpoint.meta.hasParameters
+          ? `parameters: {
+            ${parameters.query ? `query:  ${parameterObjectToString(parameters.query)},` : ""}
+        ${parameters.path ? `path:  ${parameterObjectToString(parameters.path)},` : ""}
+        ${parameters.header ? `header:  ${parameterObjectToString(parameters.header)},` : ""}
+          }`
+          : "parameters: never,"
+      }
+      response: ${
+        endpoint.response.recompute((box) => {
+          if (Box.isReference(box) && !box.params.generics) {
+            box.value = `Schemas.${box.value}`;
+          }
+
+          return box;
+        }).value
+      },
+    }\n`;
+  });
+
+  return (
+    file +
+    `
+  // </Endpoints>
+  }
+  ${ctx.runtime === "none" ? "" : "type __ENDPOINTS_END__ = {}"}
+  `
+  );
+};
+
+const generateEndpointByMethod = (ctx: GeneratorContext) => {
+  const { endpointList } = ctx;
+  const byMethods = groupBy(endpointList, "method");
+
+  const endpointByMethod = `
+     // <EndpointByMethod>
+     export ${ctx.runtime === "none" ? "type" : "const"} EndpointByMethod = {
+     ${Object.entries(byMethods)
+       .map(([method, list]) => {
+         return `${method}: {
+           ${list.map((endpoint) => `"${endpoint.path}": Endpoints.${endpoint.meta.alias}`)}
+         }`;
+       })
+       .join(",\n")}
+     }
+     ${ctx.runtime === "none" ? "" : "export type EndpointByMethod = typeof EndpointByMethod;"}
+     // </EndpointByMethod>
+     `;
+
+  const shorthands = `
+
+    // <EndpointByMethod.Shorthands>
+    ${Object.keys(byMethods)
+      .map((method) => `export type ${capitalize(method)}Endpoints = EndpointByMethod["${method}"]`)
+      .join("\n")}
+    ${endpointList.length ? `export type AllEndpoints = EndpointByMethod[keyof EndpointByMethod];` : ""}
+    // </EndpointByMethod.Shorthands>
+    `;
+
+  return endpointByMethod + shorthands;
+};
+
+const generateApiClient = (ctx: GeneratorContext) => {
+  const { endpointList } = ctx;
+  const byMethods = groupBy(endpointList, "method");
+  const endpointSchemaList = generateEndpointByMethod(ctx);
+
+  const apiClientTypes = `
+// <ApiClientTypes>
+export type EndpointParameters = {
+  body?: unknown;
+  query?: Record<string, unknown>;
+  header?: Record<string, unknown>;
+  path?: Record<string, unknown>;
+};
+
+export type MutationMethod = "post" | "put" | "patch" | "delete";
+export type Method = "get" | "head" | MutationMethod;
+
+export type DefaultEndpoint = {
+  parameters?: EndpointParameters | undefined;
+  response: unknown;
+};
+
+export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
+  operationId: string;
+  method: Method;
+  path: string;
+  parameters?: TConfig["parameters"];
+  meta: {
+    alias: string;
+    hasParameters: boolean;
+    areParametersRequired: boolean;
+  };
+  response: TConfig["response"];
+};
+
+type Fetcher = (method: Method, url: string, parameters?: EndpointParameters | undefined) => Promise<Endpoint["response"]>;
+
+type RequiredKeys<T> = {
+  [P in keyof T]-?: undefined extends T[P] ? never : P;
+}[keyof T];
+
+type MaybeOptionalArg<T> = RequiredKeys<T> extends never ? [config?: T] : [config: T];
+
+// </ApiClientTypes>
+`;
+
+  const apiClient = `
+// <ApiClient>
+export class ApiClient {
+  baseUrl: string = "";
+
+  constructor(public fetcher: Fetcher) {}
+
+  setBaseUrl(baseUrl: string) {
+    this.baseUrl = baseUrl;
+    return this;
+  }
+
+  ${Object.entries(byMethods)
+    .map(([method, endpointByMethod]) => {
+      const capitalizedMethod = capitalize(method);
+      const infer = inferByRuntime[ctx.runtime];
+
+      return endpointByMethod.length
+        ? `// <ApiClient.${method}>
+    ${method}<Path extends keyof ${capitalizedMethod}Endpoints, TEndpoint extends ${capitalizedMethod}Endpoints[Path]>(
+      path: Path,
+      ...params: MaybeOptionalArg<${match(ctx.runtime)
+        .with("zod", "yup", () => infer(`TEndpoint["parameters"]`))
+        .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["parameters"]`)
+        .otherwise(() => `TEndpoint["parameters"]`)}>
+    ): Promise<${match(ctx.runtime)
+      .with("zod", "yup", () => infer(`TEndpoint["response"]`))
+      .with("arktype", "io-ts", "typebox", "valibot", () => infer(`TEndpoint`) + `["response"]`)
+      .otherwise(() => `TEndpoint["response"]`)}> {
+      return this.fetcher("${method}", this.baseUrl + path, params[0]);
+    }
+    // </ApiClient.${method}>
+    `
+        : "";
+    })
+    .join("\n")}
+}
+
+export function createApiClient(fetcher: Fetcher, baseUrl?: string) {
+  return new ApiClient(fetcher).setBaseUrl(baseUrl ?? "");
+}
+
+
+/**
+ Example usage:
+ const api = createApiClient((method, url, params) =>
+   fetch(url, { method, body: JSON.stringify(params) }).then((res) => res.json()),
+ );
+ api.get("/users").then((users) => console.log(users));
+ api.post("/users", { body: { name: "John" } }).then((user) => console.log(user));
+ api.put("/users/:id", { path: { id: 1 }, body: { name: "John" } }).then((user) => console.log(user));
+*/
+
+// </ApiClient
+`;
+
+  return endpointSchemaList + apiClientTypes + apiClient;
+};

package/src/is-reference-object.ts

@@ -0,0 +1,16 @@
+// taken from
+// https://github.dev/metadevpro/openapi3-ts/blob/a62ff445207af599f591532ef776e671c456cc37/src/model/OpenApi.ts#L261-L269
+// to avoid the runtime dependency on `openapi3-ts`
+// which itself depends on `yaml` import (which use CJS `require` and thus can't be imported in a ESM module)
+
+import type { ReferenceObject } from "openapi3-ts/oas31";
+
+/**
+ * A type guard to check if the given value is a `ReferenceObject`.
+ * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types
+ *
+ * @param obj The value to check.
+ */
+export function isReferenceObject(obj: any): obj is ReferenceObject {
+  return obj != null && Object.prototype.hasOwnProperty.call(obj, "$ref");
+}