Safe Identifier String Sanitization

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/safe-identifier/index.js from ... not supported.

  cause Attempting to `require()` the `safe-identifier` package in a CommonJS module after v0.4.0, which transitioned to an ESM-first package structure.
  fix Change your import statement from `const { identifier } = require('safe-identifier');` to `import { identifier } from 'safe-identifier';` and ensure your project is configured for ESM.

• TypeError: identifier is not a function

  cause Incorrectly importing or destructuring `identifier` or `property`, possibly due to a mixed CommonJS/ESM environment or a typo.
  fix Verify that you are using the correct import syntax for your module type (e.g., `import { identifier } from 'safe-identifier';` for ESM) and that `safe-identifier` is correctly installed in your `node_modules`.

• The output of identifier('my_input', true) is not consistent between runs or environments.

  cause The `unique` parameter for `identifier` appends a hash, which is designed to vary based on the input key's hash and potentially other factors, making the output non-deterministic for the same 'base' string.
  fix If you require a consistent, deterministic output for a given input string, ensure you do not pass `true` as the second argument to `identifier`. Only use `unique: true` when you need to avoid name collisions.

Warnings

• breaking Version 0.4.0 introduced `exports` and `type: module` fields to `package.json`, and dropped the separate `reserved.mjs` file. This change makes the package ESM-first and can cause issues with CommonJS `require()` in environments that strictly enforce module resolution.
  Fix: Migrate your import statements to ESM `import` syntax. If you absolutely require CJS, ensure your build tool or runtime is configured to handle ESM packages correctly, or consider using dynamic `import()` for ESM packages within CJS.
• breaking The `identifier` function's signature changed in v0.3.0 to add a second optional boolean argument `unique`. While an addition, it's important to be aware if you had custom wrappers or type definitions that assumed a single argument.
  Fix: Review existing calls to `identifier` to ensure the new `unique` parameter is handled as intended. Update any custom type definitions to reflect the `(key: string, unique?: boolean): string` signature.
• gotcha The `unique` parameter for `identifier(key, unique)` appends a 32-bit hash of the original `key` to the sanitized output. If `unique` is set to `true`, the output will always vary for different inputs or even the same input if an internal hash salt were to change (though unlikely in this lib).
  Fix: Only set `unique` to `true` when you explicitly need a collision-resistant identifier, such as for dynamically generated elements or properties where input might overlap after basic sanitization. If deterministic output based solely on the sanitized key is required, omit or set `unique` to `false`.
• gotcha The `property` function applies specific rules for ECMAScript 3rd Edition reserved words (e.g., `void`, `enum`) and invalid characters, potentially quoting the key, to ensure compatibility with older browsers like IE8. This might result in a more verbose property access string than strictly necessary for modern environments.
  Fix: Understand that `property` prioritizes broad compatibility. If you are targeting only modern JavaScript environments and prefer cleaner property access for simple keys, you might opt for a direct `obj[key]` or `obj.key` if you are certain `key` is safe for the target environment, or use `identifier` for the key portion and manually construct the accessor.

Install

• npm install safe-identifier npm
• yarn add safe-identifier yarn
• pnpm add safe-identifier pnpm

Imports

• identifier
  wrong:

  const identifier = require('safe-identifier').identifier

  correct:

  import { identifier } from 'safe-identifier'

  Since v0.4.0, the package includes an `exports` map and `type: module` in `package.json`, making it ESM-first. While CommonJS might still work in some environments, direct ESM imports are recommended.
• property
  wrong:

  const property = require('safe-identifier/dist/property.js')

  correct:

  import { property } from 'safe-identifier'

  Avoid direct imports from internal paths; use the root package export. ESM imports are the canonical way to access `property`.
• All exports
  wrong:

  const safeIdentifier = require('safe-identifier')

  correct:

  import * as safeIdentifier from 'safe-identifier'

  For environments expecting ESM, `require()` may lead to `ERR_REQUIRE_ESM`. Use the star import for convenient access to all named exports.

Quickstart

Demonstrates basic usage of `identifier` for sanitizing string keys to be valid JavaScript identifiers, including handling reserved words and generating unique hashes, and `property` for generating safe object property accessors with ES3 compatibility.

import { identifier, property } from 'safe-identifier';

// Basic identifier sanitization
console.log(`'Foo' -> ${identifier('Foo')}`); // 'Foo'
console.log(`'enum' (reserved word) -> ${identifier('enum')}`); // '_enum'

// Identifier with uniqueness hash
const keyWithSpaces = 'my var';
const uniqueId1 = identifier(keyWithSpaces, true);
const uniqueId2 = identifier(' another\tkey ', true);
console.log(`'${keyWithSpaces}' (unique) -> ${uniqueId1}`); // Example: 'my_var_hk17pp'
console.log(`' another\tkey ' (unique) -> ${uniqueId2}`); // Example: 'another_key_1d8fi3'

// Property name sanitization
console.log(`'Foo', 'bar' -> ${property('Foo', 'bar')}`); // 'Foo.bar'
console.log(`'Foo', 'bar\nbar' -> ${property('Foo', 'bar\nbar')}`); // 'Foo["bar\nbar"]'
console.log(`null, 'foo' -> ${property(null, 'foo')}`); // 'foo'
console.log(`null, 'void' (ES3 reserved) -> ${property(null, 'void')}`); // '"void"' (quoted for ES3 compatibility)