{"id":13499727,"url":"https://github.com/omniscientjs/immstruct","last_synced_at":"2025-04-04T19:11:04.126Z","repository":{"id":21658270,"uuid":"24979127","full_name":"omniscientjs/immstruct","owner":"omniscientjs","description":"Immutable data structures with history for top-to-bottom properties in component based libraries like React. Based on Immutable.js","archived":false,"fork":false,"pushed_at":"2018-09-04T10:52:15.000Z","size":270,"stargazers_count":375,"open_issues_count":6,"forks_count":21,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-28T18:17:42.378Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omniscientjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-09T07:53:41.000Z","updated_at":"2025-02-07T09:48:30.000Z","dependencies_parsed_at":"2022-08-17T17:50:57.430Z","dependency_job_id":null,"html_url":"https://github.com/omniscientjs/immstruct","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omniscientjs%2Fimmstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omniscientjs%2Fimmstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omniscientjs%2Fimmstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omniscientjs%2Fimmstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omniscientjs","download_url":"https://codeload.github.com/omniscientjs/immstruct/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234921,"owners_count":20905854,"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-07-31T22:00:39.578Z","updated_at":"2025-04-04T19:11:04.099Z","avatar_url":"https://github.com/omniscientjs.png","language":"JavaScript","readme":"Immstruct [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][depstat-image]][depstat-url] [![Gitter][gitter-image]][gitter-url]\n======\n\nA wrapper for [Immutable.js](https://github.com/facebook/immutable-js/tree/master/contrib/cursor) to easily create cursors that notify when they\nare updated. Handy for use with immutable pure components for views,\nlike with [Omniscient](https://github.com/omniscientjs/omniscient) or [React.js](https://github.com/facebook/react).\n\nSee the [API References](./api.md) for more documentation and usage.\n\n## Usage\n\n### `someFile.js`\n```js\n\n// Require a default instance of immstruct (singleton instance)\nvar immstruct = require('immstruct');\n\n// Create structure under the later retrievable ID `myKey`\nvar structure = immstruct('myKey', { a: { b: { c: 1 } } });\n\n// Use event `swap` or `next-animation-frame`\nstructure.on('swap', function (newStructure, oldStructure, keyPath) {\n  console.log('Subpart of structure swapped.');\n  console.log('New structure:', newStructure.toJSON());\n\n  // e.g. with usage with React\n  // React.render(App({ cursor: structure.cursor() }), document.body);\n});\n\nvar cursor = structure.cursor(['a', 'b', 'c']);\n\n// Update the value at the cursor. As cursors are immutable,\n// this returns a new cursor that points to the new data\nvar newCursor = cursor.update(function (x) {\n  return x + 1;\n});\n\n// We unwrap the cursor, by getting the data it is pointing at using deref\n// and see that the value of the old `cursor` to is still `1`\nconsole.log(cursor.deref()); //=\u003e 1\n\n// `newCursor` points to the new data\nconsole.log(newCursor.deref()); //=\u003e 2\n```\n\n**Note:** *The cursors you see here are cursors from Facebooks Immutable.js library. Read the\ncomplete API in [their repo](https://github.com/facebook/immutable-js/blob/master/contrib/cursor/index.d.ts).*\n\n### `anotherFile.js`\n```js\n// Require a default instance of immstruct (singleton instance)\nvar immstruct = require('immstruct');\n\n// Get the structure we previously defined under the ID `myKey`\nvar structure = immstruct('myKey');\n\nvar cursor = structure.cursor(['a', 'b', 'c']);\n\nvar updatedCursor = cursor.update(function (x) { // triggers `swap` in somefile.js\n  return x + 1;\n});\n\n// Unwrap the value\nconsole.log(updatedCursor.deref()); //=\u003e 3\n```\n\n## References\n\nWhile Immutable.js cursors are immutable, Immstruct lets you create references\nto a piece of data from where cursors will always be fresh. The cursors you create\nare still immutable, but you have the ability to retrieve the newest and latest\ncursor pointing to a specific part of your immutable structure.\n\n```js\n\nvar structure = immstruct({ 'foo': 'bar' });\nvar ref = structure.reference('foo');\n\nconsole.log(ref.cursor().deref()) //=\u003e 'bar'\n\nvar oldCursor = structure.cursor('foo');\nconsole.log(oldCursor.deref()) //=\u003e 'bar'\n\nvar newCursor = structure.cursor('foo').update(function () { return 'updated'; });\nconsole.log(newCursor.deref()) //=\u003e 'updated'\n\nassert(oldCursor !== newCursor);\n\n// You don't need to manage and track fresh/stale cursors.\n// A reference cursor will do it for you.\nconsole.log(ref.cursor().deref()) //=\u003e 'updated'\n```\n\nUpdating a cursor created from a reference will also update the underlying structure.\n\nThis offers benefits similar to that of [Om](https://github.com/omcljs/om/wiki/Advanced-Tutorial#reference-cursors)'s `reference cursors`, where\n[React.js](http://facebook.github.io/react/) or [Omniscient](https://github.com/omniscientjs/omniscient/) components can observe pieces of application\nstate without it being passed as cursors in props from their parent components.\n\nReferences also allow for listeners that fire when their path or the path of sub-cursors change:\n\n```js\nvar structure = immstruct({\n  someBox: { message: 'Hello World!' }\n});\nvar ref = structure.reference(['someBox']);\n\nvar unobserve = ref.observe(function () {\n  // Called when data the path 'someBox' is changed.\n  // Also called when the data at ['someBox', 'message'] is changed.\n});\n\n// Update the data using the ref\nref.cursor().update(function () { return 'updated'; });\n\n// Update the data using the initial structure\nstructure.cursor(['someBox', 'message']).update(function () { return 'updated again'; });\n\n// Remove the listener\nunobserve();\n```\n\n### Notes\n\nParents' change listeners are also called when sub-cursors are changed.\n\nCursors created from references are still immutable. If you keep a cursor from\na `var cursor = reference.cursor()` around, the `cursor` will still point to the data\nat time of cursor creation. Updating it may rewrite newer information.\n\n## Usage Undo/Redo\n\n```js\n// optionalKey and/or optionalLimit can be omitted from the call\nvar optionalLimit = 10; // only keep last 10 of history, default Infinity\nvar structure = immstruct.withHistory('optionalKey', optionalLimit, { 'foo': 'bar' });\nconsole.log(structure.cursor('foo').deref()); //=\u003e 'bar'\n\nstructure.cursor('foo').update(function () { return 'hello'; });\nconsole.log(structure.cursor('foo').deref()); //=\u003e 'hello'\n\nstructure.undo();\nconsole.log(structure.cursor('foo').deref()); //=\u003e 'bar'\n\nstructure.redo();\nconsole.log(structure.cursor('foo').deref()); //=\u003e 'hello'\n\n```\n\n## Examples\n\nCreates or retrieves [structures](#structure--eventemitter).\n\nSee examples:\n\n```js\nvar structure = immstruct('someKey', { some: 'jsObject' })\n// Creates new structure with someKey\n```\n\n\n```js\nvar structure = immstruct('someKey')\n// Get's the structure named `someKey`.\n```\n\n**Note:** if someKey doesn't exist, an empty structure is created\n\n```js\nvar structure = immstruct({ some: 'jsObject' })\nvar randomGeneratedKey = structure.key;\n// Creates a new structure with random key\n// Used if key is not necessary\n```\n\n\n```js\nvar structure = immstruct()\nvar randomGeneratedKey = structure.key;\n// Create new empty structure with random key\n```\n\nYou can also create your own instance of Immstruct, isolating the\ndifferent instances of structures:\n\n```js\nvar localImmstruct = new immstruct.Immstruct()\nvar structure = localImmstruct.get('someKey', { my: 'object' });\n```\n\n## API Reference\n\nSee [API Reference](./api.md).\n\n## Structure Events\n\nA Structure object is an event emitter and emits the following events:\n\n* `swap`: Emitted when cursor is updated (new information is set). Is emitted\n on all types of changes, additions and deletions. The passed structures are\n always the root structure.\n One use case for this is to re-render design components. Callback\n is passed arguments: `newStructure`, `oldStructure`, `keyPath`.\n* `next-animation-frame`: Same as `swap`, but only emitted on animation frame.\n Could use with many render updates and better performance. Callback is passed\n arguments: `newStructure`, `oldStructure`, `keyPath`.\n* `change`: Emitted when data/value is updated and it existed before. Emits\n values: `newValue`, `oldValue` and `path`.\n* `delete`: Emitted when data/value is removed. Emits value:  `removedValue` and `path`.\n* `add`: Emitted when new data/value is added. Emits value: `newValue` and `path`.\n* `any`: With the same semantics as `add`, `change` or `delete`, `any` is triggered for\n  all types of changes. Differs from swap in the arguments that it is passed.\n  Is passed `newValue` (or undefined), `oldValue` (or undefined) and full `keyPath`.\n  New and old value are the changed value, not relative/scoped to the reference path as\n  with `swap`.\n\n**NOTE:** If you update cursors via `Cursor.update` or `Cursor.set`, and if the\nunderlying Immutable collection is not inherently changed, `swap` and `changed`\nevents will not be emitted, neither will the history (if any) be applied.\n\n[See tests for event examples](./tests/structure_test.js)\n\n[npm-url]: https://npmjs.org/package/immstruct\n[npm-image]: http://img.shields.io/npm/v/immstruct.svg?style=flat\n\n[travis-url]: http://travis-ci.org/omniscientjs/immstruct\n[travis-image]: http://img.shields.io/travis/omniscientjs/immstruct.svg?style=flat\n\n[depstat-url]: https://gemnasium.com/omniscientjs/immstruct\n[depstat-image]: http://img.shields.io/gemnasium/omniscientjs/immstruct.svg?style=flat\n\n[gitter-url]: https://gitter.im/omniscientjs/omniscient?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\n[gitter-image]: https://badges.gitter.im/Join%20Chat.svg\n\n## License\n\n[MIT License](http://en.wikipedia.org/wiki/MIT_License)\n","funding_links":[],"categories":["JavaScript","Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomniscientjs%2Fimmstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomniscientjs%2Fimmstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomniscientjs%2Fimmstruct/lists"}