Dot Diver 🌊🔍

A lightweight, powerful, and dependency-free TypeScript utility library that provides types and functions to work with object paths in dot notation. Dive into your objects with ease, while maintaining comprehensive type safety! 🎉

Dot notation is a popular and convenient way to access deeply nested properties in objects. With Dot Diver, you can safely work with object paths in TypeScript projects, ensuring type correctness and productivity!

Example:

1import { getByPath } from '@clickbar/dot-diver'
2
3const object = {
4  a: 'Hello world',
5}
6
7const result = getByPath(object, 'a') // result is 'Hello world'

🌟 Features

• 🎯 Works with arrays, tuples, and objects
• 🛡️ Works with readonly properties
• ✅ Tests included
• 🌀 Works with cyclic dependencies in types
• 🚫 No dependencies
• 🪶 Tiny footprint

📦 Installation

Install the package using your favorite package manager:

npm

1npm install -D @clickbar/dot-diver

yarn

1yarn add -D @clickbar/dot-diver

pnpm

1pnpm install -D @clickbar/dot-diver

🚀 Usage

🔎 getByPath and 🔏 setByPath

1import { getByPath, setByPath } from '@clickbar/dot-diver'
2
3// Define a sample object with nested properties
4const object = {
5  a: 'hello',
6  b: {
7    c: 42,
8    d: {
9      e: 'world',
10    },
11  },
12  f: [{ g: 'array-item-1' }, { g: 'array-item-2' }],
13}
14
15// Example 1: Get a value by path
16const value1 = getByPath(object, 'a') // Output: 'hello'
17console.log(value1)
18
19const value2 = getByPath(object, 'b.c') // Output: 42
20console.log(value2)
21
22const value3 = getByPath(object, 'b.d.e') // Output: 'world'
23console.log(value3)
24
25const value4 = getByPath(object, 'f.0') // Output: { g: 'array-item-1' }
26console.log(value4)
27
28const value5 = getByPath(object, 'f.1.g') // Output: 'array-item-2'
29console.log(value5)
30
31// Example 2: Set a value by path
32setByPath(object, 'a', 'new hello')
33console.log(object.a) // Output: 'new hello'
34
35setByPath(object, 'b.c', 100)
36console.log(object.b.c) // Output: 100
37
38setByPath(object, 'b.d.e', 'new world')
39console.log(object.b.d.e) // Output: 'new world'
40
41setByPath(object, 'f.0', { g: 'new array-item-1' })
42console.log(object.f[0]) // Output: { g: 'new array-item-1' }
43
44setByPath(object, 'f.1.g', 'new array-item-2')
45console.log(object.f[1].g) // Output: 'new array-item-2'

🛣️ Path and 🔖 PathValue

1import type { Path, PathValue } from '@clickbar/dot-diver'
2
3// Define a sample object type with nested properties
4type MyObjectType = {
5  a: string
6  b: {
7    c: number
8    d: {
9      e: boolean
10    }
11  }
12  f: [{ g: string }, { g: string }]
13}
14
15// Example 1: Using the Path type
16type MyObjectPaths = Path<MyObjectType>
17
18// MyObjectPaths will be a union type representing all valid paths in dot notation:
19// 'a' | 'b' | 'f' | 'b.c' | 'b.d' | 'b.d.e' | 'f.0' | 'f.1' | 'f.0.g' | 'f.1.g'
20
21// Example 2: Using the PathValue type
22type ValueAtPathA = PathValue<MyObjectType, 'a'> // Output: string
23type ValueAtPathB_C = PathValue<MyObjectType, 'b.c'> // Output: number
24type ValueAtPathB_D_E = PathValue<MyObjectType, 'b.d.e'> // Output: boolean
25type ValueAtPathF_0 = PathValue<MyObjectType, 'f.0'> // Output: { g: string }
26type ValueAtPathF_0_G = PathValue<MyObjectType, 'f.0.g'> // Output: string

🔄 Objects with cyclic dependency

1import type { Path, PathValue } from '@clickbar/dot-diver'
2
3// Define an object type with nested properties and a cyclic dependency
4type Node = {
5  id: number
6  label: string
7  parent: Node
8  children: Node[]
9}
10
11// Example 1: Using the Path type with a Depth limit
12type NodePathsDepth2 = Path<Node, 2> // Depth limit of 2
13
14// NodePathsDepth2 will be a union type representing all valid paths in dot notation up to a depth of 3:
15// 'id' | 'label' | 'parent' | 'children' | 'parent.id' | 'parent.label' | 'parent.parent' | 'parent.children' | `parent.parent.${any}` | `parent.children.${any}` | `children.${number}` | `children.${number}.${any}`
16
17// Example 2: Using the PathValue type with a Depth limit
18type ValueAtPathParent_Id = PathValue<Node, 'parent.id', 3> // Output: number
19type ValueAtPathChildren_0_Label = PathValue<Node, 'children.0.label', 3> // Output: string | undefined
20type ValueAtPathParent_Parent_Parent = PathValue<Node, 'parent.parent.parent.parent', 3> // Output: unknown (due to the depth limit)

The default depth is currently 10.
At the moment, it is not possible to customize it when using the provided getByPath and setByPath functions. This is further explained in this issue.

⚙️ Customizing the Depth Limit

You can still customize it, by implementing your own functions, which just calls ours. Example:

1import { getByPath, setByPath } from '@clickbar/dot-diver'
2
3import type { Path, SearchableObject, PathValue } from '@clickbar/dot-diver'
4
5function getByPathDepth5<T extends SearchableObject, P extends Path<T, 5> & string>(
6  object: T,
7  path: P,
8): PathValue<T, P, 5> {
9  return getByPath(object, path) as PathValue<T, P, 5>
10}
11
12function setByPathDepth5<
13  T extends SearchableObject,
14  P extends Path<T, 5> & string,
15  V extends PathValue<T, P, 5>,
16>(object: T, path: P, value: V): void {
17  setByPath(object, path, value as PathValue<T, P>)
18}
19
20export { getByPathDepth5 as getByPath, setByPathDepth5 as setByPath }

The intersection between Path<T, 5> and string is necessary for TypeScript to successfully narrow down the type of P based on the user-provided path input. Without the intersection, the path would just be of type Path<T, 5> and PathValueEntry would be a union of all possible return types. By using the intersection, TypeScript is forced to apply the Path constraints and infer the type from the provided user input.

❓ FAQ

❗ Why are my paths truncated in a object with index signature?

See this issue.

❗ Why are my paths truncated inside an array?

Your paths are not truncated. Typescript will still validate them. Some IDEs have problems with displaying children.${number} paths. If you can, define the array as an tuple. This will include all paths in the auto completion.

❗ I get the error "Type instantiation is excessively deep and possibly infinite.ts(2589)"

This happens if typescript reaches its maximum depth limit. This library should prevent this, but it can still happen if a object has a lot of cyclic dependencies.
For example:

1type TestType = {
2  a: TestType
3  b: [TestType]
4  c: TestType[]
5  d: {
6    e: TestType
7  }
8  f: TestType2
9}

You can try to decrease the depth limit of the auto completion by reimplementing the getByPath and setByPath functions. See this section for customizing the depth limit.

👨‍💻 Contributing

If you would like to contribute to Dot Diver, feel free to fork the repository, make changes, and submit a pull request. We appreciate any help and feedback.

See CONTRIBUTING.md for more information.

🔒 Security Vulnerabilities

Please see SECURITY for details.

📄 License

Dot Diver is licensed under the MIT License.

🎉 Happy diving! 🌊