reflectdb 0.1.0

package/dist/cjs/core/index.d.cts

@@ -0,0 +1,473 @@
+interface HLC {
+	ms: number;
+	counter: number;
+	nodeId: string;
+}
+declare function createHlc(nodeId: string): HLC;
+declare function sendHlc(local: HLC): HLC;
+declare function receiveHlc(local: HLC, remote: HLC): HLC;
+declare function packHlc(hlc: HLC): string;
+declare function unpackHlc(packed: string): HLC;
+declare function compareHlc(a: string, b: string): number;
+type OpType = "insert" | "update" | "delete";
+type OpStatus = "pending" | "synced" | "rejected";
+interface SyncOp {
+	id: string;
+	nodeId: string;
+	userId: string;
+	hlc: string;
+	op: OpType;
+	tableName: string;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	status: OpStatus;
+	rejectedReason: ErrorReason | null;
+	batchId: string | null;
+	batchSize: number | null;
+	batchSeq: number | null;
+}
+/**
+* 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 SyncError {
+	table: string;
+	op: SyncOp;
+	reason: ErrorReason;
+	serverRow: Record<string, unknown> | null;
+}
+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;
+type SyncMessage = ClientMessage | ServerMessage;
+/**
+* Thrown/rejected by a `ServerTransport.send` that could not hand the frame to
+* the peer (socket gone, not OPEN, queue overflow, backpressure limit).
+*
+* The broadcast engine treats a resolved `send` as "this delta reached the
+* client" and only then commits the per-client result cache. A transport that
+* swallows failures therefore makes the server believe a client holds rows it
+* never received — divergence that persists until reconnect. Report failures.
+*/
+declare class TransportSendError extends Error {
+	clientId: string;
+	cause?: unknown;
+	constructor(clientId: string, message: string, cause?: unknown);
+}
+interface ServerTransport {
+	/**
+	* Deliver a message to one client.
+	*
+	* MUST reject (ideally with `TransportSendError`) when the frame could not
+	* be handed to the peer — unknown/closed socket, full outbound queue, or a
+	* throw from the underlying socket. Resolving on a dropped frame makes the
+	* broadcast engine commit result-cache state the client never received.
+	*/
+	send(clientId: string, message: ServerMessage): Promise<void>;
+	broadcast(roomId: string, message: ServerMessage, exclude?: string): Promise<void>;
+	onMessage(handler: (clientId: string, message: ClientMessage) => void): void;
+	onConnect(handler: (clientId: string, req: Request) => void): void;
+	onDisconnect(handler: (clientId: string) => void): void;
+	close(): Promise<void>;
+	/**
+	* Force-disconnect a single client. Optional — if absent, the handler relies
+	* on the client honoring a `disconnect` server-message. Required for any
+	* transport that carries authentication state, since an adversarial client
+	* can otherwise ignore the message and continue using a revoked session.
+	*/
+	disconnect?(clientId: string): Promise<void> | void;
+}
+interface ClientTransport {
+	send(message: ClientMessage): Promise<void>;
+	subscribe(handler: (message: ServerMessage) => void): void;
+	close(): Promise<void>;
+}
+declare const PROTOCOL_VERSION: number;
+/** Versions this peer can speak, highest first. Server picks the highest shared version. */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly number[];
+declare const MAX_CLOCK_DRIFT_MS: number;
+declare const MAX_BATCH_SIZE: number;
+declare const TOMBSTONE_RETENTION_MS: number;
+declare const SERVER_TOMBSTONE_RETENTION_MS: number;
+type Dialect = "postgresql" | "mysql" | "sqlite";
+interface ShapeConfig {
+	filter?: unknown;
+	serverSet?: Record<string, unknown>;
+	readonly?: string[];
+	conflict?: ConflictPolicy;
+}
+interface RateLimitConfig {
+	opsPerSecond?: number;
+	opsPerMinute?: number;
+	batchesPerMinute?: number;
+	/**
+	* Per-table overrides. Applied in addition to the global limit: a write
+	* must pass both. Tables missing from this map inherit only the global
+	* bucket. Use to tighten write pressure on hot tables (e.g. ephemeral
+	* chat) without punishing cold ones.
+	*/
+	perTable?: Record<string, {
+		opsPerSecond?: number;
+		opsPerMinute?: number;
+	}>;
+	/**
+	* Ceiling on ephemeral (presence/cursor) messages per client per second.
+	* Metered separately from writes so presence traffic and the write budget
+	* don't starve each other. Defaults to 60; 0 disables metering entirely
+	* (each ephemeral message fans out to every room subscriber, so an
+	* unmetered channel is an amplification vector).
+	*/
+	ephemeralPerSecond?: number;
+}
+interface CompactionConfig {
+	clientInactivityTimeout: string;
+	interval: string;
+	minOpAge: string;
+}
+interface AuthContext {
+	userId: string;
+	[key: string]: unknown;
+}
+declare class MutationError extends Error {
+	reason: ErrorReason;
+	constructor(reason: ErrorReason, message?: string);
+}
+declare function isErrorReason(value: unknown): value is ErrorReason;
+/** Safely extract an ErrorReason from an unknown thrown value. Falls back to
+*  "server_error" for non-MutationError throws or invalid reason strings. */
+declare function reasonFromError(err: unknown): ErrorReason;
+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[];
+}
+declare function view<
+	TRow extends object,
+	TParams extends Record<string, unknown> | undefined = undefined
+>(opts: {
+	row?: TRow;
+	params?: TParams;
+	deps?: string[];
+	tables?: string[];
+}): SyncViewDef & {
+	row?: TRow;
+	params?: TParams;
+};
+/**
+* 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;
+}
+declare function presence<
+	TState extends object,
+	TParams extends Record<string, unknown> | undefined = undefined
+>(opts: {
+	state?: TState;
+	params?: TParams;
+	ttlMs?: number;
+}): SyncPresenceDef & {
+	state?: TState;
+	params?: TParams;
+};
+type SyncQueryEntry = SyncQueryDef | SyncViewDef | SyncPresenceDef;
+type SyncQueryMap = Record<string, SyncQueryEntry>;
+/** Extract column names from a query definition's table or row type */
+type ColumnOf<TDef> = TDef extends {
+	table: DrizzleTableLike;
+} ? keyof TDef["table"]["$inferSelect"] & string : TDef extends {
+	row: infer R extends Record<string, unknown>;
+} ? keyof R & string : string;
+/** Constrain serverSet and readonly to valid column names. Accepts either array or object form for serverSet. View/presence entries don't have these fields, so the constraint is empty. */
+type FieldsConstraint<TDef> = TDef extends {
+	__view: true;
+} | {
+	__presence: true;
+} ? Record<string, never> : {
+	serverSet?: readonly ColumnOf<TDef>[] | Readonly<Partial<Record<ColumnOf<TDef>, ServerSetSchemaValue>>>;
+	readonly?: readonly ColumnOf<TDef>[];
+};
+declare function defineSyncQueries<const T extends SyncQueryMap>(queries: T & { [K in keyof T] : FieldsConstraint<T[K]> }): T;
+/** Phantom type helper — passes a type without needing a real value or `as` cast */
+declare function t<T>(): T;
+/** 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>;
+/** Presence state type — typed shape passed to/received from `usePresence`. */
+type InferState<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	state: infer S extends Record<string, unknown>;
+} ? S : 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]>>;
+export { view, unpackHlc, t, sendHlc, receiveHlc, reasonFromError, presence, packHlc, isErrorReason, defineSyncQueries, createHlc, compareHlc, UnsyncMessage, TransportSendError, TableMeta, TOMBSTONE_RETENTION_MS, SyncViewDef, SyncQueryMap, SyncQueryEntry, SyncQueryDef, SyncPresenceDef, SyncOp, SyncMessage, SyncError, SyncDeclareMessage, SnapshotMessage, ShapeConfig, ShapeChangedMessage, ServerTransport, ServerMessage, SUPPORTED_PROTOCOL_VERSIONS, SERVER_TOMBSTONE_RETENTION_MS, ResumeRejectedMessage, ResumeMessage, ResumeCompleteMessage, RequiresParams, RejectMessage, ReauthMessage, RateLimitConfig, PROTOCOL_VERSION, OpsMessage, OpType, OpStatus, MutationError, MAX_CLOCK_DRIFT_MS, MAX_BATCH_SIZE, LoadMoreMessage, InferWritableRow, InferState, InferRow, InferParams, HelloRejectMessage, HelloMessage, HelloAckMessage, HLC, ErrorReason, EphemeralMessage, EphemeralEvent, DrizzleTableLike, DisconnectMessage, Dialect, DeltaMessage, CustomConflictPolicy, CountChangedMessage, ConflictResolver, ConflictPolicy, CompactionConfig, ClientTransport, ClientOp, ClientMessage, BootstrapMessage, BootstrapCompleteMessage, AuthMessage, AuthContext, AckMessage };