module@warp-drive/core

WarpDrive is the lightweight data library for web apps: universal, typed, reactive, and ready to scale. This package is its core: the Store that holds your data, the RequestManager that fetches it through a chain of handlers (each a function or object that can fulfill, modify, or pass along a request), the Cache interface a cache implementation fills in, and the reactive objects that present cached data to your UI.

New here?

Start with the Installation and Setup guides. The API docs assume that context.

How the Pieces Connect

Your app talks to the Store. The Store keeps resource data in the Cache and hands requests to the RequestManager, whose handlers fetch data from a source such as your API or a local persistence layer.

The Store also presents cached data to your app as reactive records. It creates each record with its instantiateRecord hook; the Store that useRecommendedStore produces presents every resource as a ReactiveResource.

Setup

useRecommendedStore produces a Store class with the recommended defaults for schema handling, reactivity, caching, and request management, including a RequestManager already wired with Fetch and CacheHandler. Pair it with a cache implementation; most apps should use @warp-drive/json-api.

import { useRecommendedStore } from '@warp-drive/core';
import { JSONAPICache } from '@warp-drive/json-api';

export const AppStore = useRecommendedStore({
  cache: JSONAPICache,
  schemas: [
    // one schema per resource type, see /guides/the-manual/schemas/
  ],
});

AppStore is a class. The Setup guide shows how each framework instantiates it and makes it available to components, and how to configure the build plugin every WarpDrive app needs. Schemas describe the shape of your resources; the Schemas guide covers writing them.

Entry Points

• @warp-drive/core: the Store, RequestManager, the Fetch handler that performs the network request and the CacheHandler that reads and writes the cache, and useRecommendedStore.
• @warp-drive/core/request: request and handler primitives, such as withResponseType.
• @warp-drive/core/reactive: the reactive objects a Store uses to present requests, resources, and relationships from the cache.
• @warp-drive/core/store: the pieces for customizing a Store beyond the recommended defaults, such as the cache policy that decides when cached data is stale.
• @warp-drive/core/types: the types, type utilities, symbols and constants shared across the WarpDrive ecosystem, including the Cache interface.
• @warp-drive/core/build-config: the build plugin that configures deprecations, optional features, and debug logging.
• @warp-drive/core/configure: the API for telling WarpDrive which framework's reactivity system to use.

Guides

• Installation: install @warp-drive/core, a cache and the reactivity package for your framework.
• Setup: configure the build plugin and create a Store with useRecommendedStore.
• Advanced Store Configuration: build a Store class by hand, one piece at a time.
• Making Requests: store.request, request options and the handler chain.
• Builders: functions that return a request and a stable cache key.
• Handlers: write a handler that transforms a response.
• Auth Handler: add JWT or CSRF tokens to outgoing requests with a handler.
• Typing Requests: withResponseType and withReactiveResponse.
• Using the Response: the Future a request returns, its errors and its content.
• Schemas: how a schema turns cached data into reactive properties.
• ResourceSchemas: define a resource with withDefaults, choose its field kinds and register it.
• SimpleFields: declare primitive attributes as field kinds.
• Complex Fields: embed nested objects and lists with schema-object and schema-array fields.
• ObjectSchemas: define the identity-less schema a schema-object field points at.
• Traits: share a group of fields across resources.
• Transformations: convert a field between its cache and app shapes.
• Derivations: define memoized, read-only derived fields.
• Caching: how the CacheHandler and the cache policy decide what to fetch and what to keep.
• Key Terminology: documents, resources and the names of their types.
• Reactivity: how WarpDrive uses signals to notify your UI.
• Reactive Control Flow: render a request's states with getRequestState.
• Async as Reactive State: derive a promise's state with getPromiseState.
• Relationships: configure each kind of relationship.
• Debugging: turn on debug logging at runtime or in the build config.
• TypeScript: opt in to the alpha types, then follow the setup pages in order.

Classes

• ConfiguredStore
• RequestManager
• Store

Variables

• CacheHandler
• Fetch

Functions

cacheKeyFor

Renames and re-exports recordIdentifierFor

Types

• CachePolicy
• StoreRequestContext
• StoreSetupOptions
• CacheOperation
• Document
• DocumentCacheOperation
• NotificationChannel
• NotificationType
• NotifyKeys
• StoreRequestInput