jsprim: JavaScript Primitive Utilities

Common errors

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

  cause Attempting to use ES module named import syntax for `jsprim`, which is a CommonJS module.
  fix Use CommonJS destructuring: `const { deepCopy } = require('jsprim');`

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ES module file where `type: "module"` is set in package.json, or implicitly when Node.js treats a file as ESM.
  fix If `jsprim` is the only CJS dependency, consider `import * as jsprim from 'jsprim';` if you're in an ES module context. Otherwise, ensure your file is treated as CommonJS (e.g., by using `.cjs` extension or `"type": "commonjs"` in package.json).

• Error: "depth" must be a non-negative integer

  cause Providing an invalid `depth` parameter (e.g., negative number, non-integer) to `flattenObject` or `flattenIter`.
  fix Ensure the `depth` argument for `flattenObject` or `flattenIter` is always a non-negative integer (0 or greater).

Warnings

• gotcha The `flattenObject` and `flattenIter` functions exhibit a behavioral difference when the `depth` parameter is 0. `flattenObject` omits the array wrapping the original object in this specific case, while `flattenIter`'s behavior is logically equivalent to `flattenObject(obj, depth).forEach(func)`, which implies a consistent array-like iteration.
  Fix: Be mindful of the `depth === 0` edge case when using `flattenObject`. If consistent iteration behavior is required, especially for `depth === 0`, `flattenIter` might be a more predictable choice, or ensure explicit handling for the `flattenObject` output when `depth` is 0.
• gotcha This package is a CommonJS module and does not natively support ES module `import` syntax. Attempting to use `import jsprim from 'jsprim'` or `import { someFunc } from 'jsprim'` directly in an ES module environment will result in errors without proper interop configuration or a build step.
  Fix: Ensure you are using `require()` for importing `jsprim` in Node.js environments. If using in an ES module context, you may need to use `import * as jsprim from 'jsprim'` or configure your build system (e.g., Babel, webpack) for CommonJS interop.
• gotcha The library has not been updated in approximately four years and targets Node.js versions as old as 0.6.0. While functional, it may not leverage modern JavaScript features, performance improvements, or security best practices introduced in newer Node.js releases.
  Fix: Evaluate the library's functionality against your specific project requirements and Node.js version. Consider auditing its source if used in security-sensitive contexts, or look for more actively maintained alternatives if up-to-date features and support are critical.

Install

• npm install jsprim npm
• yarn add jsprim yarn
• pnpm add jsprim pnpm

Imports

• jsprim
  wrong:

  import jsprim from 'jsprim';

  correct:

  const jsprim = require('jsprim');

  jsprim is a CommonJS module. Use `require()` to import the entire module object.
• deepCopy
  wrong:

  import { deepCopy } from 'jsprim';

  correct:

  const { deepCopy } = require('jsprim');

  For named functions, destructure from the `require()` result. Direct ES module named imports are not supported.
• isEmpty
  wrong:

  import { isEmpty } from 'jsprim';

  correct:

  const { isEmpty } = require('jsprim');

  As a CommonJS module, named exports are accessed by destructuring the `require()` result. ES module named imports will fail.

Quickstart

Demonstrates core utilities like deepCopy, deepEqual, isEmpty, pluck for nested property access, and flattenIter for efficient object traversal without materializing full arrays.

const jsprim = require('jsprim');

// Example 1: Deep Copy
const originalObject = { a: 1, b: { c: 2 }, d: [3, 4] };
const copiedObject = jsprim.deepCopy(originalObject);
console.log('Deep Copy:', copiedObject);
console.log('Are copies identical? (reference check):', originalObject === copiedObject); // Should be false
console.log('Are contents deeply equal:', jsprim.deepEqual(originalObject, copiedObject)); // Should be true

// Example 2: Deep Equal
const obj1 = { x: 1, y: { z: 2 } };
const obj2 = { x: 1, y: { z: 2 } };
const obj3 = { x: 1, y: { z: 3 } };
console.log('Deep Equal (obj1, obj2):', jsprim.deepEqual(obj1, obj2)); // Should be true
console.log('Deep Equal (obj1, obj3):', jsprim.deepEqual(obj1, obj3)); // Should be false

// Example 3: Is Empty
console.log('Is {} empty?', jsprim.isEmpty({})); // Should be true
console.log('Is {a: 1} empty?', jsprim.isEmpty({ a: 1 })); // Should be false

// Example 4: Pluck
const nestedObject = {
    user: {
        profile: {
            name: 'Alice',
            age: 30
        },
        settings: { theme: 'dark' }
    },
    'user.id': '123'
};
console.log('Pluck user.profile.name:', jsprim.pluck(nestedObject, 'user.profile.name')); // Should be 'Alice'
console.log('Pluck user.id:', jsprim.pluck(nestedObject, 'user.id')); // Should be '123' (direct property takes precedence)
console.log('Pluck nonExistent.path:', jsprim.pluck(nestedObject, 'nonExistent.path')); // Should be undefined

// Example 5: flattenIter (demonstrates use without full array materialization)
const data = {
    'RegionA': { 'CityX': { 'pop': 100 }, 'CityY': { 'pop': 200 } },
    'RegionB': { 'CityZ': { 'pop': 300 } }
};
const flattenedResults = [];
jsprim.flattenIter(data, 2, (entry) => {
    flattenedResults.push(entry);
});
console.log('Flattened results (using flattenIter):', flattenedResults);