{"id":20614747,"url":"https://github.com/dashed/providence","last_synced_at":"2025-03-06T18:43:54.952Z","repository":{"id":32368135,"uuid":"35944282","full_name":"dashed/providence","owner":"dashed","description":"Reference a sub-structure of any data structure that may or may not exist (DEPRECATED/UNMAINTAINED)","archived":false,"fork":false,"pushed_at":"2017-02-02T03:22:15.000Z","size":30,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-19T12:44:17.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dashed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-20T11:38:15.000Z","updated_at":"2024-02-23T19:57:12.000Z","dependencies_parsed_at":"2022-09-23T06:01:32.224Z","dependency_job_id":null,"html_url":"https://github.com/dashed/providence","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dashed%2Fprovidence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dashed%2Fprovidence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dashed%2Fprovidence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dashed%2Fprovidence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dashed","download_url":"https://codeload.github.com/dashed/providence/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242269117,"owners_count":20100071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T11:13:30.642Z","updated_at":"2025-03-06T18:43:54.934Z","avatar_url":"https://github.com/dashed.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# providence [![Build Status](https://travis-ci.org/Dashed/providence.svg)](https://travis-ci.org/Dashed/providence)\n\n# (DEPRECATED/UNMAINTAINED)\n\n\u003e Reference a sub-structure of any data structure.\n\n## Usage\n\n```\n$ npm install --save providence\n```\n\n## Extensions\n\n`Providence` is intended to be extended to fit to your needs.\n\n- [Probe](https://github.com/Dashed/probe) observable cursors\n- [minitrue](https://github.com/Dashed/minitrue) Probe cursor factory that read/write to a single source of truth\n\n### API\n\n##### `Providence(options)`\n\nCreates a new `Providence` cursor instance. May be called without the `new` keyword.\n\n**options**:  May either be a plain object or an `Immutable.Map`.\n\n```js\nconst Providence = require('providence');\n\nconst cursor = new Providence({\n    root: {\n        data: Immutable.Map()\n    }\n});\n\nconst cursor2 = Providence({\n    root: {\n        data: Immutable.Map()\n    }\n});\n```\n\n##### `options`\n\n**options.root.data**\n\nThe \"boxed\" root data structure. The user must provide this.\n\n**options.path**\n\nAn array of the path/keypath.\n\n**options.root.unbox**\n\nFunction that will given value at `options.root.data`, and \"unbox\" into the value used in `deref()`/`valueOf()`, `update()`, and `delete()`/`remove()`.\n\nBy default this is an identity function (e.g. `function(x) {return x;}`).\n\n*NOTE:* It's expected that this is the inverse of `options.root.box`.\n\n**options.root.box**\n\nFunction that will \"box\" a value back into a new value that will be written into `options.root.data`.\n\nThis is used for updating/modifying values done through `update()` and `delete()` methods.\n\nBy default this is an identity function (e.g. `function(x) {return x;}`).\n\n*NOTE:* It's expected that this is the inverse of `options.root.unbox`.\n\n**options.getIn**\n\nA higher order function, which given the unboxed root data, shall return a function, `getIn`, with the signature: `getIn(path[, notSetValue])`.\n\nThis is used internally for `deref()` and `update()`.\n\nBy default this is:\n```js\nfunction _defaultGetIn(rootData) {\n    return rootData.getIn.bind(rootData);\n}\n```\n\n**options.setIn**\n\nA higher order function, which given the unboxed root data, shall return a function, `setIn`, with the signature: `setIn(path, newvalue)`.\n\nThis is used internally for `update()`.\n\nBy default this is:\n```js\nfunction _defaultSetIn(rootData) {\n    return rootData.setIn.bind(rootData);\n}\n```\n\n**options.deleteIn**\n\nA higher order function, which given the unboxed root data, shall return a function, `deleteIn`, with the signature: `deleteIn(path)`.\n\nThis is used internally for `delete()`.\n\n```js\nfunction _defaultDeleteIn(rootData) {\n    return rootData.deleteIn.bind(rootData);\n}\n```\n\n**options.onUpdate**\n\nCalled when there is a new value change in either `update()` or `delete()` operations.\n\n**options._onUpdate**\n\nCalled when there is a new value change in either `update()` or `delete()` operations.\n\nIf you're extending the `Providence` constructor and want to subscribe to changes of either `update()` or `delete()` operations; set your function `options._onUpdate`.\n\n*NOTE:* The end-user shall not set their function at `options._onUpdate`, and should instead set it at `options.onUpdate`.\n\n##### `Providence.prototype.constructor`\n\nBy default, this points to `Providence`. This is\nIf you're extending `Providence`, ensure that `constructor` is set: `AnotherConstructor.prototype.constructor = AnotherConstructor`.\n\n##### `Providence.prototype.toString()`\n\nReturns string representation of `this.deref()`.\n\n##### `Providence.prototype.valueOf([notSetValue])`\n\nAlias of `Providence.prototype.deref([notSetValue])`.\n\n##### `Providence.prototype.deref([notSetValue])`\n\nDereference by unboxing the root data and getting the value at path.\n\nIf path happens to not exist, `notSetValue` is, instead, returned.\nIf `notSetValue` is not provided, it becomes value: `void 0`.\n\n##### `Providence.prototype.exists()`\n\nReturn true if a path exists within the unboxed root data.\n\n##### `Providence.prototype.path()`\n\nReturns the array representation of the path.\n\n##### `Providence.prototype.options()`\n\nReturns 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.\n\n##### `Providence.prototype.new(newOptions)`\n\nCreate a new Providence object with options via this instance.\n\n##### `Providence.prototype.cursor([keyValue])`\n\nWhen given no arguments, return itself.\n\nBy default, this is the same behaviour as cursor() method for immutable-js cursors:\n- Returns a sub-cursor following the path keyValue starting from this cursor.\n- If keyValue is not an array, an array containing keyValue is instead used.\n\n##### `Providence.prototype.update([notSetValue,] updater)`\n\nUpdate value in the unboxed root data at path using the updater function.\nIf the path exists, updater is called using:\n- the value at path\n- unboxed root data\n- boxed root data\n\nIf path doesn't exist, notSetValue is used as the initial value.\nIf notSetValue is not defined, it has value void 0.\n\nIf updater returns the same value the value at path (or notSetValue),\nthen no changes has truly occurred, and the current cursor is instead returned.\n\nOtherwise, 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.\nIn addition, any defined functions at onUpdate and/or _onUpdate within options will be called with the following:\n- options\n- cursor path\n- new unboxed root data with the new value\n- previous unboxed root data\n\n##### `Providence.prototype.delete()`\n\nDelete value at path.\n\nIf the new unboxed root data is the same as the previous, original unboxed root data, then the current cursor is returned.\n\nOtherwise, any defined functions at onUpdate and/or _onUpdate within options will be called with the following:\n- options\n- cursor path\n- new unboxed root data with the new value\n- previous unboxed root data\n\nIn addition, the new providence cursor containing the new unboxed root data will be returned.\n\n##### `Providence.prototype.remove()`\n\nAlias of `Providence.prototype.delete()`.\n\n\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdashed%2Fprovidence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdashed%2Fprovidence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdashed%2Fprovidence/lists"}