{"id":22710554,"url":"https://github.com/smallhelm/entity-wharf-js","last_synced_at":"2025-08-07T15:31:25.089Z","repository":{"id":23903146,"uuid":"27283086","full_name":"smallhelm/entity-wharf-js","owner":"smallhelm","description":"Store data as entity attribute values in memory. Fast queries and manipulation of state.","archived":false,"fork":false,"pushed_at":"2014-12-08T15:55:58.000Z","size":176,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-02T15:19:07.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/smallhelm.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":"2014-11-28T21:43:37.000Z","updated_at":"2023-09-26T18:51:24.000Z","dependencies_parsed_at":"2022-08-24T11:00:29.760Z","dependency_job_id":null,"html_url":"https://github.com/smallhelm/entity-wharf-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallhelm%2Fentity-wharf-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallhelm%2Fentity-wharf-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallhelm%2Fentity-wharf-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallhelm%2Fentity-wharf-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smallhelm","download_url":"https://codeload.github.com/smallhelm/entity-wharf-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229057638,"owners_count":18013289,"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-12-10T12:10:29.573Z","updated_at":"2024-12-10T12:10:30.259Z","avatar_url":"https://github.com/smallhelm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# What it does\n\nStores your data in an elegant way that will give you great flexibility and leverage. This library is designed to be used as a state management solution for applications that need to be performant for quickly mutating state over many different types of entities with similar characteristics. Applications such as games and simulations. If performance isn't this crucial then check out [DataScript](https://github.com/tonsky/datascript) which provides immutability, versioning, undo/redo, and a powerful datalog query engine.\n\nAll data stored in Wharf is organized uniformly as\n * **Entity** - just an id (i.e. _1_)\n * **Attribute** - an attribute of the entity (i.e. _name_ or _age_)\n * **Value** - the value of the attribute (i.e. _\"bob\"_ or _50_)\n\nFor example let's describe some shapes.\n * entity 1 is a blue square\n * entity 2 is a red triangle\n * entity 3 is a red circle\n\n| Entity | Attribute | Value |\n| ------ | --------- | ----- |\n|      1 | color | blue |\n|      1 | width | 20 |\n|      1 | height | 20 |\n|      1 | n\\_edges | 4 |\n|      2 | color | red |\n|      2 | base | 10 |\n|      2 | height | 40 |\n|      2 | n\\_edges | 3 |\n|      3 | color | red |\n|      3 | radius | 20 |\n|      3 | n\\_edges | 0 |\n\nAlthough there are 3 distinct types we can perform generic queries that cross types.\n\nAll entities that have a `height` attribute returns `[ 1, 2 ]`\n\n| Entity | Attribute | Value |\n| ------ | --------- | ----- |\n|      1 | **height** | 20 |\n|      2 | **height** | 40 |\n\nAll entities that have a `height` and a `width` attribute returns `[ 1 ]`\n\n| Entity | Attribute | Value |\n| ------ | --------- | ----- |\n|      1 | **width** | 20 |\n|      1 | **height** | 20 |\n\nAll entities with a value `20` returns `[ 1, 3 ]`\n\n| Entity | Attribute | Value |\n| ------ | --------- | ----- |\n|      1 | width | **20** |\n|      1 | height | **20** |\n|      3 | radius | **20** |\n\nAll entities where `color == red` returns `[ 2, 3 ]`\n\n| Entity | Attribute | Value |\n| ------ | --------- | ----- |\n|      2 | **color** | **red** |\n|      3 | **color** | **red** |\n\n\n# How to use it\n\n```js\nvar db = Wharf();//make a new \"db\" to work with\n\n//create some entities\nvar square_id   = db.add({color: \"blue\", width: 20, height: 20, n_edges: 4});// (returns false on failure)\nvar triangle_id = db.add({color: \"red\", base: 10, height: 40, n_edges: 3});\nvar circle_id   = db.add({color: \"blue\", radius: 20});\n\n//db.set will add/overwrite attributes and values on an entitiy\ndb.set(circle_id, {color: \"red\", n_edges: 0});// -\u003e true (returns false on failure)\n\n//db.get returns the entities data\ndb.get(circle_id);// -\u003e {color: \"red\", radius: 20, n_edges: 0} (returns null if it's not found)\n\n//At this point the db has 3 entities the same as in the example\n\n//All entities that have a `height` attribute\ndb.q({a: [\"height\"]});// -\u003e [ square_id, triangle_id ]\n\n//All entities that have a `height` and a `width` attribute\ndb.q({a: [\"height\", \"width\"]});// -\u003e [ square_id ]\n\n//All entities with a value `20`\ndb.q({v: [20]});// -\u003e [ square_id, circle_id ]\n\n//All entities where `color == red`\ndb.q({av: [[\"color\", \"red\"]]});// -\u003e [ triangle_id, circle_id ]\n\n//entities are easy to remove\ndb.remove(square_id);// -\u003e true\n\n//if an ID doesn't exist it returns false\ndb.remove(square_id);// -\u003e false\n```\n\n# Installing\n\nThere are 3 ways to include this library\n\n### With browserify\n\n```sh\n$ npm install --save entity-wharf\n```\n\nThen use it\n```js\nvar Wharf = require('entity-wharf');\n...\n```\n\n### With a script tag\n\nDownload [this](https://github.com/smallhelm/entity-wharf/blob/master/entity-wharf.min.js) script then include it in your html\n```html\n\u003cscript src=\"entity-wharf.min.js\"\u003e\u003c/script\u003e\n```\n\nThen use it\n```js\nvar Wharf = ENTITY_WHARF;\n...\n```\n\n### With RequireJS\n\nDownload and use [this minified script](https://github.com/smallhelm/entity-wharf/blob/master/entity-wharf.min.js) then require it\n```js\nrequire(['entity-wharf'], function(Wharf) {\n\t...\n});\n```\n\n# License\nThe MIT License (MIT)\n\nCopyright (c) 2014 Small Helm LLC\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallhelm%2Fentity-wharf-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmallhelm%2Fentity-wharf-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallhelm%2Fentity-wharf-js/lists"}