Registry / serialization / safe-identifier

safe-identifier

library0.4.2jsnpmunverified

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.

serialization

npm install safe-identifier

github ↗package ↗

INSTALL

IMPORT

SIG · SAFE-IDENTIFIER

safe-identifier

serializationjavascriptv0.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

identifier

✓ import { identifier } from 'safe-identifier'

✗ const identifier = require('safe-identifier').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

✓ import { property } from 'safe-identifier'

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

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

All exports

✓ import * as safeIdentifier from 'safe-identifier'

✗ const safeIdentifier = require('safe-identifier')

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

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)

Debug

Known issues

breakingVersion 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.

affects: >=0.4.0

breakingThe `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.

affects: >=0.3.0

gotchaThe `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`.

affects: >=0.3.0

gotchaThe `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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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

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.

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.

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/eemeli/safe-identifier ↗

packagehttps://www.npmjs.com/package/safe-identifier ↗