Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
enmap - npm Package Compare versions
Comparing version 3.0.0 to 3.0.1
| { | ||
| "name": "enmap", | ||
| "version": "3.0.0", | ||
| "version": "3.0.1", | ||
| "description": "", | ||
@@ -5,0 +5,0 @@ "main": "index.js", |
299
README.md
@@ -22,4 +22,2 @@ # Enmap - Enhanced Maps | ||
| Future versions will have ways to load partial or temporary values, etc. | ||
| ## Installation | ||
@@ -156,5 +154,17 @@ | ||
| ## UPDATING TO ENMAP 3.0 | ||
| Enmap version 3.0 has some breaking changes that are important to consider when updating. These changes are: | ||
| - setProp, hasProp, getProp, removeFrom, pushIn have all been removed. These methods are now merged into their regular counterpart, | ||
| which now have a new argument: "path". The path is previously what prop methods called "prop" and is the direct path to the property you want to change. | ||
| Please see examples in the docs for more details on these methods. Usually you only have to remove the `Prop` word from the method. For `setProp` to `set`, however, | ||
| pay more attention to the order of the arguments: `set(key, value, path)` instead of `setProp(key, path, value)`. | ||
| - setAsync, deleteAsync were removed from Enmap. I didn't honestly see a use for them, the only time I've ever had to use them was in testing, I will figure out a | ||
| different way to "wait for all changes to be written before <insert action here>". | ||
| - math(), inc() and dec() were added to 2.7.3 but I didn't really advertise them. Now they're here and they're documented. | ||
| ## API Documentation | ||
| ### Enmap ⇒ <code>Map</code> | ||
| ## Enmap ⇐ <code>Map</code> | ||
| A enhanced Map structure with additional utility methods. | ||
@@ -172,19 +182,12 @@ Can be made persistent | ||
| * [.changed(cb)](#Enmap+changed) | ||
| * [.set(key, val)](#Enmap+set) ⇒ <code>Map</code> | ||
| * [.setAsync(key, val)](#Enmap+setAsync) ⇒ <code>Promise.<Map></code> | ||
| * [.setProp(key, prop, val, save)](#Enmap+setProp) ⇒ <code>Map</code> | ||
| * [.push(key, val, allowDupes)](#Enmap+push) ⇒ <code>Map</code> | ||
| * [.pushIn(key, prop, val, allowDupes)](#Enmap+pushIn) ⇒ <code>Map</code> | ||
| * [.get(key)](#Enmap+get) ⇒ <code>\*</code> \| <code>Promise.<\*></code> | ||
| * [.getProp(key, prop)](#Enmap+getProp) ⇒ <code>\*</code> | ||
| * [.getHighestAutonum(start)](#Enmap+getHighestAutonum) ⇒ <code>Integer</code> | ||
| * [.has(key)](#Enmap+has) ⇒ <code>Promise.<boolean></code> | ||
| * [.hasProp(key, prop)](#Enmap+hasProp) ⇒ <code>boolean</code> | ||
| * [.delete(key, bulk)](#Enmap+delete) | ||
| * [.deleteAsync(key, bulk)](#Enmap+deleteAsync) | ||
| * [.set(key, val, path)](#Enmap+set) ⇒ <code>Map</code> | ||
| * [.push(key, val, path, allowDupes)](#Enmap+push) ⇒ <code>Map</code> | ||
| * [.math(key, operation, operand, path)](#Enmap+math) ⇒ <code>Map</code> | ||
| * [.inc(key, path)](#Enmap+inc) ⇒ <code>Map</code> | ||
| * [.dec(key, path)](#Enmap+dec) ⇒ <code>Map</code> | ||
| * [.get(key, path)](#Enmap+get) ⇒ <code>\*</code> | ||
| * [.has(key, path)](#Enmap+has) ⇒ <code>boolean</code> | ||
| * [.delete(key, path)](#Enmap+delete) | ||
| * [.deleteAll(bulk)](#Enmap+deleteAll) | ||
| * [.deleteAllAsync(bulk)](#Enmap+deleteAllAsync) ⇒ <code>Promise</code> | ||
| * [.remove(key, val, allowDupes)](#Enmap+remove) ⇒ <code>Map</code> | ||
| * [.removeFrom(key, prop, val)](#Enmap+removeFrom) ⇒ <code>Map</code> | ||
| * [.deleteProp(key, prop)](#Enmap+deleteProp) ⇒ [<code>Promise.<Enmap></code>](#Enmap) \| [<code>Enmap</code>](#Enmap) | ||
| * [.remove(key, val, path)](#Enmap+remove) ⇒ <code>Map</code> | ||
| * [.array()](#Enmap+array) ⇒ <code>Array</code> | ||
@@ -235,2 +238,6 @@ * [.keyArray()](#Enmap+keyArray) ⇒ <code>Array</code> | ||
| **Returns**: <code>number</code> - The generated key number. | ||
| **Example** | ||
| ```js | ||
| enmap.set(enmap.autonum(), "This is a new value"); | ||
| ``` | ||
| <a name="Enmap+changed"></a> | ||
@@ -256,3 +263,3 @@ | ||
| ### enmap.set(key, val) ⇒ <code>Map</code> | ||
| ### enmap.set(key, val, path) ⇒ <code>Map</code> | ||
| Set the value in Enmap. | ||
@@ -263,9 +270,11 @@ | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to add to The Enmap. If the Enmap is persistent this value MUST be a string or number. | | ||
| | val | <code>\*</code> | Required. The value of the element to add to The Enmap. If the Enmap is persistent this value MUST be stringifiable as JSON. | | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | Required. The key of the element to add to The Enmap. If the Enmap is persistent this value MUST be a string or number. | | ||
| | val | <code>\*</code> | | Required. The value of the element to add to The Enmap. If the Enmap is persistent this value MUST be stringifiable as JSON. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The path to the property to modify inside the value object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| **Example** | ||
| ```js | ||
| // Direct Value Examples | ||
| enmap.set('simplevalue', 'this is a string'); | ||
@@ -275,36 +284,11 @@ enmap.set('isEnmapGreat', true); | ||
| enmap.set('IhazObjects', { color: 'black', action: 'paint', desire: true }); | ||
| enmap.set('ArraysToo', [1, "two", "tree", "foor"]) | ||
| // Settings Properties | ||
| enmap.set('IhazObjects', 'color', 'blue'); //modified previous object | ||
| enmap.set('ArraysToo', 2, 'three'); // changes "tree" to "three" in array. | ||
| ``` | ||
| <a name="Enmap+setAsync"></a> | ||
| ### enmap.setAsync(key, val) ⇒ <code>Promise.<Map></code> | ||
| Set the value in Enmap, but returns a promise that resolves once writte to the database. | ||
| Useless on non-persistent Enmaps. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>Promise.<Map></code> - The Enmap. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to add to The Enmap. If the Enmap is persistent this value MUST be a string or number. | | ||
| | val | <code>\*</code> | Required. The value of the element to add to The Enmap. If the Enmap is persistent this value MUST be stringifiable as JSON. | | ||
| <a name="Enmap+setProp"></a> | ||
| ### enmap.setProp(key, prop, val, save) ⇒ <code>Map</code> | ||
| Modify the property of a value inside the enmap, if the value is an object or array. | ||
| This is a shortcut to loading the key, changing the value, and setting it back. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>Map</code> - The EnMap. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to add to The Enmap or array. This value MUST be a string or number. | | ||
| | prop | <code>\*</code> | Required. The property to modify inside the value object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| | val | <code>\*</code> | Required. The value to apply to the specified property. | | ||
| | save | <code>boolean</code> | Optional. Whether to save to persistent DB (used as false in init) | | ||
| <a name="Enmap+push"></a> | ||
| ### enmap.push(key, val, allowDupes) ⇒ <code>Map</code> | ||
| ### enmap.push(key, val, path, allowDupes) ⇒ <code>Map</code> | ||
| Push to an array value in Enmap. | ||
@@ -319,9 +303,19 @@ | ||
| | val | <code>\*</code> | | Required. The value to push to the array. | | ||
| | allowDupes | <code>boolean</code> | <code>false</code> | Allow duplicate values in the array (default: false). | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The path to the property to modify inside the value object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| | allowDupes | <code>boolean</code> | <code>false</code> | Optional. Allow duplicate values in the array (default: false). | | ||
| <a name="Enmap+pushIn"></a> | ||
| **Example** | ||
| ```js | ||
| // Assuming | ||
| enmap.set("simpleArray", [1, 2, 3, 4]); | ||
| enmap.set("arrayInObject", {sub: [1, 2, 3, 4]}); | ||
| ### enmap.pushIn(key, prop, val, allowDupes) ⇒ <code>Map</code> | ||
| Push to an array element inside an Object or Array element in Enmap. | ||
| enmap.push("simpleArray", 5); // adds 5 at the end of the array | ||
| enmap.push("arrayInObject", "five", "sub"); adds "five" at the end of the sub array | ||
| ``` | ||
| <a name="Enmap+math"></a> | ||
| ### enmap.math(key, operation, operand, path) ⇒ <code>Map</code> | ||
| Executes a mathematical operation on a value and saves it in the enmap. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
@@ -332,54 +326,85 @@ **Returns**: <code>Map</code> - The EnMap. | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | Required. The key of the element. This value MUST be a string or number. | | ||
| | prop | <code>\*</code> | | Required. The name of the array property to push to. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| | val | <code>\*</code> | | Required. The value push to the array property. | | ||
| | allowDupes | <code>boolean</code> | <code>false</code> | Allow duplicate values in the array (default: false). | | ||
| | key | <code>string</code> \| <code>number</code> | | The enmap key on which to execute the math operation. | | ||
| | operation | <code>string</code> | | Which mathematical operation to execute. Supports most math ops: =, -, *, /, %, ^, and english spelling of those operations. | | ||
| | operand | <code>number</code> | | The right operand of the operation. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The property path to execute the operation on, if the value is an object or array. | | ||
| <a name="Enmap+get"></a> | ||
| **Example** | ||
| ```js | ||
| // Assuming | ||
| points.set("number", 42); | ||
| points.set("numberInObject", {sub: { anInt: 5 }}); | ||
| ### enmap.get(key) ⇒ <code>\*</code> \| <code>Promise.<\*></code> | ||
| Retrieves a key from the enmap. If fetchAll is false, returns a promise. | ||
| points.math("number", "/", 2); // 21 | ||
| points.math("number", "add", 5); // 26 | ||
| points.math("number", "modulo", 3); // 2 | ||
| points.math("numberInObject", "+", 10, "sub.anInt"); | ||
| ``` | ||
| <a name="Enmap+inc"></a> | ||
| ### enmap.inc(key, path) ⇒ <code>Map</code> | ||
| Increments a key's value or property by 1. Value must be a number, or a path to a number. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>\*</code> \| <code>Promise.<\*></code> - The value or a promise containing the value. | ||
| **Returns**: <code>Map</code> - The EnMap. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | The key to retrieve from the enmap. | | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | The enmap key where the value to increment is stored. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The property path to increment, if the value is an object or array. | | ||
| **Example** | ||
| ```js | ||
| const myKeyValue = enmap.get("myKey"); | ||
| console.log(myKeyValue); | ||
| // Assuming | ||
| points.set("number", 42); | ||
| points.set("numberInObject", {sub: { anInt: 5 }}); | ||
| points.inc("number"); // 43 | ||
| points.inc("numberInObject", "sub.anInt"); // {sub: { anInt: 6 }} | ||
| ``` | ||
| <a name="Enmap+getProp"></a> | ||
| <a name="Enmap+dec"></a> | ||
| ### enmap.getProp(key, prop) ⇒ <code>\*</code> | ||
| Returns the specific property within a stored value. If the key does not exist or the value is not an object, throws an error. | ||
| ### enmap.dec(key, path) ⇒ <code>Map</code> | ||
| Decrements a key's value or property by 1. Value must be a number, or a path to a number. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>\*</code> - The value of the property obtained. | ||
| **Returns**: <code>Map</code> - The EnMap. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to get from The Enmap. | | ||
| | prop | <code>\*</code> | Required. The property to retrieve from the object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | The enmap key where the value to decrement is stored. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The property path to decrement, if the value is an object or array. | | ||
| <a name="Enmap+getHighestAutonum"></a> | ||
| **Example** | ||
| ```js | ||
| // Assuming | ||
| points.set("number", 42); | ||
| points.set("numberInObject", {sub: { anInt: 5 }}); | ||
| ### enmap.getHighestAutonum(start) ⇒ <code>Integer</code> | ||
| Internal method used by autonum(). | ||
| Loops on incremental numerical values until it finds a free key | ||
| of that value in the Enamp. | ||
| points.dec("number"); // 41 | ||
| points.dec("numberInObject", "sub.anInt"); // {sub: { anInt: 4 }} | ||
| ``` | ||
| <a name="Enmap+get"></a> | ||
| ### enmap.get(key, path) ⇒ <code>\*</code> | ||
| Retrieves a key from the enmap. If fetchAll is false, returns a promise. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>Integer</code> - The first non-existant value found. | ||
| **Returns**: <code>\*</code> - The value for this key. | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | start | <code>Integer</code> | <code>0</code> | The starting value to look for. | | ||
| | key | <code>string</code> \| <code>number</code> | | The key to retrieve from the enmap. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The property to retrieve from the object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| **Example** | ||
| ```js | ||
| const myKeyValue = enmap.get("myKey"); | ||
| console.log(myKeyValue); | ||
| const someSubValue = enmap.get("anObjectKey", "someprop.someOtherSubProp"); | ||
| ``` | ||
| <a name="Enmap+has"></a> | ||
| ### enmap.has(key) ⇒ <code>Promise.<boolean></code> | ||
| ### enmap.has(key, path) ⇒ <code>boolean</code> | ||
| Returns whether or not the key exists in the Enmap. | ||
@@ -389,22 +414,18 @@ | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to add to The Enmap or array. This value MUST be a string or number. | | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | Required. The key of the element to add to The Enmap or array. This value MUST be a string or number. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The property to verify inside the value object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| <a name="Enmap+hasProp"></a> | ||
| **Example** | ||
| ```js | ||
| if(enmap.has("myKey")) { | ||
| // key is there | ||
| } | ||
| ### enmap.hasProp(key, prop) ⇒ <code>boolean</code> | ||
| Returns whether or not the property exists within an object or array value in enmap. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>boolean</code> - Whether the property exists. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to check in the Enmap or array. | | ||
| | prop | <code>\*</code> | Required. The property to verify inside the value object or array. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| if(!enmap.has("myOtherKey", "oneProp.otherProp.SubProp")) return false; | ||
| ``` | ||
| <a name="Enmap+delete"></a> | ||
| ### enmap.delete(key, bulk) | ||
| ### enmap.delete(key, path) | ||
| Deletes a key in the Enmap. | ||
@@ -414,17 +435,7 @@ | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to delete from The Enmap. | | ||
| | bulk | <code>boolean</code> | Internal property used by the purge method. | | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | Required. The key of the element to delete from The Enmap. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The name of the property to remove from the object. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| <a name="Enmap+deleteAsync"></a> | ||
| ### enmap.deleteAsync(key, bulk) | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to delete from The Enmap. | | ||
| | bulk | <code>boolean</code> | Internal property used by the purge method. | | ||
| <a name="Enmap+deleteAll"></a> | ||
@@ -441,17 +452,5 @@ | ||
| <a name="Enmap+deleteAllAsync"></a> | ||
| ### enmap.deleteAllAsync(bulk) ⇒ <code>Promise</code> | ||
| Calls the `delete()` method on all items that have it. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>Promise</code> - Returns a promise that is resolved when the database is cleared. | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | bulk | <code>boolean</code> | <code>true</code> | Optional. Defaults to True. whether to use the provider's "bulk" delete feature if it has one. | | ||
| <a name="Enmap+remove"></a> | ||
| ### enmap.remove(key, val, allowDupes) ⇒ <code>Map</code> | ||
| ### enmap.remove(key, val, path) ⇒ <code>Map</code> | ||
| Remove a value in an Array or Object element in Enmap. Note that this only works for | ||
@@ -463,36 +462,8 @@ values, not keys. Complex values such as objects and arrays will not be removed this way. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to remove from in Enmap. This value MUST be a string or number. | | ||
| | val | <code>\*</code> | Required. The value to remove from the array or object. | | ||
| | allowDupes | <code>boolean</code> | Allow duplicate values in the array (default: false). | | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | | Required. The key of the element to remove from in Enmap. This value MUST be a string or number. | | ||
| | val | <code>\*</code> | | Required. The value to remove from the array or object. | | ||
| | path | <code>string</code> | <code>null</code> | Optional. The name of the array property to remove from. Can be a path with dot notation, such as "prop1.subprop2.subprop3". If not presents, removes directly from the value. | | ||
| <a name="Enmap+removeFrom"></a> | ||
| ### enmap.removeFrom(key, prop, val) ⇒ <code>Map</code> | ||
| Remove a value from an Array or Object property inside an Array or Object element in Enmap. | ||
| Confusing? Sure is. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: <code>Map</code> - The EnMap. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element. This value MUST be a string or number. | | ||
| | prop | <code>\*</code> | Required. The name of the array property to remove from. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| | val | <code>\*</code> | Required. The value to remove from the array property. | | ||
| <a name="Enmap+deleteProp"></a> | ||
| ### enmap.deleteProp(key, prop) ⇒ [<code>Promise.<Enmap></code>](#Enmap) \| [<code>Enmap</code>](#Enmap) | ||
| Delete a property from an object or array value in Enmap. | ||
| **Kind**: instance method of [<code>Enmap</code>](#Enmap) | ||
| **Returns**: [<code>Promise.<Enmap></code>](#Enmap) \| [<code>Enmap</code>](#Enmap) - If fetchAll is true, return the Enmap. Otherwise return a promise containing the Enmap. | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | key | <code>string</code> \| <code>number</code> | Required. The key of the element to delete the property from in Enmap. | | ||
| | prop | <code>\*</code> | Required. The name of the property to remove from the object. Can be a path with dot notation, such as "prop1.subprop2.subprop3" | | ||
| <a name="Enmap+array"></a> | ||
@@ -499,0 +470,0 @@ |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Number of downloads
- increased by32.43%
2197
Worsened metrics
- Total package byte prevSize
- decreased by-1.78%
99517
- Number of lines in readme file
- decreased by-3.94%
707
No dependency changes