nest-store

A lightweight JavaScript object and array store for working with nested paths.

nest-store makes it easy to set, get, delete, and manipulate deeply nested values using simple path notation.

Features

• Set nested values using dot notation
• Get nested values
• Automatically create nested objects and arrays
• Support array indexes
• Wildcard path queries
• Delete nested properties
• Array manipulation helpers
• isNull() utility
• isNullOrEmpty() utility
• Prototype pollution protection
• Lightweight with no dependencies

Installation

npm

npm install nest-store

pnpm

pnpm add nest-store

Yarn

yarn add nest-store

Basic Usage

import { ObjectStore } from "nest-store";

const store = new ObjectStore();

Set and Get

Set nested values using dot notation:

store.set("user.name", "John");
store.set("user.age", 25);

console.log(store.get("user.name"));
// John

console.log(store.get("user"));
// { name: "John", age: 25 }

Nested Objects

You can create deeply nested objects automatically:

store.set("user.profile.name", "John");
store.set("user.profile.email", "[email protected]");

console.log(store.get("user.profile"));

Result:

{
  name: "John",
  email: "[email protected]"
}

Nested Arrays

Arrays are automatically created when using array notation:

store.set("items[0].name", "Laptop");
store.set("items[1].name", "Mouse");

console.log(store.get("items"));

Result:

[
  { name: "Laptop" },
  { name: "Mouse" }
]

You can also use array paths:

store.set(["items", 0, "name"], "Laptop");

Wildcard Paths

Use * to retrieve values from multiple objects or array elements.

const store = new ObjectStore({
  users: [
    { name: "John" },
    { name: "Jane" }
  ]
});

console.log(store.get("users.*.name"));

Result:

[
  "John",
  "Jane"
]

Delete

Delete a nested property:

const store = new ObjectStore({
  user: {
    name: "John",
    age: 25
  }
});

store.delete("user.age");

console.log(store.get("user"));

Result:

{
  name: "John"
}

Deleting an array item removes it from the array:

store.delete("items[0]");

Array Helpers

Push

Add an item to the end of an array:

store.push("items", {
  name: "Keyboard"
});

Pop

Remove the last item:

const item = store.pop("items");

Shift

Remove the first item:

const item = store.shift("items");

Unshift

Add an item to the beginning:

store.unshift("items", {
  name: "Monitor"
});

Splice

Remove or replace array elements:

store.splice("items", 1, 1);

The behavior follows JavaScript's Array.prototype.splice().

Utility Helpers

isNull(value)

Checks whether a value is null or undefined.

ObjectStore.isNull(null);
// true

ObjectStore.isNull(undefined);
// true

ObjectStore.isNull("hello");
// false

ObjectStore.isNull(0);
// false

ObjectStore.isNull(false);
// false

isNullOrEmpty(value)

Checks whether a value is:

• null
• undefined
• an empty string
• an empty array
• an empty object

ObjectStore.isNullOrEmpty(null);
// true

ObjectStore.isNullOrEmpty(undefined);
// true

ObjectStore.isNullOrEmpty("");
// true

ObjectStore.isNullOrEmpty([]);
// true

ObjectStore.isNullOrEmpty({});
// true

ObjectStore.isNullOrEmpty("hello");
// false

ObjectStore.isNullOrEmpty([1, 2]);
// false

ObjectStore.isNullOrEmpty({ name: "John" });
// false

ObjectStore.isNullOrEmpty(0);
// false

ObjectStore.isNullOrEmpty(false);
// false

Whitespace-only strings are not considered empty:

ObjectStore.isNullOrEmpty("   ");
// false

API

Constructor

new ObjectStore(initialValue)

Creates a new object store.

const store = new ObjectStore({
  user: {
    name: "John"
  }
});

set(path, value)

Sets a value at a nested path.

store.set("user.name", "John");

Supports array notation:

store.set("users[0].name", "John");

get(path)

Gets a value from a nested path.

store.get("user.name");

Supports wildcards:

store.get("users.*.name");

delete(path)

Deletes a value from a nested path.

store.delete("user.name");

Returns true when a value was deleted and false when the path does not exist.

push(path, value)

Adds a value to the end of an array.

store.push("items", "Laptop");

pop(path)

Removes and returns the last item from an array.

store.pop("items");

shift(path)

Removes and returns the first item from an array.

store.shift("items");

unshift(path, value)

Adds a value to the beginning of an array.

store.unshift("items", "Laptop");

splice(path, start, deleteCount, ...items)

Changes the contents of an array by removing or replacing existing elements.

store.splice("items", 1, 1);

ObjectStore.isNull(value)

Returns true when the value is null or undefined.

ObjectStore.isNull(null);
// true

ObjectStore.isNullOrEmpty(value)

Returns true when the value is null, undefined, an empty string, empty array, or empty object.

ObjectStore.isNullOrEmpty("");
// true

Prototype Pollution Protection

nest-store blocks dangerous object property names:

__proto__
constructor
prototype

For example:

store.set("__proto__.polluted", true);

will throw an error instead of modifying the object prototype.

Example

A complete example is available in:

examples/basic.js

Run it with:

npm run example

Development

Clone the repository and install dependencies:

npm install

Run tests:

npm test

Run the example:

npm run example

Create a package preview:

npm pack --dry-run

Requirements

• Node.js 18 or later
• No external runtime dependencies

License

MIT License

Copyright (c) 2026 Fakhrul Nazmi

See the LICENSE file for the full license text.