README.md

typedots

A simple way to get and set object properties using paths (aka dot notation).
Features advanced TypeScript capabilities for better Developer Experience.

Features

Runtime

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

While developing

• Path argument is autocompleted based on the object you pass.
• Strict mode to force path argument to only match possible paths.
• Ability to filter out suggested paths based on a given type.

Install

# 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:

Directly use base methods

import { get, set, has } from 'typedots';

Advanced use through class

The class implements the exact same base methods.

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

get

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.

set

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.

has

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:

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

Filter out suggestions by type

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:

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:

/** > 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).

// 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:

// 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"

Strict mode

You can get TypeScript to ensure you're actually using one of the suggested paths, and not any other string. To achieve this, you can use typedots' class and set the strictMode parameter in its generic type. Once set, TypeScript should raise errors any time you set the path arguments to a string value which was not suggested.

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

const typedots = new Typedots<{ strictMode: true }>();
typedots.get(obj, 'myProperty'); // <-- works!
typedots.get(obj, 'helpers.maxLength'); // <-- works!
typedots.get(obj, 'oops'); // <-- should raise a TypeScript error
typedots.get(obj, 'helpers.oops'); // <-- should raise a TypeScript error

Note that both expectedType and strictMode can be combined to work together:

const typedots = new Typedots<{
  strictMode: true,
  expectedType: (...args: any) => any },
}>();
typedots.get(obj, 'myMethod'); // <-- works!
typedots.get(obj, 'helpers.count'); // <-- works!
typedots.get(obj, 'myProperty'); // <-- should raise a TypeScript error
typedots.get(obj, 'helpers.maxLength'); // <-- should raise a TypeScript error

Exported type

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

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