json-mask

library2.0.0jsnpmunverified

A tiny language and engine for selecting specific parts of a JavaScript object, hiding the rest. Version 2.0.0 is the latest stable release. It preserves the original object structure, unlike JSONPath or JSONSelect. Designed for HTTP partial responses (like Google APIs' ?fields= query). No dependencies, works in Node.js and browsers. Maintained with infrequent releases. Key differentiator: keeps the structure intact instead of flattening results.

devops

npm install json-mask

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-MASK

json-mask

devopsjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

mask (default)

✓ import mask from 'json-mask'

✗ const { mask } = require('json-mask')

ESM-only since v2. Default export is the mask function. CommonJS require with destructuring is incorrect.

mask (require)

✓ const mask = require('json-mask')

✗ const { mask } = require('json-mask')

CommonJS require returns the function directly, not as named export.

mask (TypeScript)

✓ import mask from 'json-mask'

✗ import * as mask from 'json-mask'

TypeScript with esModuleInterop: mask is default export. Star import gives object with default property.

Demonstrates masking an object by selecting specific fields (name, nested city, and array roles) while preserving structure.

import mask from 'json-mask'; const original = { id: 1, name: 'John', email: 'john@example.com', address: { street: '123 Main St', city: 'Anytown', zip: '12345' }, roles: ['admin', 'user'] }; const fields = 'name,address/city,roles'; const filtered = mask(original, fields); console.log(filtered); // Output: { name: 'John', address: { city: 'Anytown' }, roles: ['admin', 'user'] }

Debug

Known issues

breakingIn v2.0.0, the package changed from CommonJS to ESM-only. require() still works via dynamic import or bundler transform, but direct require may fail if Node.js version doesn't support ESM interop.

fix

Use import mask from 'json-mask' or update Node.js to version supporting ESM. For CommonJS projects, use dynamic import or upgrade to Node 14+ with --experimental-modules.

affects: >=2.0.0

breakingThe function signature changed. In v1, mask(obj, fields, options) accepted options object. In v2, options parameter is removed; only obj and fields are accepted.

fix

Remove the third argument from mask() calls. If you relied on options, handle them via the fields string (e.g., use nested paths).

affects: >=2.0.0

gotchaFields with special characters (e.g., dots, slashes) must be escaped with backslash. Unescaped special characters cause unexpected behavior or errors.

fix

Escape special characters in field names using backslash, e.g., 'a\.b' for field 'a.b'.

affects: >=0.0.0

gotchaThe wildcard '*' selects all keys at the current level but does not recurse into nested objects. This differs from some JSONPath implementations.

fix

Use explicit paths for deeper nesting, e.g., 'a/*/b' instead of expecting 'a/*' to recurse.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: mask is not a function

Importing with named export instead of default export: const { mask } = require('json-mask')

fix

Change to: const mask = require('json-mask') or import mask from 'json-mask'

SyntaxError: Unexpected token 'export'

Using import statement in a CommonJS environment without ESM support (e.g., Node <14 or without proper module type)

fix

Use const mask = require('json-mask') or switch to ESM by adding "type": "module" in package.json

mask returned empty object '{}'

Field path contains special characters (e.g., dots) not escaped, or fields string has typos.

fix

Escape dots with backslash: 'a\.b' for field 'a.b'. Double-check field names match exactly.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

nodeoptionalRequires Node.js >=14.0.0 for ESM support and modern features

Agent activity

9 hits · last 30 days

node

Resources

githubgit://github.com/nemtsov/json-mask ↗

packagejson-mask ↗

homepagehttps://github.com/nemtsov/json-mask#readme ↗