{"id":17229851,"url":"https://github.com/josephg/statecraft","last_synced_at":"2025-09-04T10:41:23.501Z","repository":{"id":9841115,"uuid":"63514256","full_name":"josephg/statecraft","owner":"josephg","description":"Manage state with finesse","archived":false,"fork":false,"pushed_at":"2022-12-09T18:32:09.000Z","size":1960,"stargazers_count":187,"open_issues_count":30,"forks_count":9,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-08-06T13:47:25.336Z","etag":null,"topics":["dag","database","event-sourcing","realtime-collaboration","realtime-database"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/josephg.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":"2016-07-17T04:12:14.000Z","updated_at":"2025-07-23T21:22:57.000Z","dependencies_parsed_at":"2023-01-11T20:13:23.894Z","dependency_job_id":null,"html_url":"https://github.com/josephg/statecraft","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/josephg/statecraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephg%2Fstatecraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephg%2Fstatecraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephg%2Fstatecraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephg%2Fstatecraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josephg","download_url":"https://codeload.github.com/josephg/statecraft/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephg%2Fstatecraft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273595253,"owners_count":25134257,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["dag","database","event-sourcing","realtime-collaboration","realtime-database"],"created_at":"2024-10-15T04:51:18.161Z","updated_at":"2025-09-04T10:41:23.457Z","avatar_url":"https://github.com/josephg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Statecraft\n\nStatecraft is a protocol and set of tools for interacting with data that changes over time. It is the spiritual successor to [Sharedb](https://github.com/share/sharedb).\n\nStatecraft sees the world as a series of stores. Each store has:\n\n- Some data (A single value or a set of key-value pairs)\n- A monotonically increasing version number\n\nThe store guarantees that the data is immutable with respect to time. (So if the data changes, the version number goes up).\n\nStores provide a standard set of methods to interact with the data:\n\n- **Fetch**: Run a query against the data\n- **Mutate**: Edit the data \u0026 bump the version\n- **Subscribe**: Be notified when the data changes, and optionally also fetch the current state of the data.\n- **GetOps**: *(Optional)* Get all operations in some specified version range. Stores can choose how much historical data to store and return.\n\nA Statecraft store is more than just a database abstraction. They can provide an interface to:\n\n- A file on disk\n- A single variable in memory\n- A computed view (eg rendered HTML)\n- An event log (eg Kafka)\n- A store which lives remotely over the network\n- Some other remote API\n\nAnd much more.\n\nUnlike traditional transactional databases, Statecraft stores compose together like LEGO. Stores wrap one another, adding functionality or changing the behaviour of the store living underneath in the process.\n\nFor example:\n\n- The `readonly` store transparently provides access to the underlying store, but disallows any mutation.\n- A `cache` store caches all queries made to the underlying store, and can return subsequent queries directly\n- The `map` store runs all fetch and subscribe result values through a mapping function.\n- The network server and client allow you to use a Statecraft store living on another computer as if it existed locally. This works between servers or from a web browser over websockets.\n\nThe philosophy of Statecraft is to \"ship the architecture diagram\". You should be able to take your whiteboard diagram of your application and construct (almost) all of it directly out of Statecraft stores. No reimplementation or integration necessary. And because the stores are standard, we can have standard tools for debugging too.\n\n\n## Queries\n\nStatecraft's `fetch` and `subscribe` functions use queries to specify the data to return.\n\nCurrently there's 3 standard supported query types:\n\n- *Single value query* (`Single`). This is for stores which just expose a single value. Aka, fetch everything. Single value queries return a single value result.\n- *Key-value queries* (`KV`). These contain a list (or a set) of keys to fetch, and return a map of key-value pairs in response. There is also an `AllKV` variant which requests all key-value pairs in the store.\n- *Range queries*. These specify a list of ranges (start \u0026 end pairs) to fetch. They can optionally specify a limit and offset for the start and end of the range, although not all stores support all of these fields.\n\nI've made a proof-of-concept store which adds GraphQL schema \u0026 query support, but this is not yet fully merged.\n\n\n## Ok that sounds great but how do I use it?\n\nFull developer API documentation is still in the works. Sorry.\n\nFor now you can look through the type definitions (with documentation) for stores and queries [in lib/interfaces.ts](https://github.com/josephg/statecraft/blob/master/core/lib/interfaces.ts). The set of available core stores is [in lib/stores/](https://github.com/josephg/statecraft/tree/master/core/lib/stores). And there are some demos showing different ways to use the API in [demos/](https://github.com/josephg/statecraft/tree/master/demos).\n\n\n## Why is this written in Typescript?\n\nJavascript has been to make a proof of concept because it was easy and it demos well.\n\nStatecraft is language agnostic and my plan is to have implementations in many other languages too. Once async/await support is [in rust proper](https://areweasyncyet.rs), I would like to port Statecraft's core into rust.\n\nThe API is designed to make it easy to re-expose a statecraft store over the network. For this reason it should be easy to build applications on top of Statecraft which use a mixed set of languages. For example, you should be able to write your blog rendering function in Rust or Go but use the existing nodejs code to cache the results and expose it over websockets. This requires compatible Statecraft implementations in Go, Rails, Python, Rust, Swift, etc. These are waiting on a standardization push for the network API, which is coming but not here yet.\n\n\n## Status\n\nStatecraft is in an advanced proof-of-concept stage. It works, but you and your application may need some hand holding. There are rough edges.\n\nIf you want help building Statecraft, making stuff on top of Statecraft, or if you would like to help with Statecraft [get in touch](mailto:me@josephg.com).\n\n\n## License\n\nStatecraft is licensed under the ISC:\n\n```\nCopyright 2019 Joseph Gentle\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND\nFITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\nPERFORMANCE OF THIS SOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephg%2Fstatecraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosephg%2Fstatecraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephg%2Fstatecraft/lists"}