providence - npm Package Compare versions

Comparing version 0.1.1 to 0.1.2

modules/index.js

@@ -59,3 +59,3 @@ /**
  *
- * @param {Object | Immutable Map} options [description]
+ * @param {Object | Immutable Map} options Defines the character of the providence cursor.
  */
@@ -94,3 +94,7 @@ function Providence() {
 
-// TODO: add test case
+/**
+ * Returns string representation of `this.deref()`.
+ *
+ * @return {String}
+ */
 Providence.prototype.toString = function () {
@@ -102,7 +106,9 @@ return String(this.deref());
  * Dereference by unboxing the root data and getting the value at keypath.
+ * If keypath happens to not exist, notSetValue is, instead, returned.
+ * If notSetValue is not provided, it becomes value: void 0.
  *
- * @param  {[type]} notSetValue [description]
- * @return {[type]}             [description]
+ * @param  {any} notSetValue
+ * @return {any}             The sub-structure value at keypath relative to
+ *                           root data.
  */
-// TODO: add test case for valueOf
 Providence.prototype.valueOf = Providence.prototype.deref = function (notSetValue) {
@@ -138,2 +144,7 @@
 
+/**
+ * Return true if a keypath exists within the unboxed root data.
+ *
+ * @return {Bool}
+ */
 Providence.prototype.exists = function () {
@@ -143,2 +154,7 @@ return this.deref(NOT_SET) !== NOT_SET;
 
+/**
+ * Returns the array representation of the keypath.
+ *
+ * @type {Array}
+ */
 Providence.prototype.keypath = Providence.prototype.keyPath = function () {
@@ -150,5 +166,6 @@ return this._options.getIn(KEYPATH_PATH);
  * Returns providence cursor's options. It is safe to modify this object since
- * it is an Immutable Map object.
+ * it is an Immutable Map object; and any changes will not reflect back to the
+ * originating cursor, unless it is used as the new options.
  *
- * @return {Immutable Map}            Returns
+ * @return {Immutable Map}
  */
@@ -162,7 +179,5 @@ Providence.prototype.options = function () {
  *
- * @param  {[type]} newOptions [description]
- * @return {[type]}            [description]
+ * @param  {Immutable Map | Object} newOptions
+ * @return {Providence}
  */
-// TODO: consider a better name?
-// TODO: might be better to consider instance.constructor. bikeshed?
 Providence.prototype['new'] = function (newOptions) {
@@ -175,4 +190,9 @@ return new this.constructor(newOptions);
  *
- * @param  {[type]} keyValue [description]
- * @return {[type]}            [description]
+ * By default, this is the same behaviour as cursor() method for immutable-js
+ * cursors:
+ * - Returns a sub-cursor following the path keyValue starting from this cursor.
+ * - If keyValue is not an array, an array containing keyValue is instead used.
+ *
+ * @param  {any | array } keyValue
+ * @return {Providence}
  */
@@ -204,6 +224,26 @@ Providence.prototype.cursor = function (keyValue) {
 /**
- * Update state at keypath.
+ * Update value in the unboxed root data at keypath using the updater function.
+ * If the keypath exists, updater is called using:
+ * - the value at keypath
+ * - unboxed root data
+ * - boxed root data
  *
- * @param  {Function} updater [description]
- * @return {Providence}         [description]
+ * If keypath doesn't exist, notSetValue is used as the initial value.
+ * If notSetValue is not defined, it has value void 0.
+ *
+ * If updater returns the same value the value at keypath (or notSetValue),
+ * then no changes has truly occured, and the current cursor is instead returned.
+ *
+ * Otherwise, the new value is replaced at keypath of the unboxed root data,
+ * and a new providence cursor is returned with the new boxed root data.
+ * In addition, any defined functions at onUpdate and/or _onUpdate within options
+ * will be called with the following:
+ * - options
+ * - cursor keypath
+ * - new unboxed root data with the new value
+ * - previous unboxed root data
+ *
+ * @param  {any} notSetValue
+ * @param  {Function} updater
+ * @return {Providence}
  */
@@ -261,2 +301,20 @@ Providence.prototype.update = function (notSetValue, updater) {
 
+/**
+ * Delete value at keypath.
+ *
+ * If the new unboxed root data is the same as the previous, original unboxed root data,
+ * then the current cursor is returned.
+ *
+ * Otherwise, any defined functions at onUpdate and/or _onUpdate within options
+ * will be called with the following:
+ * - options
+ * - cursor keypath
+ * - new unboxed root data with the new value
+ * - previous unboxed root data
+ *
+ * In addition, the new providence cursor containing the new unboxed root data
+ * will be returned.
+ *
+ * @type {Providence}
+ */
 Providence.prototype.remove = Providence.prototype['delete'] = function () {
@@ -263,0 +321,0 @@

package.json

 {
   "name": "providence",
-  "version": "0.1.1",
-  "description": "Abstract Om-style cursors that may be adapted to data structures of any type",
+  "version": "0.1.2",
+  "description": "Reference a sub-structure of any data structure",
   "main": "modules/index.js",
@@ -21,2 +21,10 @@ "scripts": {
   ],
+  "keywords": [
+    "cursor",
+    "immutable",
+    "providence",
+    "structure",
+    "data",
+    "datastructure"
+  ],
   "peerDependencies": {
@@ -23,0 +31,0 @@ "immutable": "3.x"

README.md

@@ -1,4 +0,4 @@
-# providence
+# providence [![Build Status](https://travis-ci.org/Dashed/providence.svg)](https://travis-ci.org/Dashed/providence)
 
-> Abstract [Om](https://github.com/omcljs/om/wiki/Cursors)-style cursors that may be adapted to data structures of any type. 
+> Reference a sub-structure of any data structure.
 
@@ -11,4 +11,201 @@ ## Usage
 
+## Extensions
+
+`Providence` is intended to be extended to fit to your needs.
+
+- [Prolefeed and minitrue](https://github.com/Dashed/minitrue) observable cursors that read and write to a single source of truth.
+
+### API
+
+##### `Providence(options)`
+
+Creates a new `Providence` cursor instance. May be called without the `new` keyword.
+
+**options**:  May either be a plain object or an `Immutable.Map`.
+
+```js
+const Providence = require('providence');
+
+const cursor = new Providence({
+    root: {
+        data: Immutable.Map()
+    }
+});
+
+const cursor2 = Providence({
+    root: {
+        data: Immutable.Map()
+    }
+});
+```
+
+##### `options`
+
+**options.root.data** 
+
+The "boxed" root data structure. The user must provide this.
+
+**options.keyPath**
+
+An array of the keypath.
+
+**options.root.unbox** 
+
+Function that will given value at `options.root.data`, and "unbox" into the value used in `deref()`/`valueOf()`, `update()`, and `delete()`/`remove()`.
+
+By default this is an identity function (e.g. `function(x) {return x;}`).
+
+*NOTE:* It's expected that this is the inverse of `options.root.box`.
+
+**options.root.box** 
+
+Function that will "box" a value back into a new value that will be written into `options.root.data`.
+
+This is used for updating/modifying values done through `update()` and `delete()` methods.
+
+By default this is an identity function (e.g. `function(x) {return x;}`).
+
+*NOTE:* It's expected that this is the inverse of `options.root.unbox`.
+
+**options.getIn** 
+
+A higher order function, which given the unboxed root data, shall return a function, `getIn`, with the signature: `getIn(keypath[, notSetValue])`.
+
+This is used internally for `deref()` and `update()`.
+
+By default this is:
+```js
+function _defaultGetIn(rootData) {
+    return rootData.getIn.bind(rootData);
+}
+```
+
+**options.setIn** 
+
+A higher order function, which given the unboxed root data, shall return a function, `setIn`, with the signature: `setIn(keypath, newvalue)`.
+
+This is used internally for `update()`.
+
+By default this is:
+```js
+function _defaultSetIn(rootData) {
+    return rootData.setIn.bind(rootData);
+}
+```
+
+**options.deleteIn** 
+
+A higher order function, which given the unboxed root data, shall return a function, `deleteIn`, with the signature: `deleteIn(keypath)`.
+
+This is used internally for `delete()`.
+
+```js
+function _defaultDeleteIn(rootData) {
+    return rootData.deleteIn.bind(rootData);
+}
+```
+
+**options.onUpdate**
+
+Called when there is a new value change in either `update()` or `delete()` operations.
+
+**options._onUpdate**
+
+Called when there is a new value change in either `update()` or `delete()` operations.
+
+If you're extending the `Providence` constructor and want to subscribe to changes of either `update()` or `delete()` operations; set your function `options._onUpdate`.
+
+*NOTE:* The end-user shall not set their function at `options._onUpdate`, and should instead set it at `options.onUpdate`.
+
+##### `Providence.prototype.constructor`
+
+By default, this points to `Providence`. This is
+If you're extending `Providence`, ensure that `constructor` is set: `AnotherConstructor.prototype.constructor = AnotherConstructor`.
+
+##### `Providence.prototype.toString()`
+
+Returns string representation of `this.deref()`.
+
+##### `Providence.prototype.valueOf([notSetValue])`
+
+Alias of `Providence.prototype.deref([notSetValue])`.
+
+##### `Providence.prototype.deref([notSetValue])`
+
+Dereference by unboxing the root data and getting the value at keypath.
+
+If keypath happens to not exist, `notSetValue` is, instead, returned.
+If `notSetValue` is not provided, it becomes value: `void 0`.
+
+##### `Providence.prototype.exists()`
+
+Return true if a keypath exists within the unboxed root data.
+
+##### `Providence.prototype.keyPath()`
+
+Returns the array representation of the keypath.
+
+##### `Providence.prototype.keypath()`
+
+Alias of `Providence.prototype.keyPath()`.
+
+##### `Providence.prototype.options()`
+
+Returns providence cursor's options which will be an `Immutable.Map` object. It is safe to modify this object since it is an Immutable Map object; and any changes will not reflect back to the originating cursor, unless it is used as the new options.
+
+##### `Providence.prototype.new(newOptions)`
+
+Create a new Providence object with options via this instance.
+
+##### `Providence.prototype.cursor([keyValue])`
+
+When given no arguments, return itself.
+
+By default, this is the same behaviour as cursor() method for immutable-js cursors:
+- Returns a sub-cursor following the path keyValue starting from this cursor.
+- If keyValue is not an array, an array containing keyValue is instead used.
+
+##### `Providence.prototype.update([notSetValue,] updater)`
+
+Update value in the unboxed root data at keypath using the updater function.
+If the keypath exists, updater is called using:
+- the value at keypath
+- unboxed root data
+- boxed root data
+
+If keypath doesn't exist, notSetValue is used as the initial value.
+If notSetValue is not defined, it has value void 0.
+
+If updater returns the same value the value at keypath (or notSetValue),
+then no changes has truly occured, and the current cursor is instead returned.
+
+Otherwise, the new value is replaced at keypath of the unboxed root data, and a new providence cursor is returned with the new boxed root data.
+In addition, any defined functions at onUpdate and/or _onUpdate within options will be called with the following:
+- options
+- cursor keypath
+- new unboxed root data with the new value
+- previous unboxed root data
+
+##### `Providence.prototype.delete()`
+
+Delete value at keypath.
+
+If the new unboxed root data is the same as the previous, original unboxed root data, then the current cursor is returned.
+
+Otherwise, any defined functions at onUpdate and/or _onUpdate within options will be called with the following:
+- options
+- cursor keypath
+- new unboxed root data with the new value
+- previous unboxed root data
+
+In addition, the new providence cursor containing the new unboxed root data will be returned.
+
+##### `Providence.prototype.remove()`
+
+Alias of `Providence.prototype.delete()`.
+
+
+
 ## License
 
 MIT

New alerts

License Policy Violation

License

This 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

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

22290

increased by46.19%

Lines of code

413

increased by16.34%

Number of lines in readme file

211

increased by1407.14%

No dependency changes