@datafn/client 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+import { DatafnEvent, DatafnSignal, DatafnSchema, DatafnPlugin, DatafnErrorCode } from '@datafn/core';
+
+/**
+ * Event filtering logic
+ */
+
+interface EventFilter {
+    type?: string | string[];
+    resource?: string | string[];
+    ids?: string | string[];
+    mutationId?: string | string[];
+    action?: string | string[];
+    fields?: string | string[];
+    contextKeys?: string[];
+}
+/**
+ * Check if an event matches the filter
+ */
+declare function matchesFilter(event: DatafnEvent, filter?: EventFilter): boolean;
+
+/**
+ * In-process event bus
+ */
+
+type EventHandler = (event: DatafnEvent) => void;
+/**
+ * Simple in-process event bus
+ */
+declare class EventBus {
+    private subscriptions;
+    private nextId;
+    /**
+     * Subscribe to events with optional filtering
+     */
+    subscribe(handler: EventHandler, filter?: EventFilter): () => void;
+    /**
+     * Emit an event to all matching subscribers
+     */
+    emit(event: DatafnEvent): void;
+}
+
+/**
+ * DataFn Table Handle
+ *
+ * Represents a table/resource from the schema with methods for query, mutation, signals, and subscriptions.
+ */
+
+interface DatafnTable<TRecord = unknown> {
+    name: string;
+    version: number;
+    query(q: unknown): Promise<unknown>;
+    mutate(m: unknown): Promise<unknown>;
+    transact(payload: unknown): Promise<unknown>;
+    signal(q: unknown): DatafnSignal<unknown>;
+    subscribe(handler: EventHandler, filter?: EventFilter): () => void;
+}
+
+/**
+ * Storage adapter types for local persistence
+ */
+type DatafnHydrationState = "notStarted" | "hydrating" | "ready";
+type DatafnChangelogEntry = {
+    /** Monotonic local sequence (assigned by storage adapter). */
+    seq: number;
+    clientId: string;
+    mutationId: string;
+    mutation: Record<string, unknown>;
+    timestampMs: number;
+};
+interface DatafnStorageAdapter {
+    getRecord(resource: string, id: string): Promise<Record<string, unknown> | null>;
+    listRecords(resource: string): Promise<Record<string, unknown>[]>;
+    upsertRecord(resource: string, record: Record<string, unknown>): Promise<void>;
+    deleteRecord(resource: string, id: string): Promise<void>;
+    listJoinRows(relationKey: string): Promise<Array<Record<string, unknown>>>;
+    upsertJoinRow(relationKey: string, row: Record<string, unknown>): Promise<void>;
+    deleteJoinRow(relationKey: string, from: string, to: string): Promise<void>;
+    getCursor(resource: string): Promise<string | null>;
+    setCursor(resource: string, cursor: string): Promise<void>;
+    getHydrationState(resource: string): Promise<DatafnHydrationState>;
+    setHydrationState(resource: string, state: DatafnHydrationState): Promise<void>;
+    changelogAppend(entry: Omit<DatafnChangelogEntry, "seq">): Promise<DatafnChangelogEntry>;
+    changelogList(options?: {
+        limit?: number;
+    }): Promise<DatafnChangelogEntry[]>;
+    changelogAck(options: {
+        throughSeq: number;
+    }): Promise<void>;
+}
+
+/**
+ * Sync Facade
+ *
+ * Client-side sync methods that delegate to remote adapter.
+ * When storage is configured, clone/pull results are applied to local storage.
+ */
+
+interface SyncFacade {
+    seed(payload: unknown): Promise<unknown>;
+    clone(payload: unknown): Promise<unknown>;
+    pull(payload: unknown): Promise<unknown>;
+    push(payload: unknown): Promise<unknown>;
+}
+
+/**
+ * DataFn client factory
+ */
+
+interface DatafnRemoteAdapter {
+    query(q: unknown): Promise<unknown>;
+    mutation(m: unknown): Promise<unknown>;
+    transact(t: unknown): Promise<unknown>;
+    seed(payload: unknown): Promise<unknown>;
+    clone(payload: unknown): Promise<unknown>;
+    pull(payload: unknown): Promise<unknown>;
+    push(payload: unknown): Promise<unknown>;
+}
+interface DatafnClientConfig {
+    schema: DatafnSchema;
+    remote: DatafnRemoteAdapter;
+    /**
+     * Optional plugins for client-side hook execution
+     */
+    plugins?: DatafnPlugin[];
+    /**
+     * Stable client/device identifier used for idempotency and offline change logs.
+     * Required when `storage` is provided.
+     */
+    clientId?: string;
+    /**
+     * Local persistence adapter. When provided, sync results are applied to local storage.
+     */
+    storage?: DatafnStorageAdapter;
+    getTimestamp?: () => number;
+}
+interface DatafnClient {
+    table<TRecord = unknown>(name: string): DatafnTable<TRecord>;
+    query(q: unknown | unknown[]): Promise<unknown>;
+    mutate(mutation: unknown | unknown[]): Promise<unknown>;
+    transact(payload: unknown): Promise<unknown>;
+    subscribe(handler: EventHandler, filter?: EventFilter): () => void;
+    sync: SyncFacade;
+}
+/**
+ * Create a DataFn client
+ */
+declare function createDatafnClient(config: DatafnClientConfig): DatafnClient;
+
+/**
+ * DataFn Client Error Types
+ */
+
+type DatafnClientError = {
+    code: DatafnErrorCode | "TRANSPORT_ERROR";
+    message: string;
+    details: {
+        path: string;
+        [key: string]: unknown;
+    };
+};
+/**
+ * Create a DataFnClientError and throw it
+ */
+declare function createClientError(code: DatafnClientError["code"], message: string, details: {
+    path: string;
+    [key: string]: unknown;
+}): never;
+
+/**
+ * Remote Response Unwrapping Utilities
+ *
+ * Handles both wrapped (DatafnEnvelope) and unwrapped server responses.
+ */
+/**
+ * Unwrap a remote response that may be wrapped in DatafnEnvelope or unwrapped.
+ *
+ * - If wrapped success `{ ok: true, result }`, return `result`
+ * - If wrapped error `{ ok: false, error }`, throw DatafnClientError
+ * - If unwrapped query result `{ data, nextCursor }`, return as-is
+ * - If unwrapped aggregate result `{ groups, nextCursor }`, return as-is
+ * - Otherwise throw TRANSPORT_ERROR
+ */
+declare function unwrapRemoteSuccess<T>(response: unknown): T;
+
+/**
+ * In-memory storage adapter for testing and development.
+ * Implements deterministic ordering and changelog deduplication.
+ */
+
+declare class MemoryStorageAdapter implements DatafnStorageAdapter {
+    private records;
+    private joinRows;
+    private cursors;
+    private hydration;
+    private changelog;
+    private changelogSeq;
+    constructor();
+    getRecord(resource: string, id: string): Promise<Record<string, unknown> | null>;
+    listRecords(resource: string): Promise<Record<string, unknown>[]>;
+    upsertRecord(resource: string, record: Record<string, unknown>): Promise<void>;
+    deleteRecord(resource: string, id: string): Promise<void>;
+    listJoinRows(relationKey: string): Promise<Array<Record<string, unknown>>>;
+    upsertJoinRow(relationKey: string, row: Record<string, unknown>): Promise<void>;
+    deleteJoinRow(relationKey: string, from: string, to: string): Promise<void>;
+    getCursor(resource: string): Promise<string | null>;
+    setCursor(resource: string, cursor: string): Promise<void>;
+    getHydrationState(resource: string): Promise<DatafnHydrationState>;
+    setHydrationState(resource: string, state: DatafnHydrationState): Promise<void>;
+    changelogAppend(entry: Omit<DatafnChangelogEntry, "seq">): Promise<DatafnChangelogEntry>;
+    changelogList(options?: {
+        limit?: number;
+    }): Promise<DatafnChangelogEntry[]>;
+    changelogAck(options: {
+        throughSeq: number;
+    }): Promise<void>;
+    clear(): void;
+}
+
+/**
+ * IndexedDB storage adapter for persistent client storage.
+ * Implements deterministic ordering and changelog deduplication.
+ */
+
+declare class IndexedDbStorageAdapter implements DatafnStorageAdapter {
+    private dbPromise;
+    constructor(dbName?: string);
+    private getStore;
+    getRecord(resource: string, id: string): Promise<Record<string, unknown> | null>;
+    listRecords(resource: string): Promise<Record<string, unknown>[]>;
+    upsertRecord(resource: string, record: Record<string, unknown>): Promise<void>;
+    deleteRecord(resource: string, id: string): Promise<void>;
+    listJoinRows(relationKey: string): Promise<Array<Record<string, unknown>>>;
+    upsertJoinRow(relationKey: string, row: Record<string, unknown>): Promise<void>;
+    deleteJoinRow(relationKey: string, from: string, to: string): Promise<void>;
+    getCursor(resource: string): Promise<string | null>;
+    setCursor(resource: string, cursor: string): Promise<void>;
+    getHydrationState(resource: string): Promise<DatafnHydrationState>;
+    setHydrationState(resource: string, state: DatafnHydrationState): Promise<void>;
+    changelogAppend(entry: Omit<DatafnChangelogEntry, "seq">): Promise<DatafnChangelogEntry>;
+    changelogList(options?: {
+        limit?: number;
+    }): Promise<DatafnChangelogEntry[]>;
+    changelogAck(options: {
+        throughSeq: number;
+    }): Promise<void>;
+}
+
+export { type DatafnChangelogEntry, type DatafnClient, type DatafnClientConfig, type DatafnClientError, type DatafnHydrationState, type DatafnRemoteAdapter, type DatafnStorageAdapter, type DatafnTable, EventBus, type EventFilter, type EventHandler, IndexedDbStorageAdapter, MemoryStorageAdapter, createClientError, createDatafnClient, matchesFilter, unwrapRemoteSuccess };