deep-case-crafter 3.0.0 → 3.2.0

package/dist/index.d.mts

@@ -27,14 +27,19 @@ type StringCase = 'camel' | 'pascal' | 'snake' | 'kebab';
 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
+ * Options for the transformKey function. The transform function takes them as well.
  */
-interface TransformOptions {
+interface TransformKeyOptions {
     /**
      * The target casing format to transform to
      * @default 'camel'
      */
     targetCase?: StringCase | undefined;
+}
+/**
+ * Options for the transform function
+ */
+interface TransformOptions extends TransformKeyOptions {
     /**
      * 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
@@ -48,6 +53,20 @@ interface TransformOptions {
      * @default Infinity
      */
     depth?: number | undefined;
+    /**
+     * Keys to leave unchanged, each given as its path: the keys of the input that lead to
+     * it, joined with `.`. `'metadata.*'` keeps the keys of `metadata`, `'users_by_id.*'`
+     * the IDs of a record. `*` stands for any key. Array items and Set members add no key
+     * to a path; Map keys do, and `*` also matches a Map key that is not a string. A key
+     * that contains a `.` can only be matched by `*`. Only the keys themselves are kept:
+     * the values under them are transformed as usual.
+     *
+     * Pass the paths inline, or `as const`, to get a precise result type. Paths only known
+     * as `string[]` give an `unknown` result type.
+     *
+     * @default []
+     */
+    exclude?: readonly string[] | 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.
@@ -55,13 +74,24 @@ interface TransformOptions {
     sourceCase?: StringCase | undefined;
 }
 /**
- * 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.
+ * Rejects option names that are not in `Known` (by default, the options of `transform`).
+ * 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 NoUnknownOptions<Options> = {
-    [K in Exclude<keyof Options, keyof TransformOptions>]: `Unknown option: ${K & string}`;
+type NoUnknownOptions<Options, Known = TransformOptions> = {
+    [K in Exclude<keyof Options, keyof Known>]: `Unknown option: ${K & string}`;
 };
+/**
+ * `NoUnknownOptions` for `transformKey`, but `unknown` when every option name is known.
+ * The options parameter is then `TransformKeyOptions` itself rather than an
+ * intersection, so TypeScript checks the argument for a property in common with it, as
+ * it does for every type whose properties are all optional: `'snake'`, an array, or a
+ * stored options object with only a misspelled option is rejected.
+ */
+type NoUnknownKeyOptions<Options> = [
+    Exclude<keyof Options, keyof TransformKeyOptions>
+] extends [never] ? unknown : NoUnknownOptions<Options, TransformKeyOptions>;
 /** `To` as a plain case literal, or `'camel'` (the default) for `undefined` */
 type CaseOrDefault<To> = To extends undefined ? 'camel' : PlainCase<To>;
 /**
@@ -74,6 +104,39 @@ type TargetCaseOf<Options> = 'targetCase' extends keyof Options ? CaseOrDefault<
  * `depth` is omitted.
  */
 type DepthOf<Options> = 'depth' extends keyof Options ? Options['depth'] : undefined;
+/**
+ * The `exclude` paths the runtime uses for one options object: `undefined` (none) when
+ * `exclude` is omitted.
+ */
+type ExcludeOf<Options> = 'exclude' extends keyof Options ? Options['exclude'] : undefined;
+
+/**
+ * Type-level mirror of the `exclude` matching (`excludePaths.ts`).
+ *
+ * The paths that still match at a level are a union of strings: the rest of each
+ * `exclude` path below the keys that lead there. `'users_by_id.*' | 'metadata.*'` at the
+ * top becomes `'*'` below `users_by_id`. `never` stands for no path.
+ */
+/**
+ * A key type `K` as the paths name its keys: a single key as its string literal, so that
+ * a string enum member or a number matches the key a path names, and any other key type
+ * (`string`, a branded `string`, a template literal pattern) as it is.
+ */
+type KeyName<K extends string | number> = K extends string ? IsStringLiteral<K> extends true ? `${K}` : K : `${K}`;
+/** The paths of `Paths` that end at this level: the keys they match keep their names */
+type PathEnds<Paths extends string> = Paths extends `${string}.${string}` ? never : Paths;
+/**
+ * The rest of each path of `Paths` that continues below the key `Key`, or below every
+ * key that no path names when `Key` is `'*'`
+ */
+type PathsBelow<Paths extends string, Key extends string> = Paths extends `${infer Head}.${infer Rest}` ? Head extends Key | '*' ? Rest : never : never;
+/**
+ * The keys that a key type `K` which is not a single literal (an index signature) may
+ * stand for, as far as `Paths` is concerned: each key in it that a path continues below,
+ * and `'*'` for every other key. A key is in `K` when they share a value, as `'u1'` does
+ * with a branded `string`.
+ */
+type KeyCases<Paths extends string, K extends string> = (Paths extends `${infer Head}.${string}` ? Head extends '*' ? never : [Head & K] extends [never] ? never : Head : never) | '*';
 
 /**
  * Character classes used by the type-level key transformation. They spell out the
@@ -86,6 +149,10 @@ type LowerLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | '
 type UpperLetter = Uppercase<LowerLetter>;
 /** ASCII digits */
 type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/** The letters of hexadecimal digits */
+type HexLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f';
+/** Hexadecimal digits, in either case */
+type HexDigit = Digit | HexLetter | Uppercase<HexLetter>;
 /** 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 _ -`) */
@@ -109,12 +176,21 @@ declare const ACRONYM_PLURAL_SUFFIX = "s";
  * (tail-recursive, so long keys compile).
  */
 type HasOnlyKeyChars<S extends string> = S extends `${infer C}${infer Rest}` ? C extends KeyChar ? HasOnlyKeyChars<Rest> : false : true;
+/** The canonical UUID form, where `x` stands for a hexadecimal digit (`UUID_REGEX`) */
+type UuidPattern = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
+/**
+ * `true` when `S` is a UUID in canonical form. `S` is compared with `UuidPattern` one
+ * character at a time, stopping at the first character that does not fit, so long keys
+ * stay cheap.
+ */
+type IsUuid<S extends string, Pattern extends string = UuidPattern> = Pattern extends `${infer P}${infer PatternRest}` ? S extends `${infer C}${infer Rest}` ? C extends (P extends 'x' ? HexDigit : P) ? IsUuid<Rest, PatternRest> : false : false : S extends '' ? true : false;
 /**
  * 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.
+ * character outside `A-Z a-z 0-9 _ -`, keys not starting with a letter, keys ending with
+ * a separator, and UUIDs. A UUID that starts with a digit is already preserved, so only
+ * keys that the other rules do not preserve are compared with the UUID form.
  */
-type IsPreservedKey<K extends string> = HasOnlyKeyChars<K> extends false ? true : K extends `${LowerLetter | UpperLetter}${string}` ? K extends `${string}${Separator}` ? true : false : true;
+type IsPreservedKey<K extends string> = HasOnlyKeyChars<K> extends false ? true : K extends `${LowerLetter | UpperLetter}${string}` ? K extends `${string}${Separator}` ? true : IsUuid<K> : true;
 /**
  * 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
@@ -125,25 +201,21 @@ type DetectedCase<K extends string> = K extends `${string}${Separator}${string}`
 type FirstChar<S extends string> = S extends `${infer C}${string}` ? C : '';
 /**
  * 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.
+ * uppercase and follows a lowercase letter or digit, or it follows an uppercase letter
+ * and comes before a lowercase letter, so the capitals before it are an acronym or a
+ * one-letter word — unless that lowercase letter is a plural `s` not followed by another
+ * lowercase letter.
  */
-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;
+type IsWordBoundary<C extends string, Prev extends string, Rest extends string> = C extends UpperLetter ? Prev extends LowerLetter | Digit ? true : Prev 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;
 /** 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;
-/**
- * Lowercases the first word, up to the first word boundary, so a leading acronym is
- * lowercased as a whole
- */
-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 ToSeparatedCase<S extends string, Sep extends Separator, Prev extends string = '', Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? ToSeparatedCase<Rest, Sep, C, `${Acc}${IsWordBoundary<C, Prev, Rest> extends true ? Sep : ''}${Lowercase<C>}`> : Acc;
 /**
- * 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`)
+ * PascalCase to camelCase (`pascalToCamelCase`): lowercases the first word, up to the
+ * first word boundary, so a leading acronym is lowercased as a whole
+ * (`HTTPRequest` -> `httpRequest`) and a leading one-letter word on its own
+ * (`XAxis` -> `xAxis`)
  */
-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>;
+type PascalToCamelCase<S extends string, Prev extends string = '', Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? IsWordBoundary<C, Prev, Rest> extends true ? `${Acc}${S}` : PascalToCamelCase<Rest, C, `${Acc}${Lowercase<C>}`> : Acc;
 /** 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`) */
@@ -155,10 +227,33 @@ type FormatKey<K extends string, From extends StringCase, To extends StringCase>
 /** 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;
 /**
- * The key a string key `K` becomes when transformed to `To`. A `string` or
+ * One key `K` (not a union) transformed to one plain target case `To`. A `string` or
  * template-literal key cannot be known exactly, so it becomes `string`.
  */
-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>;
+type TransformOneKey<K extends string, To extends StringCase> = IsStringLiteral<K> extends false ? string : K extends '' ? K : IsPreservedKey<K> extends true ? K : TransformDetectedKey<K, DetectedCase<K>, To>;
+/**
+ * One key `K` transformed to each member of a union of plain target cases `To`.
+ *
+ * Use `TransformKey` instead. This type is exported only so that declaration files can
+ * refer to it: for a fixed key and a generic target case, as in
+ * `<C extends StringCase>(targetCase: C) => transformKey('created_by_id', { targetCase })`,
+ * the key type is written in terms of it. Without a name to refer to, the compiler
+ * writes out its recursive steps, and gets them wrong.
+ */
+type TransformKeyToEach<K extends string, To extends StringCase> = To extends StringCase ? TransformOneKey<K, To> : never;
+/**
+ * The key a string key `K` becomes when transformed to `To` (default `'camel'`), as
+ * `transformKey` returns it. A `string` or template-literal key cannot be known exactly,
+ * so it becomes `string`. A union of keys or of target cases gives the union of their
+ * results, and a string enum member or branded literal stands for its case.
+ *
+ * @example
+ * ```typescript
+ * type Column = TransformKey<'createdAt' | 'userID', 'snake'>;
+ * // => 'created_at' | 'user_id'
+ * ```
+ */
+type TransformKey<K extends string, To extends StringCase = 'camel'> = K extends string ? TransformKeyToEach<K, PlainCase<To>> : never;
 
 /** Primitive values, including branded ones such as `string & { __brand: 'UserId' }` */
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
@@ -203,6 +298,47 @@ type TransformValue<T, To extends StringCase, Depth extends number | undefined,
 } : 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;
+/**
+ * `TransformValue` while `exclude` paths still match: `Paths` is the rest of each of them
+ * below this level (see `excludeTypes.ts`). A key at which a path ends keeps its name,
+ * and the paths that continue below a key go on into its value. Arrays and Sets pass
+ * them on to their items, which add no key to a path. Values that no path reaches are
+ * transformed by `TransformValue`.
+ *
+ * Use `TransformResult` instead. This type is exported for the same reason as
+ * `TransformValue`.
+ */
+type TransformValueExcluding<T, To extends StringCase, Depth extends number | undefined, Level extends unknown[], Paths extends string> = 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[] ? TransformValueExcluding<Item, To, Depth, Level, Paths>[] : readonly TransformValueExcluding<Item, To, Depth, Level, Paths>[] : {
+    [I in keyof T]: TransformValueExcluding<T[I], To, Depth, Level, Paths>;
+} : T extends ReadonlyMap<infer K, infer V> ? Map<ExcludingKey<K, To, PathEnds<Paths>>, TransformBelowMapKeys<V, To, Depth, NextLevel<Depth, Level>, MapPathsBelow<K, Paths>>> : T extends ReadonlySet<infer V> ? Set<TransformValueExcluding<V, To, Depth, NextLevel<Depth, Level>, Paths>> : T extends UntouchedValue ? T : T extends object ? {
+    [K in keyof T as ExcludingKey<K, To, PathEnds<Paths>>]: K extends symbol ? T[K] : TransformBelowKey<T[K], To, Depth, NextLevel<Depth, Level>, Paths, KeyName<K & (string | number)>>;
+} : T;
+/**
+ * A key of an object, or a member of a Map's key type: it keeps its name where a path
+ * of `Ends` ends at it, and is transformed otherwise. A key type that is not a single
+ * literal keeps its name only where `*` ends.
+ */
+type ExcludingKey<K, To extends StringCase, Ends extends string> = K extends string ? '*' extends Ends ? K : IsStringLiteral<K> extends true ? [KeyName<K> & Ends] extends [never] ? TransformKey<K, To> : K : TransformKey<K, To> : K;
+/** `T` with the paths `Paths` that go on into it: by `TransformValue` once none is left */
+type TransformBelow<T, To extends StringCase, Depth extends number | undefined, Level extends unknown[], Paths extends string> = [Paths] extends [never] ? TransformValue<T, To, Depth, Level> : TransformValueExcluding<T, To, Depth, Level, Paths>;
+/**
+ * The value `T` under the key `Key`. A key type that is not a single literal may stand
+ * for several keys, which the paths may treat differently: each gives its own result.
+ */
+type TransformBelowKey<T, To extends StringCase, Depth extends number | undefined, Level extends unknown[], Paths extends string, Key extends string> = IsStringLiteral<Key> extends true ? TransformBelow<T, To, Depth, Level, PathsBelow<Paths, Key>> : TransformBelowEach<T, To, Depth, Level, Paths, KeyCases<Paths, Key>>;
+/** `T` under each of `Keys` (distributes over them) */
+type TransformBelowEach<T, To extends StringCase, Depth extends number | undefined, Level extends unknown[], Paths extends string, Keys extends string> = Keys extends unknown ? TransformBelow<T, To, Depth, Level, PathsBelow<Paths, Keys>> : never;
+/**
+ * The paths below the keys of a Map with key type `K`, one tuple per set of them: a Map
+ * has one value type for all of its keys, while the paths below each key may differ.
+ * Only `*` matches a key that is not a string, and a key type that may also hold strings
+ * (`unknown`, `{}`) stands for every string key as well.
+ */
+type MapPathsBelow<K, Paths extends string> = K extends string ? IsStringLiteral<K> extends true ? [PathsBelow<Paths, KeyName<K>>] : EachPathsBelow<Paths, KeyCases<Paths, K>> : string extends K ? EachPathsBelow<Paths, KeyCases<Paths, string>> : [PathsBelow<Paths, '*'>];
+/** The paths below each of `Keys`, as a tuple each (distributes over them) */
+type EachPathsBelow<Paths extends string, Keys extends string> = Keys extends unknown ? [PathsBelow<Paths, Keys>] : never;
+/** The value type of a Map, below each set of paths of `Below` (see `MapPathsBelow`) */
+type TransformBelowMapKeys<V, To extends StringCase, Depth extends number | undefined, Level extends unknown[], Below> = Below extends [infer Paths extends string] ? TransformBelow<V, To, Depth, Level, Paths> : never;
 /**
  * Applies a numeric literal `Depth`: a negative depth transforms nothing, and a
  * fractional depth is not supported precisely, so its result is `unknown`.
@@ -219,23 +355,60 @@ type IsNumberLiteral<N extends number> = [N & 0] extends [never] ? true : [N & 1
  * `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;
+/**
+ * `TransformToDepth` (and `TransformWithDepth`) for the `exclude` paths `Paths`. Kept
+ * apart, so that results without `exclude` take no extra step.
+ */
+type TransformToDepthExcluding<T, To extends StringCase, Depth extends number | undefined, Paths extends string> = Depth extends unknown ? [Depth] extends [undefined] ? TransformValueExcluding<T, To, undefined, [], Paths> : IsNumberLiteral<Depth & number> extends true ? `${Depth & number}` extends `-${string}` ? T : `${Depth & number}` extends `${string}${'.' | 'e'}${string}` ? unknown : TransformValueExcluding<T, To, Depth & number, [], Paths> : unknown : never;
+/**
+ * The result for an `exclude` tuple, collecting its paths into `Paths`. A union element
+ * stands for several tuples, which give their own results. A path with an empty key makes
+ * `transform` throw (`never`), and paths that are not all known (`string[]`, a rest
+ * element, a `string` element) give `unknown`.
+ */
+type TransformExcluding<T, To extends StringCase, Depth extends number | undefined, Exclude extends readonly string[], Paths extends string = never> = Exclude extends readonly [] ? [Paths] extends [never] ? TransformToDepth<T, To, Depth> : TransformToDepthExcluding<T, To, Depth, Paths> : Exclude extends readonly [
+    infer Path extends string,
+    ...infer Rest extends readonly string[]
+] ? Path extends unknown ? IsStringLiteral<Path> extends true ? Path extends '' | `.${string}` | `${string}.` | `${string}..${string}` ? never : TransformExcluding<T, To, Depth, Rest, Paths | Path> : unknown : never : unknown;
+/**
+ * Includes `true` when a member of `Exclude` is an array that is not a tuple (`string[]`,
+ * or a tuple with a rest element), or when `Exclude` is `any`: paths that cannot be known.
+ * Their result is `unknown`, and so is the result of a union that includes them, so
+ * checking this first saves working out the other members.
+ */
+type HasUnknownPaths<Exclude> = Exclude extends readonly string[] ? number extends Exclude['length'] ? true : false : false;
+/**
+ * The result for each member of `Exclude` (distributes over them): no path for an
+ * `undefined` one.
+ */
+type TransformExcludingEach<T, To extends StringCase, Depth extends number | undefined, Exclude extends readonly string[] | undefined> = true extends HasUnknownPaths<Exclude> ? unknown : Exclude extends readonly string[] ? TransformExcluding<T, To, Depth, Exclude> : TransformToDepth<T, To, Depth>;
 /**
  * The exact type `transform` returns for `data` of type `T`, transformed to `To` (default
- * `'camel'`) for `Depth` nesting levels (default: all of them).
+ * `'camel'`) for `Depth` nesting levels (default: all of them), with the keys at the
+ * `Exclude` paths left unchanged (the type of the `exclude` option; default: none).
  *
- * `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
+ * `To`, `Depth` and `Exclude` 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 paths that are not a tuple of string literals (`string[]`), and
+ * for a `To`, `Depth` or `Exclude` 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 Page = TransformResult<
+ *   { page_items: Record<string, { item_id: number }> },
+ *   'camel',
+ *   undefined,
+ *   ['page_items.*']
+ * >;
+ * // => { pageItems: { [x: string]: { itemId: number } } }
  * ```
  */
-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;
+type TransformResult<T, To extends StringCase = 'camel', Depth extends number | undefined = undefined, Exclude extends readonly string[] | undefined = undefined> = IsAny<To | Depth | Exclude> extends true ? unknown : [Exclude] extends [undefined] ? To extends unknown ? TransformToDepth<T, PlainCase<To>, Depth> : never : To extends unknown ? TransformExcludingEach<T, PlainCase<To>, Depth, Exclude> : 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` */
@@ -246,17 +419,40 @@ type IsAnyOption<Options, Key extends PropertyKey> = Key extends keyof 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.
+ * The result for one options object, with the `exclude` paths `Exclude`. 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);
+type TransformResultForOne<T, Options, Exclude extends readonly string[] | undefined = undefined, To extends StringCase = TargetCaseOf<Options>, Depth extends number | undefined = DepthOf<Options> extends infer D extends number | undefined ? D : never> = TransformResult<T, To, Depth, Exclude> | (IsOptional<Options, 'targetCase'> extends true ? TransformResult<T, 'camel', Depth, Exclude> : never) | (IsOptional<Options, 'depth'> extends true ? TransformResult<T, To, undefined, Exclude> : never) | (IsOptional<Options, 'targetCase'> extends true ? IsOptional<Options, 'depth'> extends true ? TransformResult<T, 'camel', undefined, Exclude> : never : never);
+/**
+ * The result for one options object with an `exclude` option, which may also be omitted
+ * when it is optional (see `TransformResultForOne`). Options whose paths cannot be known,
+ * such as `TransformOptions` itself, give `unknown` straight away.
+ *
+ * Use `TransformResult` instead. This type is exported only so that declaration files
+ * can refer to it, as they do to `TransformResultFor`: the result of a generic wrapper
+ * whose `exclude` paths are a type parameter is written in terms of it.
+ */
+type TransformResultForExcluding<T, Options> = ExcludeOf<Options> extends infer Exclude extends readonly string[] | undefined ? true extends HasUnknownPaths<Exclude> ? unknown : TransformResultForOne<T, Options, Exclude> | (IsOptional<Options, 'exclude'> extends true ? TransformResultForOne<T, Options> : 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`.
+ * its own result, so its `targetCase`, `depth` and `exclude` stay paired. Options typed
+ * `any`, or with a `targetCase`, `depth` or `exclude` typed `any`, say nothing about the
+ * result: `unknown`.
  */
-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;
+type TransformResultFor<T, Options> = IsAny<Options> extends true ? unknown : Options extends unknown ? IsAnyOption<Options, 'targetCase'> extends true ? unknown : IsAnyOption<Options, 'depth'> extends true ? unknown : 'exclude' extends keyof Options ? TransformResultForExcluding<T, Options> : TransformResultForOne<T, Options> : never;
+/**
+ * The key type `transformKey` returns for an options object. Each member of a union of
+ * options objects gives its own key, and an optional `targetCase` may also be omitted,
+ * which gives the camelCase key (see `TransformResultForOne`). Options typed `any`, or a
+ * `targetCase` typed `any`, give the key in any of the four cases.
+ *
+ * Not exported: declaration files of code around `transformKey` refer to `TransformKey`
+ * instead, because options with a generic type do not match the overload that returns
+ * it.
+ */
+type TransformKeyFor<K extends string, Options> = Options extends unknown ? TransformKey<K, TargetCaseOf<Options> | (IsOptional<Options, 'targetCase'> extends true ? 'camel' : never)> : never;
 
 /**
  * Transforms the keys of `data` to camelCase, at every nesting level.
@@ -268,7 +464,7 @@ type TransformResultFor<T, Options> = IsAny<Options> extends true ? unknown : Op
 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.
+ * level unless `depth` is set, except the keys at the `exclude` paths.
  *
  * 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
@@ -281,12 +477,22 @@ declare function transform<T>(data: T, options?: undefined): TransformResult<T>;
  * 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 constraint of `Options` makes it capture an inline `exclude` array as a tuple of
+ * string literals: `[...Paths]` keeps the strings literal, and `readonly [string?]`
+ * makes TypeScript 4.7 read the array as a tuple, an empty one included; any array of
+ * strings is still accepted, and so is `undefined`: with `exactOptionalPropertyTypes`, an
+ * optional property only accepts it when its type includes it. The parameter type does
+ * not mention `exclude` itself: intersecting the captured tuple with these types would
+ * make every call compare array types member by member.
+ *
  * 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 & {
+declare function transform<T, To extends StringCase | undefined = StringCase | undefined, Depth extends number | undefined = number | undefined, Options extends TransformOptions & {
+    exclude?: readonly [...Paths] | readonly [string?] | readonly string[] | undefined;
+} = TransformOptions, Paths extends readonly string[] = readonly string[]>(data: T, options: Options & {
     targetCase?: To;
     depth?: Depth;
 } & NoUnknownOptions<Options>): IsAny<To> extends true ? true extends HasAnyTargetCase<Options> ? unknown : To : TransformResultFor<T, Options>;
@@ -294,12 +500,14 @@ declare function transform<T, To extends StringCase | undefined = StringCase | u
  * 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`.
+ * and the result type is inferred, `depth` and `exclude` included. This form does not
+ * accept `depth` or `exclude`.
  */
 declare function transform<T, From extends StringCase, To extends StringCase>(data: T, options: {
     sourceCase: From;
     targetCase: To;
     depth?: undefined;
+    exclude?: undefined;
 }): TransformResult<T, To>;
 /**
  * Transform data to a specified output type.
@@ -309,5 +517,39 @@ declare function transform<T, From extends StringCase, To extends StringCase>(da
  */
 declare function transform<T, K>(data: T, options?: Omit<TransformOptions, 'sourceCase'>): K;
 
-export { transform };
-export type { StringCase, TransformOptions, TransformResult, TransformResultFor, TransformValue };
+/**
+ * Transforms one key to camelCase, the way `transform` transforms every key. A string
+ * that is not a key in one of the four cases, such as `'Hello World'`, `'USER_ID'` or a
+ * UUID, is returned unchanged (see "Key Preservation Rules" in the readme).
+ *
+ * The result type is the transformed key: `transformKey('user_id')` is typed `'userId'`.
+ */
+declare function transformKey<K extends string>(key: K, options?: undefined): TransformKey<K>;
+/**
+ * Transforms one key to `targetCase` (default `'camel'`), the way `transform` transforms
+ * every key. A string that is not a key in one of the four cases, such as
+ * `'Hello World'`, `'USER_ID'` or a UUID, is returned unchanged (see "Key Preservation
+ * Rules" in the readme).
+ *
+ * The result type is the transformed key: `transformKey('userID', { targetCase: 'snake' })`
+ * is typed `'user_id'`, a union of keys or target cases gives the union of the results,
+ * and a `string` key gives `string`.
+ *
+ * `Options` captures the options object as a whole, as `transform` does, so each member
+ * of a union of options objects gets its own result, and an optional `targetCase` also
+ * gives the camelCase key. `NoUnknownKeyOptions` rejects option names other than
+ * `targetCase`, and otherwise leaves the parameter `TransformKeyOptions` itself, so a
+ * value with no property in common with it, such as `'snake'`, is rejected as well. An
+ * options object that may itself be `undefined` does not match this overload, and gets
+ * a `string` result type from the last one.
+ */
+declare function transformKey<K extends string, Options extends TransformKeyOptions = TransformKeyOptions>(key: K, options: Options & NoUnknownKeyOptions<Options>): TransformKeyFor<K, Options>;
+/**
+ * Transforms one key to `targetCase` (default `'camel'`), the way `transform` transforms
+ * every key, typed as a `string`: for an options object that may be `undefined`, or one
+ * with properties other than `targetCase`.
+ */
+declare function transformKey(key: string, options?: TransformKeyOptions): string;
+
+export { transform, transformKey };
+export type { StringCase, TransformKey, TransformKeyOptions, TransformKeyToEach, TransformOptions, TransformResult, TransformResultFor, TransformResultForExcluding, TransformValue, TransformValueExcluding };