Private State Utility

Common errors

• TypeError: Object.defineProperty is not a function

  cause Attempting to use `makeUniqueKey()` in an environment that does not fully support ECMAScript 5's `Object.defineProperty`.
  fix Ensure your JavaScript environment supports ES5. If not, consider using the `makeAccessor()` approach for privacy, which relies on closure scope and is more broadly compatible.

• Cannot read properties of undefined (reading 'totallySafeProperty')

  cause Trying to access a private property created with `makeAccessor()` using standard object access (e.g., `obj.totallySafeProperty`) instead of the specific accessor function.
  fix Always access private state through the accessor function returned by `makeAccessor()`, like `getSecret(obj).totallySafeProperty`.

• SyntaxError: Named export 'makeAccessor' not found. The requested module 'private' does not provide an export named 'makeAccessor'

  cause Incorrectly trying to import the CommonJS `private` module using ES module `import` syntax.
  fix Change your import statement to use CommonJS `require()`: `const { makeAccessor } = require('private');` or `const getSecret = require('private').makeAccessor();`.

Warnings

• breaking Prior to v0.1.2, this package suffered from memory leaks due to holding permanent module-local references to secret objects. This was fixed by storing secrets directly on owning objects (but securely).
  Fix: Upgrade to version 0.1.2 or newer to ensure secret objects are garbage collected when their owning objects become unreachable.
• gotcha The `makeUniqueKey()` method's safety guarantees for non-discoverability and non-enumerability rely on `Object.defineProperty`. Using this in environments without a full ES5 implementation (e.g., very old browsers) may compromise privacy.
  Fix: Ensure the target environment fully supports ES5's `Object.defineProperty`. For broader compatibility, the `makeAccessor()` approach is generally safer as it relies on closure privacy.
• deprecated For new JavaScript projects, native Private Class Fields (e.g., `#privateField`) introduced in ES2022 provide a standardized and often preferred way to encapsulate private state within classes, offering stronger guarantees and better tooling support.
  Fix: Consider refactoring code to use native private class fields for classes. For arbitrary object state, `WeakMap` can also be a modern alternative for private data association.
• breaking This package is CommonJS-only and does not provide an ES module build. Attempting to use `import` syntax will result in errors.
  Fix: Use CommonJS `require()` syntax to import and utilize this package within Node.js environments or transpiled browser bundles.
• gotcha This package appears to be abandoned, with no significant updates or active maintenance since its early versions. It may not be compatible with very recent JavaScript runtime changes or provide security updates.
  Fix: Evaluate alternatives like native private class fields or `WeakMap` for long-term project stability and security. Use with caution in production.

Install

• npm install private npm
• yarn add private yarn
• pnpm add private pnpm

Imports

• makeAccessor
  wrong:

  import { makeAccessor } from 'private';

  correct:

  const getSecret = require('private').makeAccessor();

  This package is CommonJS-only and does not support ES modules. The `makeAccessor` function returns a new function for a specific private context.
• makeUniqueKey
  wrong:

  import { makeUniqueKey } from 'private';

  correct:

  const secretKey = require('private').makeUniqueKey();

  This function returns a string property name. Its safety guarantees rely on ES5's `Object.defineProperty`.
• private module
  wrong:

  import Private from 'private';

  correct:

  const Private = require('private');

  The entire module is exposed as a CommonJS object. Named exports are accessed as properties of this object.

Quickstart

Demonstrates how to associate truly private state with a JavaScript object using `makeAccessor`, preventing direct enumeration or access.

const getSecret = require("private").makeAccessor();

const user = {
  id: 'user-123',
  name: 'Alice',
  email: 'alice@example.com'
};

// Associate private data with the 'user' object
getSecret(user).passwordHash = "$2a$10$abcdefghijklmnopqrstuv.w.x.y.z";
getSecret(user).apiTokens = ['token-a', 'token-b'];

// Public properties are visible
console.log('Public user keys:', Object.keys(user)); // [ 'id', 'name', 'email' ]
console.log('Public user properties:', Object.getOwnPropertyNames(user)); // [ 'id', 'name', 'email' ]

// Private data is only accessible via the accessor function
const userData = getSecret(user);
console.log('User private data:', userData); // { passwordHash: '$2a$10$abcdefghijklmnopqrstuv.w.x.y.z', apiTokens: [ 'token-a', 'token-b' ] }
console.log('User password hash:', userData.passwordHash);