deep-case-crafter 2.1.0 → 3.0.0

package/dist/index.d.mts

@@ -1,7 +1,30 @@
+/**
+ * `true` when `T` is `any`: a conditional type checked against `any` takes both branches,
+ * so only `any` turns `true | false` into `boolean`.
+ *
+ * Two shorter checks are not used. `0 extends 1 & T` is `false` since TypeScript 5.4 for
+ * a type parameter whose constraint excludes `1` (such as `To` in `transform`), even when
+ * `any` is passed for it. `unknown extends T` is `true` without `strictNullChecks` for an
+ * object type whose properties are all optional (such as `{ targetCase?: 'kebab' }`).
+ */
+type IsAny<T> = boolean extends (T extends never ? true : false) ? true : false;
+/**
+ * `true` when `S` is a single string literal such as `'user_id'`, and `false` for
+ * `string` and template-literal patterns such as `` `user_${string}` ``.
+ */
+type IsStringLiteral<S extends string> = Record<never, never> extends Record<S, never> ? false : true;
+
 /**
  * Represents the supported string case formats for transformation
  */
 type StringCase = 'camel' | 'pascal' | 'snake' | 'kebab';
+/**
+ * The plain literal of a target case: a string enum member or a branded literal such as
+ * `'snake' & { __brand: 'Case' }` becomes `'snake'`, so it compares equal to the case
+ * detected from a key. Only literals are produced, never `To` itself: TypeScript 4.7
+ * narrows `To` to `To & StringCase` in a true branch, which is `never` for an enum member.
+ */
+type PlainCase<To> = To extends 'camel' ? 'camel' : To extends 'snake' ? 'snake' : To extends 'kebab' ? 'kebab' : To extends 'pascal' ? 'pascal' : never;
 
 /**
  * Options for the transform function
@@ -11,234 +34,280 @@ interface TransformOptions {
      * The target casing format to transform to
      * @default 'camel'
      */
-    targetCase?: StringCase;
+    targetCase?: StringCase | undefined;
     /**
-     * The source casing format to transform from
+     * How many nesting levels to transform: `1` transforms only the top-level keys, `2`
+     * also the keys one level down, and so on. The values of objects, Maps and Sets are one
+     * level deeper; array items stay on their array's level. Deeper values are returned
+     * as they are.
      *
-     * When specified:
-     * - Provides precise TypeScript type transformations
-     * - Bypasses runtime case detection (more efficient)
-     * - Ensures consistent results if input has mixed casing
+     * Pass a numeric literal to get a precise result type. A depth that is only known to be
+     * a `number` (a variable, or `Infinity`) gives an `unknown` result type; omit `depth`
+     * to transform every level.
      *
-     * When omitted:
-     * - Automatic case detection is used at runtime
-     * - TypeScript types will be less precise (string keys)
-     * - Works with mixed case inputs (each key detected separately)
-     *
-     * @example
-     * // With source specified - precise types
-     * const result = transform(data, { targetCase: 'camel', sourceCase: 'snake' });
-     * // result has exact transformed types
-     *
-     * // Without source - flexible runtime behavior
-     * const result = transform(data, { targetCase: 'camel' });
-     * // TypeScript types are more general
-     *
-     * @default undefined (automatic detection)
+     * @default Infinity
      */
-    sourceCase?: StringCase;
+    depth?: number | undefined;
+    /**
+     * @deprecated Has no effect. Every key's case is detected from the key itself, both at
+     * runtime and in the result type, so there is nothing to declare.
+     */
+    sourceCase?: StringCase | undefined;
 }
-
 /**
- * Type utility that transforms a snake_case string to camelCase
- * Example: 'hello_world' -> 'helloWorld'
+ * Rejects option names `transform` does not know. The options object is inferred as a
+ * whole, so without this an object literal would accept any extra property, typos such
+ * as `depht` included. The error names the unknown option.
  */
-type SnakeToCamel<S extends string> = S extends `${infer P}_${infer C}${infer R}` ? `${P}${Uppercase<C>}${SnakeToCamel<R>}` : S;
+type NoUnknownOptions<Options> = {
+    [K in Exclude<keyof Options, keyof TransformOptions>]: `Unknown option: ${K & string}`;
+};
+/** `To` as a plain case literal, or `'camel'` (the default) for `undefined` */
+type CaseOrDefault<To> = To extends undefined ? 'camel' : PlainCase<To>;
 /**
- * Type utility that transforms a snake_case string to PascalCase
- * Example: 'hello_world' -> 'HelloWorld'
+ * The target case the runtime uses for one options object: `'camel'` when `targetCase`
+ * is omitted or `undefined`.
  */
-type SnakeWordsToPascal<Parts extends string[]> = Parts extends [
-    infer First extends string,
-    ...infer Rest extends string[]
-] ? `${Capitalize<First>}${SnakeWordsToPascal<Rest>}` : '';
-type SnakeToWords<S extends string> = S extends `${infer P}_${infer R}` ? [P, ...SnakeToWords<R>] : [S];
-type SnakeToPascal<S extends string> = S extends `${infer P}_${infer R}` ? SnakeWordsToPascal<[P, ...SnakeToWords<R>]> : Capitalize<S>;
+type TargetCaseOf<Options> = 'targetCase' extends keyof Options ? CaseOrDefault<Options['targetCase']> : 'camel';
 /**
- * Type utility that transforms a snake_case string to kebab-case
- * Example: 'hello_world' -> 'hello-world'
+ * The depth the runtime uses for one options object: `undefined` (every level) when
+ * `depth` is omitted.
  */
-type SnakeToKebab<S extends string> = S extends `${infer P}_${infer R}` ? `${P}-${SnakeToKebab<R>}` : S;
+type DepthOf<Options> = 'depth' extends keyof Options ? Options['depth'] : undefined;
+
 /**
- * Acronym-aware word-boundary scanner shared by all camel/pascal → snake/kebab
- * conversions. Mirrors `utils/stringFormatters/toSeparatedCase.ts` exactly so the
- * type-level and runtime results never diverge.
- *
- * Inserts `Sep` before an uppercase char when the previous char is a lowercase
- * letter or digit, or when it ends an acronym run that starts a new word (the two
- * preceding chars are uppercase and the next is lowercase). All output is lowercased.
+ * Character classes used by the type-level key transformation. They spell out the
+ * ASCII characters explicitly, because TypeScript's `Uppercase`/`Lowercase` are
+ * Unicode-aware and would treat a letter like `é` as an ordinary letter.
  */
-type IsUpper<C extends string> = C extends Uppercase<C> ? (C extends Lowercase<C> ? false : true) : false;
-type IsLower<C extends string> = C extends Lowercase<C> ? (C extends Uppercase<C> ? false : true) : false;
-type IsLowerOrDigit<C extends string> = IsLower<C> extends true ? true : C extends `${number}` ? true : false;
-type FirstChar<S extends string> = S extends `${infer F}${string}` ? F : '';
-type SeparatorScan<S extends string, Sep extends string, Prev extends string, PrevPrev extends string> = S extends `${infer C}${infer R}` ? IsUpper<C> extends true ? IsLowerOrDigit<Prev> extends true ? `${Sep}${Lowercase<C>}${SeparatorScan<R, Sep, C, Prev>}` : IsUpper<Prev> extends true ? IsUpper<PrevPrev> extends true ? IsLower<FirstChar<R>> extends true ? `${Sep}${Lowercase<C>}${SeparatorScan<R, Sep, C, Prev>}` : `${Lowercase<C>}${SeparatorScan<R, Sep, C, Prev>}` : `${Lowercase<C>}${SeparatorScan<R, Sep, C, Prev>}` : `${Lowercase<C>}${SeparatorScan<R, Sep, C, Prev>}` : `${Lowercase<C>}${SeparatorScan<R, Sep, C, Prev>}` : S;
-type SeparatorCase<S extends string, Sep extends string> = SeparatorScan<S, Sep, '', ''>;
+/** Lowercase ASCII letters */
+type LowerLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+/** Uppercase ASCII letters */
+type UpperLetter = Uppercase<LowerLetter>;
+/** ASCII digits */
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/** The word separators of snake_case and kebab-case */
+type Separator = '_' | '-';
+/** Every character a transformable key may contain (the runtime's `A-Z a-z 0-9 _ -`) */
+type KeyChar = LowerLetter | UpperLetter | Digit | Separator;
+
 /**
- * Type utility that transforms a camelCase string to snake_case (acronym-aware)
- * Example: 'helloWorld' -> 'hello_world', 'getHTTPResponse' -> 'get_http_response'
+ * The plural suffix that stays with the acronym before it instead of starting a new
+ * word: `allowedURLs` becomes `allowed_urls`, not `allowed_ur_ls`.
  */
-type CamelToSnake<S extends string> = SeparatorCase<S, '_'>;
+declare const ACRONYM_PLURAL_SUFFIX = "s";
+
 /**
- * Type utility that transforms a camelCase string to PascalCase
- * Example: 'helloWorld' -> 'HelloWorld'
+ * Type-level mirror of the runtime key transformation (`transformCase`).
+ *
+ * Every step below follows a runtime function, so the type of a transformed key is
+ * exactly the key the runtime produces. The parity test (`typeRuntimeParity.test.ts`)
+ * checks this for thousands of keys.
  */
-type CamelToPascal<S extends string> = Capitalize<S>;
 /**
- * Type utility that transforms a camelCase string to kebab-case (acronym-aware)
- * Example: 'helloWorld' -> 'hello-world', 'getHTTPResponse' -> 'get-http-response'
+ * `true` when every character of `S` may appear in a transformable key
+ * (tail-recursive, so long keys compile).
  */
-type CamelToKebab<S extends string> = SeparatorCase<S, '-'>;
+type HasOnlyKeyChars<S extends string> = S extends `${infer C}${infer Rest}` ? C extends KeyChar ? HasOnlyKeyChars<Rest> : false : true;
 /**
- * Type utility that transforms a PascalCase string to camelCase
- * Example: 'HelloWorld' -> 'helloWorld'
+ * Keys the runtime leaves unchanged (`prepareStringTransformation`): keys containing a
+ * character outside `A-Z a-z 0-9 _ -`, keys not starting with a letter and keys ending
+ * with a separator.
  */
-type PascalToCamel<S extends string> = S extends `${infer F}${infer R}` ? `${Lowercase<F>}${R}` : S;
+type IsPreservedKey<K extends string> = HasOnlyKeyChars<K> extends false ? true : K extends `${LowerLetter | UpperLetter}${string}` ? K extends `${string}${Separator}` ? true : false : true;
 /**
- * Type utility that transforms a PascalCase string to snake_case (acronym-aware)
- * Example: 'HelloWorld' -> 'hello_world', 'HTTPResponse' -> 'http_response'
+ * The case the runtime detects for a key that is not preserved (`detectStringCase`), or
+ * `'none'` when it cannot be detected (the key is then left unchanged). A string is used
+ * rather than `null`, which every type accepts without `strictNullChecks`.
  */
-type PascalToSnake<S extends string> = SeparatorCase<S, '_'>;
+type DetectedCase<K extends string> = K extends `${string}${Separator}${string}` ? K extends Lowercase<K> ? K extends `${string}-${string}` ? K extends `${string}_${string}` | `${string}--${string}` ? 'none' : 'kebab' : K extends `${string}__${string}` ? 'none' : 'snake' : 'none' : K extends `${infer First}${infer Rest}` ? Rest extends Lowercase<Rest> ? 'single' : First extends LowerLetter ? 'camel' : K extends Uppercase<K> ? 'none' : 'pascal' : 'none';
+/** The first character of `S`, or `''` */
+type FirstChar<S extends string> = S extends `${infer C}${string}` ? C : '';
 /**
- * Type utility that transforms a PascalCase string to kebab-case (acronym-aware)
- * Example: 'HelloWorld' -> 'hello-world', 'HTTPResponse' -> 'http-response'
+ * Whether a new word starts at `C`, followed by `Rest` (`isWordBoundary`): `C` is
+ * uppercase and follows a lowercase letter or digit, or it ends an acronym that starts a
+ * new word (two uppercase letters before it, a lowercase letter after it) — unless that
+ * letter is a plural `s` not followed by another lowercase letter.
  */
-type PascalToKebab<S extends string> = SeparatorCase<S, '-'>;
+type IsWordBoundary<C extends string, Prev extends string, PrevPrev extends string, Rest extends string> = C extends UpperLetter ? Prev extends LowerLetter | Digit ? true : Prev extends UpperLetter ? PrevPrev extends UpperLetter ? Rest extends `${infer Next}${infer AfterNext}` ? Next extends LowerLetter ? Next extends typeof ACRONYM_PLURAL_SUFFIX ? FirstChar<AfterNext> extends LowerLetter ? true : false : true : false : false : false : false : false;
+/** camelCase/PascalCase to snake_case or kebab-case, acronym-aware (`toSeparatedCase`) */
+type ToSeparatedCase<S extends string, Sep extends Separator, Prev extends string = '', PrevPrev extends string = '', Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? ToSeparatedCase<Rest, Sep, C, Prev, `${Acc}${IsWordBoundary<C, Prev, PrevPrev, Rest> extends true ? Sep : ''}${Lowercase<C>}`> : Acc;
 /**
- * Type utility that transforms a kebab-case string to camelCase
- * Example: 'hello-world' -> 'helloWorld'
+ * Lowercases the first word, up to the first word boundary, so a leading acronym is
+ * lowercased as a whole
  */
-type KebabToCamel<S extends string> = S extends `${infer P}-${infer C}${infer R}` ? `${P}${Uppercase<C>}${KebabToCamel<R>}` : S;
+type LowercaseFirstWord<S extends string, Prev extends string = '', PrevPrev extends string = '', Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? IsWordBoundary<C, Prev, PrevPrev, Rest> extends true ? `${Acc}${S}` : LowercaseFirstWord<Rest, C, Prev, `${Acc}${Lowercase<C>}`> : Acc;
 /**
- * Type utility that transforms a kebab-case string to PascalCase
- * Example: 'hello-world' -> 'HelloWorld'
+ * PascalCase to camelCase (`pascalToCamelCase`): two capitals followed by a lowercase
+ * letter start with a one-letter word (`XAxis` -> `xAxis`), unless that letter is a
+ * plural `s` ending the acronym (`IDs` -> `ids`); otherwise the first word is lowercased
+ * as a whole (`HTTPRequest` -> `httpRequest`)
  */
-type KebabWordsToPascal<Parts extends string[]> = Parts extends [
-    infer First extends string,
-    ...infer Rest extends string[]
-] ? `${Capitalize<First>}${KebabWordsToPascal<Rest>}` : '';
-type KebabToWords<S extends string> = S extends `${infer P}-${infer R}` ? [P, ...KebabToWords<R>] : [S];
+type PascalToCamelCase<S extends string> = S extends `${infer A}${infer B}${infer C}${infer Rest}` ? [A, B, C] extends [UpperLetter, UpperLetter, LowerLetter] ? C extends typeof ACRONYM_PLURAL_SUFFIX ? FirstChar<Rest> extends LowerLetter ? Uncapitalize<S> : LowercaseFirstWord<S> : Uncapitalize<S> : LowercaseFirstWord<S> : LowercaseFirstWord<S>;
+/** snake_case/kebab-case to camelCase (`snakeToCamelCase`, `kebabToCamelCase`) */
+type SeparatedToCamelCase<S extends string, Sep extends Separator, Acc extends string = ''> = S extends `${infer Word}${Sep}${infer Next}${infer Rest}` ? SeparatedToCamelCase<Rest, Sep, `${Acc}${Word}${Uppercase<Next>}`> : `${Acc}${S}`;
+/** Replaces every `From` separator with `To` (`snakeToKebabCase`, `kebabToSnakeCase`) */
+type ReplaceSeparator<S extends string, From extends Separator, To extends Separator, Acc extends string = ''> = S extends `${infer Head}${From}${infer Rest}` ? ReplaceSeparator<Rest, From, To, `${Acc}${Head}${To}`> : `${Acc}${S}`;
+/** A single word in the target case (`transformSingleWord`) */
+type SingleWordToCase<K extends string, To extends StringCase> = To extends 'pascal' ? Capitalize<K> : To extends 'camel' ? Uncapitalize<K> : Lowercase<K>;
+/** A key of the detected case `From` in the target case (`formatterMap`) */
+type FormatKey<K extends string, From extends StringCase, To extends StringCase> = From extends To ? K : From extends 'snake' | 'kebab' ? To extends 'camel' ? SeparatedToCamelCase<K, From extends 'snake' ? '_' : '-'> : To extends 'pascal' ? Capitalize<SeparatedToCamelCase<K, From extends 'snake' ? '_' : '-'>> : From extends 'snake' ? ReplaceSeparator<K, '_', '-'> : ReplaceSeparator<K, '-', '_'> : To extends 'pascal' ? Capitalize<K> : To extends 'camel' ? PascalToCamelCase<K> : ToSeparatedCase<K, To extends 'snake' ? '_' : '-'>;
+/** Applies the detected case of `K` (`transformCase`) */
+type TransformDetectedKey<K extends string, Detected, To extends StringCase> = Detected extends 'single' ? SingleWordToCase<K, To> : Detected extends StringCase ? FormatKey<K, Detected, To> : K;
 /**
- * Type utility that transforms a kebab-case string to PascalCase
- * Example: 'hello-world' -> 'HelloWorld'
+ * The key a string key `K` becomes when transformed to `To`. A `string` or
+ * template-literal key cannot be known exactly, so it becomes `string`.
  */
-type KebabToPascal<S extends string> = S extends `${infer P}-${infer R}` ? KebabWordsToPascal<[P, ...KebabToWords<R>]> : Capitalize<S>;
+type TransformKey<K extends string, To extends StringCase> = IsStringLiteral<K> extends false ? string : K extends '' ? K : IsPreservedKey<K> extends true ? K : TransformDetectedKey<K, DetectedCase<K>, To>;
+
+/** Primitive values, including branded ones such as `string & { __brand: 'UserId' }` */
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 /**
- * Type utility that transforms a kebab-case string to snake_case
- * Example: 'hello-world' -> 'hello_world'
+ * Values the runtime returns untouched that TypeScript can recognise: functions and
+ * classes, `Date`, `RegExp`, and built-ins that declare a `Symbol.toStringTag` (typed
+ * arrays, `ArrayBuffer`, `DataView`, `Promise`, `WeakMap`, `WeakSet`, ...).
+ *
+ * `Error`, `URL` and other host objects are returned untouched as well, but their types
+ * cannot be told apart from plain objects (an `Error` is any `{ name, message }`).
  */
-type KebabToSnake<S extends string> = S extends `${infer P}-${infer R}` ? `${P}_${KebabToSnake<R>}` : S;
+type UntouchedValue = Function | Date | RegExp | {
+    readonly [Symbol.toStringTag]: string;
+};
 /**
- * Utility type to detect preserved keys that shouldn't be transformed.
- * Preserved keys include those with leading/trailing special characters,
- * unsupported patterns, or invalid starting/ending characters.
+ * `true` once `Level` (the nesting level so far, as a tuple) reaches `Depth`.
+ * `Depth` is `undefined` when every level is transformed. The `undefined` check comes
+ * first and is not distributive, so it also holds without `strictNullChecks`; comparing
+ * `Depth extends Level['length']` also accepts a branded depth such as `1 & Brand`.
  */
-type ForbiddenStartChars = '_' | '-' | '$' | '&' | '%' | '#' | '@' | '!' | '*' | '+' | '=' | '~' | '`' | '^' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '\\' | ':' | ';' | '"' | "'" | '<' | '>' | ',' | '.' | '?' | '/' | `${number}`;
-type ForbiddenEndChars = '_' | '-' | '$' | '&' | '%' | '#' | '@' | '!' | '*' | '+' | '=' | '~' | '`' | '^' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '\\' | ':' | ';' | '"' | "'" | '<' | '>' | ',' | '.' | '?' | '/' | `${number}`;
-type PreservedKey<K extends string> = K extends `${infer First}${string}` ? First extends ForbiddenStartChars ? true : K extends `${string}${infer Last}` ? Last extends ForbiddenEndChars ? true : K extends `${string}__${string}` | `${string}--${string}` ? true : false : false : false;
+type IsDepthReached<Depth extends number | undefined, Level extends unknown[]> = [Depth] extends [undefined] ? false : Depth extends Level['length'] ? true : false;
 /**
- * Type utility that selects the correct string transformation based on source and target casing
+ * The nesting level of the values of an object, Map or Set. With unlimited depth the
+ * level stays `[]`, so recursive data types reuse the same instantiation.
  */
-type TransformKey<K extends string, O extends TransformOptions> = PreservedKey<K> extends true ? K : undefined extends O['sourceCase'] ? string : O['sourceCase'] extends 'snake' ? undefined extends O['targetCase'] ? SnakeToCamel<K> : O['targetCase'] extends 'camel' ? SnakeToCamel<K> : O['targetCase'] extends 'pascal' ? SnakeToPascal<K> : O['targetCase'] extends 'kebab' ? SnakeToKebab<K> : K : O['sourceCase'] extends 'camel' ? undefined extends O['targetCase'] ? K : O['targetCase'] extends 'snake' ? CamelToSnake<K> : O['targetCase'] extends 'pascal' ? CamelToPascal<K> : O['targetCase'] extends 'kebab' ? CamelToKebab<K> : K : O['sourceCase'] extends 'pascal' ? undefined extends O['targetCase'] ? PascalToCamel<K> : O['targetCase'] extends 'camel' ? PascalToCamel<K> : O['targetCase'] extends 'snake' ? PascalToSnake<K> : O['targetCase'] extends 'kebab' ? PascalToKebab<K> : K : O['sourceCase'] extends 'kebab' ? undefined extends O['targetCase'] ? KebabToCamel<K> : O['targetCase'] extends 'camel' ? KebabToCamel<K> : O['targetCase'] extends 'pascal' ? KebabToPascal<K> : O['targetCase'] extends 'snake' ? KebabToSnake<K> : K : K;
+type NextLevel<Depth extends number | undefined, Level extends unknown[]> = [
+    Depth
+] extends [undefined] ? Level : [...Level, unknown];
 /**
- * Recursive type transformations
- * These types handle nested structures like arrays, objects, Maps, and Sets
+ * Transforms `T` the way `internalTransform` does: arrays keep their nesting level,
+ * while the values of objects, Maps and Sets are one level deeper.
+ *
+ * Arrays are typed as arrays of transformed items, which lets TypeScript defer
+ * recursive types such as a JSON value type; only tuples are mapped position by position.
+ *
+ * Use `TransformResult` instead. This type is exported only so that declaration files
+ * can refer to it: the result of a generic wrapper around `transform` is written in terms
+ * of it, and an unexported recursive type would have to be expanded there without end.
  */
-type SnakeToCamelRecursive<T> = T extends Array<infer U> ? Array<SnakeToCamelRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? SnakeToCamel<K> : K, SnakeToCamelRecursive<V>> : T extends Set<infer V> ? Set<SnakeToCamelRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'snake';
-        targetCase: 'camel';
-    }>]: SnakeToCamelRecursive<T[K]>;
-} : T;
-type SnakeToPascalRecursive<T> = T extends Array<infer U> ? Array<SnakeToPascalRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? SnakeToPascal<K> : K, SnakeToPascalRecursive<V>> : T extends Set<infer V> ? Set<SnakeToPascalRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'snake';
-        targetCase: 'pascal';
-    }>]: SnakeToPascalRecursive<T[K]>;
-} : T;
-type SnakeToKebabRecursive<T> = T extends Array<infer U> ? Array<SnakeToKebabRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? SnakeToKebab<K> : K, SnakeToKebabRecursive<V>> : T extends Set<infer V> ? Set<SnakeToKebabRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'snake';
-        targetCase: 'kebab';
-    }>]: SnakeToKebabRecursive<T[K]>;
-} : T;
-type CamelToSnakeRecursive<T> = T extends Array<infer U> ? Array<CamelToSnakeRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? CamelToSnake<K> : K, CamelToSnakeRecursive<V>> : T extends Set<infer V> ? Set<CamelToSnakeRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'camel';
-        targetCase: 'snake';
-    }>]: CamelToSnakeRecursive<T[K]>;
-} : T;
-type CamelToPascalRecursive<T> = T extends Array<infer U> ? Array<CamelToPascalRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? CamelToPascal<K> : K, CamelToPascalRecursive<V>> : T extends Set<infer V> ? Set<CamelToPascalRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'camel';
-        targetCase: 'pascal';
-    }>]: CamelToPascalRecursive<T[K]>;
-} : T;
-type CamelToKebabRecursive<T> = T extends Array<infer U> ? Array<CamelToKebabRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? CamelToKebab<K> : K, CamelToKebabRecursive<V>> : T extends Set<infer V> ? Set<CamelToKebabRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'camel';
-        targetCase: 'kebab';
-    }>]: CamelToKebabRecursive<T[K]>;
-} : T;
-type PascalToCamelRecursive<T> = T extends Array<infer U> ? Array<PascalToCamelRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? PascalToCamel<K> : K, PascalToCamelRecursive<V>> : T extends Set<infer V> ? Set<PascalToCamelRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'pascal';
-        targetCase: 'camel';
-    }>]: PascalToCamelRecursive<T[K]>;
-} : T;
-type PascalToSnakeRecursive<T> = T extends Array<infer U> ? Array<PascalToSnakeRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? PascalToSnake<K> : K, PascalToSnakeRecursive<V>> : T extends Set<infer V> ? Set<PascalToSnakeRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'pascal';
-        targetCase: 'snake';
-    }>]: PascalToSnakeRecursive<T[K]>;
-} : T;
-type PascalToKebabRecursive<T> = T extends Array<infer U> ? Array<PascalToKebabRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? PascalToKebab<K> : K, PascalToKebabRecursive<V>> : T extends Set<infer V> ? Set<PascalToKebabRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'pascal';
-        targetCase: 'kebab';
-    }>]: PascalToKebabRecursive<T[K]>;
-} : T;
-type KebabToCamelRecursive<T> = T extends Array<infer U> ? Array<KebabToCamelRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? KebabToCamel<K> : K, KebabToCamelRecursive<V>> : T extends Set<infer V> ? Set<KebabToCamelRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'kebab';
-        targetCase: 'camel';
-    }>]: KebabToCamelRecursive<T[K]>;
-} : T;
-type KebabToPascalRecursive<T> = T extends Array<infer U> ? Array<KebabToPascalRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? KebabToPascal<K> : K, KebabToPascalRecursive<V>> : T extends Set<infer V> ? Set<KebabToPascalRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'kebab';
-        targetCase: 'pascal';
-    }>]: KebabToPascalRecursive<T[K]>;
-} : T;
-type KebabToSnakeRecursive<T> = T extends Array<infer U> ? Array<KebabToSnakeRecursive<U>> : T extends Map<infer K, infer V> ? Map<K extends string ? KebabToSnake<K> : K, KebabToSnakeRecursive<V>> : T extends Set<infer V> ? Set<KebabToSnakeRecursive<V>> : T extends object ? {
-    [K in keyof T as TransformKey<K & string, {
-        sourceCase: 'kebab';
-        targetCase: 'snake';
-    }>]: KebabToSnakeRecursive<T[K]>;
+type TransformValue<T, To extends StringCase, Depth extends number | undefined, Level extends unknown[]> = IsAny<T> extends true ? T : IsDepthReached<Depth, Level> extends true ? T : T extends Primitive ? T : T extends readonly (infer Item)[] ? number extends T['length'] ? T extends unknown[] ? TransformValue<Item, To, Depth, Level>[] : readonly TransformValue<Item, To, Depth, Level>[] : {
+    [I in keyof T]: TransformValue<T[I], To, Depth, Level>;
+} : T extends ReadonlyMap<infer K, infer V> ? Map<K extends string ? TransformKey<K, To> : K, TransformValue<V, To, Depth, NextLevel<Depth, Level>>> : T extends ReadonlySet<infer V> ? Set<TransformValue<V, To, Depth, NextLevel<Depth, Level>>> : T extends UntouchedValue ? T : T extends object ? {
+    [K in keyof T as K extends string ? TransformKey<K, To> : K]: K extends symbol ? T[K] : TransformValue<T[K], To, Depth, NextLevel<Depth, Level>>;
 } : T;
 /**
- * Generic recursive transformation type
- * Allows dynamically selecting the transformation based on source and target cases
+ * Applies a numeric literal `Depth`: a negative depth transforms nothing, and a
+ * fractional depth is not supported precisely, so its result is `unknown`.
+ */
+type TransformWithDepth<T, To extends StringCase, Depth extends number> = `${Depth}` extends `-${string}` ? T : `${Depth}` extends `${string}${'.' | 'e'}${string}` ? unknown : TransformValue<T, To, Depth, []>;
+/**
+ * `true` for a numeric literal, branded or not (`2`, `2 & Brand`), and `false` for
+ * `number` and a branded `number`: a literal shares no value with at least one of two
+ * different literals, while `number` shares one with both.
+ */
+type IsNumberLiteral<N extends number> = [N & 0] extends [never] ? true : [N & 1] extends [never] ? true : false;
+/**
+ * The result for one `Depth` (distributes over a union of depths): every level for
+ * `undefined`, `unknown` for a depth that is only known to be a `number`.
+ */
+type TransformToDepth<T, To extends StringCase, Depth extends number | undefined> = Depth extends unknown ? [Depth] extends [undefined] ? TransformValue<T, To, undefined, []> : IsNumberLiteral<Depth & number> extends true ? TransformWithDepth<T, To, Depth & number> : unknown : never;
+/**
+ * The exact type `transform` returns for `data` of type `T`, transformed to `To` (default
+ * `'camel'`) for `Depth` nesting levels (default: all of them).
+ *
+ * `To` and `Depth` distribute over unions: when they are only known to be one of several
+ * values, the result is the union of the possible results. A depth that is not a numeric
+ * literal (`number`, including `Infinity`) cannot be known, so the result is `unknown`,
+ * as it is for a `To` or `Depth` typed `any`. String enum members and branded literals
+ * are accepted for `To`.
+ *
+ * @example
+ * ```typescript
+ * type User = TransformResult<{ user_id: number; created_at: Date }>;
+ * // => { userId: number; createdAt: Date }
+ * ```
+ */
+type TransformResult<T, To extends StringCase = 'camel', Depth extends number | undefined = undefined> = IsAny<To> extends true ? unknown : IsAny<Depth> extends true ? unknown : To extends unknown ? TransformToDepth<T, PlainCase<To>, Depth> : never;
+/** `true` when `Options` may omit `Key` (an optional property) */
+type IsOptional<Options, Key extends PropertyKey> = Key extends keyof Options ? Record<never, never> extends Pick<Options, Key> ? true : false : false;
+/** `true` when the option `Key` of `Options` is typed `any` */
+type IsAnyOption<Options, Key extends PropertyKey> = Key extends keyof Options ? IsAny<Options[Key]> : false;
+/**
+ * Includes `true` when a member of a union of options objects has a `targetCase` typed
+ * `any` (check it with `true extends HasAnyTargetCase<Options>`)
+ */
+type HasAnyTargetCase<Options> = Options extends unknown ? IsAnyOption<Options, 'targetCase'> : never;
+/**
+ * The result for one options object. An optional `targetCase` or `depth` may also be
+ * omitted, which uses its default; those results are added explicitly because, without
+ * `strictNullChecks`, `undefined` disappears from the property's type.
+ */
+type TransformResultForOne<T, Options, To extends StringCase = TargetCaseOf<Options>, Depth extends number | undefined = DepthOf<Options> extends infer D extends number | undefined ? D : never> = TransformResult<T, To, Depth> | (IsOptional<Options, 'targetCase'> extends true ? TransformResult<T, 'camel', Depth> : never) | (IsOptional<Options, 'depth'> extends true ? TransformResult<T, To, undefined> : never) | (IsOptional<Options, 'targetCase'> extends true ? IsOptional<Options, 'depth'> extends true ? TransformResult<T, 'camel', undefined> : never : never);
+/**
+ * The result type for an options object. Each member of a union of options objects gives
+ * its own result, so its `targetCase` and `depth` stay paired. Options typed `any`, or
+ * with a `targetCase` or `depth` typed `any`, say nothing about the result: `unknown`.
  */
-type TransformRecursive<T, FromCase extends StringCase, ToCase extends StringCase> = FromCase extends 'snake' ? ToCase extends 'camel' ? SnakeToCamelRecursive<T> : ToCase extends 'pascal' ? SnakeToPascalRecursive<T> : ToCase extends 'kebab' ? SnakeToKebabRecursive<T> : T : FromCase extends 'camel' ? ToCase extends 'snake' ? CamelToSnakeRecursive<T> : ToCase extends 'pascal' ? CamelToPascalRecursive<T> : ToCase extends 'kebab' ? CamelToKebabRecursive<T> : T : FromCase extends 'pascal' ? ToCase extends 'snake' ? PascalToSnakeRecursive<T> : ToCase extends 'camel' ? PascalToCamelRecursive<T> : ToCase extends 'kebab' ? PascalToKebabRecursive<T> : T : FromCase extends 'kebab' ? ToCase extends 'snake' ? KebabToSnakeRecursive<T> : ToCase extends 'camel' ? KebabToCamelRecursive<T> : ToCase extends 'pascal' ? KebabToPascalRecursive<T> : T : T;
+type TransformResultFor<T, Options> = IsAny<Options> extends true ? unknown : Options extends unknown ? IsAnyOption<Options, 'targetCase'> extends true ? unknown : IsAnyOption<Options, 'depth'> extends true ? unknown : TransformResultForOne<T, Options> : never;
 
-declare function transform<T, From extends StringCase, To extends StringCase>(data: T, options: TransformOptions & {
-    depth?: number;
+/**
+ * Transforms the keys of `data` to camelCase, at every nesting level.
+ *
+ * Every key of the result type is typed the way the runtime transforms it, except in
+ * values TypeScript cannot tell apart from plain objects (see "Result types" in the
+ * readme).
+ */
+declare function transform<T>(data: T, options?: undefined): TransformResult<T>;
+/**
+ * Transforms the keys of `data` to `targetCase` (default `'camel'`), at every nesting
+ * level unless `depth` is set.
+ *
+ * Every key of the result type is typed the way the runtime transforms it, except in
+ * values TypeScript cannot tell apart from plain objects (see "Result types" in the
+ * readme).
+ *
+ * `To` and `Depth` capture the literal values of `targetCase` and `depth`. `Options`
+ * captures the options object as a whole, so a value that may be `undefined` (which the
+ * runtime treats as omitted) is reflected in the result type, and each member of a union
+ * of options objects gets its own result. `NoUnknownOptions` keeps rejecting unknown
+ * option names. An options object that may itself be `undefined` matches neither this
+ * overload nor the one above, and gets an `unknown` result type from the last one.
+ *
+ * The type parameter defaults only apply when type arguments are passed explicitly, and
+ * give an `unknown` result type. An explicit `any` as the second type argument was the
+ * output type before `To` existed, so it still gives `any` (`To` is `any` there, while
+ * the options keep their default type); a `targetCase` typed `any` gives `unknown`.
+ */
+declare function transform<T, To extends StringCase | undefined = StringCase | undefined, Depth extends number | undefined = number | undefined, Options extends TransformOptions = TransformOptions>(data: T, options: Options & {
+    targetCase?: To;
+    depth?: Depth;
+} & NoUnknownOptions<Options>): IsAny<To> extends true ? true extends HasAnyTargetCase<Options> ? unknown : To : TransformResultFor<T, Options>;
+/**
+ * The 2.x form with explicit `<Data, SourceCase, TargetCase>` type arguments.
+ *
+ * @deprecated `sourceCase` has no effect: leave out the type arguments and `sourceCase`,
+ * and the result type is inferred, `depth` included. This form does not accept `depth`.
+ */
+declare function transform<T, From extends StringCase, To extends StringCase>(data: T, options: {
     sourceCase: From;
     targetCase: To;
-}): TransformRecursive<T, From, To>;
+    depth?: undefined;
+}): TransformResult<T, To>;
 /**
  * Transform data to a specified output type.
  *
  * Note: When using this overload, type safety is not enforced between the input, options, and output type.
- * The 'sourceCase' option is intentionally omitted, as it is not used for type inference here.
- */
-declare function transform<T, K>(data: T, options?: Omit<TransformOptions, 'sourceCase'> & {
-    depth?: number;
-}): K;
-declare function transform<T>(data: T, options?: TransformOptions & {
-    depth?: number;
-}): unknown;
+ * The deprecated 'sourceCase' option is not accepted here, as it has no effect.
+ */
+declare function transform<T, K>(data: T, options?: Omit<TransformOptions, 'sourceCase'>): K;
 
 export { transform };
-export type { StringCase, TransformOptions };
+export type { StringCase, TransformOptions, TransformResult, TransformResultFor, TransformValue };