safe-dig
Version:
A safe dig function for navigating nested objects and arrays in JavaScript, with an optional prototype method for all objects.
178 lines (116 loc) • 5.92 kB
Markdown
# Safe Dig - JavaScript Utility for Safe Nested Access
**`safe-dig`** is a **zero-dependency** JavaScript utility that safely accesses deeply nested properties or indices in objects and arrays. It mimics Ruby's `dig` method but works for both objects and arrays in JavaScript, providing a robust solution for safely accessing nested data without throwing errors.
## Features
- **Safe Access**: Safely access deeply nested properties in objects or arrays without worrying about exceptions like `TypeError` or `undefined`.
- **Flexible**: Works for both objects and arrays, allowing you to handle mixed structures.
- **Optional Prototype Method**: Optionally add `safeDig` as a method to all JavaScript objects through the prototype, enabling seamless syntax like `obj.safeDig(...)`.
- **Error Handling**: Returns `null` if a property or index doesn't exist, preventing runtime errors.
## Installation
To install the package via npm, run the following command:
```bash
npm install safe-dig
```
Or if you are using yarn:
```bash
yarn add safe-dig
```
## Usage
### Importing the Functions
You can use the `safeDig` function and the `addSafeDigPrototype` function independently.
```javascript
const { safeDig, addSafeDigPrototype } = require('safe-dig');
```
### 1. Using `safeDig`
The `safeDig` function allows you to safely dig into an object or array and retrieve nested values without causing runtime errors.
#### Syntax:
```javascript
safeDig(obj, ...keys);
```
- `obj`: The object or array you want to access.
- `...keys`: The sequence of keys (for objects) or indices (for arrays) to access the desired value.
#### Example:
```javascript
const obj = { a: [{ b: { c: 42 } }] };
// Access nested properties safely
console.log(safeDig(obj, 'a', 0, 'b', 'c')); // 42
console.log(safeDig(obj, 'a', 1, 'b', 'c')); // null (out of bounds)
console.log(safeDig(obj, 'x', 'y')); // null (key not found)
```
### 2. Using `addSafeDigPrototype`
If you want to add the `safeDig` method to all objects, you can use `addSafeDigPrototype`. This will allow you to call `safeDig` directly on any object, making your code more concise.
#### Syntax:
```javascript
addSafeDigPrototype();
```
After calling this method, you can use `safeDig` on any object:
#### Example:
```javascript
addSafeDigPrototype(); // Adds `safeDig` to all objects
const obj = { a: [{ b: { c: 42 } }] };
// Using `safeDig` directly on an object
console.log(obj.safeDig('a', 0, 'b', 'c')); // 42
console.log(obj.safeDig('a', 1, 'b', 'c')); // null (out of bounds)
```
### 3. TypeScript Support
`safe-dig` comes with full TypeScript support for autocompletion and type checking. When you install and use `safe-dig` in a TypeScript project, you'll get proper types for both the `safeDig` function and `addSafeDigPrototype` method.
#### TypeScript Example:
```typescript
import { safeDig, addSafeDigPrototype } from 'safe-dig';
const obj = { a: [{ b: { c: 42 } }] };
// Safe access using safeDig function
console.log(safeDig(obj, 'a', 0, 'b', 'c')); // 42
console.log(safeDig(obj, 'a', 1, 'b', 'c')); // null (out of bounds)
// Apply the safeDig method to the prototype
addSafeDigPrototype();
console.log(obj.safeDig('a', 0, 'b', 'c')); // 42
```
## API
### `safeDig<T>(obj: T, ...args: (string | number)[]): any`
Safely digs through an object or array to access nested properties or indices.
- **`obj`**: The object or array to dig into.
- **`args`**: A sequence of keys (for objects) or indices (for arrays) to access the desired value.
- **Returns**: The value found at the specified path, or `null` if not found.
### `addSafeDigPrototype(): void`
Adds the `safeDig` method to the prototype of all objects in JavaScript. After calling this function, you can use `obj.safeDig(...)` directly on any object.
- **Returns**: `void`
## Example with Mixed Objects and Arrays
Here’s an example demonstrating how `safeDig` works for both objects and arrays:
```javascript
const data = {
users: [
{ name: 'Alice', profile: { age: 30, city: 'New York' } },
{ name: 'Bob', profile: { age: 25, city: 'Los Angeles' } },
],
};
// Safe access in objects and arrays
console.log(safeDig(data, 'users', 0, 'profile', 'age')); // 30
console.log(safeDig(data, 'users', 1, 'profile', 'city')); // 'Los Angeles'
console.log(safeDig(data, 'users', 2)); // null (index out of bounds)
console.log(safeDig(data, 'users', 0, 'profile', 'country')); // null (key not found)
```
## Contributing
Feel free to contribute to `safe-dig` by submitting bug reports, suggestions, or pull requests. If you find any issues, please open an issue on [GitHub](https://github.com/ovi/safe-dig/issues).
### Steps to Contribute
1. Fork the repository.
2. Clone your fork locally.
3. Create a new branch for your changes.
4. Make your changes and write tests if applicable.
5. Push your changes to your fork.
6. Create a pull request.
## License
`safe-dig` is open-source software licensed under the [MIT License](https://opensource.org/licenses/MIT).
---
## Directory Structure
Here’s a brief overview of the project structure:
```
safe-dig/
├── LICENSE
├── README.md
├── package.json
├── index.js # Main utility code
└── index.d.ts # TypeScript declaration file
```
---
### Final Thoughts
The `safe-dig` package provides a simple yet powerful way to safely access deeply nested values within objects and arrays in JavaScript. Whether you use it as a standalone function or apply it to all objects via the prototype, it ensures that your code is less prone to runtime errors.
Feel free to customize or extend this utility to meet your needs, and don’t forget to contribute back if you find any bugs or improvements!