typed-openapi 0.1.1

package/src/map-openapi-endpoints.ts

@@ -0,0 +1,171 @@
+import type { OpenAPIObject, ResponseObject } from "openapi3-ts/oas31";
+import { OperationObject, ParameterObject } from "openapi3-ts/oas31";
+import { capitalize, pick } from "pastable/server";
+import { Box } from "./box";
+import { createBoxFactory } from "./box-factory";
+import { openApiSchemaToTs } from "./openapi-schema-to-ts";
+import { createRefResolver } from "./ref-resolver";
+import { tsFactory } from "./ts-factory";
+import { AnyBox, BoxRef, OpenapiSchemaConvertContext } from "./types";
+import { pathToVariableName } from "./string-utils";
+
+const factory = tsFactory;
+
+export const mapOpenApiEndpoints = (doc: OpenAPIObject) => {
+  const refs = createRefResolver(doc, factory);
+  const ctx: OpenapiSchemaConvertContext = { refs, factory };
+  const endpointList = [] as Array<Endpoint>;
+
+  Object.entries(doc.paths ?? {}).forEach(([path, pathItemObj]) => {
+    const pathItem = pick(pathItemObj, ["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+    Object.entries(pathItem).forEach(([method, operation]) => {
+      if (operation.deprecated) return;
+
+      const endpoint = {
+        operation,
+        method: method as Method,
+        path,
+        response: openApiSchemaToTs({ schema: {}, ctx }),
+        meta: {
+          alias: getAlias({ path, method, operation } as Endpoint),
+          areParametersRequired: false,
+          hasParameters: false,
+        },
+      } as Endpoint;
+
+      // Build a list of parameters by type + fill an object with all of them
+      const lists = { query: [] as ParameterObject[], path: [] as ParameterObject[], header: [] as ParameterObject[] };
+      const paramObjects = (operation.parameters ?? []).reduce(
+        (acc, paramOrRef) => {
+          const param = refs.unwrap(paramOrRef);
+          const schema = openApiSchemaToTs({ schema: refs.unwrap(param.schema ?? {}), ctx });
+          lists.query.push(param);
+
+          if (param.required) endpoint.meta.areParametersRequired = true;
+          endpoint.meta.hasParameters = true;
+
+          if (param.in === "query") acc.query[param.name] = schema;
+          if (param.in === "path") acc.path[param.name] = schema;
+          if (param.in === "header") acc.header[param.name] = schema;
+
+          return acc;
+        },
+        { query: {} as Record<string, Box>, path: {} as Record<string, Box>, header: {} as Record<string, Box> },
+      );
+
+      // Filter out empty objects
+      const params = Object.entries(paramObjects).reduce((acc, [key, value]) => {
+        if (Object.keys(value).length) {
+          // @ts-expect-error
+          acc[key] = value;
+        }
+        return acc;
+      }, {} as { query?: Record<string, Box>; path?: Record<string, Box>; header?: Record<string, Box>; body?: Box });
+
+      // Body
+      if (operation.requestBody) {
+        const requestBody = refs.unwrap(operation.requestBody ?? {});
+        const content = requestBody.content;
+        const matchingMediaType = Object.keys(content).find(isAllowedParamMediaTypes);
+
+        if (matchingMediaType && content[matchingMediaType]) {
+          params.body = openApiSchemaToTs({
+            schema: content[matchingMediaType]?.schema ?? {} ?? {},
+            ctx,
+          });
+        }
+      }
+
+      // Make parameters optional if none of them are required
+      if (params) {
+        const t = createBoxFactory({}, ctx);
+        if (params.query && lists.query.length && lists.query.every((param) => !param.required)) {
+          if (!params.query) params.query = {};
+          params.query = t.reference("Partial", [t.object(params.query)]) as any;
+        }
+        if (params.path && lists.path.length && lists.path.every((param) => !param.required)) {
+          params.path = t.reference("Partial", [t.object(params.path)]) as any;
+        }
+        if (params.header && lists.header.length && lists.header.every((param) => !param.required)) {
+          params.header = t.reference("Partial", [t.object(params.header)]) as any;
+        }
+
+        // No need to pass empty objects, it's confusing
+        endpoint.parameters = Object.keys(params).length ? (params as any as EndpointParameters) : undefined;
+      }
+
+      let responseObject;
+      // Match the default response or first 2xx-3xx response found
+      if (operation.responses.default) {
+        responseObject = refs.unwrap(operation.responses.default);
+      } else {
+        Object.entries(operation.responses).map(([status, responseOrRef]) => {
+          const statusCode = Number(status);
+          if (statusCode >= 200 && statusCode < 300) {
+            responseObject = refs.unwrap<ResponseObject>(responseOrRef);
+          }
+        });
+      }
+
+      const content = responseObject?.content;
+      if (content) {
+        const matchingMediaType = Object.keys(content).find(isResponseMediaType);
+        if (matchingMediaType && content[matchingMediaType]) {
+          endpoint.response = openApiSchemaToTs({
+            schema: content[matchingMediaType]?.schema ?? {} ?? {},
+            ctx,
+          });
+        }
+      }
+
+      endpointList.push(endpoint);
+    });
+  });
+
+  return { doc, refs, endpointList, factory };
+};
+
+const allowedParamMediaTypes = [
+  "application/octet-stream",
+  "multipart/form-data",
+  "application/x-www-form-urlencoded",
+  "*/*",
+] as const;
+const isAllowedParamMediaTypes = (
+  mediaType: string,
+): mediaType is (typeof allowedParamMediaTypes)[number] | `application/${string}json${string}` | `text/${string}` =>
+  (mediaType.includes("application/") && mediaType.includes("json")) ||
+  allowedParamMediaTypes.includes(mediaType as any) ||
+  mediaType.includes("text/");
+
+const isResponseMediaType = (mediaType: string) => mediaType === "application/json";
+const getAlias = ({ path, method, operation }: Endpoint) =>
+  method + "_" + capitalize(operation.operationId ?? pathToVariableName(path));
+
+type MutationMethod = "post" | "put" | "patch" | "delete";
+type Method = "get" | "head" | "options" | MutationMethod;
+
+export type EndpointParameters = {
+  body?: Box;
+  query?: Box<BoxRef> | Record<string, AnyBox>;
+  header?: Box<BoxRef> | Record<string, AnyBox>;
+  path?: Box<BoxRef> | Record<string, AnyBox>;
+};
+
+type DefaultEndpoint = {
+  parameters?: EndpointParameters | undefined;
+  response: AnyBox;
+};
+
+export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
+  operation: OperationObject;
+  method: Method;
+  path: string;
+  parameters?: TConfig["parameters"];
+  meta: {
+    alias: string;
+    hasParameters: boolean;
+    areParametersRequired: boolean;
+  };
+  response: TConfig["response"];
+};

package/src/openapi-schema-to-ts.ts

@@ -0,0 +1,157 @@
+import { isPrimitiveType } from "./asserts";
+import { Box } from "./box";
+import { createBoxFactory } from "./box-factory";
+import { isReferenceObject } from "./is-reference-object";
+import { AnyBoxDef, OpenapiSchemaConvertArgs } from "./types";
+import { wrapWithQuotesIfNeeded } from "./string-utils";
+
+export const openApiSchemaToTs = ({ schema, meta: _inheritedMeta, ctx }: OpenapiSchemaConvertArgs): Box<AnyBoxDef> => {
+  const meta = {} as OpenapiSchemaConvertArgs["meta"];
+
+  if (!schema) {
+    throw new Error("Schema is required");
+  }
+
+  const t = createBoxFactory(schema, ctx);
+  const getTs = () => {
+    if (isReferenceObject(schema)) {
+      const refInfo = ctx.refs.getInfosByRef(schema.$ref);
+
+      return t.reference(refInfo.normalized);
+    }
+
+    if (Array.isArray(schema.type)) {
+      if (schema.type.length === 1) {
+        return openApiSchemaToTs({ schema: { ...schema, type: schema.type[0]! }, ctx, meta });
+      }
+
+      return t.union(schema.type.map((prop) => openApiSchemaToTs({ schema: { ...schema, type: prop }, ctx, meta })));
+    }
+
+    if (schema.type === "null") {
+      return t.reference("null");
+    }
+
+    if (schema.oneOf) {
+      if (schema.oneOf.length === 1) {
+        return openApiSchemaToTs({ schema: schema.oneOf[0]!, ctx, meta });
+      }
+
+      return t.union(schema.oneOf.map((prop) => openApiSchemaToTs({ schema: prop, ctx, meta })));
+    }
+
+    // anyOf = oneOf but with 1 or more = `T extends oneOf ? T | T[] : never`
+    if (schema.anyOf) {
+      if (schema.anyOf.length === 1) {
+        return openApiSchemaToTs({ schema: schema.anyOf[0]!, ctx, meta });
+      }
+
+      const oneOf = t.union(schema.anyOf.map((prop) => openApiSchemaToTs({ schema: prop, ctx, meta })));
+      return t.union([oneOf, t.array(oneOf)]);
+    }
+
+    if (schema.allOf) {
+      if (schema.allOf.length === 1) {
+        return openApiSchemaToTs({ schema: schema.allOf[0]!, ctx, meta });
+      }
+
+      const types = schema.allOf.map((prop) => openApiSchemaToTs({ schema: prop, ctx, meta }));
+      return t.intersection(types);
+    }
+
+    const schemaType = schema.type ? (schema.type.toLowerCase() as NonNullable<typeof schema.type>) : undefined;
+    if (schemaType && isPrimitiveType(schemaType)) {
+      if (schema.enum) {
+        if (schema.enum.length === 1) {
+          const value = schema.enum[0];
+          return t.literal(value === null ? "null" : `"${value}"`);
+        }
+
+        if (schemaType === "string") {
+          return t.union(schema.enum.map((value) => t.literal(`"${value}"`)));
+        }
+
+        if (schema.enum.some((e) => typeof e === "string")) {
+          return t.never();
+        }
+
+        return t.union(schema.enum.map((value) => t.literal(value === null ? "null" : value)));
+      }
+
+      if (schemaType === "string") return t.string();
+      if (schemaType === "boolean") return t.boolean();
+      if (schemaType === "number" || schemaType === "integer") return t.number();
+      if (schemaType === "null") return t.reference("null");
+    }
+
+    if (schemaType === "array") {
+      if (schema.items) {
+        let arrayOfType = openApiSchemaToTs({ schema: schema.items, ctx, meta });
+        if (typeof arrayOfType === "string") {
+          arrayOfType = t.reference(arrayOfType);
+        }
+
+        return t.array(arrayOfType);
+      }
+
+      return t.array(t.any());
+    }
+
+    if (schemaType === "object" || schema.properties || schema.additionalProperties) {
+      if (!schema.properties) {
+        return t.unknown();
+      }
+
+      let additionalProperties;
+      if (schema.additionalProperties) {
+        let additionalPropertiesType;
+        if (
+          (typeof schema.additionalProperties === "boolean" && schema.additionalProperties) ||
+          (typeof schema.additionalProperties === "object" && Object.keys(schema.additionalProperties).length === 0)
+        ) {
+          additionalPropertiesType = t.any();
+        } else if (typeof schema.additionalProperties === "object") {
+          additionalPropertiesType = openApiSchemaToTs({
+            schema: schema.additionalProperties,
+            ctx,
+            meta,
+          });
+        }
+
+        additionalProperties = t.object({ [t.string().value]: additionalPropertiesType! });
+      }
+
+      const hasRequiredArray = schema.required && schema.required.length > 0;
+      const isPartial = !schema.required?.length;
+
+      const props = Object.fromEntries(
+        Object.entries(schema.properties).map(([prop, propSchema]) => {
+          let propType = openApiSchemaToTs({ schema: propSchema, ctx, meta });
+          if (typeof propType === "string") {
+            // TODO Partial ?
+            propType = t.reference(propType);
+          }
+
+          const isRequired = Boolean(isPartial ? true : hasRequiredArray ? schema.required?.includes(prop) : false);
+          const isOptional = !isPartial && !isRequired;
+          return [
+            `${wrapWithQuotesIfNeeded(prop)}${isOptional ? "?" : ""}`,
+            isOptional ? t.optional(propType) : propType,
+          ];
+        }),
+      );
+
+      const objectType = additionalProperties
+        ? t.intersection([t.object(props), additionalProperties])
+        : t.object(props);
+
+      return isPartial ? t.reference("Partial", [objectType]) : objectType;
+    }
+
+    if (!schemaType) return t.unknown();
+
+    throw new Error(`Unsupported schema type: ${schemaType}`);
+  };
+
+  return getTs();
+};

package/src/ref-resolver.ts

@@ -0,0 +1,206 @@
+import type { OpenAPIObject, ReferenceObject, SchemaObject } from "openapi3-ts/oas31";
+import { get } from "pastable/server";
+
+import { Box } from "./box";
+import { isReferenceObject } from "./is-reference-object";
+import { openApiSchemaToTs } from "./openapi-schema-to-ts";
+import { normalizeString } from "./string-utils";
+import { AnyBoxDef, GenericFactory } from "./types";
+import { topologicalSort } from "./topological-sort";
+
+const autocorrectRef = (ref: string) => (ref[1] === "/" ? ref : "#/" + ref.slice(1));
+const componentsWithSchemas = ["schemas", "responses", "parameters", "requestBodies", "headers"];
+
+export 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";
+};
+
+export const createRefResolver = (doc: OpenAPIObject, factory: GenericFactory) => {
+  // both used for debugging purpose
+  const nameByRef = new Map<string, string>();
+  const refByName = new Map<string, string>();
+
+  const byRef = new Map<string, RefInfo>();
+  const byNormalized = new Map<string, RefInfo>();
+
+  const boxByRef = new Map<string, Box<AnyBoxDef>>();
+
+  const getSchemaByRef = <T = SchemaObject>(ref: string) => {
+    // #components -> #/components
+    const correctRef = autocorrectRef(ref);
+    const split = correctRef.split("/");
+
+    // "#/components/schemas/Something.jsonld" -> #/components/schemas
+    const path = split.slice(1, -1).join("/")!;
+    const normalizedPath = path.replace("#/", "").replace("#", "").replaceAll("/", ".");
+    const map = get(doc, normalizedPath) ?? ({} as any);
+
+    // "#/components/schemas/Something.jsonld" -> "Something.jsonld"
+    const name = split[split.length - 1]!;
+    const normalized = normalizeString(name);
+
+    nameByRef.set(correctRef, normalized);
+    refByName.set(normalized, correctRef);
+
+    const infos = { ref: correctRef, name, normalized, kind: normalizedPath.split(".")[1] as RefInfo["kind"] };
+    byRef.set(infos.ref, infos);
+    byNormalized.set(infos.normalized, infos);
+
+    // doc.components.schemas["Something.jsonld"]
+    const schema = map[name] as T;
+    if (!schema) {
+      throw new Error(`Unresolved ref "${name}" not found in "${path}"`);
+    }
+
+    return schema;
+  };
+
+  const getInfosByRef = (ref: string) => byRef.get(autocorrectRef(ref))!;
+
+  const schemaEntries = Object.entries(doc.components ?? {}).filter(([key]) => componentsWithSchemas.includes(key));
+
+  schemaEntries.forEach(([key, component]) => {
+    Object.keys(component).map((name) => {
+      const ref = `#/components/${key}/${name}`;
+      getSchemaByRef(ref);
+    });
+  });
+
+  const directDependencies = new Map<string, Set<string>>();
+
+  // need to be done after all refs are resolved
+  schemaEntries.forEach(([key, component]) => {
+    Object.keys(component).map((name) => {
+      const ref = `#/components/${key}/${name}`;
+      const schema = getSchemaByRef(ref);
+      boxByRef.set(ref, openApiSchemaToTs({ schema, ctx: { factory, refs: { getInfosByRef } as any } }));
+
+      if (!directDependencies.has(ref)) {
+        directDependencies.set(ref, new Set<string>());
+      }
+      setSchemaDependencies(schema, directDependencies.get(ref)!);
+    });
+  });
+
+  const transitiveDependencies = getTransitiveDependencies(directDependencies);
+
+  return {
+    get: getSchemaByRef,
+    unwrap: <T extends ReferenceObject | {}>(component: T) => {
+      return (isReferenceObject(component) ? getSchemaByRef(component.$ref) : component) as Exclude<T, ReferenceObject>;
+    },
+    getInfosByRef: getInfosByRef,
+    infos: byRef,
+    /**
+     * 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: () => {
+      const schemaOrderedByDependencies = topologicalSort(transitiveDependencies).map((ref) => {
+        const infos = getInfosByRef(ref);
+        return [boxByRef.get(infos.ref)!, infos] as [schema: Box<AnyBoxDef>, infos: RefInfo];
+      });
+
+      return schemaOrderedByDependencies;
+    },
+    directDependencies,
+    transitiveDependencies,
+  };
+};
+
+export interface RefResolver extends ReturnType<typeof createRefResolver> {}
+
+const setSchemaDependencies = (schema: SchemaObject, deps: Set<string>) => {
+  const visit = (schema: SchemaObject | ReferenceObject): void => {
+    if (!schema) return;
+
+    if (isReferenceObject(schema)) {
+      deps.add(schema.$ref);
+      return;
+    }
+
+    if (schema.allOf) {
+      for (const allOf of schema.allOf) {
+        visit(allOf);
+      }
+
+      return;
+    }
+
+    if (schema.oneOf) {
+      for (const oneOf of schema.oneOf) {
+        visit(oneOf);
+      }
+
+      return;
+    }
+
+    if (schema.anyOf) {
+      for (const anyOf of schema.anyOf) {
+        visit(anyOf);
+      }
+
+      return;
+    }
+
+    if (schema.type === "array") {
+      if (!schema.items) return;
+      return void visit(schema.items);
+    }
+
+    if (schema.type === "object" || schema.properties || schema.additionalProperties) {
+      if (schema.properties) {
+        for (const property in schema.properties) {
+          visit(schema.properties[property]!);
+        }
+      }
+
+      if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        visit(schema.additionalProperties);
+      }
+    }
+  };
+
+  visit(schema);
+};
+
+const getTransitiveDependencies = (directDependencies: Map<string, Set<string>>) => {
+  const transitiveDependencies = new Map<string, Set<string>>();
+  const visitedsDeepRefs = new Set<string>();
+
+  directDependencies.forEach((deps, ref) => {
+    if (!transitiveDependencies.has(ref)) {
+      transitiveDependencies.set(ref, new Set());
+    }
+
+    const visit = (depRef: string) => {
+      transitiveDependencies.get(ref)!.add(depRef);
+
+      const deps = directDependencies.get(depRef);
+      if (deps && ref !== depRef) {
+        deps.forEach((transitive) => {
+          const key = ref + "__" + transitive;
+          if (visitedsDeepRefs.has(key)) return;
+
+          visitedsDeepRefs.add(key);
+          visit(transitive);
+        });
+      }
+    };
+
+    deps.forEach((dep) => visit(dep));
+  });
+
+  return transitiveDependencies;
+};

package/src/string-utils.ts

@@ -0,0 +1,42 @@
+import { capitalize, kebabToCamel } from "pastable/server";
+
+export const toSchemasRef = (name: string) => `#/components/schemas/${name}`;
+
+export function normalizeString(text: string) {
+  const prefixed = prefixStringStartingWithNumberIfNeeded(text);
+  return prefixed
+    .normalize("NFKD") // The normalize() using NFKD method returns the Unicode Normalization Form of a given string.
+    .trim() // Remove whitespace from both sides of a string (optional)
+    .replace(/\s+/g, "_") // Replace spaces with _
+    .replace(/-+/g, "_") // Replace - with _
+    .replace(/[^\w\-]+/g, "_") // Remove all non-word chars
+    .replace(/--+/g, "-"); // Replace multiple - with single -
+}
+
+const onlyWordRegex = /^\w+$/;
+export const wrapWithQuotesIfNeeded = (str: string) => {
+  if (str[0] === '"' && str[str.length - 1] === '"') return str;
+  if (onlyWordRegex.test(str)) {
+    return str;
+  }
+
+  return `"${str}"`;
+};
+
+const prefixStringStartingWithNumberIfNeeded = (str: string) => {
+  const firstAsNumber = Number(str[0]);
+  if (typeof firstAsNumber === "number" && !Number.isNaN(firstAsNumber)) {
+    return "_" + str;
+  }
+
+  return str;
+};
+
+const pathParamWithBracketsRegex = /({\w+})/g;
+const wordPrecededByNonWordCharacter = /[^\w\-]+/g;
+
+/** @example turns `/media-objects/{id}` into `MediaObjectsId` */
+export const pathToVariableName = (path: string) =>
+  capitalize(kebabToCamel(path).replaceAll("/", "")) // /media-objects/{id} -> MediaObjects{id}
+    .replace(pathParamWithBracketsRegex, (group) => capitalize(group.slice(1, -1))) // {id} -> Id
+    .replace(wordPrecededByNonWordCharacter, "_"); // "/robots.txt" -> "/robots_txt"

package/src/topological-sort.ts

@@ -0,0 +1,35 @@
+/** @see https://gist.github.com/RubyTuesdayDONO/5006455 */
+export function topologicalSort(graph: Map<string, Set<string>>) {
+  const sorted: string[] = [], // sorted list of IDs ( returned value )
+    visited: Record<string, boolean> = {}; // hash: id of already visited node => true
+
+  function visit(name: string, ancestors: string[]) {
+    if (!Array.isArray(ancestors)) ancestors = [];
+    ancestors.push(name);
+    visited[name] = true;
+
+    const deps = graph.get(name);
+    if (deps) {
+      deps.forEach((dep) => {
+        if (ancestors.includes(dep)) {
+          // if already in ancestors, a closed chain (recursive relation) exists
+          return;
+          // throw new Error(
+          //     'Circular dependency "' + dep + '" is required by "' + name + '": ' + ancestors.join(" -> ")
+          // );
+        }
+
+        // if already exists, do nothing
+        if (visited[dep]) return;
+        visit(dep, ancestors.slice(0)); // recursive call
+      });
+    }
+
+    if (!sorted.includes(name)) sorted.push(name);
+  }
+
+  // 2. topological sort
+  graph.forEach((_, name) => visit(name, []));
+
+  return sorted;
+}

package/src/ts-factory.ts

@@ -0,0 +1,24 @@
+import { createFactory, unwrap } from "./box-factory";
+import { wrapWithQuotesIfNeeded } from "./string-utils";
+
+export const tsFactory = createFactory({
+  union: (types) => types.map(unwrap).join(" | "),
+  intersection: (types) => types.map(unwrap).join(" & "),
+  array: (type) => `Array<${unwrap(type)}>`,
+  optional: (type) => `${unwrap(type)} | undefined`,
+  reference: (name, typeArgs) => `${name}${typeArgs ? `<${typeArgs.map(unwrap).join(", ")}>` : ""}`,
+  literal: (value) => value.toString(),
+  string: () => "string" as const,
+  number: () => "number" as const,
+  boolean: () => "boolean" as const,
+  unknown: () => "unknown" as const,
+  any: () => "any" as const,
+  never: () => "never" as const,
+  object: (props) => {
+    const propsString = Object.entries(props)
+      .map(([prop, type]) => `${wrapWithQuotesIfNeeded(prop)}: ${unwrap(type)}`)
+      .join(", ");
+
+    return `{ ${propsString} }`;
+  },
+});