A lightweight, type-safe utility for effortlessly navigating and querying deeply nested objects and arrays in JavaScript and TypeScript.
You can install nested-navigator using npm:
npm install nested-navigatorOr using yarn:
yarn add nested-navigatorimport { navigator } from "nested-navigator";
const data = {
user: {
name: "John Doe",
address: {
city: "New York",
},
hobbies: ["reading", "coding"],
},
};
const city = navigator(data).navigateTo("user.address.city").value();
console.log(city); // Outputs: 'New York'
const hobbiesCount = navigator(data).navigateTo("user.hobbies").getLength();
console.log(hobbiesCount); // Outputs: 2const users = [
{ id: 1, name: "Alice", age: 30, skills: ["JavaScript", "React"] },
{ id: 2, name: "Bob", age: 25, skills: ["Python", "Django"] },
];
const olderThan25 = navigator(users)
.filter("age", 25, "greater_than")
.value();
console.log(olderThan25); // Outputs: [{ id: 1, name: "Alice", age: 30, skills: ["JavaScript", "React"] }]
const bobsFirstSkill = navigator(users)
.find("name", "Bob")
.navigateTo("skills.0")
.value();
console.log(bobsFirstSkill); // Outputs: 'Python'
const aliceIndex = navigator(users).getIndex("name", "Alice");
console.log(aliceIndex); // Outputs: 0Creates a new NestedNavigator instance.
-
obj: The object to navigate.
Returns: A new NestedNavigator instance.
Navigates to a nested property specified by the given key path.
-
path: A string representing the path to the desired property, using dot notation for nested properties.
Returns: A new NestedNavigator instance positioned at the specified nested location.
Finds an element in the current array based on a key-value pair and an optional comparison operation.
-
key: The key to search on. -
value: The value to search for. -
operation: (Optional) The comparison operation to use. Defaults to "equals".
Returns: A new NestedNavigator instance with the found array element.
Filters elements in the current array based on a key-value pair and an optional comparison operation.
-
key: The key to filter on. -
value: The value to filter for. -
operation: (Optional) The comparison operation to use. Defaults to "equals".
Returns: A new NestedNavigator instance with an array of matching elements.
Finds the index of an element in the current array based on a key-value pair (for arrays of objects) or a direct value (for arrays of primitives).
-
keyOrValue: For arrays of objects, this is the key to search on. For arrays of primitives, this is the value to search for. -
value: (Optional) For arrays of objects, this is the value to search for. This parameter is not used for arrays of primitives. -
operation: (Optional) The comparison operation to use. Defaults to "equals".
Returns: The index of the found element, or -1 if not found.
Returns the length of the current array if it's an array, or undefined otherwise.
Returns: The length of the array (number) if the current value is an array, or undefined if it's not an array.
Returns the current value in the navigation.
Returns: The current value, or undefined if the navigation led to an invalid path.
The following comparison operations are available for find, filter, and getIndex methods:
-
"equals"(default): Checks if values are strictly equal. -
"not_equals": Checks if values are not strictly equal. -
"greater_than": Checks if the first value is greater than the second. -
"less_than": Checks if the first value is less than the second. -
"greater_than_or_equal": Checks if the first value is greater than or equal to the second. -
"less_than_or_equal": Checks if the first value is less than or equal to the second.
Note: Numerical operations ("greater_than", "less_than", "greater_than_or_equal", "less_than_or_equal") are only performed if both values are numbers.
const data = {
user: {
profile: {
name: "John Doe",
age: 30,
},
},
};
const age = navigator(data).navigateTo("user.profile.age").value();
console.log(age); // Outputs: 30const data = {
users: [
{ id: 1, name: "Alice", age: 28 },
{ id: 2, name: "Bob", age: 32 },
{ id: 3, name: "Charlie", age: 22 },
],
};
// Finding users older than 25
const olderThan25 = navigator(data)
.navigateTo("users")
.filter("age", 25, "greater_than")
.value();
console.log(olderThan25);
// Outputs: [
// { id: 1, name: "Alice", age: 28 },
// { id: 2, name: "Bob", age: 32 }
// ]
// Finding the first user not named "Bob"
const notBob = navigator(data)
.navigateTo("users")
.find("name", "Bob", "not_equals")
.value();
console.log(notBob); // Outputs: { id: 1, name: "Alice", age: 28 }
// Getting the index of the youngest user
const youngestIndex = navigator(data)
.navigateTo("users")
.getIndex("age", undefined, "less_than_or_equal");
console.log(youngestIndex); // Outputs: 2 (index of Charlie)nested-navigator is written in TypeScript and provides full type safety and autocompletion when used in TypeScript projects.
import { navigator, NestedKeyOf } from "nested-navigator";
interface User {
name: string;
age: number;
address: {
city: string;
country: string;
};
}
const user: User = {
name: "John Doe",
age: 30,
address: {
city: "New York",
country: "USA",
},
};
const path: NestedKeyOf<User> = "address.city";
const city = navigator(user).navigateTo(path).value();
console.log(city); // Outputs: 'New York'Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.