diff --git a/README.md b/README.md index 2bf3c05..ee188ff 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,24 @@ $ npm i --save @blakek/deep ## Usage ```js -import { clone, get, getOr, has, omit, pluck, remove, set } from '@blakek/deep'; +import { + clone, + createGetter, + get, + has, + omit, + pluck, + remove, + set + // also available: + // - createHas + // - createOmit + // - createPluck + // - createRemove + // - createSetter + // - isObject + // - traverseObject +} from '@blakek/deep'; const user = { id: 'abf87de', @@ -43,12 +60,12 @@ user.roles[0] === userCopy.roles[0]; //» true // Get a property value get('sites.github.username', user); //» 'blakek' -// Arguments can be partially applied -const githubUsername = get('sites.github.username'); -githubUsername(user); //» 'blakek' - // Get a property value with a fallback other than `undefined` -getOr('no-account', 'sites.facebook.username', user); //» 'no-account' +get('sites.facebook.username', user, 'no-account'); //» 'no-account' + +// Create a function to get a property value later +const getUsername = createGetter('sites.github.username'); +getUsername(user); //» 'blakek' // Test for a property value has('sites.github', user); //» true @@ -72,7 +89,6 @@ set(123, 'a.b.c', { a: 42 }); //» { a: { b: { c: 123 } } } For all these: - `path` can be either a dot-notation string or array of path parts -- arguments can be partially applied ### `clone` @@ -90,12 +106,17 @@ cloned === object; //» false cloned.value === object.value; //» true ``` -### `get` +### `get` / `createGetter` Gets the value for a given path with an optional fallback value. ```ts -function get(path: Path, object: any): any; +function get(path: Path, object: object, fallbackValue?: any): unknown; + +function createGetter( + path: Path, + fallbackValue?: any +): (object: object) => unknown; ``` ```js @@ -114,45 +135,24 @@ get('roles.0', user); //» 'alert:create' get('roles[0]', user); //» 'alert:create' get(['roles', 1], user); //» 'alert:read' get('sites.github.username', user); //» 'blakek' +get('sites.github.avatar.src', user, 'default.png'); //» 'default.png' const getID = get('id'); getID(user); //» 'abf87de' -``` - -### `getOr` - -Like `get`, gets a value from an object. Will return a fallback other than -`undefined` if the value was not found equal to `undefined`. - -```ts -function getOr(defaultValue: any, path: Path, object: any): any; -``` - -```js -const user = { - id: 'abf87de', - roles: ['alert:create', 'alert:read'], - sites: { - github: { - username: 'blakek' - } - } -}; - -getOr('/images/placeholder.png', 'sites.github.image', user); //» '/images/placeholder.png' -const getRoles = getOr([], 'roles'); +const getRoles = createGetter('roles'); getRoles(user); //» ['alert:create', 'alert:read'] -getRoles({}); //» [] ``` -### `has` +### `has` / `createHas` Returns `true` if a value was found at the given path or `false` if nothing was found. ```ts function has(path: Path, object: any): boolean; + +function createHas(path: Path): (object: any) => boolean; ``` ```js @@ -169,19 +169,24 @@ has('attributes.materials', product); //» true has(['avability', 'sizes'], product); //» false has('attributes.isCool', product); //» true; property exists but is undefined -// `get()` should be used if you want to ensure a value is not `undefined` -getOr(false, 'attributes.isCool', product); //» false +const hasMaterials = createHas('attributes.materials'); +hasMaterials(product); //» true + +// NOTE: `get()` should be used if you want to ensure a value is not `undefined` +get('attributes.isCool', product, false); //» false ``` -### `omit` +### `omit` / `createOmit` -Returns a clone of an object with some properties removed. +Returns a clone of an object with a list of properties removed. Note: `omit()` returns a clone with properties removed. If you'd rather modify the existing object for performance, consider using `remove()`. ```ts function omit(properties: Path[], object: any): any; + +function createOmit(properties: Path[]): (object: any) => any; ``` ```js @@ -198,9 +203,12 @@ const user = { omit(['roles', 'sites'], user); //» { username: 'blakek' } omit(['username', 'roles', 'sites.doesnt.exist'], user); //» { sites: { github: { username: 'blakek' } } } + +const omitExtra = createOmit(['roles, sites']); +omitExtra(user); //» { username: 'blakek' } ``` -### `pluck` +### `pluck` / `createPluck` Gets a subset of properties from an object. @@ -222,9 +230,12 @@ const user = { pluck(['username'], user); //» { username: 'blakek' } pluck(['username', 'roles'], user); //» { username: 'blakek', roles: [ 'alert:create', 'alert:read' ] } + +const permissionInfo = pluck(['roles', 'username']); +permissionInfo(user); //» { roles: [ 'alert:create', 'alert:read' ], username: 'blakek' } ``` -### `remove` +### `remove` / `createRemove` Removes a value at a path and returns the object. @@ -237,6 +248,8 @@ you'd rather return a new object: ```ts function remove(path: Path, object: any): any; + +function createRemove(path: Path): (object: any) => any; ``` ```js @@ -248,9 +261,12 @@ const user = { remove('password', user); //» { username: 'blakek' } remove('property.does.not.exist', user); //» { username: 'blakek' } (same object from previous line) + +const removePassword = createRemove('password'); +removePassword({ username: 'bob', password: 'laskjfl' }); //» { username: 'bob' } ``` -### `set` +### `set` / `createSetter` Sets a value at a path and returns the object. @@ -262,6 +278,8 @@ you'd rather return a new object: ```ts function set(value: any, path: Path, object: any): any; + +function createSetter(path: Path, object: any): (value: any) => any; ``` ```js @@ -278,6 +296,9 @@ set('/images/user.png', 'profile.bgImage', user); const logout = set(null, 'profile'); logout(user); //» { profile: null } + +const setUsername = createSetter('username', user); +setUsername('blakek'); //» { profile: { bgColor: 'tomato', bgImage: '/images/user.png' }, username: 'blakek' } ``` ## Contributing