https://github.com/dashed/providence
Reference a sub-structure of any data structure that may or may not exist (DEPRECATED/UNMAINTAINED)
https://github.com/dashed/providence
Last synced: 11 months ago
JSON representation
Reference a sub-structure of any data structure that may or may not exist (DEPRECATED/UNMAINTAINED)
- Host: GitHub
- URL: https://github.com/dashed/providence
- Owner: dashed
- License: mit
- Created: 2015-05-20T11:38:15.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2017-02-02T03:22:15.000Z (about 9 years ago)
- Last Synced: 2025-02-19T12:44:17.390Z (12 months ago)
- Language: JavaScript
- Homepage:
- Size: 29.3 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# providence [](https://travis-ci.org/Dashed/providence)
# (DEPRECATED/UNMAINTAINED)
> Reference a sub-structure of any data structure.
## Usage
```
$ npm install --save providence
```
## Extensions
`Providence` is intended to be extended to fit to your needs.
- [Probe](https://github.com/Dashed/probe) observable cursors
- [minitrue](https://github.com/Dashed/minitrue) Probe cursor factory that read/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.path**
An array of the path/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(path[, 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(path, 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(path)`.
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 path.
If path 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 path exists within the unboxed root data.
##### `Providence.prototype.path()`
Returns the array representation of the path.
##### `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 path using the updater function.
If the path exists, updater is called using:
- the value at path
- unboxed root data
- boxed root data
If path 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 path (or notSetValue),
then no changes has truly occurred, and the current cursor is instead returned.
Otherwise, the new value is replaced at path 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 path
- new unboxed root data with the new value
- previous unboxed root data
##### `Providence.prototype.delete()`
Delete value at path.
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 path
- 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