typedots

A simple way to get and set object properties using paths (aka dot notation).


Features advanced TypeScript capabilities for better Developer Experience.

Features

$3

- [x] Get object property value from path: get(obj, 'prop.subprop')
- [x] Set object property value from path: set(obj, 'prop.subprop', 'value')
- [x] Check if object has property from path: has(obj, 'prop.subprop')
- [x] Supports property names containing dots: {'my.property': true}

$3

- [x] Path argument is autocompleted based on the object you pass.
- [x] Ability to filter out suggested paths based on a given type.

Install


``bash


Using npm

npm i typedots

Using Yarn

yarn add typedots

Using pnpm

pnpm add typedots
`

Usage

There are two ways of consuming typedots depending on your needs and preferences:

$3

`ts
import { get, set, has } from "typedots";
`

$3

The class implements the exact same base methods.

`ts
import Typedots from "typedots";

const td = new Typedots(); // td.get, td.set, td.has
`

It is mainly used to get finer control over the way typedots' type system behaves as further explored in Advanced usage.

Methods

$3

































Arguments
name	type	description
object	Record<string, any>	Base object you want to get data from.
path	string	Path you want to get the value from. Possible values should be suggested by your IDE.
Return type
any | undefined		It returns the property value if it exists, or undefined if it does not exist.

$3











































Arguments
name	type	description
object	Record<string, any>	Base object you want to update.
path	string	Path you want to set the value for. Possible values should be suggested by your IDE.
value	any	Value to assign to the target property.
force	boolean (defaults to true)	Defines whether typedots should force value update. When set to false, value update will be cancelled in the following cases: The target path traverses a non-existing property The target path traverses an intermediate property which is not an object (and therefore is not supposed to have child properties)
Return type
boolean		Returns true if the property was updated, false if update was cancelled.

$3

































Arguments
name	type	description
object	Record<string, any>	Base object.
path	string	Path you want to get the value from. Possible values should be automatically suggested by your IDE.
Return type
boolean		Returns true if the property exists, false if it does not exist.

> Note
> When one of the properties in the path contains a dot, such property should be wrapped with parentheses so that it does not conflict with typedots inner workings. e.g. "sites.(my.host.com).ip"

Advanced usage

By default, using the base methods does not enforce the path arguments to actually strictly match one of the values provided by autocompletion. Those are just bare suggestions and you may pass any other string without TypeScript yelling at you.

Additionally, when drawing up the list of suggestions, all paths resolving to non-object properties are automatically picked.

Both behaviours may be tweaked by making use of the Typedots class instead of the base methods. It provides a generic type which is constrained to the following interface:

`ts
export interface TypedotsParams = {
expectedType?: any;
preventDistribution?: boolean;
}
`

$3

You may want to add some constraints to the list of suggested paths. To achieve this, you can use typedots' class and set the expectedType parameter in its generic type. Once set, only properties matching the type you passed in expectedType will be suggested in the path arguments. Here's a quick example which should only suggest paths resolving to functions:

`ts
const obj = {
myProperty: "value of my property",
myMethod: (message) => received ${message},
helpers: {
maxLength: 255,
count(item) {
return item.length;
},
},
};

const typedots = new Typedots<{ expectedType: (...args: any) => any }>();
const method = typedots.get(obj, ""); // <-- should only suggest "myMethod" and "helpers.count"
`

Please note that typedots relies on TypeScript's own type inference mechanism. This means its behaviour may be influenced by TypeScript's configuration.

#### False, undefined and null values

For example, strictNullChecks changes the way types are infered:

`ts
/* > When strictNullChecks: false: /
// infered as { prop, string un: any }
const obj = { prop: "some string", un: undefined };
new Typedots<{ expectedType: string }>(); // suggests "prop" | "un"

/* > When strictNullChecks: true: /
// infered as { prop: string, un: undefined }
const obj = { prop: "some string", un: undefined };
new Typedots<{ expectedType: string }>(); // suggests "prop"
`

#### Boolean distributivity

Because conditional types in generic parameters are distributive, when specifically expecting true or false types, paths resolving to boolean are also suggested since they match (boolean = true | false).

`ts
// infered as { one: boolean, two: boolean, tree: boolean }
const obj = { one: false, two: true, three: true as boolean };
new Typedots<{ expectedType: true }>(); // suggests "one" | "two" | "three"

// infered as { one: false, two: true, tree: boolean }
const obj = { one: false, two: true, three: true as boolean } as const;
new Typedots<{ expectedType: true }>(); // suggests "two" | "three"
`

You may want to go even stricter by preventing boolean to be distributed when expecting false or true. To achieve this, you can use typedots' class and set the preventDistribution parameter in its generic type:

`ts
// infered as { one: boolean, two: boolean, tree: boolean }
const obj = { one: false, two: true, three: true as boolean };
new Typedots<{ expectedType: true; preventDistribution: true }>(); // no suggestion

// infered as { one: false, two: true, tree: boolean }
const obj = { one: false, two: true, three: true as boolean } as const;
new Typedots<{ expectedType: true; preventDistribution: true }>(); // suggests "two"
`

$3

The type which powers the suggestion system is exported as ExtractObjectPaths, you may be interested in using it even if you're not actually using the runtime methods. It takes three generic parameters:

1. BaseObject, which extends any non-null object.
2. ExpectedType, see Filter out suggestions by type
3. PreventDistribution, see Boolean distributivity

Examples

`ts
import { get, set, has } from "typedots";

const variableName = "content";
const baseObject = {
prop1: true,
prop2: false,
prop3: {
subprop1: "string",
subprop2: ["first", 2_000, { third: undefined }],
subprop3: { one: true, two: true, three: false },
subprop4: undefined,
},
[variableName]: {},
"prop.5": { nested: "string", "another.sub.prop": {} },
};

get(baseObject, "prop1"); // true
get(baseObject, "prop3.subprop1"); // "string"
get(baseObject, "prop3.subprop3.three"); // false
get(baseObject, "(prop.5).nested"); // 'string'
get(baseObject, "content"); // {}
get(baseObject, variableName); // {}

set(baseObject, "prop1", value); // true
set(baseObject, "prop100", value, false); // false
set(baseObject, "prop100", value); // true
set(baseObject, "prop2.child", value, false); // false
set(baseObject, "prop2.child", value); // true

has(baseObject, "prop1"); // true
has(baseObject, "prop3.NOOP"); // false
has(baseObject, "NOPE"); // false
has(baseObject, "prop3.subprop4"); // true
has(baseObject, "(prop.5).(another.sub.prop)"); // true
``