deep-case-crafter 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -1 +1 @@
-"use strict";const e="[object Object]";function t(e,t,r){"__proto__"===t?Object.defineProperty(e,t,{value:r,enumerable:!0,writable:!0,configurable:!0}):e[t]=r}function r(e){return e>="a"&&e<="z"}function n(e){return e>="A"&&e<="Z"}function o(e,t){var o,s,u,a,c;if(!n(null!==(o=e[t])&&void 0!==o?o:""))return!1;const i=null!==(s=e[t-1])&&void 0!==s?s:"";if(r(i)||(l=i)>="0"&&l<="9")return!0;var l;if(!(n(i)&&n(null!==(u=e[t-2])&&void 0!==u?u:"")&&r(null!==(a=e[t+1])&&void 0!==a?a:"")))return!1;return!("s"===e[t+1]&&!r(null!==(c=e[t+2])&&void 0!==c?c:""))}function s(e,t){if(!e)return e;let r="";for(let n=0;n<e.length;n++)o(e,n)&&(r+=t),r+=e[n].toLowerCase();return r}const u={snake:{camel:function(e){return e.toLowerCase().replace(/_([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/_+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:function(e){return e.replace(/_/g,"-")},snake:e=>e},camel:{snake:function(e){return s(e,"_")},pascal:function(e){return e?e.charAt(0).toUpperCase()+e.slice(1):e},kebab:function(e){return s(e,"-")},camel:e=>e},pascal:{snake:function(e){return s(e,"_")},camel:function(e){var t,s,u;if(!e)return e;const a=null!==(t=e[2])&&void 0!==t?t:"";if(n(e[0])&&n(null!==(s=e[1])&&void 0!==s?s:"")&&r(a)&&("s"!==a||r(null!==(u=e[3])&&void 0!==u?u:"")))return e[0].toLowerCase()+e.slice(1);let c=1;for(;c<e.length&&!o(e,c);)c++;return e.slice(0,c).toLowerCase()+e.slice(c)},kebab:function(e){return s(e,"-")},pascal:e=>e},kebab:{snake:function(e){return e.replace(/-/g,"_")},camel:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:e=>e}};const a=/^[a-z0-9_]+$/,c=/__+/,i=/^[a-z][a-zA-Z0-9]*$/,l=/^[A-Z][a-zA-Z0-9]*$/,f=/^[a-z0-9-]+$/,p=/-{2,}/,g=/[A-Z]/,d=/[a-z]/,b=/^[a-z0-9]+$/;function h(e){return"string"!=typeof e?null:function(e){if(e.includes("_")||e.includes("-")||e.includes(" "))return!1;if(e.length>0&&!/^[A-Za-z0-9]+$/.test(e))return!1;if(e.length<=1)return!0;const t=e[0],r=e.slice(1);return e===e.toLowerCase()||t===t.toUpperCase()&&r===r.toLowerCase()}(e)?"single":function(e){return"string"==typeof e&&a.test(e)&&!c.test(e)&&(e.includes("_")||b.test(e))}(e)?"snake":function(e){return"string"==typeof e&&i.test(e)&&g.test(e)}(e)?"camel":function(e){return"string"==typeof e&&l.test(e)&&d.test(e)}(e)?"pascal":function(e){return"string"==typeof e&&f.test(e)&&!p.test(e)&&(e.includes("-")||b.test(e))}(e)?"kebab":null}function y(e,t){if(!e)return e;const{string:r,shouldTransform:n,sourceCase:o,singleWord:s}=function(e){if("string"!=typeof e)throw new Error("Input must be a string");if(0===e.length)return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};if(/[^A-Za-z0-9_-]/.test(e)||/^[^A-Za-z]/.test(e)||/[^A-Za-z0-9]$/.test(e))return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};const t=h(e);return t?"single"===t?{string:e,shouldTransform:!0,sourceCase:null,singleWord:!0}:{string:e,shouldTransform:!0,sourceCase:t,singleWord:!1}:{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1}}(e);return n?s?function(e,t){switch(t){case"pascal":return e.charAt(0).toUpperCase()+e.slice(1).toLowerCase();case"camel":return e.charAt(0).toLowerCase()+e.slice(1);case"snake":case"kebab":return e.toLowerCase();default:return e}}(r,t):o&&o!==t?u[o][t](r):r:r}const C=new Map;function v(e,t){var r;if(e.length>100)return y(e,t);let n=C.get(t);n||(n={current:new Map,previous:new Map},C.set(t,n));let o=n.current.get(e);return void 0===o&&(o=null!==(r=n.previous.get(e))&&void 0!==r?r:y(e,t),n.current.size>=1e3&&(n.previous=n.current,n.current=new Map),n.current.set(e,o)),o}function w(r,n,o=[],s=0){var u;if(null===r||"object"!=typeof r)return r;if(s>=n.depth)return r;const a=n.depth===1/0?0:s,c=null!==(u=o[a])&&void 0!==u?u:o[a]=new WeakMap;if(c.has(r))return c.get(r);if(Array.isArray(r)){const e=[];return c.set(r,e),function(e,t,r,n,o){for(const s of e)t.push(w(s,r,n,o))}(r,e,n,o,s),e}const i=s+1,l=function(t){try{return Object.prototype.toString.call(t)}catch(t){return e}}(r);if(function(e,t){if(!(e instanceof Map)&&"[object Map]"!==t)return!1;try{return Map.prototype.has.call(e,void 0),!0}catch(e){return!1}}(r,l)){const e=new Map;return c.set(r,e),function(e,t,r,n,o){for(const[s,u]of e)t.set("string"==typeof s?y(s,r.targetCase):s,w(u,r,n,o))}(r,e,n,o,i),e}if(function(e,t){if(!(e instanceof Set)&&"[object Set]"!==t)return!1;try{return Set.prototype.has.call(e,void 0),!0}catch(e){return!1}}(r,l)){const e=new Set;return c.set(r,e),function(e,t,r,n,o){for(const s of e)t.add(w(s,r,n,o))}(r,e,n,o,i),e}if(l===e){const e=r,s={};c.set(r,s);for(const r in e)Object.prototype.hasOwnProperty.call(e,r)&&t(s,v(r,n.targetCase),w(e[r],n,o,i));for(const t of Object.getOwnPropertySymbols(e))s[t]=e[t];return s}return r}const m=["camel","snake","pascal","kebab"];function z(e){if("string"==typeof e)return JSON.stringify(e);if("bigint"==typeof e)return`${e}n`;if(null===e)return"null";if("object"==typeof e||"function"==typeof e)try{return Object.prototype.toString.call(e)}catch(e){return"an object"}return String(e)}exports.transform=function(e,t){var r;const n=(null==t?void 0:t.targetCase)||"camel",o=null!==(r=null==t?void 0:t.depth)&&void 0!==r?r:1/0;if(s=n,!m.includes(s))throw new TypeError(`Unsupported targetCase ${z(n)}. Use one of: ${m.join(", ")}.`);var s;if("number"!=typeof o||Number.isNaN(o))throw new TypeError(`Unsupported depth ${z(o)}. Use a number, or omit depth to transform every level.`);return w(e,{targetCase:n,depth:o})};
+"use strict";const e=/^[a-z0-9_]+$/,t=/__+/,n=/^[a-z][a-zA-Z0-9]*$/,r=/^[A-Z][a-zA-Z0-9]*$/,o=/^[a-z0-9-]+$/,s=/-{2,}/,u=/[A-Z]/,a=/[a-z]/,i=/^[a-z0-9]+$/,c=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,l=/^[^.]+(?:\.[^.]+)*$/;function f(e){if("string"==typeof e)return JSON.stringify(e);if("bigint"==typeof e)return`${e}n`;if(null===e)return"null";if("object"==typeof e||"function"==typeof e)try{return Object.prototype.toString.call(e)}catch(e){return"an object"}return String(e)}function p(e){const t=e.indexOf(".");return-1===t?[e]:[e.slice(0,t),e.slice(t+1)]}const d=[];function g(e){let t,n=!1;for(const r of e)void 0===r?n=!0:(null!=t?t:t=[]).push(r);return{keepKey:n,pathsBelow:t?h(t):d,scope:void 0}}function h(e){return 1===e.length?e:[...new Set(e)].sort()}function y(e,t){const n=[];let r;for(const t of e){const[e,o]=p(t);if("*"===e)n.push(o);else{null!=r||(r=new Map);const t=r.get(e);t?t.push(o):r.set(e,[o])}}const o=new Map;for(const[e,t]of null!=r?r:[])o.set(e,g(n.length?[...t,...n]:t));const{targetCase:s,depth:u}=t.plain.options,a={targetCase:s,depth:u,exclude:null},i={options:a,visitedRefs:[],named:o,other:g(n),root:t};return a.exclude=i,i}function w(e,t){const n="string"==typeof t?e.named.get(t):void 0;return null!=n?n:e.other}function b(e,t){var n;return null!==(n=t.scope)&&void 0!==n?n:t.scope=0===t.pathsBelow.length?e.root.plain:function(e,t){const n=JSON.stringify(e);let r=t.states.get(n);return r||(r=y(e,t),t.states.set(n,r)),r}(t.pathsBelow,e.root)}const v="[object Object]";function C(e,t,n){"__proto__"===t?Object.defineProperty(e,t,{value:n,enumerable:!0,writable:!0,configurable:!0}):e[t]=n}function m(e){return e>="a"&&e<="z"}function k(e){return e>="A"&&e<="Z"}function U(e,t){var n,r,o,s;if(!k(null!==(n=e[t])&&void 0!==n?n:""))return!1;const u=null!==(r=e[t-1])&&void 0!==r?r:"";if(m(u)||(a=u)>="0"&&a<="9")return!0;var a;if(!(k(u)&&m(null!==(o=e[t+1])&&void 0!==o?o:"")))return!1;return!("s"===e[t+1]&&!m(null!==(s=e[t+2])&&void 0!==s?s:""))}function z(e,t){if(!e)return e;let n="";for(let r=0;r<e.length;r++)U(e,r)&&(n+=t),n+=e[r].toLowerCase();return n}const $={snake:{camel:function(e){return e.toLowerCase().replace(/_([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/_+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:function(e){return e.replace(/_/g,"-")},snake:e=>e},camel:{snake:function(e){return z(e,"_")},pascal:function(e){return e?e.charAt(0).toUpperCase()+e.slice(1):e},kebab:function(e){return z(e,"-")},camel:e=>e},pascal:{snake:function(e){return z(e,"_")},camel:function(e){if(!e)return e;let t=1;for(;t<e.length&&!U(e,t);)t++;return e.slice(0,t).toLowerCase()+e.slice(t)},kebab:function(e){return z(e,"-")},pascal:e=>e},kebab:{snake:function(e){return e.replace(/-/g,"_")},camel:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:e=>e}};function j(c){return"string"!=typeof c?null:function(e){if(e.includes("_")||e.includes("-")||e.includes(" "))return!1;if(e.length>0&&!/^[A-Za-z0-9]+$/.test(e))return!1;if(e.length<=1)return!0;const t=e[0],n=e.slice(1);return e===e.toLowerCase()||t===t.toUpperCase()&&n===n.toLowerCase()}(c)?"single":function(n){return"string"==typeof n&&e.test(n)&&!t.test(n)&&(n.includes("_")||i.test(n))}(c)?"snake":function(e){return"string"==typeof e&&n.test(e)&&u.test(e)}(c)?"camel":function(e){return"string"==typeof e&&r.test(e)&&a.test(e)}(c)?"pascal":function(e){return"string"==typeof e&&o.test(e)&&!s.test(e)&&(e.includes("-")||i.test(e))}(c)?"kebab":null}function A(e,t){if(!e)return e;const{string:n,shouldTransform:r,sourceCase:o,singleWord:s}=function(e){if("string"!=typeof e)throw new Error("Input must be a string");if(0===e.length)return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};if(/[^A-Za-z0-9_-]/.test(e)||/^[^A-Za-z]/.test(e)||/[^A-Za-z0-9]$/.test(e)||c.test(e))return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};const t=j(e);return t?"single"===t?{string:e,shouldTransform:!0,sourceCase:null,singleWord:!0}:{string:e,shouldTransform:!0,sourceCase:t,singleWord:!1}:{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1}}(e);return r?s?function(e,t){switch(t){case"pascal":return e.charAt(0).toUpperCase()+e.slice(1).toLowerCase();case"camel":return e.charAt(0).toLowerCase()+e.slice(1);case"snake":case"kebab":return e.toLowerCase();default:return e}}(n,t):o&&o!==t?$[o][t](n):n:n}const _=new Map;function x(e,t){var n;if(e.length>100)return A(e,t);let r=_.get(t);r||(r={current:new Map,previous:new Map},_.set(t,r));let o=r.current.get(e);return void 0===o&&(o=null!==(n=r.previous.get(e))&&void 0!==n?n:A(e,t),r.current.size>=1e3&&(r.previous=r.current,r.current=new Map),r.current.set(e,o)),o}function O(e,t,n=[],r=0){var o;if(null===e||"object"!=typeof e)return e;if(r>=t.depth)return e;const s=t.depth===1/0?0:r,u=null!==(o=n[s])&&void 0!==o?o:n[s]=new WeakMap;if(u.has(e))return u.get(e);if(Array.isArray(e)){const o=[];return u.set(e,o),function(e,t,n,r,o){for(const s of e)t.push(O(s,n,r,o))}(e,o,t,n,r),o}const a=r+1,i=function(e){try{return Object.prototype.toString.call(e)}catch(e){return v}}(e);if(function(e,t){if(!(e instanceof Map)&&"[object Map]"!==t)return!1;try{return Map.prototype.has.call(e,void 0),!0}catch(e){return!1}}(e,i)){const r=new Map;return u.set(e,r),null===t.exclude?function(e,t,n,r,o){for(const[s,u]of e)t.set("string"==typeof s?A(s,n.targetCase):s,O(u,n,r,o))}(e,r,t,n,a):function(e,t,n,r){for(const[o,s]of e){const e=w(n,o),u=b(n,e);t.set("string"!=typeof o||e.keepKey?o:A(o,n.options.targetCase),O(s,u.options,u.visitedRefs,r))}}(e,r,t.exclude,a),r}if(function(e,t){if(!(e instanceof Set)&&"[object Set]"!==t)return!1;try{return Set.prototype.has.call(e,void 0),!0}catch(e){return!1}}(e,i)){const r=new Set;return u.set(e,r),function(e,t,n,r,o){for(const s of e)t.add(O(s,n,r,o))}(e,r,t,n,a),r}if(i===v){const r=e,o={};if(u.set(e,o),null===t.exclude)for(const e in r)Object.prototype.hasOwnProperty.call(r,e)&&C(o,x(e,t.targetCase),O(r[e],t,n,a));else!function(e,t,n,r){for(const o in e)if(Object.prototype.hasOwnProperty.call(e,o)){const s=w(n,o),u=b(n,s);C(t,s.keepKey?o:x(o,n.options.targetCase),O(e[o],u.options,u.visitedRefs,r))}}(r,o,t.exclude,a);for(const e of Object.getOwnPropertySymbols(r))o[e]=r[e];return o}return e}const M=["camel","snake","pascal","kebab"];function T(e){const t=e||"camel";if(n=t,!M.includes(n))throw new TypeError(`Unsupported targetCase ${f(t)}. Use one of: ${M.join(", ")}.`);var n;return t}exports.transform=function(e,t){var n;const r=null==t?void 0:t.targetCase,o=null!==(n=null==t?void 0:t.depth)&&void 0!==n?n:1/0,s=T(r);if("number"!=typeof o||Number.isNaN(o))throw new TypeError(`Unsupported depth ${f(o)}. Use a number, or omit depth to transform every level.`);const u={targetCase:s,depth:o,exclude:null},a=null==t?void 0:t.exclude,i=void 0===a?null:function(e,t){if(null==e)return null;if(!Array.isArray(e))throw new TypeError(`Unsupported exclude ${f(e)}. Use an array of paths, such as ["metadata.*"].`);for(const t of e)if("string"!=typeof t||!l.test(t))throw new TypeError(`Unsupported exclude path ${f(t)}. Use non-empty keys joined with dots, such as "metadata.*".`);if(0===e.length)return null;const n={plain:{options:t,visitedRefs:[]},states:new Map};return y(h(e),n)}(a,u);return null===i?O(e,u):O(e,i.options,i.visitedRefs)},exports.transformKey=function(e,t){if("string"!=typeof e)throw new TypeError(`Unsupported key ${f(e)}. Use a string.`);if("string"==typeof t)throw new TypeError(`Unsupported options ${f(t)}. Use an options object: { targetCase: ${f(t)} }.`);return A(e,T(null==t?void 0:t.targetCase))};

package/dist/index.mjs

@@ -1 +1 @@
-const e="[object Object]";function t(e,t,r){"__proto__"===t?Object.defineProperty(e,t,{value:r,enumerable:!0,writable:!0,configurable:!0}):e[t]=r}function r(e){return e>="a"&&e<="z"}function n(e){return e>="A"&&e<="Z"}function o(e,t){var o,s,u,a,c;if(!n(null!==(o=e[t])&&void 0!==o?o:""))return!1;const i=null!==(s=e[t-1])&&void 0!==s?s:"";if(r(i)||(l=i)>="0"&&l<="9")return!0;var l;if(!(n(i)&&n(null!==(u=e[t-2])&&void 0!==u?u:"")&&r(null!==(a=e[t+1])&&void 0!==a?a:"")))return!1;return!("s"===e[t+1]&&!r(null!==(c=e[t+2])&&void 0!==c?c:""))}function s(e,t){if(!e)return e;let r="";for(let n=0;n<e.length;n++)o(e,n)&&(r+=t),r+=e[n].toLowerCase();return r}const u={snake:{camel:function(e){return e.toLowerCase().replace(/_([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/_+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:function(e){return e.replace(/_/g,"-")},snake:e=>e},camel:{snake:function(e){return s(e,"_")},pascal:function(e){return e?e.charAt(0).toUpperCase()+e.slice(1):e},kebab:function(e){return s(e,"-")},camel:e=>e},pascal:{snake:function(e){return s(e,"_")},camel:function(e){var t,s,u;if(!e)return e;const a=null!==(t=e[2])&&void 0!==t?t:"";if(n(e[0])&&n(null!==(s=e[1])&&void 0!==s?s:"")&&r(a)&&("s"!==a||r(null!==(u=e[3])&&void 0!==u?u:"")))return e[0].toLowerCase()+e.slice(1);let c=1;for(;c<e.length&&!o(e,c);)c++;return e.slice(0,c).toLowerCase()+e.slice(c)},kebab:function(e){return s(e,"-")},pascal:e=>e},kebab:{snake:function(e){return e.replace(/-/g,"_")},camel:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:e=>e}};const a=/^[a-z0-9_]+$/,c=/__+/,i=/^[a-z][a-zA-Z0-9]*$/,l=/^[A-Z][a-zA-Z0-9]*$/,f=/^[a-z0-9-]+$/,p=/-{2,}/,g=/[A-Z]/,d=/[a-z]/,b=/^[a-z0-9]+$/;function h(e){return"string"!=typeof e?null:function(e){if(e.includes("_")||e.includes("-")||e.includes(" "))return!1;if(e.length>0&&!/^[A-Za-z0-9]+$/.test(e))return!1;if(e.length<=1)return!0;const t=e[0],r=e.slice(1);return e===e.toLowerCase()||t===t.toUpperCase()&&r===r.toLowerCase()}(e)?"single":function(e){return"string"==typeof e&&a.test(e)&&!c.test(e)&&(e.includes("_")||b.test(e))}(e)?"snake":function(e){return"string"==typeof e&&i.test(e)&&g.test(e)}(e)?"camel":function(e){return"string"==typeof e&&l.test(e)&&d.test(e)}(e)?"pascal":function(e){return"string"==typeof e&&f.test(e)&&!p.test(e)&&(e.includes("-")||b.test(e))}(e)?"kebab":null}function y(e,t){if(!e)return e;const{string:r,shouldTransform:n,sourceCase:o,singleWord:s}=function(e){if("string"!=typeof e)throw new Error("Input must be a string");if(0===e.length)return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};if(/[^A-Za-z0-9_-]/.test(e)||/^[^A-Za-z]/.test(e)||/[^A-Za-z0-9]$/.test(e))return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};const t=h(e);return t?"single"===t?{string:e,shouldTransform:!0,sourceCase:null,singleWord:!0}:{string:e,shouldTransform:!0,sourceCase:t,singleWord:!1}:{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1}}(e);return n?s?function(e,t){switch(t){case"pascal":return e.charAt(0).toUpperCase()+e.slice(1).toLowerCase();case"camel":return e.charAt(0).toLowerCase()+e.slice(1);case"snake":case"kebab":return e.toLowerCase();default:return e}}(r,t):o&&o!==t?u[o][t](r):r:r}const C=new Map;function v(e,t){var r;if(e.length>100)return y(e,t);let n=C.get(t);n||(n={current:new Map,previous:new Map},C.set(t,n));let o=n.current.get(e);return void 0===o&&(o=null!==(r=n.previous.get(e))&&void 0!==r?r:y(e,t),n.current.size>=1e3&&(n.previous=n.current,n.current=new Map),n.current.set(e,o)),o}function w(r,n,o=[],s=0){var u;if(null===r||"object"!=typeof r)return r;if(s>=n.depth)return r;const a=n.depth===1/0?0:s,c=null!==(u=o[a])&&void 0!==u?u:o[a]=new WeakMap;if(c.has(r))return c.get(r);if(Array.isArray(r)){const e=[];return c.set(r,e),function(e,t,r,n,o){for(const s of e)t.push(w(s,r,n,o))}(r,e,n,o,s),e}const i=s+1,l=function(t){try{return Object.prototype.toString.call(t)}catch(t){return e}}(r);if(function(e,t){if(!(e instanceof Map)&&"[object Map]"!==t)return!1;try{return Map.prototype.has.call(e,void 0),!0}catch(e){return!1}}(r,l)){const e=new Map;return c.set(r,e),function(e,t,r,n,o){for(const[s,u]of e)t.set("string"==typeof s?y(s,r.targetCase):s,w(u,r,n,o))}(r,e,n,o,i),e}if(function(e,t){if(!(e instanceof Set)&&"[object Set]"!==t)return!1;try{return Set.prototype.has.call(e,void 0),!0}catch(e){return!1}}(r,l)){const e=new Set;return c.set(r,e),function(e,t,r,n,o){for(const s of e)t.add(w(s,r,n,o))}(r,e,n,o,i),e}if(l===e){const e=r,s={};c.set(r,s);for(const r in e)Object.prototype.hasOwnProperty.call(e,r)&&t(s,v(r,n.targetCase),w(e[r],n,o,i));for(const t of Object.getOwnPropertySymbols(e))s[t]=e[t];return s}return r}const m=["camel","snake","pascal","kebab"];function z(e){if("string"==typeof e)return JSON.stringify(e);if("bigint"==typeof e)return`${e}n`;if(null===e)return"null";if("object"==typeof e||"function"==typeof e)try{return Object.prototype.toString.call(e)}catch(e){return"an object"}return String(e)}function k(e,t){var r;const n=(null==t?void 0:t.targetCase)||"camel",o=null!==(r=null==t?void 0:t.depth)&&void 0!==r?r:1/0;if(s=n,!m.includes(s))throw new TypeError(`Unsupported targetCase ${z(n)}. Use one of: ${m.join(", ")}.`);var s;if("number"!=typeof o||Number.isNaN(o))throw new TypeError(`Unsupported depth ${z(o)}. Use a number, or omit depth to transform every level.`);return w(e,{targetCase:n,depth:o})}export{k as transform};
+const e=/^[a-z0-9_]+$/,t=/__+/,n=/^[a-z][a-zA-Z0-9]*$/,r=/^[A-Z][a-zA-Z0-9]*$/,o=/^[a-z0-9-]+$/,s=/-{2,}/,u=/[A-Z]/,a=/[a-z]/,i=/^[a-z0-9]+$/,c=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,l=/^[^.]+(?:\.[^.]+)*$/;function f(e){if("string"==typeof e)return JSON.stringify(e);if("bigint"==typeof e)return`${e}n`;if(null===e)return"null";if("object"==typeof e||"function"==typeof e)try{return Object.prototype.toString.call(e)}catch(e){return"an object"}return String(e)}function p(e){const t=e.indexOf(".");return-1===t?[e]:[e.slice(0,t),e.slice(t+1)]}const d=[];function g(e){let t,n=!1;for(const r of e)void 0===r?n=!0:(null!=t?t:t=[]).push(r);return{keepKey:n,pathsBelow:t?h(t):d,scope:void 0}}function h(e){return 1===e.length?e:[...new Set(e)].sort()}function y(e,t){const n=[];let r;for(const t of e){const[e,o]=p(t);if("*"===e)n.push(o);else{null!=r||(r=new Map);const t=r.get(e);t?t.push(o):r.set(e,[o])}}const o=new Map;for(const[e,t]of null!=r?r:[])o.set(e,g(n.length?[...t,...n]:t));const{targetCase:s,depth:u}=t.plain.options,a={targetCase:s,depth:u,exclude:null},i={options:a,visitedRefs:[],named:o,other:g(n),root:t};return a.exclude=i,i}function w(e,t){const n="string"==typeof t?e.named.get(t):void 0;return null!=n?n:e.other}function b(e,t){var n;return null!==(n=t.scope)&&void 0!==n?n:t.scope=0===t.pathsBelow.length?e.root.plain:function(e,t){const n=JSON.stringify(e);let r=t.states.get(n);return r||(r=y(e,t),t.states.set(n,r)),r}(t.pathsBelow,e.root)}const v="[object Object]";function C(e,t,n){"__proto__"===t?Object.defineProperty(e,t,{value:n,enumerable:!0,writable:!0,configurable:!0}):e[t]=n}function m(e){return e>="a"&&e<="z"}function k(e){return e>="A"&&e<="Z"}function U(e,t){var n,r,o,s;if(!k(null!==(n=e[t])&&void 0!==n?n:""))return!1;const u=null!==(r=e[t-1])&&void 0!==r?r:"";if(m(u)||(a=u)>="0"&&a<="9")return!0;var a;if(!(k(u)&&m(null!==(o=e[t+1])&&void 0!==o?o:"")))return!1;return!("s"===e[t+1]&&!m(null!==(s=e[t+2])&&void 0!==s?s:""))}function z(e,t){if(!e)return e;let n="";for(let r=0;r<e.length;r++)U(e,r)&&(n+=t),n+=e[r].toLowerCase();return n}const $={snake:{camel:function(e){return e.toLowerCase().replace(/_([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/_+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:function(e){return e.replace(/_/g,"-")},snake:e=>e},camel:{snake:function(e){return z(e,"_")},pascal:function(e){return e?e.charAt(0).toUpperCase()+e.slice(1):e},kebab:function(e){return z(e,"-")},camel:e=>e},pascal:{snake:function(e){return z(e,"_")},camel:function(e){if(!e)return e;let t=1;for(;t<e.length&&!U(e,t);)t++;return e.slice(0,t).toLowerCase()+e.slice(t)},kebab:function(e){return z(e,"-")},pascal:e=>e},kebab:{snake:function(e){return e.replace(/-/g,"_")},camel:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase())},pascal:function(e){return e.toLowerCase().replace(/-+([a-z0-9])/g,(e,t)=>t.toUpperCase()).replace(/^[a-z]/,e=>e.toUpperCase())},kebab:e=>e}};function j(c){return"string"!=typeof c?null:function(e){if(e.includes("_")||e.includes("-")||e.includes(" "))return!1;if(e.length>0&&!/^[A-Za-z0-9]+$/.test(e))return!1;if(e.length<=1)return!0;const t=e[0],n=e.slice(1);return e===e.toLowerCase()||t===t.toUpperCase()&&n===n.toLowerCase()}(c)?"single":function(n){return"string"==typeof n&&e.test(n)&&!t.test(n)&&(n.includes("_")||i.test(n))}(c)?"snake":function(e){return"string"==typeof e&&n.test(e)&&u.test(e)}(c)?"camel":function(e){return"string"==typeof e&&r.test(e)&&a.test(e)}(c)?"pascal":function(e){return"string"==typeof e&&o.test(e)&&!s.test(e)&&(e.includes("-")||i.test(e))}(c)?"kebab":null}function A(e,t){if(!e)return e;const{string:n,shouldTransform:r,sourceCase:o,singleWord:s}=function(e){if("string"!=typeof e)throw new Error("Input must be a string");if(0===e.length)return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};if(/[^A-Za-z0-9_-]/.test(e)||/^[^A-Za-z]/.test(e)||/[^A-Za-z0-9]$/.test(e)||c.test(e))return{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1};const t=j(e);return t?"single"===t?{string:e,shouldTransform:!0,sourceCase:null,singleWord:!0}:{string:e,shouldTransform:!0,sourceCase:t,singleWord:!1}:{string:e,shouldTransform:!1,sourceCase:null,singleWord:!1}}(e);return r?s?function(e,t){switch(t){case"pascal":return e.charAt(0).toUpperCase()+e.slice(1).toLowerCase();case"camel":return e.charAt(0).toLowerCase()+e.slice(1);case"snake":case"kebab":return e.toLowerCase();default:return e}}(n,t):o&&o!==t?$[o][t](n):n:n}const _=new Map;function O(e,t){var n;if(e.length>100)return A(e,t);let r=_.get(t);r||(r={current:new Map,previous:new Map},_.set(t,r));let o=r.current.get(e);return void 0===o&&(o=null!==(n=r.previous.get(e))&&void 0!==n?n:A(e,t),r.current.size>=1e3&&(r.previous=r.current,r.current=new Map),r.current.set(e,o)),o}function x(e,t,n=[],r=0){var o;if(null===e||"object"!=typeof e)return e;if(r>=t.depth)return e;const s=t.depth===1/0?0:r,u=null!==(o=n[s])&&void 0!==o?o:n[s]=new WeakMap;if(u.has(e))return u.get(e);if(Array.isArray(e)){const o=[];return u.set(e,o),function(e,t,n,r,o){for(const s of e)t.push(x(s,n,r,o))}(e,o,t,n,r),o}const a=r+1,i=function(e){try{return Object.prototype.toString.call(e)}catch(e){return v}}(e);if(function(e,t){if(!(e instanceof Map)&&"[object Map]"!==t)return!1;try{return Map.prototype.has.call(e,void 0),!0}catch(e){return!1}}(e,i)){const r=new Map;return u.set(e,r),null===t.exclude?function(e,t,n,r,o){for(const[s,u]of e)t.set("string"==typeof s?A(s,n.targetCase):s,x(u,n,r,o))}(e,r,t,n,a):function(e,t,n,r){for(const[o,s]of e){const e=w(n,o),u=b(n,e);t.set("string"!=typeof o||e.keepKey?o:A(o,n.options.targetCase),x(s,u.options,u.visitedRefs,r))}}(e,r,t.exclude,a),r}if(function(e,t){if(!(e instanceof Set)&&"[object Set]"!==t)return!1;try{return Set.prototype.has.call(e,void 0),!0}catch(e){return!1}}(e,i)){const r=new Set;return u.set(e,r),function(e,t,n,r,o){for(const s of e)t.add(x(s,n,r,o))}(e,r,t,n,a),r}if(i===v){const r=e,o={};if(u.set(e,o),null===t.exclude)for(const e in r)Object.prototype.hasOwnProperty.call(r,e)&&C(o,O(e,t.targetCase),x(r[e],t,n,a));else!function(e,t,n,r){for(const o in e)if(Object.prototype.hasOwnProperty.call(e,o)){const s=w(n,o),u=b(n,s);C(t,s.keepKey?o:O(o,n.options.targetCase),x(e[o],u.options,u.visitedRefs,r))}}(r,o,t.exclude,a);for(const e of Object.getOwnPropertySymbols(r))o[e]=r[e];return o}return e}const M=["camel","snake","pascal","kebab"];function T(e){const t=e||"camel";if(n=t,!M.includes(n))throw new TypeError(`Unsupported targetCase ${f(t)}. Use one of: ${M.join(", ")}.`);var n;return t}function L(e,t){var n;const r=null==t?void 0:t.targetCase,o=null!==(n=null==t?void 0:t.depth)&&void 0!==n?n:1/0,s=T(r);if("number"!=typeof o||Number.isNaN(o))throw new TypeError(`Unsupported depth ${f(o)}. Use a number, or omit depth to transform every level.`);const u={targetCase:s,depth:o,exclude:null},a=null==t?void 0:t.exclude,i=void 0===a?null:function(e,t){if(null==e)return null;if(!Array.isArray(e))throw new TypeError(`Unsupported exclude ${f(e)}. Use an array of paths, such as ["metadata.*"].`);for(const t of e)if("string"!=typeof t||!l.test(t))throw new TypeError(`Unsupported exclude path ${f(t)}. Use non-empty keys joined with dots, such as "metadata.*".`);if(0===e.length)return null;const n={plain:{options:t,visitedRefs:[]},states:new Map};return y(h(e),n)}(a,u);return null===i?x(e,u):x(e,i.options,i.visitedRefs)}function S(e,t){if("string"!=typeof e)throw new TypeError(`Unsupported key ${f(e)}. Use a string.`);if("string"==typeof t)throw new TypeError(`Unsupported options ${f(t)}. Use an options object: { targetCase: ${f(t)} }.`);return A(e,T(null==t?void 0:t.targetCase))}export{L as transform,S as transformKey};