TypeScript Type-Preserving Case Converter

Common errors

• Objects with keys like `my-kebab-case` are not converting correctly to `myKebabCase` after upgrading.

  cause The conversion logic for `kebab-case` changed in v2.0.0, treating hyphens as word breaks.
  fix This is expected behavior in v2.0.0+. Adjust your input data or conversion expectations if relying on the old `kebab-case` handling. If you need the old behavior, you might need to pre-process keys or stick to v1.x.

• Date objects are being converted to plain objects when using `objectToCamel` or `objectToSnake`.

  cause Older versions of the library did not preserve `Date` object types during key conversion.
  fix Upgrade `ts-case-convert` to version `2.0.5` or newer to ensure `Date` objects are properly preserved.

• ReferenceError: Buffer is not defined in browser environment when using `ts-case-convert`.

  cause Versions prior to 2.0.4 had a hard dependency on the Node.js `Buffer` global, which is not available in browsers.
  fix Upgrade `ts-case-convert` to version `2.0.4` or newer. This version replaced `Buffer` with `Uint8Array` for better cross-environment compatibility.

• When passing an array as the top-level object to `objectToCamel` or `objectToSnake`, the return type is an object, not an array.

  cause A bug in early 2.x versions (fixed in 2.0.1) caused top-level arrays to be incorrectly typed as objects.
  fix Upgrade `ts-case-convert` to version `2.0.1` or newer.

Warnings

• breaking In version 2.0.0, the conversion logic for kebab-case strings changed. Previously, `kebab-case` was treated as a single unit; now, hyphens are considered unit breaks, affecting how it converts to `camelCase` or `PascalCase`.
  Fix: Review existing code that relies on `kebab-case` conversion if upgrading from v1.x. Adjust input keys or expect different output for `kebab-case` strings.
• gotcha Prior to versions 2.0.5 and 2.0.2, `Date` objects and Node.js `Buffer` objects were not correctly preserved during conversion, potentially leading to them being converted into generic plain objects or having their internal keys transformed. This could corrupt data or break functionality.
  Fix: Upgrade to `ts-case-convert@2.0.5` or later to ensure `Date` objects are preserved. Upgrade to `ts-case-convert@2.0.2` or later for `Buffer` object preservation.
• gotcha In early 2.x versions (e.g., prior to 2.0.1), passing a top-level array to conversion functions would incorrectly result in an object type instead of an array type being returned, affecting type inference and direct array method calls.
  Fix: Upgrade to `ts-case-convert@2.0.1` or later to ensure top-level arrays are correctly typed and returned as arrays.
• gotcha Versions prior to 2.0.4 had hard dependencies on the Node.js `Buffer` global object, causing issues when used in non-Node.js environments (like browsers) that do not define `Buffer`.
  Fix: Upgrade to `ts-case-convert@2.0.4` or later, which switched to `Uint8Array` internally to remove Node.js-specific dependencies and improve browser compatibility.

Install

• npm install ts-case-convert npm
• yarn add ts-case-convert yarn
• pnpm add ts-case-convert pnpm

Imports

• objectToCamel
  wrong:

  const objectToCamel = require('ts-case-convert').objectToCamel

  correct:

  import { objectToCamel } from 'ts-case-convert'

  ts-case-convert primarily uses ESM; CommonJS `require` should be avoided for new projects.
• objectToSnake
  wrong:

  const objectToSnake = require('ts-case-convert').objectToSnake

  correct:

  import { objectToSnake } from 'ts-case-convert'

  ESM is the recommended import style. Use default imports carefully, as this library uses named exports.
• CamelKeys

  import type { CamelKeys } from 'ts-case-convert'

  Utility types like `CamelKeys` and `SnakeKeys` can be imported for manual type manipulation, exposed since v2.1.0.

Quickstart

Demonstrates converting a complex object with nested structures, arrays, and special types (Date, null, undefined) from snake_case to camelCase and vice-versa, showcasing accurate type preservation and property access.

import { objectToCamel, objectToSnake } from 'ts-case-convert';

const sourceObject = {
  user_id: 123,
  first_name: 'John',
  last_name: 'Doe',
  email_address: 'john.doe@example.com',
  is_active: true,
  created_at: new Date('2023-01-01T10:00:00Z'),
  addresses_list: [
    { street_name: 'Main St', street_number: 123 },
    { street_name: 'Oak Ave', street_number: 45 },
  ],
  settings_map: {
    theme_color: 'blue',
    font_size: 16,
  },
  null_value: null,
  undefined_value: undefined,
};

// Convert keys to camelCase
const camelCaseObject = objectToCamel(sourceObject);

// Demonstrates type inference and access
type UserIDType = typeof camelCaseObject.userId; // type is 'number'
const userId: UserIDType = camelCaseObject.userId;
console.log('CamelCase Object:', camelCaseObject);
console.log('User ID:', userId); // Access property with camelCase

// Convert keys back to snake_case
const snakeCaseObject = objectToSnake(camelCaseObject);

// Demonstrates type inference and access
type FirstNameType = typeof snakeCaseObject.first_name; // type is 'string'
const firstName: FirstNameType = snakeCaseObject.first_name;
console.log('SnakeCase Object:', snakeCaseObject);
console.log('First Name:', firstName); // Access property with snake_case

// Example of nested access and type preservation
const firstAddressCamel = camelCaseObject.addressesList[0];
type StreetNameCamel = typeof firstAddressCamel.streetName; // type is 'string'
console.log('First address street name (camel):', firstAddressCamel.streetName);

const firstAddressSnake = snakeCaseObject.addresses_list[0];
type StreetNameSnake = typeof firstAddressSnake.street_name; // type is 'string'
console.log('First address street name (snake):', firstAddressSnake.street_name);