openapi-typesafe 1.0.0-rc.4 → 1.0.0-rc.6

package/src/application/transform/document/path-template-refs.ts

@@ -0,0 +1,127 @@
+import { irRaw } from "../../../domain/ir/constructors.js";
+import type { IrDeclaration } from "../../../domain/ir/nodes.js";
+import type { PathsObject } from "../../../domain/openapi/path-item-object.js";
+import { documentEntries } from "../document-entries.js";
+import { HELPER_TYPES } from "../helper-types.js";
+import type { TransformContext } from "../transform-context.js";
+import type { PathKeyPart } from "./path-key-overlaps.js";
+import { booleanExpandedKeys, pathTemplateParts, templateText } from "./path-template-key.js";
+import { isUntakenKey, pathKeyOf } from "./paths.js";
+
+/**
+ * `--path-params-as-types` and `$ref`s into a templated path. Such a path is an index signature
+ * of `paths` (`` [path: `/pets/${number}`] ``), so `paths["/pets/{id}"]`, the type of a `$ref`
+ * to it, names no key: `{id}` is no number (TS2339). The reference indexes `paths` by the
+ * template instead, which reaches the signature; so does the type of an `--enum-values` array,
+ * which indexes `FlattenedDeepRequired<paths>`. With only `${string}` placeholders the URL
+ * itself matches the template and the output compiles, so it stays as it is.
+ */
+
+const PATHS_TYPE_NAME = "paths";
+
+/**
+ * The index of a templated path: the union of the keys it is written with. A `${boolean}` key the
+ * document's own path took (`/flags/true` next to `/flags/{enabled}`) is left out, so the index
+ * names only this path's members. Undefined when every key was taken: the path has no member.
+ */
+function templateIndexText(url: string, parts: readonly PathKeyPart[], takenUrls: Set<string>) {
+  const keys = booleanExpandedKeys(parts)
+    .map(pathKeyOf)
+    .filter((key) => isUntakenKey(url, key, takenUrls));
+  const texts = keys.map((key) =>
+    key.kind === "literal" ? JSON.stringify(key.url) : templateText(key.parts),
+  );
+  return texts.length === 0 ? undefined : texts.join(" | ");
+}
+
+/** The index of each templated path whose URL does not match its keys, by URL. */
+export function unmatchedTemplateKeys(
+  paths: PathsObject | null | undefined,
+  context: TransformContext,
+): ReadonlyMap<string, string> {
+  const keys = new Map<string, string>();
+  // A document may hold any value as `paths`; one that is no object has no paths.
+  if (!context.options.pathParamsAsTypes || typeof paths !== "object" || paths === null) {
+    return keys;
+  }
+  // The same walk as `pathMembers`, so a URL is taken by the same path as there.
+  const takenUrls = new Set(Object.keys(paths));
+  for (const [url, pathItem] of documentEntries(paths, context.options)) {
+    if (!pathItem || typeof pathItem !== "object" || "$ref" in pathItem || !url.includes("{")) {
+      continue;
+    }
+    const parts = pathTemplateParts(url, pathItem, context);
+    const index = parts === null ? undefined : templateIndexText(url, parts, takenUrls);
+    const isUnmatched = parts?.some(
+      (part) => part.kind === "placeholder" && part.type !== "string",
+    );
+    if (isUnmatched && index !== undefined) {
+      keys.set(url, index);
+    }
+  }
+  return keys;
+}
+
+function isNode(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}
+
+function isBarePathsReference(node: unknown): boolean {
+  const reference = node as Readonly<Record<string, unknown>> | undefined;
+  return (
+    reference?.kind === "reference" &&
+    reference.name === PATHS_TYPE_NAME &&
+    (reference.typeArguments as readonly unknown[] | undefined)?.length === 0
+  );
+}
+
+/**
+ * The `paths` root as a `$ref` or an `--enum-values` array indexes it: `paths`, or
+ * `FlattenedDeepRequired<paths>` (`rootType`), whose mapped keys are those of `paths`.
+ */
+function isPathsRoot(node: unknown): boolean {
+  const reference = node as Readonly<Record<string, unknown>> | undefined;
+  const typeArguments = reference?.typeArguments as readonly unknown[] | undefined;
+  const isDeepRoot =
+    reference?.kind === "reference" &&
+    reference.name === HELPER_TYPES.flattenedDeepRequired.name &&
+    typeArguments?.length === 1 &&
+    isBarePathsReference(typeArguments[0]);
+  return isDeepRoot || isBarePathsReference(node);
+}
+
+/** `paths["<url>"]`: an index of the `paths` root by a string literal. */
+function pathsIndexUrl(node: Readonly<Record<string, unknown>>): string | undefined {
+  const index = node.index as Readonly<Record<string, unknown>> | undefined;
+  const isPathsIndex =
+    node.kind === "indexedAccess" && isPathsRoot(node.object) && index?.kind === "stringLiteral";
+  return isPathsIndex ? (index.value as string) : undefined;
+}
+
+function rewrittenNode(value: unknown, keys: ReadonlyMap<string, string>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => rewrittenNode(item, keys));
+  }
+  if (!isNode(value)) {
+    return value;
+  }
+  const template = keys.get(pathsIndexUrl(value) ?? "");
+  if (template !== undefined) {
+    return { ...value, index: irRaw(template) };
+  }
+  // `origin` holds the compiler node a raw type was printed from; it is not IR.
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      key === "origin" ? child : rewrittenNode(child, keys),
+    ]),
+  );
+}
+
+/** The declarations with each `paths["<url>"]` of an unmatched template indexed by it. */
+export function withTemplatePathRefs<T extends IrDeclaration>(
+  declarations: readonly T[],
+  keys: ReadonlyMap<string, string>,
+): T[] {
+  return keys.size === 0 ? [...declarations] : (rewrittenNode(declarations, keys) as T[]);
+}

package/src/application/transform/document/paths-enum.ts

@@ -3,6 +3,7 @@ import type { OperationObject } from "../../../domain/openapi/operation-object.j
 import {
   ADDITIONAL_OPERATIONS_KEY,
   HTTP_METHODS,
+  type OperationEntry,
   type PathItemMethod,
   type PathsObject,
   QUERY_METHOD,
@@ -72,12 +73,19 @@ function pathItemEntries(pathItem: object): [string, unknown][] {
   });
 }
 
-function pathOperations(paths: PathsObject): PathOperation[] {
+/** Which operations get a member; the generator leaves out those `--exclude-deprecated` drops. */
+export type OperationFilter = (operation: OperationEntry) => boolean;
+
+const INCLUDES_EVERY_OPERATION: OperationFilter = () => true;
+
+function pathOperations(paths: PathsObject, isIncluded: OperationFilter): PathOperation[] {
   return Object.entries(paths).flatMap(([url, pathItem]) =>
-    pathItemEntries(pathItem).map(([method, operation]) => {
-      const operationId = (operation as OperationObject).operationId || undefined;
-      return { url, method, operationId };
-    }),
+    pathItemEntries(pathItem)
+      .filter(([, operation]) => isIncluded(operation as OperationEntry))
+      .map(([method, operation]) => {
+        const operationId = (operation as OperationObject).operationId || undefined;
+        return { url, method, operationId };
+      }),
   );
 }
 
@@ -108,8 +116,11 @@ function uniqueNames(operations: readonly PathOperation[]): string[] {
  * One enum member per operation: the URL as the value, the operation ID (or a key built from the
  * method and URL) as the name. Paths are in document order; `--alphabetize` does not apply.
  */
-export function apiPathsEnum(paths: PathsObject): ApiPathsEnum {
-  const operations = pathOperations(paths);
+export function apiPathsEnum(
+  paths: PathsObject,
+  isIncluded: OperationFilter = INCLUDES_EVERY_OPERATION,
+): ApiPathsEnum {
+  const operations = pathOperations(paths, isIncluded);
   const names = uniqueNames(operations);
   return {
     values: operations.map((operation) => operation.url),
@@ -121,7 +132,10 @@ export function apiPathsEnum(paths: PathsObject): ApiPathsEnum {
  * The `ApiPaths` enum declaration. Its own naming state is equivalent to the run's: the name is a
  * valid identifier, and member names only reset the state, never read it.
  */
-export function apiPathsEnumDeclaration(paths: PathsObject): IrEnumDeclaration {
+export function apiPathsEnumDeclaration(
+  paths: PathsObject,
+  isIncluded: OperationFilter = INCLUDES_EVERY_OPERATION,
+): IrEnumDeclaration {
   const naming = new EnumNaming();
-  return enumDeclaration(naming.enumName(API_PATHS_NAME), apiPathsEnum(paths), naming);
+  return enumDeclaration(naming.enumName(API_PATHS_NAME), apiPathsEnum(paths, isIncluded), naming);
 }

package/src/application/transform/document/paths.ts

@@ -1,20 +1,8 @@
 import { irIntersection, irObject, irProperty, irRaw } from "../../../domain/ir/constructors.js";
 import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { escapeTemplateText } from "../../../domain/ir/raw-text-escapes.js";
 import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
-import type { OperationObject } from "../../../domain/openapi/operation-object.js";
-import type {
-  ParameterObject,
-  ParameterOrReference,
-} from "../../../domain/openapi/parameter-object.js";
-import {
-  type PathItemObject,
-  type PathsObject,
-  pathItemOperations,
-} from "../../../domain/openapi/path-item-object.js";
-import type { ReferenceSchema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { FIX } from "../../../domain/output-fixes.js";
+import type { PathItemObject, PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { documentEntries } from "../document-entries.js";
 import { refType } from "../ref-type.js";
 import type { TransformContext } from "../transform-context.js";
@@ -26,124 +14,73 @@ import {
   coveringTemplateKeys,
   type PathKey,
   type PathKeyPart,
-  type PathPlaceholder,
 } from "./path-key-overlaps.js";
 import {
-  type PathParameterMatch,
-  placeholderText,
-  replacedTemplateParts,
-} from "./path-template-replace.js";
+  booleanExpandedKeys,
+  pathTemplateParts,
+  plainUrlOf,
+  templateText,
+} from "./path-template-key.js";
 import { assignabilityProof } from "./type-assignability.js";
 
-/** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
-const PATH_PARAMETER_RE = /\{[^{}]+\}/g;
-
-/** Placeholders by parameter schema type; anything else is a string placeholder. */
-const PLACEHOLDERS: ReadonlyMap<unknown, PathPlaceholder> = new Map([
-  ["number", "number"],
-  ["integer", "number"],
-  ["boolean", "boolean"],
-]);
-const STRING_PLACEHOLDER: PathPlaceholder = "string";
-
-function resolvedParameter(
-  parameter: ParameterOrReference,
-  context: TransformContext,
-): ParameterObject | undefined {
-  return "$ref" in parameter && parameter.$ref
-    ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
-    : (parameter as ParameterObject);
+/** A path's member, its key and its path item type for the overlap check. */
+export interface PathMember {
+  readonly url: string;
+  readonly member: IrMember;
+  readonly key: PathKey;
+  readonly type: IrType;
 }
 
-function addPathParameters(
-  parameters: readonly ParameterOrReference[],
-  byName: Map<string, ParameterObject>,
-  context: TransformContext,
-): void {
-  for (const parameter of parameters) {
-    const resolved = resolvedParameter(parameter, context);
-    if (resolved && resolved.in === "path") {
-      byName.set(resolved.name, resolved);
-    }
-  }
+/** The key of the parts: a plain URL, or a template with placeholders left. */
+export function pathKeyOf(parts: readonly PathKeyPart[]): PathKey {
+  const plainUrl = plainUrlOf(parts);
+  return plainUrl === null ? { kind: "template", parts } : literalKey(plainUrl);
 }
 
-/** Path parameters of the path item and of its operations; later definitions win. */
-function pathParameters(
-  pathItem: PathItemObject,
-  context: TransformContext,
-): Map<string, ParameterObject> {
-  const byName = new Map<string, ParameterObject>();
-  addPathParameters(pathItem.parameters ?? [], byName, context);
-  for (const { operation: entry } of pathItemOperations(pathItem)) {
-    const operation = (entry as ReferenceSchema).$ref
-      ? (context.refs.resolve((entry as ReferenceSchema).$ref) as OperationObject | undefined)
-      : (entry as OperationObject);
-    addPathParameters(operation?.parameters ?? [], byName, context);
+/** The member of one key of a path: a property for a plain URL, else an index signature. */
+function keyMember(url: string, parts: readonly PathKeyPart[], type: IrType, isReadonly: boolean) {
+  const key = pathKeyOf(parts);
+  if (key.kind === "literal") {
+    const member = irProperty(toPropertyName(key.url), type, { isReadonly });
+    return { url, member, key, type };
   }
-  return byName;
-}
-
-/** Each `{name}` of the URL and its own placeholder, from the URL split at the matches. */
-function splitTemplateParts(url: string, matches: readonly PathParameterMatch[]): PathKeyPart[] {
-  return url.split(PATH_PARAMETER_RE).flatMap((text, index): PathKeyPart[] => {
-    const type = matches[index]?.type;
-    const textPart: PathKeyPart = { kind: "text", text };
-    return type === undefined ? [textPart] : [textPart, { kind: "placeholder", type }];
-  });
+  const member: IrMember = {
+    kind: "indexSignature",
+    parameterName: "path",
+    parameterType: irRaw(templateText(parts)),
+    type,
+    isReadonly,
+    comments: [],
+  };
+  return { url, member, key, type };
 }
 
 /**
- * `--path-params-as-types`: the URL as template parts, each `{name}` replaced by a placeholder for
- * its parameter's type, the way the original replaces them unless the `path-param-type-names` fix
- * is on (see `replacedTemplateParts`). Null when the URL has no complete `{…}` placeholder.
+ * Whether a key of the path at `url` is written. A URL that `${boolean}` keys give is not when it
+ * is taken already: by a path of the document, which OpenAPI matches before a template (Paths
+ * Object), or by the keys of an earlier path. A property written twice does not compile (TS2300).
+ * `takenUrls` starts with the document's URLs and gets each expanded URL, in document order.
  */
-function pathTemplateParts(
-  url: string,
-  pathItem: PathItemObject,
-  context: TransformContext,
-): PathKeyPart[] | null {
-  const found = url.match(PATH_PARAMETER_RE);
-  if (!found) {
-    return null;
+export function isUntakenKey(url: string, key: PathKey, takenUrls: Set<string>): boolean {
+  const isExpandedUrl = key.kind === "literal" && key.url !== url;
+  if (!isExpandedUrl) {
+    return true;
   }
-  const parameters = pathParameters(pathItem, context);
-  const matches = found.map((match): PathParameterMatch => {
-    const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
-    return { match, type: PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER };
-  });
-  return context.options.fixes.has(FIX.PATH_PARAM_TYPE_NAMES)
-    ? splitTemplateParts(url, matches)
-    : replacedTemplateParts(url, matches);
+  const isTaken = takenUrls.has(key.url);
+  takenUrls.add(key.url);
+  return !isTaken;
 }
 
-/**
- * The template literal type of the parts. The original escaped only backticks: a backslash or
- * `${` in the URL could end the literal or open a placeholder, and add code to the generated file
- * (intentional fix). So the text parts are escaped.
- */
-function templateText(parts: readonly PathKeyPart[]): string {
-  const text = parts
-    .map((part) =>
-      part.kind === "text" ? escapeTemplateText(part.text) : placeholderText(part.type),
-    )
-    .join("");
-  return `\`${text}\``;
+function withoutTakenUrls(url: string, members: readonly PathMember[], takenUrls: Set<string>) {
+  return members.filter(({ key }) => isUntakenKey(url, key, takenUrls));
 }
 
-/** A path's member, its key and its path item type for the overlap check. */
-export interface PathMember {
-  readonly url: string;
-  readonly member: IrMember;
-  readonly key: PathKey;
-  readonly type: IrType;
-}
-
-function pathItemMember(
+/** The members of a path: one, or one per key of its `${boolean}` placeholders. */
+function pathItemMembers(
   url: string,
   pathItem: PathItemObject,
   context: TransformContext,
-): PathMember {
+): PathMember[] {
   const isReadonly = context.options.immutable;
   const type = pathItemType(
     pathItem,
@@ -156,17 +93,9 @@ function pathItemMember(
       : null;
   if (parts === null) {
     const member = irProperty(toPropertyName(url), type, { isReadonly });
-    return { url, member, key: literalKey(url), type };
+    return [{ url, member, key: literalKey(url), type }];
   }
-  const member: IrMember = {
-    kind: "indexSignature",
-    parameterName: "path",
-    parameterType: irRaw(templateText(parts)),
-    type,
-    isReadonly,
-    comments: [],
-  };
-  return { url, member, key: { kind: "template", parts }, type };
+  return booleanExpandedKeys(parts).map((key) => keyMember(url, key, type, isReadonly));
 }
 
 function literalKey(url: string): PathKey {
@@ -248,6 +177,7 @@ export function pathsObjectType(
 /** The members of the `paths` interface (OpenAPI 3.1 §4.8.8): one per path, by URL. */
 export function pathMembers(paths: PathsObject, context: TransformContext): PathMember[] {
   const members: PathMember[] = [];
+  const takenUrls = new Set(Object.keys(paths));
   for (const [url, pathItem] of documentEntries(paths, context.options)) {
     if (!pathItem || typeof pathItem !== "object") {
       continue;
@@ -259,10 +189,10 @@ export function pathMembers(paths: PathsObject, context: TransformContext): Path
       continue;
     }
     const startedAt = context.diagnostics.now();
-    const path = pathItemMember(url, pathItem, context);
-    members.push(path);
+    const pathMembersOfUrl = pathItemMembers(url, pathItem, context);
+    members.push(...withoutTakenUrls(url, pathMembersOfUrl, takenUrls));
     // The original reports only paths written as properties.
-    if (path.member.kind === "property") {
+    if (pathMembersOfUrl[0]?.key.kind === "literal" && pathMembersOfUrl[0].key.url === url) {
       context.diagnostics.debug(`Transformed path "${url}"`, context.diagnostics.now() - startedAt);
     }
   }

package/src/application/transform/document/webhooks.ts

@@ -4,19 +4,32 @@ import { toPropertyName } from "../../../domain/ir/property-name.js";
 import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { PathItemObject, PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
 import type { TransformContext } from "../transform-context.js";
 import { pathItemType } from "./path-item.js";
 
 /**
- * The `webhooks` interface body (OpenAPI 3.1 §4.8.1): one path item per webhook name. Unlike
- * `paths`, a `$ref` entry is read as a path item (so every method is `never`), as in the original,
- * and members carry no JSDoc.
+ * The `webhooks` interface body (OpenAPI 3.1 §4.8.1): one path item per webhook name. A `$ref`
+ * entry (often to `components/pathItems`) is the type it points at, as in `paths`; the original
+ * read it as a path item, so every method was `never`. Members carry no JSDoc.
  */
 export function webhooksType(webhooks: PathsObject, context: TransformContext): IrType {
   const members = documentEntries(webhooks, context.options).map(([name, pathItem]) => {
-    const location = { path: appendPointer(ROOT_POINTER, ["webhooks", name]) };
-    const type = pathItemType(pathItem as PathItemObject, location, context);
+    const type = webhookType(name, pathItem, context);
     return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
   });
   return irObject(members);
 }
+
+function webhookType(
+  name: string,
+  pathItem: PathsObject[string],
+  context: TransformContext,
+): IrType {
+  // A document may hold any value here; one that is no object is read as a path item, as before.
+  if (typeof pathItem === "object" && pathItem !== null && "$ref" in pathItem) {
+    return refType(pathItem.$ref);
+  }
+  const location = { path: appendPointer(ROOT_POINTER, ["webhooks", name]) };
+  return pathItemType(pathItem as PathItemObject, location, context);
+}

package/src/application/transform/footer/document-footer.ts

@@ -32,14 +32,23 @@ export interface FooterSink {
 }
 
 /**
- * The `--dedupe-enums` key of the original: the values in default sort order, each paired with
- * the metadata at its sorted position (not the value's own metadata), as the original does.
+ * The `--dedupe-enums` key. Two enums share a declaration only when the original shares it and
+ * each value has the same name and description in both. The original key pairs the values in
+ * default sort order with the metadata at the sorted position, not with the value's own metadata,
+ * so `[desc, asc]` and `[asc, desc]`, both named `[Desc, Asc]`, shared one declaration, and one of
+ * them typed `asc` as `Desc = "desc"`. The original also joined `name:description` texts with
+ * `,`, and a member name stood in for its value, so enums with other values (`"1"` and `1`, `A`
+ * and `1` both named `Active`, `["a", "b"]` and `["a:,b"]`) shared one key. As JSON, an equal key
+ * means the same values and metadata; enums the original kept apart still are.
  */
 function dedupeKey(request: EnumDeclarationRequest): string {
-  return [...request.values]
-    .sort(compareAsStrings)
-    .map((value, index) => metadataKey(String(value), request.metadata[index]))
-    .join(",");
+  const sorted = [...request.values].sort(compareAsStrings);
+  const originalPairs = sorted.map((value, index) => memberKey(value, request.metadata[index]));
+  const ownPairs = request.values
+    .map((value, index) => ({ value, member: memberKey(value, request.metadata[index]) }))
+    .sort((left, right) => compareAsStrings(left.value, right.value))
+    .map(({ member }) => member);
+  return JSON.stringify([originalPairs, ownPairs]);
 }
 
 /** `Array.prototype.sort` without a comparator: compares the values as strings. */
@@ -52,8 +61,9 @@ function compareAsStrings(left: string | number, right: string | number): number
   return leftText < rightText ? -1 : 1;
 }
 
-function metadataKey(value: string, metadata: EnumMemberMetadata | undefined): string {
-  return `${metadata?.name ?? value}:${metadata?.description || ""}`;
+/** One member: the value (JSON keeps `"1"` and `1` apart), its name and its description. */
+function memberKey(value: string | number, metadata: EnumMemberMetadata | undefined) {
+  return [value, metadata?.name ?? null, metadata?.description || null];
 }
 
 /** Separates a repeated `--enum-values` array name from its number, as root type aliases do. */

package/src/application/transform/helper-types.ts

@@ -65,10 +65,10 @@ export const READ_WRITE_MARKER_TYPES = lines(
   "};",
   "type ReadWritePrimitive = string | number | boolean | bigint | symbol | null | undefined;",
   "type ReadWriteLeaf = ReadWritePrimitive | ((...args: never) => unknown);",
-  "type ReadWriteMarkedKeys<T, Marker> = {",
-  "    [K in keyof T]-?: 0 extends 1 & T[K] ? never : NonNullable<T[K]> extends never ? never : " +
-    "NonNullable<T[K]> extends Marker ? K : never;",
-  "}[keyof T];",
+  "type ReadWriteMarkedKeys<T, Marker> = keyof {",
+  "    [K in keyof T as 0 extends 1 & T[K] ? never : NonNullable<T[K]> extends never ? never : " +
+    "NonNullable<T[K]> extends Marker ? K : never]: never;",
+  "};",
   'type ReadWriteResolveArray<T extends readonly unknown[], Resolved extends "read" | ' +
     '"write"> = T[number][] extends T ? T extends unknown[] ? ReadWriteResolve<T[number], ' +
     "Resolved>[] : readonly ReadWriteResolve<T[number], Resolved>[] : {",

package/src/application/transform/ref-pointer/generated-location.ts

@@ -1,6 +1,6 @@
 import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { RefResolver } from "../schema/schema-context.js";
-import { isJsonObject } from "./generated-shape.js";
+import { isJsonObject } from "./located-node.js";
 import {
   leadingSegmentsOf,
   type RefPointer,