openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/domain/output-fixes.ts

@@ -0,0 +1,95 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "./errors.js";
+
+/**
+ * Opt-in fixes of the output of valid schemas (ADR-021). Each one changes only the cases it names;
+ * without any, the output is the same as openapi-typescript 7.13 gives. In 2.0 they become the
+ * default.
+ */
+export const OutputFix = {
+  /** An `allOf` member with only `required` makes those properties of the others required. */
+  ALLOF_REQUIRED: "allof-required",
+  /** `anyOf` next to object keywords or `allOf` is intersected with them, not added to a union. */
+  ANYOF_PROPERTIES: "anyof-properties",
+  /** `--array-length` tuples have `min` to `max` items, nest right and follow `--immutable`. */
+  ARRAY_LENGTH_TUPLES: "array-length-tuples",
+  /** A schema two discriminators name gets one enum of their values, a mapping before its name. */
+  DISCRIMINATOR_VALUES: "discriminator-values",
+  /** Schemas of one root type name without the prefix each get an alias, the earlier numbered. */
+  ROOT_TYPE_NUMBERING: "root-type-numbering",
+  /** `unevaluatedProperties` types the keys no other keyword declares (an index signature). */
+  UNEVALUATED_PROPERTIES: "unevaluated-properties",
+} as const;
+export type OutputFix = (typeof OutputFix)[keyof typeof OutputFix];
+
+/** Every fix of this version, in the order the docs list them. */
+export const OUTPUT_FIXES: readonly OutputFix[] = Object.values(OutputFix);
+
+/** The name that turns on every fix of the installed version. */
+export const ALL_OUTPUT_FIXES = "all";
+
+/** A name the `fix` option accepts: one fix, or `all`. */
+export type OutputFixName = OutputFix | typeof ALL_OUTPUT_FIXES;
+
+const KNOWN_NAMES: ReadonlySet<string> = new Set<string>([...OUTPUT_FIXES, ALL_OUTPUT_FIXES]);
+
+function isOutputFixName(value: unknown): value is OutputFixName {
+  return typeof value === "string" && KNOWN_NAMES.has(value);
+}
+
+/** The fix names as given; fails with `OPTION_FIX_UNKNOWN` for any other value. */
+export function outputFixNamesOf(values: readonly unknown[]): readonly OutputFixName[] {
+  const unknown = values.filter((value) => !isOutputFixName(value));
+  if (unknown.length > 0) {
+    const names = unknown.map((value) => JSON.stringify(value)).join(", ");
+    const known = [...KNOWN_NAMES].join(", ");
+    throw new OpenAPITypesafeError({
+      code: ERROR_CODES.OPTION_FIX_UNKNOWN,
+      message: `Unknown fix ${names}. Known fixes: ${known}.`,
+      details: { unknown, known: [...KNOWN_NAMES] },
+    });
+  }
+  return values as readonly OutputFixName[];
+}
+
+/** The fixes the names turn on; `all` stands for every fix of this version. */
+export function resolveOutputFixes(names: readonly OutputFixName[]): ReadonlySet<OutputFix> {
+  return new Set(names.flatMap((name) => (name === ALL_OUTPUT_FIXES ? OUTPUT_FIXES : [name])));
+}
+
+/** A generator option that a fix works with; without it, the fix changes nothing (ADR-021). */
+export interface OutputFixRequirement {
+  readonly option: "arrayLength" | "rootTypes" | "rootTypesNoSchemaPrefix";
+  readonly flag: string;
+}
+
+const ROOT_TYPES = { option: "rootTypes", flag: "--root-types" } as const;
+const NO_SCHEMA_PREFIX = {
+  option: "rootTypesNoSchemaPrefix",
+  flag: "--root-types-no-schema-prefix",
+} as const;
+
+/** The options each fix needs, by fix name; `all` has none. */
+const REQUIREMENTS: Readonly<Partial<Record<OutputFixName, readonly OutputFixRequirement[]>>> = {
+  [OutputFix.ARRAY_LENGTH_TUPLES]: [{ option: "arrayLength", flag: "--array-length" }],
+  [OutputFix.ROOT_TYPE_NUMBERING]: [ROOT_TYPES, NO_SCHEMA_PREFIX],
+};
+
+function describeRequirement(requirement: OutputFixRequirement): string {
+  return `${requirement.option} (${requirement.flag})`;
+}
+
+/**
+ * A notice for each fix given by name with an option it needs off; it names the options that are
+ * off. `all` adds none: it means every fix that applies, so one that does not apply is expected.
+ */
+export function ineffectiveFixNotices(
+  names: readonly OutputFixName[],
+  isOptionOn: (option: OutputFixRequirement["option"]) => boolean,
+): string[] {
+  return [...new Set(names)].flatMap((name) => {
+    const missing = (REQUIREMENTS[name] ?? []).filter(({ option }) => !isOptionOn(option));
+    return missing.length === 0
+      ? []
+      : [`Fix "${name}" has no effect without ${missing.map(describeRequirement).join(" and ")}`];
+  });
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+import openapiTS from "./api/openapi-ts.js";
+
+/**
+ * The package entry: the public Node API (ENGINEERING_PLAN 4.1, `api/`). `openapiTS` is the default
+ * export, as in the original.
+ */
+
+export * from "./api/ast-to-string.js";
+export { COMMENT_HEADER } from "./api/comment-header.js";
+export { scanDiscriminators } from "./api/discriminator-scan.js";
+export type { FooterEntry } from "./api/footer-entry.js";
+export * from "./api/legacy-ts-helpers.js";
+export * from "./api/legacy-utils.js";
+export * from "./api/string-to-ast.js";
+export { default as transformSchema } from "./api/transform-schema.js";
+export {
+  BOOLEAN,
+  FALSE,
+  NEVER,
+  NULL,
+  NUMBER,
+  type OapiRefOptions,
+  oapiRef,
+  STRING,
+  TRUE,
+  type TypeInput,
+  tsIntersection,
+  tsLiteral,
+  tsNullable,
+  tsOmit,
+  tsRecord,
+  tsUnion,
+  tsWithRequired,
+  UNDEFINED,
+  UNKNOWN,
+} from "./api/type-helpers.js";
+export {
+  ERROR_CODES,
+  type ErrorCode,
+  type ErrorDetails,
+  isOpenAPITypesafeError,
+  OpenAPITypesafeError,
+} from "./domain/errors.js";
+export type * from "./domain/ir/nodes.js";
+export {
+  ALL_OUTPUT_FIXES,
+  OUTPUT_FIXES,
+  OutputFix,
+  type OutputFixName,
+} from "./domain/output-fixes.js";
+export { default as transformComponentsObject } from "./transform/components-object.js";
+export { default as transformHeaderObject } from "./transform/header-object.js";
+export { default as transformMediaTypeObject } from "./transform/media-type-object.js";
+export * from "./transform/operation-object.js";
+export { default as transformOperationObject } from "./transform/operation-object.js";
+export { default as transformParameterObject } from "./transform/parameter-object.js";
+export * from "./transform/path-item-object.js";
+export { default as transformPathItemObject } from "./transform/path-item-object.js";
+export { default as transformPathsObject } from "./transform/paths-object.js";
+export { default as transformRequestBodyObject } from "./transform/request-body-object.js";
+export { default as transformResponseObject } from "./transform/response-object.js";
+export { default as transformResponsesObject } from "./transform/responses-object.js";
+export * from "./transform/schema-object.js";
+export { default as transformSchemaObject } from "./transform/schema-object.js";
+export * from "./types.js";
+
+export default openapiTS;

package/src/transform/components-object.ts

@@ -0,0 +1,25 @@
+import { createTransformContext } from "../api/transform-context.js";
+import { componentsType } from "../application/transform/document/components.js";
+import type { IrType, IrTypeAliasDeclaration } from "../domain/ir/nodes.js";
+import { isEnumSchema, singularizeComponentKind } from "../domain/openapi/components-object.js";
+import type { ComponentsObject, GlobalContext } from "../types.js";
+
+export { isEnumSchema };
+
+/** `requestBodies` → `requestBody`; other keys drop the final `s`. */
+export const singularizeComponentKey = singularizeComponentKind;
+
+/**
+ * Transform the ComponentsObject (4.8.7)
+ * @see https://spec.openapis.org/oas/latest.html#components-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 6). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API: the `components` type, then the root type aliases.
+ */
+export default function transformComponentsObject(
+  componentsObject: ComponentsObject,
+  ctx: GlobalContext,
+): (IrType | IrTypeAliasDeclaration)[] {
+  const { type, rootTypes } = componentsType(componentsObject, createTransformContext(ctx));
+  return [type, ...rootTypes];
+}

package/src/transform/header-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { headerType } from "../application/transform/document/header.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { HeaderObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform HeaderObject nodes (4.8.21)
+ * @see https://spec.openapis.org/oas/v3.1.0#header-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformHeaderObject(
+  headerObject: HeaderObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return headerType(headerObject, schemaLocation(options), context);
+}

package/src/transform/media-type-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { mediaTypeType } from "../application/transform/document/media-type.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { MediaTypeObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform MediaTypeObject nodes (4.8.14)
+ * @see https://spec.openapis.org/oas/v3.1.0#media-type-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformMediaTypeObject(
+  mediaTypeObject: MediaTypeObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return mediaTypeType(mediaTypeObject, schemaLocation(options), context);
+}

package/src/transform/operation-object.ts

@@ -0,0 +1,36 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { operationMembers } from "../application/transform/document/operation.js";
+import { irObject, irProperty } from "../domain/ir/constructors.js";
+import type { IrMember } from "../domain/ir/nodes.js";
+import { toPropertyName } from "../domain/ir/property-name.js";
+import type { OperationObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform OperationObject nodes (4.8.10)
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformOperationObject(
+  operationObject: OperationObject,
+  options: TransformNodeOptions,
+): IrMember[] {
+  const context = createTransformContext(options.ctx);
+  return operationMembers(operationObject, schemaLocation(options), context);
+}
+
+/** inject an operation at the top level */
+export function injectOperationObject(
+  operationId: string,
+  operationObject: OperationObject,
+  options: TransformNodeOptions,
+): void {
+  const context = createTransformContext(options.ctx);
+  context.footer.addOperation(() => {
+    const members = operationMembers(operationObject, schemaLocation(options), context);
+    return irProperty(toPropertyName(operationId), irObject(members), {
+      isReadonly: options.ctx.immutable,
+    });
+  });
+}

package/src/transform/parameter-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { parameterType } from "../application/transform/document/parameter.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ParameterObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform ParameterObject nodes (4.8.12)
+ * @see https://spec.openapis.org/oas/v3.1.0#parameter-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformParameterObject(
+  parameterObject: ParameterObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return parameterType(parameterObject, schemaLocation(options), context);
+}

package/src/transform/parameters-array.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { parametersMember } from "../application/transform/document/parameters.js";
+import type { IrMember } from "../domain/ir/nodes.js";
+import type { ParameterObject, ReferenceObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Synthetic type. Array of (ParameterObject | ReferenceObject)s found in OperationObject and
+ * PathItemObject.
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 3). Same name and parameters as the original;
+ * returns IR (task 6.2). For the deep imports of this module.
+ */
+export function transformParametersArray(
+  parametersArray: (ParameterObject | ReferenceObject)[],
+  options: TransformNodeOptions,
+): IrMember[] {
+  const context = createTransformContext(options.ctx);
+  return [parametersMember(parametersArray, schemaLocation(options), context)];
+}

package/src/transform/path-item-object.ts

@@ -0,0 +1,22 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { pathItemType } from "../application/transform/document/path-item.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { HttpMethod } from "../domain/openapi/path-item-object.js";
+import type { PathItemObject, TransformNodeOptions } from "../types.js";
+
+export type Method = HttpMethod;
+
+/**
+ * Transform PathItem nodes (4.8.9)
+ * @see https://spec.openapis.org/oas/v3.1.0#path-item-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformPathItemObject(
+  pathItem: PathItemObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return pathItemType(pathItem, schemaLocation(options), context);
+}

package/src/transform/paths-enum.ts

@@ -0,0 +1,8 @@
+import { apiPathsEnumDeclaration } from "../application/transform/document/paths-enum.js";
+import type { IrEnumDeclaration } from "../domain/ir/nodes.js";
+import type { PathsObject } from "../types.js";
+
+/** The `ApiPaths` enum (`--make-paths-enum`), built in IR (ENGINEERING_PLAN Phase 5, step 6). */
+export default function makeApiPathsEnum(pathsObject: PathsObject): IrEnumDeclaration {
+  return apiPathsEnumDeclaration(pathsObject);
+}

package/src/transform/paths-object.ts

@@ -0,0 +1,15 @@
+import { createTransformContext } from "../api/transform-context.js";
+import { pathsType } from "../application/transform/document/paths.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { GlobalContext, PathsObject } from "../types.js";
+
+/**
+ * Transform the PathsObject node (4.8.8)
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformPathsObject(pathsObject: PathsObject, ctx: GlobalContext): IrType {
+  return pathsType(pathsObject, createTransformContext(ctx));
+}

package/src/transform/request-body-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { requestBodyType } from "../application/transform/document/request-body.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { RequestBodyObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform RequestBodyObject nodes (4.8.13)
+ * @see https://spec.openapis.org/oas/v3.1.0#request-body-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 4). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformRequestBodyObject(
+  requestBodyObject: RequestBodyObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return requestBodyType(requestBodyObject, schemaLocation(options), context);
+}

package/src/transform/response-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { responseType } from "../application/transform/document/response.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ResponseObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform ResponseObject nodes (4.8.17)
+ * @see https://spec.openapis.org/oas/v3.1.0#response-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 4). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformResponseObject(
+  responseObject: ResponseObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return responseType(responseObject, schemaLocation(options), context);
+}

package/src/transform/responses-object.ts

@@ -0,0 +1,19 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import { responsesType } from "../application/transform/document/responses.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ResponsesObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform ResponsesObject nodes (4.8.16)
+ * @see https://spec.openapis.org/oas/v3.1.0#responses-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 4). Same name and parameters as the original;
+ * returns IR (task 6.2). For the public API and for users who call it from callbacks.
+ */
+export default function transformResponsesObject(
+  responsesObject: ResponsesObject,
+  options: TransformNodeOptions,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  return responsesType(responsesObject, schemaLocation(options), context);
+}

package/src/transform/schema-object.ts

@@ -0,0 +1,36 @@
+import { createTransformContext, schemaLocation } from "../api/transform-context.js";
+import {
+  transformSchema,
+  transformSchemaShape,
+} from "../application/transform/schema/schema-transform.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { ReferenceObject, SchemaObject, TransformNodeOptions } from "../types.js";
+
+/**
+ * Transform SchemaObject nodes (4.8.24)
+ * @see https://spec.openapis.org/oas/v3.1.0#schema-object
+ *
+ * Ported to IR (ENGINEERING_PLAN Phase 5, step 2): the work happens in
+ * `application/transform/schema`; this keeps the original name and parameters, returning IR
+ * (task 6.2), for the public API and for users who call it from callbacks.
+ */
+export default function transformSchemaObject(
+  schemaObject: SchemaObject | ReferenceObject,
+  options: TransformNodeOptions,
+  fromAdditionalProperties = false,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  const location = schemaLocation(options);
+  return transformSchema(schemaObject, location, context, fromAdditionalProperties);
+}
+
+/** Transform SchemaObjects without the `postTransform` callback at the top level. */
+export function transformSchemaObjectWithComposition(
+  schemaObject: SchemaObject | ReferenceObject,
+  options: TransformNodeOptions,
+  fromAdditionalProperties = false,
+): IrType {
+  const context = createTransformContext(options.ctx);
+  const location = schemaLocation(options);
+  return transformSchemaShape(schemaObject, location, context, fromAdditionalProperties);
+}

package/src/transform/webhooks-object.ts

@@ -0,0 +1,15 @@
+import { createTransformContext } from "../api/transform-context.js";
+import { webhooksType } from "../application/transform/document/webhooks.js";
+import type { IrType } from "../domain/ir/nodes.js";
+import type { GlobalContext, WebhooksObject } from "../types.js";
+
+/**
+ * Transform the WebhooksObject node. Ported to IR (ENGINEERING_PLAN Phase 5, step 5); this keeps
+ * the original name and parameters, returning IR (task 6.2), for deep imports of this module.
+ */
+export default function transformWebhooksObject(
+  webhooksObject: WebhooksObject,
+  options: GlobalContext,
+): IrType {
+  return webhooksType(webhooksObject, createTransformContext(options));
+}