Xorma In-memory Reactive Database

Common errors

• Error: [mobx] Property 'fieldName' is not observable. Please ensure it is annotated with @observable, or added to an object passed to 'makeObservable'.

  cause 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.
  fix In 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.

  cause A React/Vue component that consumes data from the Xorma store is not properly wrapped as an observer.
  fix Ensure 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.

  cause 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.
  fix This 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.

Warnings

• breaking Xorma is currently at version 0.0.1. The API is in a very early stage of development and is subject to frequent and significant breaking changes without prior notice. Use in production at your own risk.
  Fix: Monitor the official GitHub repository and documentation for updates. Pin exact versions in your `package.json` to prevent unexpected breaks.
• gotcha Xorma enforces a 'single instance per ID' guarantee. Attempting to `create` a model with an ID that already exists in the store will not create a new instance, but instead update the existing instance's data via its `loadJSON` method.
  Fix: Understand that `create` acts as an 'upsert' when an ID collision occurs. If you need distinct instances, ensure unique IDs or use other methods if provided by the API for deep cloning/copying.
• gotcha The project repository indicates no security policy (`SECURITY.md`) has been defined. This means there's no formal process for reporting or addressing security vulnerabilities.
  Fix: Exercise caution if handling sensitive data. For critical applications, consider performing a security audit or contributing to the project's security posture.

Install

• npm install xorma npm
• yarn add xorma yarn
• pnpm add xorma pnpm

Imports

• Store
  wrong:

  const { Store } = require('xorma');

  correct:

  import { Store } from 'xorma';

  The central repository for all models and data. ESM-only due to modern frontend focus.
• Model
  wrong:

  import Model from 'xorma/Model';

  correct:

  import { Model } from 'xorma';

  Base class for defining data structures. Typically extended via `Model.withType(DataType)`.
• DataType
  wrong:

  import { Data } from 'xorma';

  correct:

  import { DataType } 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.

Quickstart

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)