✏️ update documentation for v4

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