- Notifications
You must be signed in to change notification settings - Fork0
A schema-driven JSON Database with immutable snapshots capabilities. 💾
License
eriestrisnadi/struma
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A schema-driven JSON Database with immutable snapshots capabilities. Built on top ofImmutable,Superstruct andlowdb.
- Schema Validation: Ensure data integrity with
Superstructschemas - Immutable State: Use
Immutableto manage state in a predictable way. - Flexible Adapter: Compatible with
lowdbadapters (filesystem, localStorage, memory, etc), or extend functionality with custom adapters for advanced use cases. - Sync/Async Supports: Supports seamlessly both synchronous and asynchronous adapters.
- Cross-Platform: Works in both Node.js and Browser environments.
- Snapshot History: Automatically takes snapshots of the state, providing historical views of your data.
- Explicit Writes: Mutate state without immediate persistence, and write changes explicitly when needed.
Install the library using npm:
npm install immutable superstruct struma --save
Or with yarn:
yarn add immutable superstruct struma
Usesuperstruct to define a schema for your data:
import{number,object,string}from'superstruct';constUserSchema=object({name:string(),age:number(),preferences:object({theme:string(),}),});
import{Struma}from'struma';import{JSONFile}from'struma/adapters/node';constadapter=newJSONFile('db.json');constdb=newStruma(UserSchema,adapter);
import{Map}from'immutable';// Update stateconstnewState=Map({name:'Alice',age:30,preferences:Map({theme:'dark',}),});// Either you can use plain js object too, it will// auto resolves using `fromJS` method from `immutable`db.state=newState;// Save state to write into db.jsonawaitdb.write();
// db.json{"name":"Alice","age":30,"preferences":{"theme":"dark"}}
console.log((awaitdb.state).toJS());// { name: 'Alice', age: 30, preferences: { theme: 'dark'}}
console.log((awaitdb.snapshots).toJS());// Array of historical states
Creates a newStruma instance.
schema: Asuperstructschema for data validation.adapter: An adapter that conforms to theAdapterinterface.
- Getter: Returns the current state as an immutable object.
- Setter: Updates the state. Throws an error if the data is invalid.
Write the current state to the adapter. Returns a promise that resolves when the write operation is complete.
Returns 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.
You can create your own adapter as long as it conforms to theAdapter interface
importtype{AdapterasAsyncAdapter,SyncAdapter}from'lowdb';exportinterfaceAdapter<T>{read:()=>ReturnType<AsyncAdapter<T>['read']|SyncAdapter<T>['read']>;write:(data:T)=>ReturnType<AsyncAdapter<T>['write']|SyncAdapter<T>['write']>;}
Tip
For common case, you can go tolowdbDocumentation
import{Struma}from'struma';import{JSONFile}from'struma/adapters/node';import{number,object,string}from'superstruct';constUserSchema=object({name:string(),age:number(),});constadapter=newJSONFile('db.json');constdb=newStruma(UserSchema,adapter);(async()=>{// Update statedb.state={name:'Alice',age:25};// Save stateawaitdb.write();// Read stateconsole.log((awaitdb.state).toJS());// { name: 'Alice', age: 25 }// Access snapshot historyconsole.log((awaitdb.snapshots).toJS());// [null, { name: 'Alice', age: 25 }]})();
As for UMD build, it will exposesStruma class,andStruma.adapters compatible adapters for browser as global.
<scriptsrc="https://unpkg.com/immutable"></script><scriptsrc="https://unpkg.com/superstruct"></script><scriptsrc="https://unpkg.com/struma"></script><script>// Define a schemaconstUserSchema=Superstruct.object({name:Superstruct.string(),age:Superstruct.string(),});constadapter=newStruma.adapters.LocalStorage('db');constdb=newStruma(UserSchema,adapter);(async()=>{// Update stateconstnewState={name:'John',age:'30'};db.state=newState;// Save state to write into LocalStorageawaitdb.write();// Read stateconststate=awaitdb.state;console.log('Current State:',state.toJS());// { name: 'John', age: '30' }// Access snapshot historyconstsnapshots=awaitdb.snapshots;console.log('Snapshot History:',snapshots.toJS());// [null, { name: 'John', age: '30' }]})();</script>
For feedbacks or issues, check out theIssues.
About
A schema-driven JSON Database with immutable snapshots capabilities. 💾