Logo for jsDocs.io

dot-prop

  • Version 9.0.0
  • Published
  • 16.9 kB
  • 1 dependency
  • MIT license

Install

npm i dot-prop
yarn add dot-prop
pnpm add dot-prop

Overview

Get, set, or delete a property from a nested object using a dot path

Index

Functions

Functions

function deepKeys

deepKeys: (object: unknown) => string[];

  • Returns an array of every path. Non-empty plain objects and arrays are deeply recursed and are not themselves included.

    This can be useful to help flatten an object for an API that only accepts key-value pairs or for a tagged template literal.

    Parameter object

    The object to iterate through.

    Example 1

    import {getProperty, deepKeys} from 'dot-prop';
    

    const user = {
    	name: {
    		first: 'Richie',
    		last: 'Bendall',
    	},
    	activeTasks: [],
    	currentProject: null
    };
    

    for (const property of deepKeys(user)) {
    	console.log(`${property}: ${getProperty(user, property)}`);
    	//=> name.first: Richie
    	//=> name.last: Bendall
    	//=> activeTasks: []
    	//=> currentProject: null
    }

function deleteProperty

deleteProperty: (object: Record<string, any>, path: string) => boolean;

  • Delete the property at the given path.

    Parameter object

    Object or array to delete the path value.

    Parameter path

    Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key.

    Returns

    A boolean of whether the property existed before being deleted.

    Example 1

    import {deleteProperty} from 'dot-prop';
    

    const object = {foo: {bar: 'a'}};
    deleteProperty(object, 'foo.bar');
    console.log(object);
    //=> {foo: {}}
    

    object.foo.bar = {x: 'y', y: 'x'};
    deleteProperty(object, 'foo.bar.x');
    console.log(object);
    //=> {foo: {bar: {y: 'x'}}}

function escapePath

escapePath: (path: string) => string;

  • Escape special characters in a path. Useful for sanitizing user input.

    Parameter path

    The dot path to sanitize.

    Example 1

    import {getProperty, escapePath} from 'dot-prop';
    

    const object = {
    	foo: {
    		bar: '👸🏻 You found me Mario!',
    	},
    	'foo.bar' : '🍄 The princess is in another castle!',
    };
    const escapedPath = escapePath('foo.bar');
    

    console.log(getProperty(object, escapedPath));
    //=> '🍄 The princess is in another castle!'

function getProperty

getProperty: <ObjectType, PathType extends string, DefaultValue = undefined>(
    object: ObjectType,
    path: PathType,
    defaultValue?: DefaultValue
) => ObjectType extends Record<string, unknown> | unknown[]
    ? unknown extends Get<ObjectType, PathType>
        ? DefaultValue
        : Get<ObjectType, PathType>
    : undefined;

  • Get the value of the property at the given path.

    Parameter object

    Object or array to get the path value.

    Parameter path

    Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key.

    Parameter defaultValue

    Default value.

    Example 1

    import {getProperty} from 'dot-prop';
    

    getProperty({foo: {bar: 'unicorn'}}, 'foo.bar');
    //=> 'unicorn'
    

    getProperty({foo: {bar: 'a'}}, 'foo.notDefined.deep');
    //=> undefined
    

    getProperty({foo: {bar: 'a'}}, 'foo.notDefined.deep', 'default value');
    //=> 'default value'
    

    getProperty({foo: {'dot.dot': 'unicorn'}}, 'foo.dot\\.dot');
    //=> 'unicorn'
    

    getProperty({foo: [{bar: 'unicorn'}]}, 'foo[0].bar');
    //=> 'unicorn'

function hasProperty

hasProperty: (object: Record<string, any> | undefined, path: string) => boolean;

  • Check whether the property at the given path exists.

    Parameter object

    Object or array to test the path value.

    Parameter path

    Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key.

    Example 1

    import {hasProperty} from 'dot-prop';
    

    hasProperty({foo: {bar: 'unicorn'}}, 'foo.bar');
    //=> true

function setProperty

setProperty: <ObjectType extends Record<string, any>>(
    object: ObjectType,
    path: string,
    value: unknown
) => ObjectType;

  • Set the property at the given path to the given value.

    Parameter object

    Object or array to set the path value.

    Parameter path

    Path of the property in the object, using . to separate each nested key. Use \\. if you have a . in the key.

    Parameter value

    Value to set at path.

    Returns

    The object.

    Example 1

    import {setProperty} from 'dot-prop';
    

    const object = {foo: {bar: 'a'}};
    setProperty(object, 'foo.bar', 'b');
    console.log(object);
    //=> {foo: {bar: 'b'}}
    

    const foo = setProperty({}, 'foo.bar', 'c');
    console.log(foo);
    //=> {foo: {bar: 'c'}}
    

    setProperty(object, 'foo.baz', 'x');
    console.log(object);
    //=> {foo: {bar: 'b', baz: 'x'}}
    

    setProperty(object, 'foo.biz[0]', 'a');
    console.log(object);
    //=> {foo: {bar: 'b', baz: 'x', biz: ['a']}}

Package Files (1)

Dependencies (1)

Dev Dependencies (5)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/dot-prop.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/dot-prop)
  • HTML
    <a href="https://www.jsdocs.io/package/dot-prop"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>