API Reference

Complete API documentation for Routier packages. This page provides an overview of the main APIs available in each package.

Quick Navigation

@routier/datastore

The main package for creating data stores and managing collections.

DataStore

The primary class for managing collections and data persistence.

Import:

import { DataStore } from "@routier/datastore";

Main Methods:

  • constructor(dbPlugin: IDbPlugin) - Creates a new DataStore instance
  • collection(schema) - Returns a collection builder (protected, used in subclasses)
  • view(schema) - Returns a view builder (protected, used in subclasses)
  • saveAsync() - Persists all pending changes
  • save(done) - Persists all pending changes (callback)
  • hasChanges() - Checks if there are unsaved changes
  • dispose() - Cleans up resources

Collection

Represents a collection of entities with full CRUD operations.

Import:

import { Collection } from "@routier/datastore";

Main Methods:

Query Operations:

  • where(expression, params?) - Filter entities
  • sort(selector) - Sort ascending
  • sortDescending(selector) - Sort descending
  • skip(amount) - Skip n entities
  • take(amount) - Limit to n entities
  • toArray(done) - Get all results (callback)
  • toArrayAsync() - Get all results (Promise)
  • first(expression?, done) - Get first entity (callback)
  • firstAsync(expression?) - Get first entity (Promise)
  • subscribe() - Create a live query subscription
  • toQueryable() - Convert to QueryableAsync for dynamic queries

Modification Operations:

  • add(...entities) - Add entities (returns entities)
  • addAsync(...entities) - Add entities (returns Promise)
  • instance(...entities) - Create entity instances for change tracking
  • remove(...entities) - Remove entities
  • removeAsync(...entities) - Remove entities (Promise)

Change Tracking:

  • hasChanges() - Check if collection has unsaved changes
  • tags.get() - Get all tag values
  • tags.destroy() - Destroy all tags
  • tag(value) - Create or get a tag for tracking changes
  • attachments.set(...entities) - Attach entities to change tracking
  • attachments.remove(...entities) - Detach entities from change tracking
  • attachments.has(entity) - Check if entity is attached
  • attachments.get(entity) - Get attached entity
  • attachments.filter(selector) - Filter attached entities
  • attachments.find(selector) - Find attached entity
  • attachments.markDirty(...entities) - Force mark entities as dirty
  • attachments.getChangeType(entity) - Get change type for entity

@routier/core

Core utilities, schema definitions, and shared types.

Schema API (@routier/core/schema)

Import:

import { s, InferType, InferCreateType } from "@routier/core/schema";

Schema Builder:

  • s.define(name, properties) - Define a new schema
  • s.string() - String property type
  • s.number() - Number property type
  • s.boolean() - Boolean property type
  • s.date() - Date property type
  • s.object({ ... }) - Object property type
  • s.array(type) - Array property type

Property Modifiers:

  • .key() - Mark as primary key
  • .identity() - Auto-generate identity value
  • .distinct() - Ensure unique values
  • .default(value) - Default value
  • .optional() - Make optional
  • .nullable() - Allow null
  • .index() - Create index for querying
  • .tracked() - Track changes to this property

Schema Modifiers:

  • .modify(w => ({ ... })) - Add computed/function properties
  • .compile() - Compile schema to use with collections

Type Utilities:

  • InferType<typeof schema> - Extract entity type from schema
  • InferCreateType<typeof schema> - Extract creation type (excludes identities/defaults)

Query API

Filtering:

collection.where((entity) => entity.field === value);
collection.where(([entity, params]) => entity.field === params.value, {
  value,
});

Sorting:

collection.sort((entity) => entity.field);
collection.sortDescending((entity) => entity.field);

Pagination:

collection.skip(10).take(20);

Terminal Operations:

await collection.toArrayAsync();
await collection.firstAsync();
collection.subscribe().toArray(callback);

@routier/react

React integration hooks for Routier.

useQuery

React hook for subscribing to live queries.

Import:

import { useQuery } from "@routier/react";

Signature:

function useQuery<T>(
  query: (callback: (result: ResultType<T>) => void) => void | (() => void),
  deps: any[] = []
): LiveQueryState<T>;

Return Type:

type LiveQueryState<T> =
  | { status: "pending"; loading: true; error: null; data: undefined }
  | { status: "error"; loading: false; error: Error; data: undefined }
  | { status: "success"; loading: false; error: null; data: T };

Usage:

const products = useQuery(
  c => dataStore.products.subscribe().toArray(c),
  [dataStore]
);

if (products.status === "loading") return <div>Loading...</div>;
if (products.status === "error") return <div>Error: {products.error.message}</div>;
return <div>{products.data.map(...)}</div>;

Core Utilities

Results (@routier/core/results)

  • Result.SUCCESS - Success result code
  • Result.ERROR - Error result code
  • Result.success<T>(data) - Create success result
  • Result.error(error) - Create error result

Plugins (@routier/core/plugins)

  • IDbPlugin - Interface for database plugins
  • QueryOptionsCollection<T> - Query options configuration

Detailed API Reference

Complete auto-generated API documentation with full type signatures, method parameters, return types, and detailed descriptions is available:

Key API Classes

@routier/datastore:

  • DataStore - Main data store class
  • Collection - Collection class with query and CRUD operations

@routier/core:

@routier/react:

  • useQuery - React hook for live queries