Orbit Documentation

Orbit is a composable data framework designed for managing complex web application data needs. While primarily used as a flexible client-side ORM, it is also compatible with Node.js for server-side use.

Key capabilities include:

• Multi-source interaction: Seamlessly work with REST servers, WebSocket streams, IndexedDB, or in-memory stores.
• Offline-first support: Transition smoothly between offline and online modes.
• Flexible UX patterns: Support both optimistic and pessimistic user experiences.
• Unified Data Modeling: Use a common schema and a consistent set of query/update expressions regardless of the underlying data source.
• Deterministic Change Tracking: Track changes and support undo/redo functionality.
• Immutable State Management: Fork immutable stores and merge changes back when ready.

Orbit is a framework designed to orchestrate access, transformation, and synchronization between disparate data sources. It is written in TypeScript and distributed via npm. Most Orbit packages are isomorphic, meaning they can run in both modern web browsers and the Node.js runtime.

Key capabilities include:

• Optimistic and pessimistic UX patterns.
• Pluggable sources with common interfaces.
• Connection durability via request queuing and retries.
• Application durability by persisting transient state.
• Warm caches available immediately on startup.
• Custom request coordination (priority and fallback plans).
• Branching and merging of data caches.
• Deterministic change tracking and undo/redo support.

Sources provide access to data in Orbit and vary in capability. Some support updating or querying records, while others only broadcast changes.

Orbit provides several standard sources:

• @orbit/memory: An in-memory source.
• @orbit/jsonapi: A JSON:API client.
• @orbit/indexeddb: For accessing IndexedDB.
• @orbit/local-storage: For accessing LocalStorage.

Custom sources can be implemented to connect to any data provider. All sources must be instantiated with a RecordSchema to understand the domain-specific data they manage.

Data in an Orbit source is updated by applying a Transform. A transform consists of one or more Operations, where each operation represents a single atomic change to a record or a relationship (e.g., adding a record, updating a field, or deleting a relationship).

Key Concepts:

• Atomicity: Transforms must be applied atomically—either all operations within a transform succeed, or they all fail together.
• Operations: The building blocks of a transform. They define specific actions like addRecord, updateRecord, or replaceAttribute.
• Transforms: A collection of operations identified by a unique id. You typically use a TransformBuilder to construct these rather than creating them manually.

To apply changes, use a source's update or push method and pass in a builder function.

A record's identity is defined by the combination of its type (string) and id (string). There are three common strategies for managing identity:

1. Auto-generate IDs locally: Use UUIDs locally and remotely. This is the simplest approach.
2. Reference remote IDs: Only use IDs generated by the server. This works if you don't need to create new records locally.
3. Map local IDs to remote keys: Auto-generate IDs locally and map them to canonical IDs (keys) generated remotely. This is the most flexible for complex applications.

When using the third approach, store remote IDs in a keys object at the root of the record. You can use a RecordKeyMap to manage these mappings.

{
  type: 'planet',
  id: '34677136-c0b7-4015-b9e5-57f6fdd16bd2',
  keys: {
    remoteId: '123456'
  }
}

A Coordinator is a high-level abstraction in Orbit that manages a set of sources by applying coordination strategies to them. Instead of manually attaching event handlers to every source, you use a coordinator to orchestrate interactions between sources.

Key benefits include:

• Preconfigured Strategies: Easily apply complex behaviors like event logging or log truncation.
• Lifecycle Management: You can activate or deactivate all strategies at once using coordinator.activate() and coordinator.deactivate(), which helps prevent memory leaks.
• Unified Configuration: Coordinators can share a single logLevel across all attached strategies.

import Coordinator from '@orbit/coordinator';

const coordinator = new Coordinator({
  sources: [memory, backup],
  strategies: [backupMemorySync]
});

A Coordinator manages a set of sources and applies coordination strategies. This is a higher-level abstraction than manual event handling.

Using a Coordinator allows you to:

• Use preconfigured strategies like SyncStrategy.
• Activate or deactivate all strategies at once using .activate() and .deactivate().
• Share a single log level across all strategies.

To use it, create a Coordinator with your sources, add strategies (like SyncStrategy), and call await coordinator.activate().

import { Coordinator, SyncStrategy } from '@orbit/coordinator';

const coordinator = new Coordinator({
  sources: [memory, backup]
});

const backupMemorySync = new SyncStrategy({
  source: 'memory',
  target: 'backup',
  blocking: true
});

coordinator.addStrategy(backupMemorySync);
await coordinator.activate();

Orbit records are lightweight, serializable Plain Old JavaScript Objects (POJOs) that follow the JSON:API specification. A record must contain type and id to establish identity, and can optionally contain attributes, relationships, and keys.

Important Constraints:

• All fields in a record share the same namespace and must be unique.
• You cannot have an attribute or relationship with the same name as another field.
• You cannot name an attribute or relationship type or id.

{
  type: 'planet',
  id: 'earth',
  attributes: {
    name: 'Earth',
    classification: 'terrestrial',
    atmosphere: true
  },
  relationships: {
    solarSystem: {
      data: { type: 'solarSystem', id: 'theSolarSystem' }
    },
    moons: {
      data: [
        { type: 'moon', id: 'theMoon' }
      ]
    }
  }
}

Interfaces like Updatable and Queryable follow a consistent event pattern. For any method x, the source emits three specific events:

1. beforeX: Emitted before the method is processed. Listeners can return a Promise to block processing. If a listener's promise fails, the source emits xFail and stops processing.
2. x: Emitted after the method is successfully processed.
3. xFail: Emitted if an error occurs during the beforeX phase or during the internal processing of x.

Additionally, any mutations caused by calling x will trigger the general transform event.

Important Lifecycle Detail: While a failure in a beforeX listener can block the method, failures in listeners attached to the transform or x events will not prevent further processing.