reflectdb 0.1.0

package/dist/svelte/index.d.ts

@@ -0,0 +1,645 @@
+type OpType = "insert" | "update" | "delete";
+type OpStatus = "pending" | "synced" | "rejected";
+/**
+* Server-side conflict policy for concurrent writes to the same row.
+*
+* Scope note for `"merge"`: the server resolves per column using the **client
+* op HLCs** recorded in reflectdb's mirror, so two clients editing different
+* fields both land. The per-column clocks the client sees on a broadcast are a
+* different domain — a diff-driven broadcast can't attribute a column to the
+* op that produced it, so every column changed in one broadcast carries that
+* broadcast's HLC. Client-side merge therefore orders *broadcasts* against each
+* other and against local optimistic state; it does not reconstruct per-column
+* causality between clients. Column-level convergence is a server guarantee.
+*/
+type ConflictPolicy = "lww" | "merge" | "server" | CustomConflictPolicy;
+interface CustomConflictPolicy {
+	policy: "custom";
+	resolve: ConflictResolver;
+}
+interface ConflictResolver {
+	(incoming: {
+		op: OpType;
+		payload: Record<string, unknown> | null;
+		hlc: string;
+	}, existing: {
+		row: Record<string, unknown>;
+		colClocks: Record<string, string>;
+	}, meta: {
+		table: string;
+		rowId: string;
+		userId: string;
+	}): {
+		row: Record<string, unknown>;
+	};
+}
+type ErrorReason = "outside_shape" | "readonly_query" | "rate_limited" | "buffer_full" | "server_conflict" | "custom_conflict" | "merge_stale" | "clock_drift" | "replay" | "batch_too_large" | "schema_outdated" | "auth_revoked" | "compacted" | "mutation_rejected" | "server_error" | "unknown_query";
+interface HelloMessage {
+	type: "hello";
+	/** Highest protocol version the client prefers. Retained for back-compat. */
+	protocolVersion: number;
+	/** All versions the client can speak. Omit for legacy single-version clients. */
+	supportedVersions?: readonly number[];
+	clientId: string;
+	token: string;
+}
+interface BootstrapMessage {
+	type: "bootstrap";
+	syncParams?: Record<string, Record<string, unknown>>;
+}
+interface ResumeMessage {
+	type: "resume";
+	since: string;
+}
+interface OpsMessage {
+	type: "ops";
+	ops: ClientOp[];
+	token: string;
+}
+interface ClientOp {
+	id: string;
+	table: string;
+	op: OpType;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	batchId?: string;
+	batchSize?: number;
+	batchSeq?: number;
+}
+interface SyncDeclareMessage {
+	type: "sync_declare";
+	table: string;
+	params?: Record<string, unknown>;
+	window?: number;
+}
+interface LoadMoreMessage {
+	type: "load_more";
+	table: string;
+	count: number;
+}
+interface UnsyncMessage {
+	type: "unsync";
+	table: string;
+}
+interface AuthMessage {
+	type: "auth";
+	token: string;
+}
+interface EphemeralMessage {
+	type: "ephemeral";
+	key: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+}
+interface HelloAckMessage {
+	type: "hello_ack";
+	protocolVersion: number;
+	serverId: string;
+}
+interface HelloRejectMessage {
+	type: "hello_reject";
+	reason: string;
+	supported: number[];
+}
+interface SnapshotMessage {
+	type: "snapshot";
+	table: string;
+	rows: Record<string, unknown>[];
+	colClocks: Record<string, Record<string, string>>;
+	append?: boolean;
+	totalCount?: number;
+	/**
+	* Primary key column name for this table. Self-contained per message so the
+	* client doesn't depend on `bootstrap_complete.tableMeta` arriving first.
+	* When omitted (older servers), the client falls back to tableMeta, then "id".
+	*/
+	pk?: string;
+}
+interface BootstrapCompleteMessage {
+	type: "bootstrap_complete";
+	serverHlc: string;
+	tableMeta: Record<string, TableMeta>;
+}
+interface TableMeta {
+	serverSet: string[];
+	readonly: string[];
+	broadcast: "consistent" | "eager" | "eager-durable";
+	/** Primary key column name. Defaults to "id" when omitted (older servers). */
+	pk?: string;
+}
+interface DeltaMessage {
+	type: "delta";
+	table: string;
+	op: OpType;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	colClocks?: Record<string, string>;
+}
+interface AckMessage {
+	type: "ack";
+	opIds: string[];
+}
+interface RejectMessage {
+	type: "reject";
+	opId?: string;
+	batchId?: string;
+	reason: ErrorReason;
+	serverRow?: Record<string, unknown>;
+}
+interface ResumeCompleteMessage {
+	type: "resume_complete";
+	serverHlc: string;
+}
+interface ResumeRejectedMessage {
+	type: "resume_rejected";
+	reason: string;
+	serverHlc: string;
+}
+interface ShapeChangedMessage {
+	type: "shape_changed";
+	table: string;
+	reason: "auth_changed" | "params_changed" | "server_policy";
+}
+interface DisconnectMessage {
+	type: "disconnect";
+	reason: string;
+}
+interface ReauthMessage {
+	type: "reauth";
+}
+interface CountChangedMessage {
+	type: "count_changed";
+	table: string;
+	totalCount: number;
+}
+interface EphemeralEvent {
+	type: "ephemeral";
+	key: string;
+	clientId: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+}
+type ClientMessage = HelloMessage | BootstrapMessage | ResumeMessage | OpsMessage | SyncDeclareMessage | LoadMoreMessage | UnsyncMessage | AuthMessage | EphemeralMessage;
+type ServerMessage = HelloAckMessage | HelloRejectMessage | SnapshotMessage | BootstrapCompleteMessage | DeltaMessage | AckMessage | RejectMessage | ResumeCompleteMessage | ResumeRejectedMessage | ShapeChangedMessage | DisconnectMessage | ReauthMessage | EphemeralEvent | CountChangedMessage;
+interface ClientTransport {
+	send(message: ClientMessage): Promise<void>;
+	subscribe(handler: (message: ServerMessage) => void): void;
+	close(): Promise<void>;
+}
+interface ClientStorageAdapter {
+	getRows(table: string): Promise<LocalRow[]>;
+	getAllRows(): Promise<LocalRow[]>;
+	putRow(table: string, rowId: string, row: LocalRow): Promise<void>;
+	deleteRow(table: string, rowId: string): Promise<void>;
+	clearTable(table: string): Promise<void>;
+	getPendingOps(): Promise<PendingOp[]>;
+	putPendingOps(ops: PendingOp[]): Promise<void>;
+	appendPendingOps(ops: PendingOp[]): Promise<void>;
+	updatePendingOps(ops: PendingOp[]): Promise<void>;
+	removePendingOps(opIds: string[]): Promise<void>;
+	clearPendingOps(): Promise<void>;
+	getMeta(key: string): Promise<string | null>;
+	setMeta(key: string, value: string): Promise<void>;
+	deleteMeta(key: string): Promise<void>;
+	clear(): Promise<void>;
+}
+interface PendingOp {
+	op: ClientOp;
+	status: OpStatus;
+	rejectedReason: ErrorReason | null;
+	createdAt: number;
+	/**
+	* Row state captured just before the optimistic apply. Restored on reject
+	* so a rejected optimistic insert collapses back to no-row (instead of
+	* leaving a tombstone), and a rejected update reverts to the merged row
+	* the client had before touching it.
+	*/
+	preState?: {
+		data: Record<string, unknown> | null;
+		colClocks: Record<string, string>;
+		serverHlc: string | null;
+	} | null;
+}
+interface LocalRow {
+	table: string;
+	rowId: string;
+	data: Record<string, unknown> | null;
+	colClocks: Record<string, string>;
+	serverHlc: string | null;
+}
+declare class ClientStore {
+	private pendingOps;
+	private rows;
+	private tableMeta;
+	private storage;
+	private pendingWrites;
+	private writeChain;
+	constructor(storage?: ClientStorageAdapter);
+	/**
+	* Load durable state into memory.
+	*
+	* @param options.tables — hydrate only these tables. Rows only ever reach
+	*   local storage through a subscription, so restoring just the tables the
+	*   client is actually subscribed to reads no less than it needs. Omit to
+	*   load every row of every table the client has ever synced.
+	*/
+	hydrate(options?: {
+		tables?: string[];
+	}): Promise<void>;
+	flush(): Promise<void>;
+	private enqueue;
+	addPendingOp(op: ClientOp): void;
+	getPendingOps(): PendingOp[];
+	markSynced(opIds: string[]): void;
+	markRejected(opId: string, reason: ErrorReason): void;
+	rejectBatch(batchId: string, reason: ErrorReason): void;
+	private autoTrimRejected;
+	clearRejected(): void;
+	setRow(table: string, rowId: string, data: Record<string, unknown> | null, colClocks: Record<string, string>, serverHlc: string | null): void;
+	getRow(table: string, rowId: string): LocalRow | undefined;
+	/** Internal: includes tombstones for HLC comparison in applyDelta. */
+	private getRowEntry;
+	getRows(table: string, includeDeleted?: boolean): LocalRow[];
+	clearTable(table: string): void;
+	applySnapshot(table: string, rows: Record<string, unknown>[], colClocks: Record<string, Record<string, string>>, append?: boolean, pk?: string): void;
+	applyDelta(table: string, op: string, rowId: string, payload: Record<string, unknown> | null, hlc: string, colClocks?: Record<string, string>): void;
+	revertOp(opId: string, serverRow: Record<string, unknown> | null | undefined): void;
+	setTableMeta(meta: Record<string, {
+		serverSet: string[];
+		readonly: string[];
+		broadcast?: "consistent" | "eager" | "eager-durable";
+		pk?: string;
+	}>): void;
+	getTableMeta(table: string): {
+		serverSet: string[];
+		readonly: string[];
+		broadcast: "consistent" | "eager" | "eager-durable";
+		pk: string;
+	} | undefined;
+	applyOptimistic(op: ClientOp): void;
+	clear(): Promise<void>;
+}
+interface SyncClientConfig {
+	clientId: string;
+	transport: ClientTransport;
+	token: string;
+	storage?: ClientStorageAdapter;
+	onSync?: (table: string) => void;
+	/**
+	* Structured error callback. `reason` is drawn from the protocol's
+	* ErrorReason taxonomy when the error originates server-side; local
+	* failures (reauth/transport) use a "local:*" namespace so consumers
+	* can switch on the string.
+	*/
+	onError?: (error: {
+		opId?: string;
+		batchId?: string;
+		table?: string;
+		reason: ErrorReason | `local:${string}`;
+		message?: string;
+	}) => void;
+	onReauth?: () => Promise<string>;
+	/** Max reconnect backoff in ms (before jitter). Default: 30_000. */
+	maxReconnectDelayMs?: number;
+	/**
+	* Load every stored row at boot instead of only the tables this client is
+	* subscribed to. Needed only if you read rows for a table before calling
+	* `sync()` on it. Default: false.
+	*/
+	hydrateAllTables?: boolean;
+}
+type SyncClientState = "hydrating" | "disconnected" | "connecting" | "connected" | "bootstrapping" | "synced";
+interface SyncOptions {
+	window?: number;
+}
+declare class SyncClient {
+	private config;
+	private transport;
+	private opCreator;
+	private store;
+	private state;
+	/** Version agreed on in hello_ack. Null until first successful handshake. */
+	private negotiatedProtocolVersion;
+	private syncedTables;
+	private serverHlc;
+	private listeners;
+	private version;
+	private tableVersions;
+	private tableListeners;
+	private connectResolve;
+	private connectReject;
+	private connectInFlight;
+	private ephemeralListeners;
+	private totalCounts;
+	private syncOptions;
+	private bootstrapScheduled;
+	private initialized;
+	private syncParams;
+	private reconnectTimer;
+	private reconnectAttempts;
+	private closed;
+	/**
+	* Ops already transmitted, mapped to when they were sent. Without this,
+	* every mutation re-sends the whole pending set: 50 rapid edits before the
+	* first ack land as 1+2+…+50 = 1275 ops on the wire, each one a `reserveOp`
+	* insert server-side. Cleared on disconnect so a reconnect resends them.
+	*/
+	private inFlightOps;
+	/**
+	* How long an op may sit unacked before a later push retries it. A frame can
+	* be dropped without the connection dying — a full server-side queue, for
+	* one — and without this the op would stay marked in-flight, never re-sent,
+	* until the connection happens to drop. Resends are idempotent server-side.
+	*/
+	private static readonly IN_FLIGHT_TTL_MS;
+	/** Tail of the serialized push chain; also the coalescing slot. */
+	private pushChain;
+	private pushPending;
+	constructor(config: SyncClientConfig);
+	init(): Promise<void>;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+	getState(): SyncClientState;
+	/** Version negotiated with the server. Null before the first hello_ack. */
+	getProtocolVersion(): number | null;
+	sync(table: string, params?: Record<string, unknown>, options?: SyncOptions): Promise<void>;
+	loadMore(table: string, count: number): Promise<void>;
+	getTotalCount(table: string): number | null;
+	unsync(table: string): Promise<void>;
+	bootstrap(): Promise<void>;
+	/**
+	* Schedule a bootstrap in the next microtask.
+	* Multiple calls within the same tick are coalesced into one bootstrap.
+	*/
+	scheduleBootstrap(): void;
+	resume(): Promise<void>;
+	insert(table: string, rowId: string, payload: Record<string, unknown>): ClientOp;
+	update(table: string, rowId: string, payload: Record<string, unknown>): ClientOp;
+	delete(table: string, rowId: string): ClientOp;
+	batch(ops: Array<{
+		table: string;
+		op: OpType;
+		rowId: string;
+		payload: Record<string, unknown> | null;
+	}>): ClientOp[];
+	/**
+	* Transmit pending ops.
+	*
+	* Concurrent calls are coalesced: at most one push runs and at most one
+	* more is queued behind it, so a burst of mutations (every `useSync`
+	* mutation calls this) produces one send per op rather than one send of
+	* everything pending per mutation. The returned promise resolves once the
+	* caller's own ops have been handed to the transport.
+	*/
+	push(): Promise<void>;
+	private doPush;
+	/** Forget which ops are on the wire — used when the connection drops. */
+	private clearInFlight;
+	sendEphemeral(params: {
+		key: string;
+		userId: string;
+		data: Record<string, unknown>;
+		ttlMs?: number;
+	}): Promise<void>;
+	subscribeEphemeral(key: string, listener: (event: EphemeralEvent) => void): () => void;
+	getRows(table: string, options?: {
+		includeDeleted?: boolean;
+	}): Record<string, unknown>[];
+	getRow(table: string, rowId: string): Record<string, unknown> | null;
+	getPendingCount(): number;
+	getStore(): ClientStore;
+	/**
+	* Subscribe to store changes. Returns an unsubscribe function.
+	* Compatible with React's useSyncExternalStore.
+	*/
+	subscribe(listener: () => void): () => void;
+	/**
+	* Subscribe to changes for a specific table. Returns an unsubscribe function.
+	* More efficient than subscribe() — only fires when the given table changes.
+	*/
+	subscribeTable(table: string, listener: () => void): () => void;
+	/** Returns a version number that increments on every data change. */
+	getVersion(): number;
+	/** Returns a version number for a specific table. Only increments when that table changes. */
+	getTableVersion(table: string): number;
+	private notify;
+	/**
+	* Reset client state. With no argument, wipes everything (pending ops,
+	* rows, server HLC, subscriptions). With `tables`, only those tables'
+	* rows + subscriptions are dropped — useful for logging out of a single
+	* scope or evicting a stale dataset without losing pending ops elsewhere.
+	*/
+	clear(opts?: {
+		tables?: string[];
+	}): Promise<void>;
+	private handleMessage;
+	private mergeServerHlc;
+	private persistMeta;
+	private persistSyncSubscriptions;
+	private handleReauth;
+	private scheduleReconnect;
+}
+interface Readable<T> {
+	subscribe(cb: (value: T) => void): () => void;
+}
+declare function createBrowserWsTransport(url: string): ClientTransport;
+interface SyncStoreConfig {
+	url: string;
+	token: string;
+	tables?: string[];
+	clientId?: string;
+	storage?: ClientStorageAdapter;
+	onReauth?: () => Promise<string>;
+	onError?: (error: {
+		opId?: string;
+		reason: string;
+	}) => void;
+}
+interface SyncStore {
+	client: SyncClient;
+	status: Readable<SyncClientState>;
+	pendingCount: Readable<number>;
+	sync<T extends object = Record<string, unknown>>(table: string, options?: {
+		params?: Record<string, unknown>;
+		includeDeleted?: boolean;
+		window?: number;
+	}): {
+		rows: Readable<T[]>;
+		insert: (rowId: string, payload: Partial<T>) => void;
+		update: (rowId: string, payload: Partial<T>) => void;
+		remove: (rowId: string) => void;
+	};
+	row<T extends object = Record<string, unknown>>(table: string, rowId: string): Readable<T | null>;
+	ephemeral<T extends object>(config: {
+		key: string;
+		userId: string;
+		ttlMs?: number;
+	}): {
+		events: Readable<Record<string, T>>;
+		broadcast: (data: T) => Promise<void>;
+		destroy: () => void;
+	};
+	totalCount(table: string): Readable<number | null>;
+	loadMore(table: string, count: number): void;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+}
+declare function createSyncStore(config: SyncStoreConfig): SyncStore;
+interface DrizzleTableLike {
+	$inferSelect: Record<string, unknown>;
+	$inferInsert: Record<string, unknown>;
+}
+/**
+* Value supplied per serverSet field in the schema's object form.
+* Either a static value or a function that receives the request context.
+*/
+type ServerSetSchemaValue = unknown | ((ctx: {
+	auth: unknown;
+	params: unknown;
+}) => unknown);
+/**
+* Schema-side `serverSet` declaration. Two shapes:
+*  - `string[]` — keys only; values are supplied at `implement(...)` time.
+*  - `Record<string, ServerSetSchemaValue>` — keys + values collocated in schema.
+*/
+type SchemaServerSet = readonly string[] | Readonly<Record<string, ServerSetSchemaValue>>;
+interface SyncQueryDef {
+	/** Drizzle table — row type derived from $inferSelect */
+	table?: DrizzleTableLike;
+	/** Phantom row type for non-drizzle usage: `{} as MyRow` */
+	row?: Record<string, unknown>;
+	/** Database tables for change detection. Falls back to query key name. */
+	tables?: string[];
+	/** Phantom value for params type: `{} as { orgId: string }` */
+	params?: Record<string, unknown>;
+	/** Primary key column name. Defaults to "id". Single-column only. */
+	pk?: string;
+	conflict?: ConflictPolicy;
+	readonly?: readonly string[];
+	serverSet?: SchemaServerSet;
+	countHints?: boolean;
+}
+/**
+* Read-only computed query. Compiles down to `server.query(...)` with a
+* throwing mutate so the type system blocks `useSync(...).insert/update/remove`
+* and the runtime rejects any direct write attempt.
+*/
+interface SyncViewDef {
+	__view: true;
+	row?: Record<string, unknown>;
+	params?: Record<string, unknown>;
+	tables?: string[];
+	/** Tables to watch for change-detection. Defaults to `tables` or query key. */
+	deps?: string[];
+}
+/**
+* Typed ephemeral channel. Sugar over the runtime `useEphemeral` hook —
+* derives a stable key from the schema name + serialized params and gives
+* `peers`/`set` a typed `state`.
+*/
+interface SyncPresenceDef {
+	__presence: true;
+	state?: Record<string, unknown>;
+	params?: Record<string, unknown>;
+	ttlMs?: number;
+}
+type SyncQueryEntry = SyncQueryDef | SyncViewDef | SyncPresenceDef;
+type SyncQueryMap = Record<string, SyncQueryEntry>;
+/** Row type: from `table.$inferSelect` if drizzle, otherwise from `row` phantom */
+type InferRow<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	table: DrizzleTableLike;
+} ? TQueries[K]["table"]["$inferSelect"] : TQueries[K] extends {
+	row: infer R extends Record<string, unknown>;
+} ? R : Record<string, unknown>;
+/** Params type. `undefined` when no params declared. */
+type InferParams<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	params: infer P extends Record<string, unknown>;
+} ? P : undefined;
+/** `true` when the query declares params */
+type RequiresParams<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	params: Record<string, unknown>;
+} ? true : false;
+/** Primary key column name. Defaults to "id". */
+type PkOf<TDef> = TDef extends {
+	pk: infer P extends string;
+} ? P : "id";
+/** Extract serverSet field names from either array form or object form. */
+type InferServerSetKeys<TDef> = TDef extends {
+	serverSet: readonly (infer S extends string)[];
+} ? S : TDef extends {
+	serverSet: infer O extends Readonly<Record<string, unknown>>;
+} ? keyof O & string : never;
+/**
+* Row minus readonly fields, serverSet fields, and the primary key.
+* View defs collapse to `never` to block client-side writes at the type level.
+* Presence defs aren't writable rows; they collapse to `never` too.
+*/
+type InferWritableRow<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	__view: true;
+} | {
+	__presence: true;
+} ? never : Omit<InferRow<TQueries, K>, (TQueries[K] extends {
+	readonly: readonly (infer R extends string)[];
+} ? R : never) | InferServerSetKeys<TQueries[K]> | PkOf<TQueries[K]>>;
+type SyncOptions2<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = RequiresParams<TQueries, K> extends true ? {
+	params: InferParams<TQueries, K>;
+	includeDeleted?: boolean;
+	window?: number;
+} : {
+	params?: undefined;
+	includeDeleted?: boolean;
+	window?: number;
+};
+interface SyncResult<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> {
+	rows: Readable<InferRow<TQueries, K>[]>;
+	insert: (rowId: string, payload: InferWritableRow<TQueries, K>) => void;
+	update: (rowId: string, payload: Partial<InferWritableRow<TQueries, K>>) => void;
+	remove: (rowId: string) => void;
+}
+interface TypedSyncStore<TQueries extends SyncQueryMap> {
+	client: SyncClient;
+	status: Readable<SyncClientState>;
+	pendingCount: Readable<number>;
+	sync<K extends keyof TQueries & string>(...args: RequiresParams<TQueries, K> extends true ? [table: K, options: SyncOptions2<TQueries, K>] : [table: K, options?: SyncOptions2<TQueries, K>]): SyncResult<TQueries, K>;
+	row<K extends keyof TQueries & string>(table: K, rowId: string): Readable<InferRow<TQueries, K> | null>;
+	ephemeral<T extends object>(config: {
+		key: string;
+		userId: string;
+		ttlMs?: number;
+	}): {
+		events: Readable<Record<string, T>>;
+		broadcast: (data: T) => Promise<void>;
+		destroy: () => void;
+	};
+	totalCount<K extends keyof TQueries & string>(table: K): Readable<number | null>;
+	loadMore<K extends keyof TQueries & string>(table: K, count: number): void;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+}
+interface SyncSvelteHooks<TQueries extends SyncQueryMap> {
+	createStore: (config: SyncStoreConfig) => TypedSyncStore<TQueries>;
+}
+declare function createSyncSvelte<TQueries extends SyncQueryMap>(): SyncSvelteHooks<TQueries>;
+export { createSyncSvelte, createSyncStore, createBrowserWsTransport, TypedSyncStore, SyncSvelteHooks, SyncStoreConfig, SyncStore, Readable };