🛤️ @chaisser/obj-path

Safe dot-notation object access: get, set, has, delete, pick, omit, and wildcard find

✨ Features

• 🎯 Type-safe - Full TypeScript support with generics
• 🔍 Dot notation - Access nested properties with 'user.address.city'
• 📋 Array paths - Also supports ['user', 'address', 'city']
• 🔧 Auto-create - set() creates intermediate objects/arrays automatically
• 🗑️ Delete - Remove nested properties safely
• 🔎 Wildcard find - Find values matching patterns like 'users.*.name'
• ✂️ Pick & Omit - Extract or exclude paths from objects
• ✅ Has check - Check if a nested path exists
• 🪶 Zero dependencies - Lightweight and tree-shakeable
• 🏎️ ESM + CJS - Dual module format support

📦 Installation

npm install @chaisser/obj-path
# or
yarn add @chaisser/obj-path
# or
pnpm add @chaisser/obj-path

🚀 Quick Start

import { get, set, has, del, find, pick, omit } from '@chaisser/obj-path';

const user = {
  name: 'Doruk',
  address: {
    city: 'Istanbul',
    zip: '34000',
  },
  hobbies: ['coding', 'music'],
};

// Get nested values safely
get(user, 'address.city');          // 'Istanbul'
get(user, 'address.country', 'TR'); // 'TR' (default)
get(user, 'hobbies.0');             // 'coding'

// Set nested values (auto-creates path)
set(user, 'address.country', 'Turkey');

// Check existence
has(user, 'address.city');   // true
has(user, 'address.phone');  // false

// Delete
del(user, 'address.zip');

// Pick specific paths
pick(user, ['name', 'address.city']);
// { name: 'Doruk', address: { city: 'Istanbul' } }

// Omit paths
omit(user, ['address', 'hobbies']);
// { name: 'Doruk' }

📖 What It Does

This package provides safe dot-notation access to nested JavaScript objects and arrays. It handles null/undefined values gracefully, auto-creates intermediate paths when setting values, and includes utilities for picking, omitting, and finding values with wildcard patterns.

🎯 How It Works

The package provides 7 core functions:

• get - Traverse a path and return the value, or a default if not found
• set - Set a value at a path, creating intermediate objects/arrays as needed
• has - Check if a path resolves to a defined value
• del - Delete a property at a path, returning whether it existed
• find - Wildcard pattern matching to collect values across nested structures
• pick - Create a new object containing only specified paths
• omit - Create a deep clone excluding specified paths

🎨 What It's Useful For

• Form Data - Safely read/write nested form state
• API Responses - Extract fields from deep JSON structures
• Configuration - Access nested config values with defaults
• Data Transformation - Pick/omit fields for API payloads
• Tree Structures - Wildcard find across hierarchical data
• Deep Path Operations - Work with nested objects without manual null checks

💡 Usage Examples

Get with Defaults

import { get } from '@chaisser/obj-path';

const config = { database: { host: 'localhost' } };

get(config, 'database.host');              // 'localhost'
get(config, 'database.port', 5432);        // 5432 (path missing, uses default)
get(config, 'database.credentials.user');  // undefined
get(null, 'anything');                     // undefined

// Array indexing
const data = { items: [{ name: 'a' }, { name: 'b' }] };
get(data, 'items.1.name'); // 'b'

// Array path syntax
get(config, ['database', 'host']); // 'localhost'

Set with Auto-Creation

import { set } from '@chaisser/obj-path';

const obj: any = {};

set(obj, 'user.profile.name', 'Doruk');
// { user: { profile: { name: 'Doruk' } } }

set(obj, 'items.0.title', 'First');
// { items: [{ title: 'First' }] }  — auto-creates array for numeric keys

set(obj, 'a.b.c.d.e', 42);
// Creates the entire nested path

Has Check

import { has } from '@chaisser/obj-path';

const data = { user: { name: 'Doruk' } };

has(data, 'user.name');       // true
has(data, 'user.email');      // false
has(data, 'user.name.first'); // false

Delete

import { del } from '@chaisser/obj-path';

const data = { a: { b: { c: 1, d: 2 } } };

del(data, 'a.b.c');  // true
// data = { a: { b: { d: 2 } } }

del(data, 'x.y.z');  // false (path didn't exist)

Wildcard Find

import { find } from '@chaisser/obj-path';

const data = {
  users: [
    { name: 'Alice', age: 30 },
    { name: 'Bob', age: 25 },
  ],
};

find(data, 'users.*.name'); // ['Alice', 'Bob']
find(data, 'users.*.age');  // [30, 25]

Pick Paths

import { pick } from '@chaisser/obj-path';

const user = {
  name: 'Doruk',
  email: '[email protected]',
  password: 'secret',
  profile: { avatar: 'pic.jpg', bio: 'Dev' },
};

pick(user, ['name', 'email', 'profile.avatar']);
// { name: 'Doruk', email: '[email protected]', profile: { avatar: 'pic.jpg' } }

Omit Paths

import { omit } from '@chaisser/obj-path';

const user = {
  name: 'Doruk',
  email: '[email protected]',
  password: 'secret',
  token: 'abc123',
};

omit(user, ['password', 'token']);
// { name: 'Doruk', email: '[email protected]' }

📚 API Reference

get(obj, path, defaultValue?)

Get a value at a dot-notation path.

| Parameter | Type | Description | |---|---|---| | obj | object \| array | Source object | | path | string \| string[] | Dot notation path or key array | | defaultValue | any | Returned if path doesn't exist |

Returns: Value at path, or defaultValue, or undefined

set(obj, path, value)

Set a value at a dot-notation path. Auto-creates intermediate objects/arrays.

| Parameter | Type | Description | |---|---|---| | obj | object | Target object | | path | string \| string[] | Dot notation path | | value | any | Value to set |

Returns: The modified object

has(obj, path)

Check if a path exists and has a defined value.

Returns: boolean

del(obj, path)

Delete a property at a path.

Returns: boolean — true if the property existed and was deleted

find(obj, pattern)

Find all values matching a wildcard pattern. Use * as wildcard.

| Parameter | Type | Description | |---|---|---| | obj | object \| array | Source object | | pattern | string | Pattern with * wildcards (e.g. 'users.*.name') |

Returns: T[] — Array of matching values

pick(obj, paths)

Create a new object with only the specified paths.

| Parameter | Type | Description | |---|---|---| | obj | object | Source object | | paths | string[] | Paths to include |

Returns: New object with only picked paths

omit(obj, paths)

Create a deep clone of the object without the specified paths.

| Parameter | Type | Description | |---|---|---| | obj | object | Source object | | paths | string[] | Paths to exclude |

Returns: New object without omitted paths

🔗 Related Packages

Explore our other utility packages in the @chaisser namespace:

• @chaisser/obj-path (this package) - Safe dot-notation object access
• @chaisser/string-wizard - Advanced string manipulation
• @chaisser/type-guard - Runtime type guards and validators
• @chaisser/uuid-v7 - Time-ordered UUID v7 generator
• @chaisser/wait-for - Promise-based wait utilities
• @chaisser/regex-humanizer - Regex to human-readable descriptions
• @chaisser/password-strength - Password strength checker
• @chaisser/human-time - Human-readable time formatting
• @chaisser/debounce-throttle - Rate limiting utilities
• @chaisser/color-utils - Color conversion utilities
• @chaisser/deep-clone - Deep cloning functions
• @chaisser/array-group-by - Array grouping utilities
• @chaisser/merge-objects - Object merge utilities
• @chaisser/chunk-array - Array chunking functions
• @chaisser/event-emitter - Typed event emitter

🔒 License

MIT - Free to use in personal and commercial projects

👨 Developed by

Doruk Karaboncuk [email protected]

📄 Repository

• GitHub: @chaisser
• NPM: @chaisser/obj-path

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📞 Support

For issues, questions, or suggestions, please reach out through:

• Email: [email protected]
• GitHub Issues: Create an issue

Made with ❤️ by @chaisser