@kubb/plugin-ts 5.1.0-canary.20261024T075028 → 5.1.0

package/dist/index.d.cts

@@ -1,13 +1,233 @@
 import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "kubb/kit";
 import { KubbReactNode } from "kubb/jsx";
-import ts from "@typescript/typescript6";
+declare namespace factory_d_exports {
+  export { TsNode, appendJSDocToNode, buildIndexSignatures, buildMemberNodes, buildPropertyType, buildTupleNode, constToTypeNode, createArrayDeclaration, createEnumDeclaration, createIntersectionDeclaration, createOmitDeclaration, createPropertySignature, createRaw, createTypeDeclaration, createTypeLiteralNode, createTypeReferenceNode, createUnionDeclaration, createUrlTemplateType, dateOrStringNode, isNonNullable, keywordTypeNodes, print, wrapNullableOptional };
+}
+/**
+ * A TS-ESTree node, the AST shape `yuku-codegen` prints. Nodes built here carry no source positions.
+ */
+type TsNode = {
+  type: string;
+  [key: string]: unknown;
+};
+declare function isNonNullable<T>(value: T | null | undefined): value is T;
+/**
+ * Prints `node` as TypeScript source with single quotes and two-space indentation.
+ */
+declare function print(node: TsNode): string;
+/**
+ * Wraps already printed TypeScript, such as a user override result, so it can sit inside a node tree.
+ * Parentheses keep a union or function type intact when it lands inside an array or intersection.
+ */
+declare function createRaw(text: string): TsNode;
+/**
+ * Creates a TypeScript intersection type.
+ * Returns the single type if only one is provided. `yuku-codegen` adds the parentheses a union member needs.
+ */
+declare function createIntersectionDeclaration({ nodes, withParentheses }: {
+  nodes: Array<TsNode>;
+  withParentheses?: boolean;
+}): TsNode | null;
+/**
+ * Creates a TypeScript array type.
+ * Use `arrayType: 'array'` for bracket syntax (`T[]`), or `'generic'` for `Array<T>`.
+ *
+ * @example Array bracket syntax
+ * `createArrayDeclaration({ nodes: [string], arrayType: 'array' }) // → string[]`
+ *
+ * @example Generic Array syntax
+ * `createArrayDeclaration({ nodes: [string], arrayType: 'generic' }) // → Array<string>`
+ */
+declare function createArrayDeclaration({ nodes, arrayType }: {
+  nodes: Array<TsNode>;
+  arrayType?: 'array' | 'generic';
+}): TsNode;
+/**
+ * Minimum nodes length of 2
+ * @example Union type example
+ * `string | number`
+ */
+declare function createUnionDeclaration({ nodes, withParentheses }: {
+  nodes: Array<TsNode>;
+  withParentheses?: boolean;
+}): TsNode;
+/**
+ * Creates a TypeScript property signature for object/interface members.
+ * Supports optional markers, readonly modifiers, and type annotations.
+ */
+declare function createPropertySignature({ readOnly, name, questionToken, type }: {
+  readOnly?: boolean;
+  name: string;
+  questionToken?: boolean;
+  type?: TsNode;
+}): TsNode;
+/**
+ * Attaches a JSDoc block built from `comments` to `node`, dropping empty comments.
+ */
+declare function appendJSDocToNode<TNode extends TsNode>({ node, comments }: {
+  node: TNode;
+  comments: Array<string | undefined>;
+}): TNode;
+/**
+ * Creates a TypeScript type literal (anonymous object type) with one member per line.
+ */
+declare function createTypeLiteralNode(members: Array<TsNode>): TsNode;
+/**
+ * Creates a TypeScript type reference (e.g., `Array<string>`, `Record<K, V>`).
+ */
+declare function createTypeReferenceNode(name: string, typeArguments?: Array<TsNode>): TsNode;
+/**
+ * Prints a TypeScript type declaration as either a type alias or interface.
+ * Uses interface syntax only when requested and the type is an object literal, and attaches JSDoc comments.
+ */
+declare function createTypeDeclaration({ syntax, isExportable, comments, name, type }: {
+  syntax: 'type' | 'interface';
+  comments: Array<string | undefined>;
+  isExportable?: boolean;
+  name: string;
+  type: TsNode;
+}): string;
+/**
+ * Creates a TypeScript enum declaration or equivalent construct in various formats.
+ * Returns a tuple of [name declaration, type declaration] - the name declaration may be undefined for certain types.
+ *
+ * @example
+ * ```ts
+ * const [name, type] = createEnumDeclaration({
+ *   type: 'enum',
+ *   name: 'petType',
+ *   typeName: 'PetType',
+ *   enums: [['cat', 'cat', 'A cat'], ['dog', 'dog']],
+ * })
+ * ```
+ */
+declare function createEnumDeclaration({ type, name, typeName, enums, enumKeyCasing }: {
+  /**
+   * Choose to use `enum`, `asConst`, `constEnum`, or `literal` for enums.
+   * - `enum`: TypeScript enum
+   * - `asConst`: const object asserted with `as const` (the caller decides the const name casing)
+   * - `constEnum`: const enum
+   * - `literal`: literal union type
+   * @default `'enum'`
+   */
+  type?: 'enum' | 'asConst' | 'constEnum' | 'literal' | 'inlineLiteral';
+  /**
+   * Enum name in camelCase.
+   */
+  name: string;
+  /**
+   * Enum name in PascalCase.
+   */
+  typeName: string;
+  enums: Array<[key: string | number, value: string | number | boolean, description?: string]>;
+  /**
+   * Choose the casing for enum key names.
+   * @default 'none'
+   */
+  enumKeyCasing?: 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none';
+}): [name: string | undefined, type: string];
+/**
+ * Creates a TypeScript `Omit<T, Keys>` type reference.
+ * Optionally wraps the type in `NonNullable<T>` if `nonNullable` is true.
+ */
+declare function createOmitDeclaration({ keys, type, nonNullable }: {
+  keys: Array<string> | string;
+  type: TsNode;
+  nonNullable?: boolean;
+}): TsNode;
+/**
+ * TypeScript keyword types for common primitive types.
+ */
+declare const keywordTypeNodes: {
+  readonly any: {
+    readonly type: 'TSAnyKeyword';
+  };
+  readonly unknown: {
+    readonly type: 'TSUnknownKeyword';
+  };
+  readonly void: {
+    readonly type: 'TSVoidKeyword';
+  };
+  readonly number: {
+    readonly type: 'TSNumberKeyword';
+  };
+  readonly integer: {
+    readonly type: 'TSNumberKeyword';
+  };
+  readonly bigint: {
+    readonly type: 'TSBigIntKeyword';
+  };
+  readonly object: {
+    readonly type: 'TSObjectKeyword';
+  };
+  readonly string: {
+    readonly type: 'TSStringKeyword';
+  };
+  readonly boolean: {
+    readonly type: 'TSBooleanKeyword';
+  };
+  readonly undefined: {
+    readonly type: 'TSUndefinedKeyword';
+  };
+  readonly null: {
+    readonly type: 'TSNullKeyword';
+  };
+  readonly never: {
+    readonly type: 'TSNeverKeyword';
+  };
+};
+/**
+ * Converts an OAS-style path (e.g. `/pets/{petId}`) or an Express-style path
+ * (e.g. `/pets/:petId`) to a TypeScript template literal type
+ * like `` `/pets/${string}` ``.
+ */
+declare function createUrlTemplateType(path: string): TsNode;
+/**
+ * Converts a primitive const value to a TypeScript literal type.
+ */
+declare function constToTypeNode(value: string | number | boolean, format: 'string' | 'number' | 'boolean'): TsNode | undefined;
+/**
+ * Returns a `Date` reference type when `representation` is `'date'`, otherwise falls back to `string`.
+ */
+declare function dateOrStringNode(node: {
+  representation?: string;
+}): TsNode;
+/**
+ * Maps an array of `SchemaNode`s through the printer, filtering out `null` and `undefined` results.
+ */
+declare function buildMemberNodes(members: Array<ast.SchemaNode> | undefined, print: (node: ast.SchemaNode) => TsNode | null | undefined): Array<TsNode>;
+/**
+ * Builds a TypeScript tuple type from an array schema's `items`,
+ * applying min/max slice and optional/rest element rules.
+ */
+declare function buildTupleNode(node: ast.ArraySchemaNode, print: (node: ast.SchemaNode) => TsNode | null | undefined): TsNode;
+/**
+ * Appends `| null` and then `| undefined` to a type when requested.
+ */
+declare function wrapNullableOptional(type: TsNode, nullable: boolean, addsUndefined: boolean): TsNode;
+/**
+ * Applies `nullable` and optional/nullish `| undefined` union modifiers to a property's resolved base type.
+ */
+declare function buildPropertyType(schema: ast.SchemaNode, baseType: TsNode, optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined', optional?: boolean): TsNode;
+/**
+ * Creates a TypeScript index signature for `additionalProperties` and `patternProperties` on an
+ * object schema node. TypeScript allows only one string index signature and its value must be
+ * assignable from every named property, so both keywords collapse into a single signature: the
+ * union of all value types (deduplicated), or `unknown` when the object also has fixed properties.
+ * The key regex of `patternProperties` cannot be expressed by an index signature and is dropped.
+ */
+declare function buildIndexSignatures(node: {
+  additionalProperties?: ast.SchemaNode | boolean;
+  patternProperties?: Record<string, ast.SchemaNode>;
+}, propertyCount: number, printNode: (node: ast.SchemaNode) => TsNode | null | undefined): Array<TsNode>;
+//#endregion
 //#region src/printers/printerTs.d.ts
 /**
  * Partial map of node-type overrides for the TypeScript printer.
  *
  * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`). The function
- * replaces the built-in handler for that node type. Use `this.transform` to
- * recurse into nested schema nodes, and `this.options` to read printer options.
+ * replaces the built-in handler for that node type and returns the TypeScript type as a string.
+ * Use `this.transform` to recurse into nested schema nodes, and `this.options` to read printer options.
  *
  * @example Override the `date` handler
  * ```ts
@@ -15,14 +235,18 @@ import ts from "@typescript/typescript6";
  *   printer: {
  *     nodes: {
  *       date(node) {
- *         return ts.factory.createTypeReferenceNode('Date', [])
+ *         return 'Date'
  *       },
  *     },
  *   },
  * })
  * ```
  */
-type PrinterTsNodes = ast.PrinterPartial<ts.TypeNode, PrinterTsOptions>;
+type PrinterTsNodes = ast.PrinterPartial<string | DeprecatedTsNode, PrinterTsOptions>;
+/** @deprecated A TypeScript compiler node returned by an override. Return a string; removed in the next major. */
+type DeprecatedTsNode = {
+  readonly kind: number;
+};
 type PrinterTsOptions = {
   /**
    * Mark parameters as optional with `?` or `| undefined`.
@@ -82,16 +306,16 @@ type PrinterTsOptions = {
   nodes?: PrinterTsNodes;
 };
 /**
- * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).
+ * TypeScript printer factory options: maps `SchemaNode` → a TS-ESTree node, printed to a type string or a full declaration string.
  */
-type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions, ts.TypeNode, string>;
+type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions, TsNode, string>;
 /**
  * TypeScript type printer built with `definePrinter`.
  *
- * Converts a `SchemaNode` AST node into a TypeScript AST node:
- * - **`printer.print(node)`** — when `options.typeName` is set, returns a full
- *   `type Name = …` or `interface Name { … }` declaration (`ts.Node`).
- *   Without `typeName`, returns the raw `ts.TypeNode` for the schema.
+ * Converts a `SchemaNode` AST node into TypeScript source:
+ * - **`printer.print(node)`** — when `options.name` is set, returns a full
+ *   `type Name = …` or `interface Name { … }` declaration.
+ *   Without `name`, returns the type for the schema, such as `string | null`.
  *
  * Dispatches on `node.type` to the appropriate handler in `nodes`. Options are closed
  * over per printer instance, so each call to `printerTs(options)` produces an independent printer.
@@ -99,13 +323,13 @@ type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions
  * @example Raw type node (no `typeName`)
  * ```ts
  * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' } })
- * const typeNode = printer.print(schemaNode) // ts.TypeNode
+ * const type = printer.print(schemaNode) // 'string | null'
  * ```
  *
  * @example Full declaration (with `typeName`)
  * ```ts
  * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' }, typeName: 'MyType' })
- * const declaration = printer.print(schemaNode) // ts.TypeAliasDeclaration | ts.InterfaceDeclaration
+ * const declaration = printer.print(schemaNode) // 'export type MyType = …'
  * ```
  */
 export declare const printerTs: (options?: PrinterTsOptions | undefined) => ast.Printer<PrinterTsFactory>;
@@ -383,17 +607,16 @@ type Options = OutputOptions & {
   macros?: Array<ast.Macro>;
   /**
    * Replace the TypeScript handler for a specific schema type (`'integer'`, `'date'`, ...).
-   * Each handler returns a TypeScript AST node for that schema type. Use `this.transform`
-   * to recurse into nested schema nodes.
+   * Each handler returns the TypeScript type for that schema type as a string. Use `this.transform`
+   * to recurse into nested schema nodes. Returning a TypeScript compiler node is deprecated.
    *
    * @example Use the JavaScript `Date` object for date schemas
    * ```ts
-   * import ts from '@typescript/typescript6'
    * pluginTs({
    *   printer: {
    *     nodes: {
    *       date() {
-   *         return ts.factory.createTypeReferenceNode('Date', [])
+   *         return 'Date'
    *       },
    *     },
    *   },

package/dist/index.d.ts

@@ -1,13 +1,233 @@
 import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "kubb/kit";
 import { KubbReactNode } from "kubb/jsx";
-import ts from "@typescript/typescript6";
+declare namespace factory_d_exports {
+  export { TsNode, appendJSDocToNode, buildIndexSignatures, buildMemberNodes, buildPropertyType, buildTupleNode, constToTypeNode, createArrayDeclaration, createEnumDeclaration, createIntersectionDeclaration, createOmitDeclaration, createPropertySignature, createRaw, createTypeDeclaration, createTypeLiteralNode, createTypeReferenceNode, createUnionDeclaration, createUrlTemplateType, dateOrStringNode, isNonNullable, keywordTypeNodes, print, wrapNullableOptional };
+}
+/**
+ * A TS-ESTree node, the AST shape `yuku-codegen` prints. Nodes built here carry no source positions.
+ */
+type TsNode = {
+  type: string;
+  [key: string]: unknown;
+};
+declare function isNonNullable<T>(value: T | null | undefined): value is T;
+/**
+ * Prints `node` as TypeScript source with single quotes and two-space indentation.
+ */
+declare function print(node: TsNode): string;
+/**
+ * Wraps already printed TypeScript, such as a user override result, so it can sit inside a node tree.
+ * Parentheses keep a union or function type intact when it lands inside an array or intersection.
+ */
+declare function createRaw(text: string): TsNode;
+/**
+ * Creates a TypeScript intersection type.
+ * Returns the single type if only one is provided. `yuku-codegen` adds the parentheses a union member needs.
+ */
+declare function createIntersectionDeclaration({ nodes, withParentheses }: {
+  nodes: Array<TsNode>;
+  withParentheses?: boolean;
+}): TsNode | null;
+/**
+ * Creates a TypeScript array type.
+ * Use `arrayType: 'array'` for bracket syntax (`T[]`), or `'generic'` for `Array<T>`.
+ *
+ * @example Array bracket syntax
+ * `createArrayDeclaration({ nodes: [string], arrayType: 'array' }) // → string[]`
+ *
+ * @example Generic Array syntax
+ * `createArrayDeclaration({ nodes: [string], arrayType: 'generic' }) // → Array<string>`
+ */
+declare function createArrayDeclaration({ nodes, arrayType }: {
+  nodes: Array<TsNode>;
+  arrayType?: 'array' | 'generic';
+}): TsNode;
+/**
+ * Minimum nodes length of 2
+ * @example Union type example
+ * `string | number`
+ */
+declare function createUnionDeclaration({ nodes, withParentheses }: {
+  nodes: Array<TsNode>;
+  withParentheses?: boolean;
+}): TsNode;
+/**
+ * Creates a TypeScript property signature for object/interface members.
+ * Supports optional markers, readonly modifiers, and type annotations.
+ */
+declare function createPropertySignature({ readOnly, name, questionToken, type }: {
+  readOnly?: boolean;
+  name: string;
+  questionToken?: boolean;
+  type?: TsNode;
+}): TsNode;
+/**
+ * Attaches a JSDoc block built from `comments` to `node`, dropping empty comments.
+ */
+declare function appendJSDocToNode<TNode extends TsNode>({ node, comments }: {
+  node: TNode;
+  comments: Array<string | undefined>;
+}): TNode;
+/**
+ * Creates a TypeScript type literal (anonymous object type) with one member per line.
+ */
+declare function createTypeLiteralNode(members: Array<TsNode>): TsNode;
+/**
+ * Creates a TypeScript type reference (e.g., `Array<string>`, `Record<K, V>`).
+ */
+declare function createTypeReferenceNode(name: string, typeArguments?: Array<TsNode>): TsNode;
+/**
+ * Prints a TypeScript type declaration as either a type alias or interface.
+ * Uses interface syntax only when requested and the type is an object literal, and attaches JSDoc comments.
+ */
+declare function createTypeDeclaration({ syntax, isExportable, comments, name, type }: {
+  syntax: 'type' | 'interface';
+  comments: Array<string | undefined>;
+  isExportable?: boolean;
+  name: string;
+  type: TsNode;
+}): string;
+/**
+ * Creates a TypeScript enum declaration or equivalent construct in various formats.
+ * Returns a tuple of [name declaration, type declaration] - the name declaration may be undefined for certain types.
+ *
+ * @example
+ * ```ts
+ * const [name, type] = createEnumDeclaration({
+ *   type: 'enum',
+ *   name: 'petType',
+ *   typeName: 'PetType',
+ *   enums: [['cat', 'cat', 'A cat'], ['dog', 'dog']],
+ * })
+ * ```
+ */
+declare function createEnumDeclaration({ type, name, typeName, enums, enumKeyCasing }: {
+  /**
+   * Choose to use `enum`, `asConst`, `constEnum`, or `literal` for enums.
+   * - `enum`: TypeScript enum
+   * - `asConst`: const object asserted with `as const` (the caller decides the const name casing)
+   * - `constEnum`: const enum
+   * - `literal`: literal union type
+   * @default `'enum'`
+   */
+  type?: 'enum' | 'asConst' | 'constEnum' | 'literal' | 'inlineLiteral';
+  /**
+   * Enum name in camelCase.
+   */
+  name: string;
+  /**
+   * Enum name in PascalCase.
+   */
+  typeName: string;
+  enums: Array<[key: string | number, value: string | number | boolean, description?: string]>;
+  /**
+   * Choose the casing for enum key names.
+   * @default 'none'
+   */
+  enumKeyCasing?: 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none';
+}): [name: string | undefined, type: string];
+/**
+ * Creates a TypeScript `Omit<T, Keys>` type reference.
+ * Optionally wraps the type in `NonNullable<T>` if `nonNullable` is true.
+ */
+declare function createOmitDeclaration({ keys, type, nonNullable }: {
+  keys: Array<string> | string;
+  type: TsNode;
+  nonNullable?: boolean;
+}): TsNode;
+/**
+ * TypeScript keyword types for common primitive types.
+ */
+declare const keywordTypeNodes: {
+  readonly any: {
+    readonly type: 'TSAnyKeyword';
+  };
+  readonly unknown: {
+    readonly type: 'TSUnknownKeyword';
+  };
+  readonly void: {
+    readonly type: 'TSVoidKeyword';
+  };
+  readonly number: {
+    readonly type: 'TSNumberKeyword';
+  };
+  readonly integer: {
+    readonly type: 'TSNumberKeyword';
+  };
+  readonly bigint: {
+    readonly type: 'TSBigIntKeyword';
+  };
+  readonly object: {
+    readonly type: 'TSObjectKeyword';
+  };
+  readonly string: {
+    readonly type: 'TSStringKeyword';
+  };
+  readonly boolean: {
+    readonly type: 'TSBooleanKeyword';
+  };
+  readonly undefined: {
+    readonly type: 'TSUndefinedKeyword';
+  };
+  readonly null: {
+    readonly type: 'TSNullKeyword';
+  };
+  readonly never: {
+    readonly type: 'TSNeverKeyword';
+  };
+};
+/**
+ * Converts an OAS-style path (e.g. `/pets/{petId}`) or an Express-style path
+ * (e.g. `/pets/:petId`) to a TypeScript template literal type
+ * like `` `/pets/${string}` ``.
+ */
+declare function createUrlTemplateType(path: string): TsNode;
+/**
+ * Converts a primitive const value to a TypeScript literal type.
+ */
+declare function constToTypeNode(value: string | number | boolean, format: 'string' | 'number' | 'boolean'): TsNode | undefined;
+/**
+ * Returns a `Date` reference type when `representation` is `'date'`, otherwise falls back to `string`.
+ */
+declare function dateOrStringNode(node: {
+  representation?: string;
+}): TsNode;
+/**
+ * Maps an array of `SchemaNode`s through the printer, filtering out `null` and `undefined` results.
+ */
+declare function buildMemberNodes(members: Array<ast.SchemaNode> | undefined, print: (node: ast.SchemaNode) => TsNode | null | undefined): Array<TsNode>;
+/**
+ * Builds a TypeScript tuple type from an array schema's `items`,
+ * applying min/max slice and optional/rest element rules.
+ */
+declare function buildTupleNode(node: ast.ArraySchemaNode, print: (node: ast.SchemaNode) => TsNode | null | undefined): TsNode;
+/**
+ * Appends `| null` and then `| undefined` to a type when requested.
+ */
+declare function wrapNullableOptional(type: TsNode, nullable: boolean, addsUndefined: boolean): TsNode;
+/**
+ * Applies `nullable` and optional/nullish `| undefined` union modifiers to a property's resolved base type.
+ */
+declare function buildPropertyType(schema: ast.SchemaNode, baseType: TsNode, optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined', optional?: boolean): TsNode;
+/**
+ * Creates a TypeScript index signature for `additionalProperties` and `patternProperties` on an
+ * object schema node. TypeScript allows only one string index signature and its value must be
+ * assignable from every named property, so both keywords collapse into a single signature: the
+ * union of all value types (deduplicated), or `unknown` when the object also has fixed properties.
+ * The key regex of `patternProperties` cannot be expressed by an index signature and is dropped.
+ */
+declare function buildIndexSignatures(node: {
+  additionalProperties?: ast.SchemaNode | boolean;
+  patternProperties?: Record<string, ast.SchemaNode>;
+}, propertyCount: number, printNode: (node: ast.SchemaNode) => TsNode | null | undefined): Array<TsNode>;
+//#endregion
 //#region src/printers/printerTs.d.ts
 /**
  * Partial map of node-type overrides for the TypeScript printer.
  *
  * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`). The function
- * replaces the built-in handler for that node type. Use `this.transform` to
- * recurse into nested schema nodes, and `this.options` to read printer options.
+ * replaces the built-in handler for that node type and returns the TypeScript type as a string.
+ * Use `this.transform` to recurse into nested schema nodes, and `this.options` to read printer options.
  *
  * @example Override the `date` handler
  * ```ts
@@ -15,14 +235,18 @@ import ts from "@typescript/typescript6";
  *   printer: {
  *     nodes: {
  *       date(node) {
- *         return ts.factory.createTypeReferenceNode('Date', [])
+ *         return 'Date'
  *       },
  *     },
  *   },
  * })
  * ```
  */
-type PrinterTsNodes = ast.PrinterPartial<ts.TypeNode, PrinterTsOptions>;
+type PrinterTsNodes = ast.PrinterPartial<string | DeprecatedTsNode, PrinterTsOptions>;
+/** @deprecated A TypeScript compiler node returned by an override. Return a string; removed in the next major. */
+type DeprecatedTsNode = {
+  readonly kind: number;
+};
 type PrinterTsOptions = {
   /**
    * Mark parameters as optional with `?` or `| undefined`.
@@ -82,16 +306,16 @@ type PrinterTsOptions = {
   nodes?: PrinterTsNodes;
 };
 /**
- * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).
+ * TypeScript printer factory options: maps `SchemaNode` → a TS-ESTree node, printed to a type string or a full declaration string.
  */
-type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions, ts.TypeNode, string>;
+type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions, TsNode, string>;
 /**
  * TypeScript type printer built with `definePrinter`.
  *
- * Converts a `SchemaNode` AST node into a TypeScript AST node:
- * - **`printer.print(node)`** — when `options.typeName` is set, returns a full
- *   `type Name = …` or `interface Name { … }` declaration (`ts.Node`).
- *   Without `typeName`, returns the raw `ts.TypeNode` for the schema.
+ * Converts a `SchemaNode` AST node into TypeScript source:
+ * - **`printer.print(node)`** — when `options.name` is set, returns a full
+ *   `type Name = …` or `interface Name { … }` declaration.
+ *   Without `name`, returns the type for the schema, such as `string | null`.
  *
  * Dispatches on `node.type` to the appropriate handler in `nodes`. Options are closed
  * over per printer instance, so each call to `printerTs(options)` produces an independent printer.
@@ -99,13 +323,13 @@ type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions
  * @example Raw type node (no `typeName`)
  * ```ts
  * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' } })
- * const typeNode = printer.print(schemaNode) // ts.TypeNode
+ * const type = printer.print(schemaNode) // 'string | null'
  * ```
  *
  * @example Full declaration (with `typeName`)
  * ```ts
  * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' }, typeName: 'MyType' })
- * const declaration = printer.print(schemaNode) // ts.TypeAliasDeclaration | ts.InterfaceDeclaration
+ * const declaration = printer.print(schemaNode) // 'export type MyType = …'
  * ```
  */
 export declare const printerTs: (options?: PrinterTsOptions | undefined) => ast.Printer<PrinterTsFactory>;
@@ -383,17 +607,16 @@ type Options = OutputOptions & {
   macros?: Array<ast.Macro>;
   /**
    * Replace the TypeScript handler for a specific schema type (`'integer'`, `'date'`, ...).
-   * Each handler returns a TypeScript AST node for that schema type. Use `this.transform`
-   * to recurse into nested schema nodes.
+   * Each handler returns the TypeScript type for that schema type as a string. Use `this.transform`
+   * to recurse into nested schema nodes. Returning a TypeScript compiler node is deprecated.
    *
    * @example Use the JavaScript `Date` object for date schemas
    * ```ts
-   * import ts from '@typescript/typescript6'
    * pluginTs({
    *   printer: {
    *     nodes: {
    *       date() {
-   *         return ts.factory.createTypeReferenceNode('Date', [])
+   *         return 'Date'
    *       },
    *     },
    *   },