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

package/dist/index.d.cts

@@ -4,6 +4,22 @@ import { Config } from '@redocly/openapi-core';
 import * as TypeScript from 'typescript';
 import colors from 'ansi-colors';
 
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+interface Logger {
+    /**
+     * A debug line, with how long the step took when it was measured. A line without a group is
+     * written whenever debug output is on.
+     */
+    debug(message: string, group?: DebugGroup, durationMs?: number): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
 /**
  * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
  * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
@@ -268,6 +284,11 @@ declare const FIX: {
     readonly ARRAY_LENGTH_TUPLES: "array-length-tuples";
     /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
     readonly DEDUPE_ENUM_NAMES: "dedupe-enum-names";
+    /**
+     * `--default-non-nullable` finds parameters and request bodies by the document's structure, not
+     * by the words `parameters` and `requestBody` anywhere in a schema's location.
+     */
+    readonly DEFAULT_INPUT_LOCATIONS: "default-input-locations";
     /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
     readonly DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required";
     /**
@@ -280,6 +301,8 @@ declare const FIX: {
     readonly EXPLODED_QUERY_OBJECTS: "exploded-query-objects";
     /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
     readonly NULLABLE_ENUMS: "nullable-enums";
+    /** A parameter or header with `content`, not `schema`, is typed by its media type's schema. */
+    readonly PARAMETER_HEADER_CONTENT: "parameter-header-content";
     /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
     readonly PATH_PARAM_TYPE_NAMES: "path-param-type-names";
     /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
@@ -291,6 +314,11 @@ declare const FIX: {
      * points at, also where the original type compiles through an index signature.
      */
     readonly REF_POINTERS: "ref-pointers";
+    /**
+     * OpenAPI 3.1 and 3.2: keywords next to a `$ref` (`required`, `properties`) apply too, so the
+     * type is the reference intersected with them. OpenAPI 3.0 ignores them, as its spec says.
+     */
+    readonly REF_SIBLINGS: "ref-siblings";
     /** Schemas of one root type name without the prefix each get an alias, the earlier numbered. */
     readonly ROOT_TYPE_NUMBERING: "root-type-numbering";
     /** `unevaluatedProperties` types the keys no other keyword declares (an index signature). */
@@ -1298,7 +1326,7 @@ interface OpenAPITSBaseOptions {
      * still fail the run.
      */
     lint?: boolean;
-    /** (optional) Should logging be suppressed? (necessary for STDOUT) */
+    /** Hide warnings (default: false). Every line of the logger goes to stderr, never to stdout. */
     silent?: boolean;
     /** Accepted for compatibility with openapi-typescript; not read. */
     version?: number;
@@ -1467,22 +1495,6 @@ declare const DEPRECATION_CODES: {
 };
 type DeprecationCode = (typeof DEPRECATION_CODES)[keyof typeof DEPRECATION_CODES];
 
-/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
-type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
-/**
- * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
- * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
- */
-interface Logger {
-    /**
-     * A debug line, with how long the step took when it was measured. A line without a group is
-     * written whenever debug output is on.
-     */
-    debug(message: string, group?: DebugGroup, durationMs?: number): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-
 /**
  * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
  * @param {string|URL|object|Readable} source OpenAPI schema source:
@@ -1519,14 +1531,20 @@ declare const ERROR_CODES: {
     readonly ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY";
     readonly CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE";
     readonly OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN";
+    readonly OPTION_INVALID: "OPTION_INVALID";
     readonly TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND";
     readonly CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED";
+    readonly CLI_FLAG_INVALID: "CLI_FLAG_INVALID";
     readonly CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED";
     readonly CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND";
     readonly CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID";
     readonly CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING";
     readonly CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING";
     readonly CLI_INPUT_MISSING: "CLI_INPUT_MISSING";
+    readonly CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT";
+    readonly CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE";
+    readonly CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID";
+    readonly CLI_LOCATION_INVALID: "CLI_LOCATION_INVALID";
     readonly OUTPUT_STALE: "OUTPUT_STALE";
     readonly OUTPUT_READ_FAILED: "OUTPUT_READ_FAILED";
     readonly OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED";
@@ -1541,12 +1559,15 @@ interface OpenAPITypesafeErrorInit {
     readonly code: ErrorCode;
     readonly message: string;
     readonly details?: ErrorDetails;
-    /** The lower-level error this one reports, if any (kept as the standard `cause`). */
+    /**
+     * The lower-level error this one reports, if any (kept as the standard `cause`; a copy with URL
+     * secrets hidden when its chain names one, see cause-secrets.ts).
+     */
     readonly cause?: unknown;
 }
 /**
  * The base of every expected failure; check `code`, not the class or the message. The message
- * never shows the user info of a URL (`url-credentials.ts`).
+ * and the `cause` chain never show the user info or the query of a URL (`url-secrets.ts`).
  */
 declare class OpenAPITypesafeError extends Error {
     readonly code: ErrorCode;
@@ -1773,7 +1794,11 @@ declare function createDiscriminatorProperty(discriminator: DiscriminatorObject,
     path: string;
     readonly?: boolean;
 }): IrPropertySignature;
-/** Create a $ref pointer (even from other $refs) */
+/**
+ * Create a $ref pointer (even from other $refs). A part that contains `#/` is read as a `$ref`
+ * and contributes its decoded segments, so it throws URIError for a malformed percent escape; any
+ * other part is one segment. To append raw document keys, escape each one instead.
+ */
 declare function createRef(parts: (number | string | undefined | null)[]): string;
 /**
  * Print debug message (cribbed from the `debug` package, but without all the bells & whistles
@@ -1831,6 +1856,7 @@ declare function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclar
 /** Every warning code. */
 declare const WARNING_CODES: {
     readonly CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED";
+    readonly CLI_OUTPUT_IGNORED: "CLI_OUTPUT_IGNORED";
     readonly CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN";
     readonly DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID";
     readonly DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED";

package/dist/index.d.mts

@@ -4,6 +4,22 @@ import { Config } from '@redocly/openapi-core';
 import * as TypeScript from 'typescript';
 import colors from 'ansi-colors';
 
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+interface Logger {
+    /**
+     * A debug line, with how long the step took when it was measured. A line without a group is
+     * written whenever debug output is on.
+     */
+    debug(message: string, group?: DebugGroup, durationMs?: number): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
 /**
  * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
  * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
@@ -268,6 +284,11 @@ declare const FIX: {
     readonly ARRAY_LENGTH_TUPLES: "array-length-tuples";
     /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
     readonly DEDUPE_ENUM_NAMES: "dedupe-enum-names";
+    /**
+     * `--default-non-nullable` finds parameters and request bodies by the document's structure, not
+     * by the words `parameters` and `requestBody` anywhere in a schema's location.
+     */
+    readonly DEFAULT_INPUT_LOCATIONS: "default-input-locations";
     /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
     readonly DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required";
     /**
@@ -280,6 +301,8 @@ declare const FIX: {
     readonly EXPLODED_QUERY_OBJECTS: "exploded-query-objects";
     /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
     readonly NULLABLE_ENUMS: "nullable-enums";
+    /** A parameter or header with `content`, not `schema`, is typed by its media type's schema. */
+    readonly PARAMETER_HEADER_CONTENT: "parameter-header-content";
     /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
     readonly PATH_PARAM_TYPE_NAMES: "path-param-type-names";
     /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
@@ -291,6 +314,11 @@ declare const FIX: {
      * points at, also where the original type compiles through an index signature.
      */
     readonly REF_POINTERS: "ref-pointers";
+    /**
+     * OpenAPI 3.1 and 3.2: keywords next to a `$ref` (`required`, `properties`) apply too, so the
+     * type is the reference intersected with them. OpenAPI 3.0 ignores them, as its spec says.
+     */
+    readonly REF_SIBLINGS: "ref-siblings";
     /** Schemas of one root type name without the prefix each get an alias, the earlier numbered. */
     readonly ROOT_TYPE_NUMBERING: "root-type-numbering";
     /** `unevaluatedProperties` types the keys no other keyword declares (an index signature). */
@@ -1298,7 +1326,7 @@ interface OpenAPITSBaseOptions {
      * still fail the run.
      */
     lint?: boolean;
-    /** (optional) Should logging be suppressed? (necessary for STDOUT) */
+    /** Hide warnings (default: false). Every line of the logger goes to stderr, never to stdout. */
     silent?: boolean;
     /** Accepted for compatibility with openapi-typescript; not read. */
     version?: number;
@@ -1467,22 +1495,6 @@ declare const DEPRECATION_CODES: {
 };
 type DeprecationCode = (typeof DEPRECATION_CODES)[keyof typeof DEPRECATION_CODES];
 
-/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
-type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
-/**
- * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
- * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
- */
-interface Logger {
-    /**
-     * A debug line, with how long the step took when it was measured. A line without a group is
-     * written whenever debug output is on.
-     */
-    debug(message: string, group?: DebugGroup, durationMs?: number): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-
 /**
  * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
  * @param {string|URL|object|Readable} source OpenAPI schema source:
@@ -1519,14 +1531,20 @@ declare const ERROR_CODES: {
     readonly ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY";
     readonly CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE";
     readonly OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN";
+    readonly OPTION_INVALID: "OPTION_INVALID";
     readonly TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND";
     readonly CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED";
+    readonly CLI_FLAG_INVALID: "CLI_FLAG_INVALID";
     readonly CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED";
     readonly CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND";
     readonly CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID";
     readonly CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING";
     readonly CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING";
     readonly CLI_INPUT_MISSING: "CLI_INPUT_MISSING";
+    readonly CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT";
+    readonly CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE";
+    readonly CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID";
+    readonly CLI_LOCATION_INVALID: "CLI_LOCATION_INVALID";
     readonly OUTPUT_STALE: "OUTPUT_STALE";
     readonly OUTPUT_READ_FAILED: "OUTPUT_READ_FAILED";
     readonly OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED";
@@ -1541,12 +1559,15 @@ interface OpenAPITypesafeErrorInit {
     readonly code: ErrorCode;
     readonly message: string;
     readonly details?: ErrorDetails;
-    /** The lower-level error this one reports, if any (kept as the standard `cause`). */
+    /**
+     * The lower-level error this one reports, if any (kept as the standard `cause`; a copy with URL
+     * secrets hidden when its chain names one, see cause-secrets.ts).
+     */
     readonly cause?: unknown;
 }
 /**
  * The base of every expected failure; check `code`, not the class or the message. The message
- * never shows the user info of a URL (`url-credentials.ts`).
+ * and the `cause` chain never show the user info or the query of a URL (`url-secrets.ts`).
  */
 declare class OpenAPITypesafeError extends Error {
     readonly code: ErrorCode;
@@ -1773,7 +1794,11 @@ declare function createDiscriminatorProperty(discriminator: DiscriminatorObject,
     path: string;
     readonly?: boolean;
 }): IrPropertySignature;
-/** Create a $ref pointer (even from other $refs) */
+/**
+ * Create a $ref pointer (even from other $refs). A part that contains `#/` is read as a `$ref`
+ * and contributes its decoded segments, so it throws URIError for a malformed percent escape; any
+ * other part is one segment. To append raw document keys, escape each one instead.
+ */
 declare function createRef(parts: (number | string | undefined | null)[]): string;
 /**
  * Print debug message (cribbed from the `debug` package, but without all the bells & whistles
@@ -1831,6 +1856,7 @@ declare function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclar
 /** Every warning code. */
 declare const WARNING_CODES: {
     readonly CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED";
+    readonly CLI_OUTPUT_IGNORED: "CLI_OUTPUT_IGNORED";
     readonly CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN";
     readonly DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID";
     readonly DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED";

package/dist/index.d.ts

@@ -4,6 +4,22 @@ import { Config } from '@redocly/openapi-core';
 import * as TypeScript from 'typescript';
 import colors from 'ansi-colors';
 
+/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
+type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
+/**
+ * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
+ * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
+ */
+interface Logger {
+    /**
+     * A debug line, with how long the step took when it was measured. A line without a group is
+     * written whenever debug output is on.
+     */
+    debug(message: string, group?: DebugGroup, durationMs?: number): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
 /**
  * Type IR: the closed set of immutable nodes that describes the TypeScript types and declarations
  * the generator emits (ENGINEERING_PLAN §4.2, ADR-002). Nodes are plain readonly data with a `kind`
@@ -268,6 +284,11 @@ declare const FIX: {
     readonly ARRAY_LENGTH_TUPLES: "array-length-tuples";
     /** `--dedupe-enums` names a shared enum by all of its schemas, not by the first one. */
     readonly DEDUPE_ENUM_NAMES: "dedupe-enum-names";
+    /**
+     * `--default-non-nullable` finds parameters and request bodies by the document's structure, not
+     * by the words `parameters` and `requestBody` anywhere in a schema's location.
+     */
+    readonly DEFAULT_INPUT_LOCATIONS: "default-input-locations";
     /** `required` next to an `allOf` `$ref` to a discriminator member still gives `WithRequired`. */
     readonly DISCRIMINATOR_MEMBER_REQUIRED: "discriminator-member-required";
     /**
@@ -280,6 +301,8 @@ declare const FIX: {
     readonly EXPLODED_QUERY_OBJECTS: "exploded-query-objects";
     /** `--enum` declares an enum that lists `null` without it, and the type adds `| null`. */
     readonly NULLABLE_ENUMS: "nullable-enums";
+    /** A parameter or header with `content`, not `schema`, is typed by its media type's schema. */
+    readonly PARAMETER_HEADER_CONTENT: "parameter-header-content";
     /** `--path-params-as-types` gives each `{name}` its placeholder, `{number}` included. */
     readonly PATH_PARAM_TYPE_NAMES: "path-param-type-names";
     /** A `prefixItems` tuple is open unless `items` or `unevaluatedItems` closes it (2020-12). */
@@ -291,6 +314,11 @@ declare const FIX: {
      * points at, also where the original type compiles through an index signature.
      */
     readonly REF_POINTERS: "ref-pointers";
+    /**
+     * OpenAPI 3.1 and 3.2: keywords next to a `$ref` (`required`, `properties`) apply too, so the
+     * type is the reference intersected with them. OpenAPI 3.0 ignores them, as its spec says.
+     */
+    readonly REF_SIBLINGS: "ref-siblings";
     /** Schemas of one root type name without the prefix each get an alias, the earlier numbered. */
     readonly ROOT_TYPE_NUMBERING: "root-type-numbering";
     /** `unevaluatedProperties` types the keys no other keyword declares (an index signature). */
@@ -1298,7 +1326,7 @@ interface OpenAPITSBaseOptions {
      * still fail the run.
      */
     lint?: boolean;
-    /** (optional) Should logging be suppressed? (necessary for STDOUT) */
+    /** Hide warnings (default: false). Every line of the logger goes to stderr, never to stdout. */
     silent?: boolean;
     /** Accepted for compatibility with openapi-typescript; not read. */
     version?: number;
@@ -1467,22 +1495,6 @@ declare const DEPRECATION_CODES: {
 };
 type DeprecationCode = (typeof DEPRECATION_CODES)[keyof typeof DEPRECATION_CODES];
 
-/** The debug groups of the original `DEBUG=openapi-ts:<group>` output. */
-type DebugGroup = "redoc" | "lint" | "bundle" | "ts";
-/**
- * Where the generator reports progress and problems (ENGINEERING_PLAN 4.5). Whether warnings are
- * printed (`silent`) and debug output (`DEBUG`) is decided by the adapter, when it is created.
- */
-interface Logger {
-    /**
-     * A debug line, with how long the step took when it was measured. A line without a group is
-     * written whenever debug output is on.
-     */
-    debug(message: string, group?: DebugGroup, durationMs?: number): void;
-    warn(message: string): void;
-    error(message: string): void;
-}
-
 /**
  * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)
  * @param {string|URL|object|Readable} source OpenAPI schema source:
@@ -1519,14 +1531,20 @@ declare const ERROR_CODES: {
     readonly ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY";
     readonly CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE";
     readonly OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN";
+    readonly OPTION_INVALID: "OPTION_INVALID";
     readonly TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND";
     readonly CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED";
+    readonly CLI_FLAG_INVALID: "CLI_FLAG_INVALID";
     readonly CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED";
     readonly CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND";
     readonly CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID";
     readonly CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING";
     readonly CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING";
     readonly CLI_INPUT_MISSING: "CLI_INPUT_MISSING";
+    readonly CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT";
+    readonly CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE";
+    readonly CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID";
+    readonly CLI_LOCATION_INVALID: "CLI_LOCATION_INVALID";
     readonly OUTPUT_STALE: "OUTPUT_STALE";
     readonly OUTPUT_READ_FAILED: "OUTPUT_READ_FAILED";
     readonly OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED";
@@ -1541,12 +1559,15 @@ interface OpenAPITypesafeErrorInit {
     readonly code: ErrorCode;
     readonly message: string;
     readonly details?: ErrorDetails;
-    /** The lower-level error this one reports, if any (kept as the standard `cause`). */
+    /**
+     * The lower-level error this one reports, if any (kept as the standard `cause`; a copy with URL
+     * secrets hidden when its chain names one, see cause-secrets.ts).
+     */
     readonly cause?: unknown;
 }
 /**
  * The base of every expected failure; check `code`, not the class or the message. The message
- * never shows the user info of a URL (`url-credentials.ts`).
+ * and the `cause` chain never show the user info or the query of a URL (`url-secrets.ts`).
  */
 declare class OpenAPITypesafeError extends Error {
     readonly code: ErrorCode;
@@ -1773,7 +1794,11 @@ declare function createDiscriminatorProperty(discriminator: DiscriminatorObject,
     path: string;
     readonly?: boolean;
 }): IrPropertySignature;
-/** Create a $ref pointer (even from other $refs) */
+/**
+ * Create a $ref pointer (even from other $refs). A part that contains `#/` is read as a `$ref`
+ * and contributes its decoded segments, so it throws URIError for a malformed percent escape; any
+ * other part is one segment. To append raw document keys, escape each one instead.
+ */
 declare function createRef(parts: (number | string | undefined | null)[]): string;
 /**
  * Print debug message (cribbed from the `debug` package, but without all the bells & whistles
@@ -1831,6 +1856,7 @@ declare function transformSchema(schema: OpenAPI3, ctx: GlobalContext): IrDeclar
 /** Every warning code. */
 declare const WARNING_CODES: {
     readonly CLI_INPUT_IGNORED: "CLI_INPUT_IGNORED";
+    readonly CLI_OUTPUT_IGNORED: "CLI_OUTPUT_IGNORED";
     readonly CONFIG_SETTING_UNKNOWN: "CONFIG_SETTING_UNKNOWN";
     readonly DISCRIMINATOR_MAPPING_INVALID: "DISCRIMINATOR_MAPPING_INVALID";
     readonly DISCRIMINATOR_VALUE_NOT_ALLOWED: "DISCRIMINATOR_VALUE_NOT_ALLOWED";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-typesafe",
   "description": "Convert OpenAPI 3.0, 3.1 & 3.2 schemas to TypeScript",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.5",
   "author": {
     "name": "Fedor Chishchin",
     "url": "https://github.com/fedorello"
@@ -35,6 +35,7 @@
     "./*": "./*"
   },
   "files": [
+    "CHANGELOG.md",
     "bin",
     "dist",
     "src"
@@ -61,7 +62,7 @@
   },
   "peerDependencies": {
     "@typescript/typescript6": "^6.0.0",
-    "typescript": ">=5.0.0"
+    "typescript": ">=5.4.0"
   },
   "peerDependenciesMeta": {
     "@typescript/typescript6": {
@@ -106,11 +107,9 @@
     "lint:ts": "tsc --noEmit && tsc -p tsconfig.strict.json",
     "test": "pnpm run test:js && pnpm run test:examples && pnpm run test:exports",
     "test:js": "vitest run",
-    "test:exports": "pnpm run build && ../../scripts/check-exports.sh",
+    "test:exports": "../../scripts/check-exports.sh",
     "test:examples": "tsc -p tsconfig.examples.json --noEmit",
     "update:examples": "pnpm run build && pnpm run download:schemas && vite-node ./scripts/update-examples.ts",
-    "prepublish": "pnpm run build",
-    "version": "pnpm run build",
     "lint:deps": "depcruise src --config .dependency-cruiser.cjs",
     "test:coverage": "vitest run --coverage",
     "lint:sizes": "vite-node scripts/size-rules/check-sizes.ts src"

package/src/adapters/node-file-system/file-claims.ts

@@ -0,0 +1,138 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ClaimedFile } from "../../application/ports/file-system.js";
+import { creationPath, type FileNumber, type PathQueries } from "./file-identity.js";
+
+/**
+ * Claiming an output on Node's `fs` (ADR-043, decision 1): the file is opened for appending,
+ * which creates it when it is missing (also through a symbolic link) and never truncates it.
+ * The device and file number of the open file are its identity. A claim or a write that fails
+ * removes the directories it created.
+ */
+
+/**
+ * The directories that do not exist yet on the way to `directory`, deepest first: the ones a
+ * recursive `fs.mkdirSync` creates. They are listed before it runs, in the form of `directory`
+ * itself: on Windows the path that `fs.mkdirSync` returns did not match that form, so comparing
+ * with it found no new directory and a failed run left them behind.
+ */
+export function missingDirectories(
+  directory: string,
+  exists: (candidate: string) => boolean,
+): string[] {
+  const missing: string[] = [];
+  for (let current = directory; !exists(current); current = path.dirname(current)) {
+    missing.push(current);
+    if (path.dirname(current) === current) {
+      break;
+    }
+  }
+  return missing;
+}
+
+/**
+ * The identity of an open file: its device and file number, or its stored path on a file system
+ * that reports the file number 0 (FAT, some network shares), which proves nothing.
+ */
+export function claimIdentity(number: FileNumber, storedPath: () => string): string {
+  return number.file === 0n ? `path:${storedPath()}` : `${number.device}:${number.file}`;
+}
+
+function identityOf(descriptor: number, filePath: string): string {
+  const status = fs.fstatSync(descriptor, { bigint: true });
+  return claimIdentity({ device: status.dev, file: status.ino }, () =>
+    fs.realpathSync.native(filePath),
+  );
+}
+
+function errorCodeOf(error: unknown): unknown {
+  return error instanceof Error && "code" in error ? error.code : undefined;
+}
+
+/** Remove the new directories, deepest first, until one holds another file. */
+function removeDirectories(directories: readonly string[]): void {
+  for (const directory of directories) {
+    try {
+      fs.rmdirSync(directory);
+    } catch (error) {
+      const code = errorCodeOf(error);
+      // Another output or the user put a file there since: the directory and its parents stay.
+      if (code === "ENOTEMPTY" || code === "EEXIST") {
+        return;
+      }
+      // Removed since: nothing to remove, but its parents may still be empty. Windows also gives
+      // ENOENT for a file put in its place, which must fail like any other path it cannot remove.
+      if (code !== "ENOENT" || fs.lstatSync(directory, { throwIfNoEntry: false }) !== undefined) {
+        throw error;
+      }
+    }
+  }
+}
+
+/**
+ * Create `directory` and give the directories that this created. Through a link to a missing
+ * directory it creates the link's target, as a write through the link would, so the path to
+ * create and the new directories are real paths, where links are already followed. A recursive
+ * `mkdir` that fails part of the way (a directory name too long for the file system) keeps the
+ * directories above the failing one, so the ones that exist now are removed here.
+ */
+function createDirectory(directory: string, queries: PathQueries): string[] {
+  const target = creationPath(directory, queries);
+  const missing = missingDirectories(target, fs.existsSync);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+  } catch (error) {
+    removeDirectories(missing.filter((created) => fs.existsSync(created)));
+    throw error;
+  }
+  return missing;
+}
+
+/** Open `filePath` for appending, which creates it, and give its identity and whether it is new. */
+function openClaim(filePath: string): { identity: string; createdFile: string | undefined } {
+  const isCreated = !fs.existsSync(filePath);
+  const descriptor = fs.openSync(filePath, "a");
+  try {
+    const identity = identityOf(descriptor, filePath);
+    // A link to a missing file created its target: that file is what the claim removes.
+    return { identity, createdFile: isCreated ? fs.realpathSync.native(filePath) : undefined };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+/**
+ * Claim the file at `filePath`; the caller turns a failure into a typed error. A claim that fails
+ * after creating directories (a file name too long for the file system) removes them again.
+ */
+export function claimFileAt(filePath: string, queries: PathQueries): ClaimedFile {
+  const directories = createDirectory(path.dirname(filePath), queries);
+  let opened: ReturnType<typeof openClaim>;
+  try {
+    opened = openClaim(filePath);
+  } catch (error) {
+    removeDirectories(directories);
+    throw error;
+  }
+  const { identity, createdFile } = opened;
+  return {
+    identity,
+    release: () => {
+      if (createdFile !== undefined) {
+        fs.rmSync(createdFile, { force: true });
+      }
+      removeDirectories(directories);
+    },
+  };
+}
+
+/** Write `contents` to `filePath`, creating its directory; a failed write removes what it made. */
+export function writeFileAt(filePath: string, contents: string, queries: PathQueries): void {
+  const directories = createDirectory(path.dirname(filePath), queries);
+  try {
+    fs.writeFileSync(filePath, contents, "utf8");
+  } catch (error) {
+    removeDirectories(directories);
+    throw error;
+  }
+}