remeda/dist/toTitleCase.cjs.map

A utility library for JavaScript and Typescript.

{"version":3,"file":"toTitleCase.cjs","names":["words"],"sources":["../src/toTitleCase.ts"],"sourcesContent":["import type { IsEqual, IsLiteral, Join, Words } from \"type-fest\";\nimport type { OptionalOptionsWithDefaults } from \"./internal/types/OptionalOptionsWithDefaults\";\nimport { words } from \"./internal/words\";\n\nconst LOWER_CASE_CHARACTER_RE = /[a-z]/u;\n\nconst DEFAULT_PRESERVE_CONSECUTIVE_UPPERCASE = true;\n\ntype TitleCaseOptions = {\n  readonly preserveConsecutiveUppercase?: boolean;\n};\n\ntype TitleCaseOptionsWithDefaults<Options extends TitleCaseOptions> =\n  OptionalOptionsWithDefaults<\n    TitleCaseOptions,\n    Options,\n    {\n      // We use the runtime const for the default type so they stay coupled.\n      preserveConsecutiveUppercase: typeof DEFAULT_PRESERVE_CONSECUTIVE_UPPERCASE;\n    }\n  >;\n\ntype TitleCase<S extends string, Options extends TitleCaseOptions> =\n  IsLiteral<S> extends true\n    ? Join<\n        TitleCasedArray<\n          Words<IsEqual<S, Uppercase<S>> extends true ? Lowercase<S> : S>,\n          TitleCaseOptionsWithDefaults<Options>\n        >,\n        \" \"\n      >\n    : string;\n\ntype TitleCasedArray<\n  T extends ReadonlyArray<string>,\n  Options extends TitleCaseOptions,\n> = {\n  [I in keyof T]: Capitalize<\n    Options[\"preserveConsecutiveUppercase\"] extends true\n      ? T[I]\n      : Lowercase<T[I]>\n  >;\n};\n\n/**\n * Converts text to **Title Case** by splitting it into words, capitalizing the\n * first letter of each word, then joining them back together with spaces.\n *\n * Because it uses the built-in case conversion methods, the function shares\n * their _[locale inaccuracies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleLowerCase#description)_,\n * making it best suited for simple strings like identifiers and internal keys.\n * For linguistic text processing, use [`Intl.Segmenter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter)\n * with [`granularity: \"word\"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter#parameters),\n * [`toLocaleLowerCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleLowerCase),\n * and [`toLocaleUpperCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleUpperCase)\n * which are purpose-built to handle nuances in languages and locales.\n *\n * For other case manipulations see: `toLowerCase`, `toUpperCase`, `capitalize`,\n * `uncapitalize`, `toCamelCase`, `toKebabCase`, and `toSnakeCase`.\n *\n * @param data - A string.\n * @param options - An _optional_ object with the _optional_ property\n * `preserveConsecutiveUppercase` that can be used to change the way consecutive\n * uppercase characters are handled. Defaults to `true`.\n * @signature\n *   R.toTitleCase(data);\n *   R.toTitleCase(data, { preserveConsecutiveUppercase });\n * @example\n *   R.toTitleCase(\"hello world\"); // \"Hello World\"\n *   R.toTitleCase(\"--foo-bar--\"); // \"Foo Bar\"\n *   R.toTitleCase(\"fooBar\"); // \"Foo Bar\"\n *   R.toTitleCase(\"__FOO_BAR__\"); // \"Foo Bar\"\n *   R.toTitleCase(\"XMLHttpRequest\"); // \"XML Http Request\"\n *   R.toTitleCase(\"XMLHttpRequest\", { preserveConsecutiveUppercase: false }); // \"Xml Http Request\"\n * @dataFirst\n * @category String\n */\nexport function toTitleCase<S extends string, Options extends TitleCaseOptions>(\n  data: S,\n  options?: Options,\n): TitleCase<S, Options>;\n\n/**\n * Converts text to **Title Case** by splitting it into words, capitalizing the\n * first letter of each word, then joining them back together with spaces.\n *\n * Because it uses the built-in case conversion methods, the function shares\n * their _[locale inaccuracies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleLowerCase#description)_,\n * making it best suited for simple strings like identifiers and internal keys.\n * For linguistic text processing, use [`Intl.Segmenter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter)\n * with [`granularity: \"word\"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter#parameters),\n * [`toLocaleLowerCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleLowerCase),\n * and [`toLocaleUpperCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleUpperCase)\n * which are purpose-built to handle nuances in languages and locales.\n *\n * For other case manipulations see: `toLowerCase`, `toUpperCase`, `capitalize`,\n * `uncapitalize`, `toCamelCase`, `toKebabCase`, and `toSnakeCase`.\n *\n * @param options - An _optional_ object with the _optional_ property\n * `preserveConsecutiveUppercase` that can be used to change the way consecutive\n * uppercase characters are handled. Defaults to `true`.\n * @signature\n *   R.toTitleCase()(data);\n *   R.toTitleCase({ preserveConsecutiveUppercase })(data);\n * @example\n *   R.pipe(\"hello world\", R.toTitleCase()); // \"Hello World\"\n *   R.pipe(\"--foo-bar--\", R.toTitleCase()); // \"Foo Bar\"\n *   R.pipe(\"fooBar\", R.toTitleCase()); // \"Foo Bar\"\n *   R.pipe(\"__FOO_BAR__\", R.toTitleCase()); // \"Foo Bar\"\n *   R.pipe(\"XMLHttpRequest\", R.toTitleCase()); // \"XML Http Request\"\n *   R.pipe(\n *     \"XMLHttpRequest\",\n *     R.toTitleCase({ preserveConsecutiveUppercase: false }),\n *   ); // \"Xml Http Request\"\n * @dataLast\n * @category String\n */\nexport function toTitleCase<Options extends TitleCaseOptions>(\n  options?: Options,\n): <S extends string>(data: S) => TitleCase<S, Options>;\n\nexport function toTitleCase(\n  dataOrOptions?: TitleCaseOptions | string,\n  options?: TitleCaseOptions,\n): unknown {\n  return typeof dataOrOptions === \"string\"\n    ? toTitleCaseImplementation(dataOrOptions, options)\n    : (data: string) => toTitleCaseImplementation(data, dataOrOptions);\n}\n\n// Similar to the implementation used in toCamelCase\nconst toTitleCaseImplementation = (\n  data: string,\n  {\n    preserveConsecutiveUppercase = DEFAULT_PRESERVE_CONSECUTIVE_UPPERCASE,\n  }: TitleCaseOptions = {},\n): string =>\n  words(\n    LOWER_CASE_CHARACTER_RE.test(data)\n      ? data\n      : // If the text doesn't have **any** lowercase characters, we lowercase\n        // everything; otherwise we maintain existing case as it affects word\n        // boundaries.\n        data.toLowerCase(),\n  )\n    .map(\n      (word) =>\n        `${word[0]!.toUpperCase()}${\n          preserveConsecutiveUppercase\n            ? word.slice(1)\n            : word.slice(1).toLowerCase()\n        }`,\n    )\n    .join(\" \");\n"],"mappings":"wCAIM,EAA0B,SAE1B,EAAyC,GAmH/C,SAAgB,EACd,EACA,EACS,CACT,OAAO,OAAO,GAAkB,SAC5B,EAA0B,EAAe,EAAQ,CAChD,GAAiB,EAA0B,EAAM,EAAc,CAItE,MAAM,GACJ,EACA,CACE,+BAA+B,IACX,EAAE,GAExBA,EAAAA,EACE,EAAwB,KAAK,EAAK,CAC9B,EAIA,EAAK,aAAa,CACvB,CACE,IACE,GACC,GAAG,EAAK,GAAI,aAAa,GACvB,EACI,EAAK,MAAM,EAAE,CACb,EAAK,MAAM,EAAE,CAAC,aAAa,GAEpC,CACA,KAAK,IAAI"}