{"id":25941861,"url":"https://github.com/eriestrisnadi/struma","last_synced_at":"2026-02-14T11:35:02.042Z","repository":{"id":277227792,"uuid":"931710919","full_name":"eriestrisnadi/struma","owner":"eriestrisnadi","description":"A schema-driven JSON Database with immutable snapshots capabilities. 💾 ","archived":false,"fork":false,"pushed_at":"2025-02-24T02:14:14.000Z","size":148,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-31T20:44:24.750Z","etag":null,"topics":["cross-platform","database","electron","embeddable","embedded-database","esm","immutable","javascript","json","json-database","localstorage","nodejs","schema","storage","typescript","umd"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/eriestrisnadi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-12T18:20:50.000Z","updated_at":"2025-02-24T02:14:18.000Z","dependencies_parsed_at":"2025-02-12T20:44:54.834Z","dependency_job_id":null,"html_url":"https://github.com/eriestrisnadi/struma","commit_stats":null,"previous_names":["eriestrisnadi/struma"],"tags_count":0,"template":false,"template_full_name":"xituru/typescript-package-boilerplate","purl":"pkg:github/eriestrisnadi/struma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriestrisnadi%2Fstruma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriestrisnadi%2Fstruma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriestrisnadi%2Fstruma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriestrisnadi%2Fstruma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eriestrisnadi","download_url":"https://codeload.github.com/eriestrisnadi/struma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriestrisnadi%2Fstruma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29443452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T10:51:12.367Z","status":"ssl_error","status_checked_at":"2026-02-14T10:50:52.088Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cross-platform","database","electron","embeddable","embedded-database","esm","immutable","javascript","json","json-database","localstorage","nodejs","schema","storage","typescript","umd"],"created_at":"2025-03-04T06:15:47.518Z","updated_at":"2026-02-14T11:35:02.028Z","avatar_url":"https://github.com/eriestrisnadi.png","language":"TypeScript","readme":"# Struma\n\n[![npm package](https://img.shields.io/badge/npm-struma-brightgreen)](https://www.npmjs.com/package/struma)\n[![version number](https://img.shields.io/npm/v/struma?color=green\u0026label=version)](https://github.com/eriestrisnadi/struma/releases)\n[![Release \u0026 Publish](https://github.com/eriestrisnadi/struma/actions/workflows/release.yml/badge.svg)](https://github.com/eriestrisnadi/struma/actions/workflows/release.yml)\n[![License](https://img.shields.io/github/license/eriestrisnadi/struma)](https://github.com/eriestrisnadi/struma/blob/main/LICENSE)\n\nA schema-driven JSON Database with immutable snapshots capabilities. Built on top of [Immutable](https://github.com/facebook/immutable-js), [Superstruct](https://github.com/ianstormtaylor/superstruct) and [lowdb](https://github.com/typicode/lowdb).\n\n## Features\n\n- **Schema Validation**: Ensure data integrity with `Superstruct` schemas\n- **Immutable State**: Use `Immutable` to manage state in a predictable way.\n- **Flexible Adapter**: Compatible with `lowdb` adapters (filesystem, localStorage, memory, etc), or extend functionality with custom adapters for advanced use cases.\n- **Sync/Async Supports**: Supports seamlessly both synchronous and asynchronous adapters.\n- **Cross-Platform**: Works in both Node.js and Browser environments.\n- **Snapshot History**: Automatically takes snapshots of the state, providing historical views of your data.\n- **Explicit Writes**: Mutate state without immediate persistence, and write changes explicitly when needed.\n\n## Installation\n\nInstall the library using npm:\n\n```sh\nnpm install immutable superstruct struma --save\n```\n\nOr with yarn:\n\n```sh\nyarn add immutable superstruct struma\n```\n\n## Usage\n\n### 1. Define a Schema\n\nUse `superstruct` to define a schema for your data:\n\n```ts\nimport { number, object, string } from 'superstruct';\n\nconst UserSchema = object({\n  name: string(),\n  age: number(),\n  preferences: object({\n    theme: string(),\n  }),\n});\n```\n\n### 2. Initialize Struma\n\n```ts\nimport { Struma } from 'struma';\nimport { JSONFile } from 'struma/adapters/node';\n\nconst adapter = new JSONFile('db.json');\nconst db = new Struma(UserSchema, adapter);\n```\n\n### 3. Update and Save State\n\n```ts\nimport { Map } from 'immutable';\n\n// Update state\nconst newState = Map({\n  name: 'Alice',\n  age: 30,\n  preferences: Map({\n    theme: 'dark',\n  }),\n});\n// Either you can use plain js object too, it will\n// auto resolves using `fromJS` method from `immutable`\ndb.state = newState;\n\n// Save state to write into db.json\nawait db.write();\n```\n\n```ts\n// db.json\n{\n  \"name\": \"Alice\",\n  \"age\": 30,\n  \"preferences\": {\n    \"theme\": \"dark\"\n  }\n}\n```\n\n### 4. Read State\n\n```ts\nconsole.log((await db.state).toJS()); // { name: 'Alice', age: 30, preferences: { theme: 'dark'} }\n```\n\n### 5. Access Snapshot History\n\n```ts\nconsole.log((await db.snapshots).toJS()); // Array of historical states\n```\n\n## API\n\n### `new Struma(schema, adapter)`\n\nCreates a new `Struma` instance.\n\n- `schema`: A `superstruct` schema for data validation.\n- `adapter`: An adapter that conforms to the `Adapter` interface.\n\n### `db.state`\n\n- **Getter**: Returns the current state as an immutable object.\n- **Setter**: Updates the state. Throws an error if the data is invalid.\n\n### `db.write()`\n\nWrite the current state to the adapter. Returns a promise that resolves when the write operation is complete.\n\n### `db.snapshots`\n\nReturns a Promise that resolves a list of historical states (snapshots) as an immutable List. Each snapshot is an immutable representation of the state at a specific point in time.\n\n### Custom Adapters\n\nYou can create your own adapter as long as it conforms to the `Adapter` interface\n\n```ts\nimport type { Adapter as AsyncAdapter, SyncAdapter } from 'lowdb';\n\nexport interface Adapter\u003cT\u003e {\n  read: () =\u003e ReturnType\u003cAsyncAdapter\u003cT\u003e['read'] | SyncAdapter\u003cT\u003e['read']\u003e;\n  write: (data: T) =\u003e ReturnType\u003cAsyncAdapter\u003cT\u003e['write'] | SyncAdapter\u003cT\u003e['write']\u003e;\n}\n```\n\n\u003e [!TIP]\n\u003e For common case, you can go to `lowdb` [Documentation](https://github.com/typicode/lowdb/blob/main/README.md#third-party-adapters)\n\n## Examples\n\n### Node.js / ES Modules\n\n```es6\nimport { Struma } from 'struma';\nimport { JSONFile } from 'struma/adapters/node';\nimport { number, object, string } from 'superstruct';\n\nconst UserSchema = object({\n  name: string(),\n  age: number(),\n});\n\nconst adapter = new JSONFile('db.json');\nconst db = new Struma(UserSchema, adapter);\n\n(async () =\u003e {\n  // Update state\n  db.state = { name: 'Alice', age: 25 };\n\n  // Save state\n  await db.write();\n\n  // Read state\n  console.log((await db.state).toJS()); // { name: 'Alice', age: 25 }\n\n  // Access snapshot history\n  console.log((await db.snapshots).toJS()); // [null, { name: 'Alice', age: 25 }]\n})();\n```\n\n### UMD\n\nAs for UMD build, it will exposes `Struma` class,\nand `Struma.adapters` compatible adapters for browser as global.\n\n```html\n\u003cscript src=\"https://unpkg.com/immutable\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/superstruct\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/struma\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // Define a schema\n  const UserSchema = Superstruct.object({\n    name: Superstruct.string(),\n    age: Superstruct.string(),\n  });\n\n  const adapter = new Struma.adapters.LocalStorage('db');\n  const db = new Struma(UserSchema, adapter);\n\n  (async () =\u003e {\n    // Update state\n    const newState = { name: 'John', age: '30' };\n    db.state = newState;\n\n    // Save state to write into LocalStorage\n    await db.write();\n\n    // Read state\n    const state = await db.state;\n    console.log('Current State:', state.toJS()); // { name: 'John', age: '30' }\n\n    // Access snapshot history\n    const snapshots = await db.snapshots;\n    console.log('Snapshot History:', snapshots.toJS()); // [null, { name: 'John', age: '30' }]\n  })();\n\u003c/script\u003e\n```\n\n## Support\n\nFor feedbacks or issues, check out the [Issues](https://github.com/eriestrisnadi/struma/issues).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feriestrisnadi%2Fstruma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feriestrisnadi%2Fstruma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feriestrisnadi%2Fstruma/lists"}