openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.5

package/src/application/transform/document/path-item.ts

@@ -1,12 +1,8 @@
 import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrMember, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
-import { createRef } from "../../../domain/openapi/json-pointer.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 {
   ADDITIONAL_OPERATIONS_KEY,
   HTTP_METHODS,
@@ -21,13 +17,19 @@ import type { SchemaLocation } from "../schema/schema-context.js";
 import type { TransformContext } from "../transform-context.js";
 import { documentMember } from "./document-member.js";
 import { operationMembers } from "./operation.js";
+import { mergedParameters } from "./parameter-entries.js";
 import { parametersMember } from "./parameters.js";
 
 /** Redocly reads `#` in an operation ID as a pointer, so it is replaced (upstream issue #1542). */
 const HASH_RE = /#/g;
 
+/** The `operations` key an `operationId` asks for, before a repeated one gets a number. */
+export function operationKeyOf(operationId: string): string {
+  return operationId.replace(HASH_RE, "/");
+}
+
 /** Whether the method has an operation, not removed by `--exclude-deprecated`. */
-function isIncluded(
+export function isIncludedOperation(
   operation: OperationEntry | undefined,
   context: TransformContext,
 ): operation is OperationEntry {
@@ -41,26 +43,6 @@ function isIncluded(
   return !(context.options.excludeDeprecated && resolved?.deprecated);
 }
 
-/**
- * Path item parameters followed by the operation's, keyed by location and name, so an operation
- * parameter replaces the path item parameter it redefines (upstream issue #1798).
- */
-function mergedParameters(
-  pathItem: PathItemObject,
-  operation: OperationObject,
-  context: TransformContext,
-): ParameterOrReference[] {
-  const byKey = new Map<string, ParameterOrReference>();
-  for (const parameter of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
-    const resolved =
-      "$ref" in parameter
-        ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
-        : parameter;
-    byKey.set(`${resolved?.in}-${resolved?.name}`, parameter);
-  }
-  return [...byKey.values()];
-}
-
 /**
  * An operation with an `operationId` goes into the `operations` interface and is referenced from
  * the path item; others are written inline.
@@ -71,17 +53,17 @@ function operationType(
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context) };
+  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context.refs) };
   if (!operation.operationId) {
     return irObject(operationMembers(merged, location, context));
   }
-  const operationId = operation.operationId.replace(HASH_RE, "/");
+  const operationId = context.footer.operationKey(operationKeyOf(operation.operationId));
   context.footer.addOperation(() =>
     irProperty(toPropertyName(operationId), irObject(operationMembers(merged, location, context)), {
       isReadonly: context.options.immutable,
     }),
   );
-  return refType(createRef(["operations", operationId]));
+  return refType(appendPointer(ROOT_POINTER, ["operations", operationId]));
 }
 
 /** An included operation, the member name it gets and its location below the path item. */
@@ -112,11 +94,11 @@ function methodMember(
   context: TransformContext,
 ): IrPropertySignature {
   const operation = pathItem[method];
-  if (!isIncluded(operation, context)) {
+  if (!isIncludedOperation(operation, context)) {
     const isReadonly = context.options.immutable;
     return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
   }
-  const path = createRef([location.path, method]);
+  const path = appendPointer(location.path, [method]);
   return operationMember({ name: method, operation, path }, pathItem, location, context);
 }
 
@@ -131,9 +113,9 @@ function additionalOperationsMember(
 ): IrPropertySignature | null {
   const entries = documentEntries(pathItem.additionalOperations ?? {}, context.options);
   const members = entries
-    .filter(([, operation]) => isIncluded(operation, context))
+    .filter(([, operation]) => isIncludedOperation(operation, context))
     .map(([method, operation]) => {
-      const path = createRef([location.path, ADDITIONAL_OPERATIONS_KEY, method]);
+      const path = appendPointer(location.path, [ADDITIONAL_OPERATIONS_KEY, method]);
       return operationMember({ name: method, operation, path }, pathItem, location, context);
     });
   return members.length > 0
@@ -152,7 +134,7 @@ export function pathItemType(
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const parametersLocation = { ...location, path: createRef([location.path, "parameters"]) };
+  const parametersLocation = { ...location, path: appendPointer(location.path, ["parameters"]) };
   const members: IrMember[] = [
     parametersMember(pathItem.parameters ?? [], parametersLocation, context),
     ...HTTP_METHODS.map((method) => methodMember(method, pathItem, location, context)),

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

@@ -0,0 +1,152 @@
+import { escapeTemplateText } from "../../../domain/ir/raw-text-escapes.js";
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  type PathItemObject,
+  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 { TransformContext } from "../transform-context.js";
+import type { PathKeyPart, PathPlaceholder } from "./path-key-overlaps.js";
+import {
+  type PathParameterMatch,
+  placeholderText,
+  replacedTemplateParts,
+} from "./path-template-replace.js";
+
+/** The `--path-params-as-types` key of a path: its URL with a placeholder per parameter. */
+
+/** `[^{}]` 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);
+}
+
+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);
+    }
+  }
+}
+
+/** 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);
+  }
+  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 }];
+  });
+}
+
+/**
+ * `--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.
+ */
+export function pathTemplateParts(
+  url: string,
+  pathItem: PathItemObject,
+  context: TransformContext,
+): PathKeyPart[] | null {
+  const found = url.match(PATH_PARAMETER_RE);
+  if (!found) {
+    return null;
+  }
+  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);
+}
+
+/**
+ * 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.
+ */
+export function templateText(parts: readonly PathKeyPart[]): string {
+  const text = parts
+    .map((part) =>
+      part.kind === "text" ? escapeTemplateText(part.text) : placeholderText(part.type),
+    )
+    .join("");
+  return `\`${text}\``;
+}
+
+const BOOLEAN_TEXTS = ["true", "false"] as const;
+
+const isBooleanPlaceholder = (part: PathKeyPart): boolean =>
+  part.kind === "placeholder" && part.type === "boolean";
+
+/**
+ * The keys of a template whose only placeholders are `${boolean}`, with each written as `true`
+ * and as `false`. Such a template is a union of literals, and an index signature takes none
+ * (TS1337), so the original's `` [path: `/flags/${boolean}`] `` did not compile. A path with n
+ * boolean parameters gets 2ⁿ plain URLs (`/flags/true`), all with the same path item type. Next to
+ * another placeholder the template is a pattern, a valid signature that admits the same URLs, so
+ * those parts stay one key.
+ */
+export function booleanExpandedKeys(parts: readonly PathKeyPart[]): PathKeyPart[][] {
+  const isBooleanOnly = parts.every((part) => part.kind === "text" || isBooleanPlaceholder(part));
+  if (!isBooleanOnly) {
+    return [[...parts]];
+  }
+  return parts.reduce<PathKeyPart[][]>(
+    (keys, part) => {
+      const choices: readonly PathKeyPart[] = isBooleanPlaceholder(part)
+        ? BOOLEAN_TEXTS.map((text) => ({ kind: "text", text }))
+        : [part];
+      return keys.flatMap((key) => choices.map((choice) => [...key, choice]));
+    },
+    [[]],
+  );
+}
+
+/** The URL of parts without placeholders; null when one is left. */
+export function plainUrlOf(parts: readonly PathKeyPart[]): string | null {
+  const texts = parts.map((part) => (part.kind === "text" ? part.text : null));
+  return texts.includes(null) ? null : texts.join("");
+}

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

@@ -0,0 +1,106 @@
+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 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. 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;
+}
+
+/** `paths["<url>"]`: an index of the `paths` root by a string literal. */
+function pathsIndexUrl(node: Readonly<Record<string, unknown>>): string | undefined {
+  const object = node.object as Readonly<Record<string, unknown>> | undefined;
+  const index = node.index as Readonly<Record<string, unknown>> | undefined;
+  const isPathsIndex =
+    node.kind === "indexedAccess" &&
+    object?.kind === "reference" &&
+    object.name === PATHS_TYPE_NAME &&
+    (object.typeArguments as readonly unknown[] | undefined)?.length === 0 &&
+    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,
@@ -15,7 +16,7 @@ import type { EnumMemberMetadata } from "../schema/schema-context.js";
 const PARAMETER_SEGMENT_RE = /^(?:{(.+)}|:(.+))$/;
 /** Characters not allowed in an enum key, or a `{param}` / `:param` part (first match only). */
 const INVALID_KEY_PART_RE = /{.*}|:.*|[^a-zA-Z\d_]+/;
-const API_PATHS_NAME = "ApiPaths";
+export const API_PATHS_NAME = "ApiPaths";
 const METHODS: ReadonlySet<string> = new Set<PathItemMethod>([...HTTP_METHODS, QUERY_METHOD]);
 
 /** The members of the `ApiPaths` enum (`--make-paths-enum`). */
@@ -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);
 }