trellis
Version:
Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications
67 lines • 3.12 kB
TypeScript
/**
* Trellis Live Reads — Signal-first reactive queries.
*
* `liveQuery` is the framework-agnostic read primitive: it returns a {@link Signal}
* of read-state that the React/Vue/Svelte adapters all wrap, so the subscription
* is implemented once. It is lazy — `start()` opens the underlying source and
* returns a disposer — which lets adapters bind start/stop to component lifetime
* without side effects during render.
*
* Source today: the remote WebSocket subscription (`TrellisDb.subscribe`). The
* local embedded-kernel path is NOT live yet (`subscribe()` throws in local mode);
* a kernel op-stream source is the seam for that and is surfaced here as an error
* state rather than a throw.
*
* @module trellis/client
*/
import { Signal } from './reactive.js';
import { type WhereInput } from '../schema/eql.js';
import { type ResolveSpec } from '../schema/resolve.js';
import type { AnyType } from '../schema/define.js';
import type { EntityData, TrellisDb } from './sdk.js';
export interface ReadState<T> {
data: T;
loading: boolean;
error: Error | null;
}
export interface LiveResource<T> {
/** Reactive read-state. Subscribe via any framework adapter (or `.subscribe`). */
readonly signal: Signal<ReadState<T>>;
/** Open the subscription. Idempotent. Returns a disposer. */
start(): () => void;
}
/**
* Subscribe to a live EQL-S query as a {@link Signal}. The returned resource is
* inert until `start()` is called.
*/
export declare function liveQuery<T = Record<string, unknown>>(client: TrellisDb, eql: string): LiveResource<T[]>;
export interface LiveEntitiesOptions {
where?: WhereInput;
/** Expand declared relations after hydration (requires `schema`). */
resolve?: ResolveSpec;
}
export interface LiveEntityOptions {
/** Expand declared relations on the loaded row (requires `schema`). */
resolve?: ResolveSpec;
}
/**
* Live, *hydrated* entity list for a type.
*
* Remote subscriptions are server-hydrated to full entity records when possible.
* When `resolve` is set, the server expands relations on the wire (TRL-6) and
* the client skips a second resolve pass. Stale hydrations are dropped if a
* newer push arrives first.
*
* Pass a {@link AnyType} schema (or `resolve` in options) to expand relations
* in one batched pass — e.g. `NavSection` with `{ resolve: { items: true } }`
* loads all `NavItem` rows grouped by `section`, avoiding per-parent reads.
*/
export declare function liveEntities<T extends EntityData = EntityData>(client: TrellisDb, typeOrSchema: string | AnyType, whereOrOpts?: Record<string, unknown> | LiveEntitiesOptions): LiveResource<T[]>;
/**
* Live single entity by id (TRL-9).
*
* Opens with a direct `read(id)` for fast first paint, then keeps the row fresh
* via an id-scoped subscription ({@link entityQuery}) — not a full-type scan.
*/
export declare function liveEntity<T extends EntityData = EntityData>(client: TrellisDb, typeOrSchema: string | AnyType, id: string | null | undefined, opts?: LiveEntityOptions): LiveResource<T | null>;
//# sourceMappingURL=live.d.ts.map