{"id":12754,"library":"safe-identifier","title":"Safe Identifier String Sanitization","description":"safe-identifier is a focused utility library designed to sanitize arbitrary strings for safe use as JavaScript identifiers and object property names. It currently stands at version 0.4.2 and has shown an active release cadence, with several minor versions released recently. The library's core functionality includes replacing invalid characters with underscores, pre-pending an underscore if the resulting identifier conflicts with a JavaScript reserved word (covering ES3 to ES2018 and active proposals), and optionally appending a unique hash to generated identifiers. For property names, it intelligently uses dot notation (`obj.key`) or bracket notation (`obj[\"key\"]`) based on key validity and ECMAScript 3rd Edition reserved words, ensuring compatibility down to IE8. Its primary differentiator is its comprehensive standard coverage and explicit handling for browser compatibility and uniqueness.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/eemeli/safe-identifier","tags":["javascript","es3","es5","esnext","reserved","words","code","generation","identifier"],"install":[{"cmd":"npm install safe-identifier","lang":"bash","label":"npm"},{"cmd":"yarn add safe-identifier","lang":"bash","label":"yarn"},{"cmd":"pnpm add safe-identifier","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const identifier = require('safe-identifier').identifier","symbol":"identifier","correct":"import { identifier } from 'safe-identifier'"},{"note":"Avoid direct imports from internal paths; use the root package export. ESM imports are the canonical way to access `property`.","wrong":"const property = require('safe-identifier/dist/property.js')","symbol":"property","correct":"import { property } from 'safe-identifier'"},{"note":"For environments expecting ESM, `require()` may lead to `ERR_REQUIRE_ESM`. Use the star import for convenient access to all named exports.","wrong":"const safeIdentifier = require('safe-identifier')","symbol":"All exports","correct":"import * as safeIdentifier from 'safe-identifier'"}],"quickstart":{"code":"import { identifier, property } from 'safe-identifier';\n\n// Basic identifier sanitization\nconsole.log(`'Foo' -> ${identifier('Foo')}`); // 'Foo'\nconsole.log(`'enum' (reserved word) -> ${identifier('enum')}`); // '_enum'\n\n// Identifier with uniqueness hash\nconst keyWithSpaces = 'my var';\nconst uniqueId1 = identifier(keyWithSpaces, true);\nconst uniqueId2 = identifier(' another\\tkey ', true);\nconsole.log(`'${keyWithSpaces}' (unique) -> ${uniqueId1}`); // Example: 'my_var_hk17pp'\nconsole.log(`' another\\tkey ' (unique) -> ${uniqueId2}`); // Example: 'another_key_1d8fi3'\n\n// Property name sanitization\nconsole.log(`'Foo', 'bar' -> ${property('Foo', 'bar')}`); // 'Foo.bar'\nconsole.log(`'Foo', 'bar\\nbar' -> ${property('Foo', 'bar\\nbar')}`); // 'Foo[\"bar\\nbar\"]'\nconsole.log(`null, 'foo' -> ${property(null, 'foo')}`); // 'foo'\nconsole.log(`null, 'void' (ES3 reserved) -> ${property(null, 'void')}`); // '\"void\"' (quoted for ES3 compatibility)","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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`.","message":"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).","severity":"gotcha","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` the `safe-identifier` package in a CommonJS module after v0.4.0, which transitioned to an ESM-first package structure.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/safe-identifier/index.js from ... not supported."},{"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`.","cause":"Incorrectly importing or destructuring `identifier` or `property`, possibly due to a mixed CommonJS/ESM environment or a typo.","error":"TypeError: identifier is not a function"},{"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.","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.","error":"The output of identifier('my_input', true) is not consistent between runs or environments."}],"ecosystem":"npm"}