Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Store
✓ import { Store } from 'xorma';
✗ const { Store } = require('xorma');
The central repository for all models and data. ESM-only due to modern frontend focus.
Model
✓ import { Model } from 'xorma';
✗ import Model from 'xorma/Model';
Base class for defining data structures. Typically extended via `Model.withType(DataType)`.
DataType
✓ import { DataType } from 'xorma';
✗ import { Data } from 'xorma';
Used with `Model.withType()` to provide type information for model instances.
observable, makeObservable
✓ import { observable, makeObservable } from 'mobx';
Essential MobX decorators/functions for making Xorma model properties reactive. Although from MobX, they are integral to defining Xorma models.
This quickstart demonstrates defining models, creating a central store, performing synchronous CRUD operations, and observing reactive updates using MobX's `autorun`.
import { DataType, Model, Store } from 'xorma';
import { observable, makeObservable, autorun } from 'mobx';
interface TaskData {
id: string;
name: string;
done: boolean;
}
// 1. Define your base model
class BaseModel extends Model.withType(DataType<TaskData>()) {
static idSelector(data: TaskData) {
return data.id;
}
}
// 2. Define your specific data model extending BaseModel
class TaskModel extends BaseModel.withType(DataType<TaskData>()) {
name!: string;
done!: boolean;
constructor(data: TaskData) {
super(data);
makeObservable(this, {
name: observable,
done: observable
});
this.loadJSON(data);
}
// Method to update instance data from JSON
loadJSON(data: TaskData) {
this.name = data.name;
this.done = data.done;
}
toJSON(): TaskData {
return { id: this.id, name: this.name, done: this.done };
}
}
// 3. Create a store and register your models
const store = new Store({
schemaVersion: 1,
models: {
Task: TaskModel // Register TaskModel under the key 'Task'
}
});
// Access the collection for TaskModel
const taskCollection = store.getCollection(TaskModel);
// 4. Add data to the store (synchronous)
console.log('Adding tasks...');
const task1 = taskCollection.create({
id: 'task-1',
name: 'Learn Xorma',
done: false
});
const task2 = taskCollection.create({
id: 'task-2',
name: 'Build something great',
done: false
});
// 5. Demonstrate reactivity with MobX autorun
autorun(() => {
const allTasks = taskCollection.getAll();
console.log('\n--- Reactive Task List ---');
allTasks.forEach(task => console.log(`[${task.id}] ${task.name} (Done: ${task.done})`));
console.log('--------------------------');
});
// 6. Update data and observe reactivity (synchronous)
setTimeout(() => {
console.log('\nUpdating task-1...');
task1.name = 'Master Xorma';
task1.done = true;
// Trying to create a task with an existing ID will update it
taskCollection.create({
id: 'task-2',
name: 'Deploy something awesome', // Name is updated
done: true // Done status is updated
});
// Add a new task
taskCollection.create({
id: 'task-3',
name: 'Celebrate success',
done: false
});
}, 1000);
// Output after all operations (will be reactive, showing changes from setTimeout)
Errors
Common errors & fixes
Error: [mobx] Property 'fieldName' is not observable. Please ensure it is annotated with @observable, or added to an object passed to 'makeObservable'.
A property on a Xorma `Model` instance was accessed or modified in a reactive context but was not marked as observable using `makeObservable` in the constructor.
fixIn your custom `Model` class's constructor, ensure all properties intended to be reactive are listed in the `makeObservable(this, { ... })` call with `observable` or `computed`. Component is not re-rendering after data changes.
A React/Vue component that consumes data from the Xorma store is not properly wrapped as an observer.
fixEnsure your functional React components are wrapped with `observer` from `mobx-react` (or `mobx-vue` for Vue) to subscribe them to observable changes from the Xorma store.
My `create` call is not returning a new instance, but modifying an existing one.
You attempted to `create` a new model instance with an ID that already exists in the Xorma store. Xorma guarantees a single instance per ID.
fixThis is expected behavior. If you need a truly new, separate instance, provide a unique ID. If you intend to update, this is the correct method. Otherwise, consider cloning an existing instance if the API provides such functionality.
Audit
Dependencies
mobxrequiredCore reactivity engine for Xorma models and store operations.