lakesync 0.1.0

package/dist/proto.d.ts

@@ -0,0 +1,434 @@
+import { H as HLCTimestamp, R as Result } from './result-CojzlFE2.js';
+import { i as ActionPush$1, j as ActionResponse$1 } from './types-Bs-QyOe-.js';
+import { R as RowDelta$1 } from './types-V_jVu2sA.js';
+import { GenMessage, GenEnum } from '@bufbuild/protobuf/codegenv2';
+import { Message } from '@bufbuild/protobuf';
+
+/** Error returned when encoding or decoding a protobuf message fails. */
+declare class CodecError extends Error {
+    readonly code = "CODEC_ERROR";
+    constructor(message: string, cause?: Error);
+}
+/** Shape of a SyncPush payload using core domain types. */
+interface SyncPushPayload {
+    /** Client identifier. */
+    clientId: string;
+    /** Deltas to push to the server. */
+    deltas: RowDelta$1[];
+    /** Last HLC timestamp seen by the client. */
+    lastSeenHlc: HLCTimestamp;
+}
+/** Shape of a SyncPull request using core domain types. */
+interface SyncPullPayload {
+    /** Client identifier. */
+    clientId: string;
+    /** Request deltas since this HLC timestamp. */
+    sinceHlc: HLCTimestamp;
+    /** Maximum number of deltas to return. */
+    maxDeltas: number;
+}
+/** Shape of a SyncResponse using core domain types. */
+interface SyncResponsePayload {
+    /** Deltas returned by the server. */
+    deltas: RowDelta$1[];
+    /** Current server HLC timestamp. */
+    serverHlc: HLCTimestamp;
+    /** Whether more deltas are available. */
+    hasMore: boolean;
+}
+/** Tag byte for SyncPush frames. */
+declare const TAG_SYNC_PUSH = 1;
+/** Tag byte for SyncPull frames. */
+declare const TAG_SYNC_PULL = 2;
+/** Tag byte for server-initiated broadcast frames. */
+declare const TAG_BROADCAST = 3;
+/** Tag byte for ActionPush frames. */
+declare const TAG_ACTION_PUSH = 4;
+/** Tag byte for ActionResponse frames. */
+declare const TAG_ACTION_RESPONSE = 5;
+/**
+ * Encode a broadcast frame: tag `0x03` + SyncResponse proto bytes.
+ *
+ * Used by the server to push deltas to connected WebSocket clients.
+ *
+ * @param response - The SyncResponse payload to broadcast.
+ * @returns A `Result` containing the framed binary, or a `CodecError` on failure.
+ */
+declare function encodeBroadcastFrame(response: SyncResponsePayload): Result<Uint8Array, CodecError>;
+/**
+ * Decode a broadcast frame: strip tag `0x03` and decode the SyncResponse.
+ *
+ * @param frame - The full framed binary (tag byte + proto payload).
+ * @returns A `Result` containing the SyncResponse payload, or a `CodecError` on failure.
+ */
+declare function decodeBroadcastFrame(frame: Uint8Array): Result<SyncResponsePayload, CodecError>;
+/**
+ * Serialise a core RowDelta to protobuf binary.
+ *
+ * @param delta - The core RowDelta to serialise.
+ * @returns A `Result` containing the binary bytes, or a `CodecError` on failure.
+ */
+declare function encodeRowDelta(delta: RowDelta$1): Result<Uint8Array, CodecError>;
+/**
+ * Deserialise protobuf binary to a core RowDelta.
+ *
+ * @param bytes - The protobuf binary to deserialise.
+ * @returns A `Result` containing the core RowDelta, or a `CodecError` on failure.
+ */
+declare function decodeRowDelta(bytes: Uint8Array): Result<RowDelta$1, CodecError>;
+/**
+ * Serialise a SyncPush payload to protobuf binary.
+ *
+ * @param push - The SyncPush payload containing client ID, deltas, and last seen HLC.
+ * @returns A `Result` containing the binary bytes, or a `CodecError` on failure.
+ */
+declare function encodeSyncPush(push: SyncPushPayload): Result<Uint8Array, CodecError>;
+/**
+ * Deserialise protobuf binary to a SyncPush payload.
+ *
+ * @param bytes - The protobuf binary to deserialise.
+ * @returns A `Result` containing the SyncPush payload, or a `CodecError` on failure.
+ */
+declare function decodeSyncPush(bytes: Uint8Array): Result<SyncPushPayload, CodecError>;
+/**
+ * Serialise a SyncPull request to protobuf binary.
+ *
+ * @param pull - The SyncPull payload containing client ID, since HLC, and max deltas.
+ * @returns A `Result` containing the binary bytes, or a `CodecError` on failure.
+ */
+declare function encodeSyncPull(pull: SyncPullPayload): Result<Uint8Array, CodecError>;
+/**
+ * Deserialise protobuf binary to a SyncPull payload.
+ *
+ * @param bytes - The protobuf binary to deserialise.
+ * @returns A `Result` containing the SyncPull payload, or a `CodecError` on failure.
+ */
+declare function decodeSyncPull(bytes: Uint8Array): Result<SyncPullPayload, CodecError>;
+/**
+ * Serialise a SyncResponse to protobuf binary.
+ *
+ * @param response - The SyncResponse payload containing deltas, server HLC, and has_more flag.
+ * @returns A `Result` containing the binary bytes, or a `CodecError` on failure.
+ */
+declare function encodeSyncResponse(response: SyncResponsePayload): Result<Uint8Array, CodecError>;
+/**
+ * Deserialise protobuf binary to a SyncResponse payload.
+ *
+ * @param bytes - The protobuf binary to deserialise.
+ * @returns A `Result` containing the SyncResponse payload, or a `CodecError` on failure.
+ */
+declare function decodeSyncResponse(bytes: Uint8Array): Result<SyncResponsePayload, CodecError>;
+/**
+ * Serialise an ActionPush payload to protobuf binary.
+ *
+ * @param push - The ActionPush payload containing client ID and actions.
+ * @returns A `Result` containing the binary bytes, or a `CodecError` on failure.
+ */
+declare function encodeActionPush(push: ActionPush$1): Result<Uint8Array, CodecError>;
+/**
+ * Deserialise protobuf binary to an ActionPush payload.
+ *
+ * @param bytes - The protobuf binary to deserialise.
+ * @returns A `Result` containing the ActionPush payload, or a `CodecError` on failure.
+ */
+declare function decodeActionPush(bytes: Uint8Array): Result<ActionPush$1, CodecError>;
+/**
+ * Serialise an ActionResponse to protobuf binary.
+ *
+ * @param response - The ActionResponse payload.
+ * @returns A `Result` containing the binary bytes, or a `CodecError` on failure.
+ */
+declare function encodeActionResponse(response: ActionResponse$1): Result<Uint8Array, CodecError>;
+/**
+ * Deserialise protobuf binary to an ActionResponse payload.
+ *
+ * @param bytes - The protobuf binary to deserialise.
+ * @returns A `Result` containing the ActionResponse payload, or a `CodecError` on failure.
+ */
+declare function decodeActionResponse(bytes: Uint8Array): Result<ActionResponse$1, CodecError>;
+
+/**
+ * @generated from message lakesync.v1.ColumnDelta
+ */
+type ColumnDelta = Message<"lakesync.v1.ColumnDelta"> & {
+    /**
+     * @generated from field: string column = 1;
+     */
+    column: string;
+    /**
+     * @generated from field: bytes value = 2;
+     */
+    value: Uint8Array;
+};
+/**
+ * Describes the message lakesync.v1.ColumnDelta.
+ * Use `create(ColumnDeltaSchema)` to create a new message.
+ */
+declare const ColumnDeltaSchema: GenMessage<ColumnDelta>;
+/**
+ * @generated from message lakesync.v1.RowDelta
+ */
+type RowDelta = Message<"lakesync.v1.RowDelta"> & {
+    /**
+     * @generated from field: lakesync.v1.DeltaOp op = 1;
+     */
+    op: DeltaOp;
+    /**
+     * @generated from field: string table = 2;
+     */
+    table: string;
+    /**
+     * @generated from field: string row_id = 3;
+     */
+    rowId: string;
+    /**
+     * @generated from field: repeated lakesync.v1.ColumnDelta columns = 4;
+     */
+    columns: ColumnDelta[];
+    /**
+     * @generated from field: fixed64 hlc = 5;
+     */
+    hlc: bigint;
+    /**
+     * @generated from field: string client_id = 6;
+     */
+    clientId: string;
+    /**
+     * @generated from field: string delta_id = 7;
+     */
+    deltaId: string;
+};
+/**
+ * Describes the message lakesync.v1.RowDelta.
+ * Use `create(RowDeltaSchema)` to create a new message.
+ */
+declare const RowDeltaSchema: GenMessage<RowDelta>;
+/**
+ * @generated from message lakesync.v1.SyncPush
+ */
+type SyncPush = Message<"lakesync.v1.SyncPush"> & {
+    /**
+     * @generated from field: string client_id = 1;
+     */
+    clientId: string;
+    /**
+     * @generated from field: repeated lakesync.v1.RowDelta deltas = 2;
+     */
+    deltas: RowDelta[];
+    /**
+     * @generated from field: fixed64 last_seen_hlc = 3;
+     */
+    lastSeenHlc: bigint;
+};
+/**
+ * Describes the message lakesync.v1.SyncPush.
+ * Use `create(SyncPushSchema)` to create a new message.
+ */
+declare const SyncPushSchema: GenMessage<SyncPush>;
+/**
+ * @generated from message lakesync.v1.SyncPull
+ */
+type SyncPull = Message<"lakesync.v1.SyncPull"> & {
+    /**
+     * @generated from field: string client_id = 1;
+     */
+    clientId: string;
+    /**
+     * @generated from field: fixed64 since_hlc = 2;
+     */
+    sinceHlc: bigint;
+    /**
+     * @generated from field: uint32 max_deltas = 3;
+     */
+    maxDeltas: number;
+};
+/**
+ * Describes the message lakesync.v1.SyncPull.
+ * Use `create(SyncPullSchema)` to create a new message.
+ */
+declare const SyncPullSchema: GenMessage<SyncPull>;
+/**
+ * @generated from message lakesync.v1.SyncResponse
+ */
+type SyncResponse = Message<"lakesync.v1.SyncResponse"> & {
+    /**
+     * @generated from field: repeated lakesync.v1.RowDelta deltas = 1;
+     */
+    deltas: RowDelta[];
+    /**
+     * @generated from field: fixed64 server_hlc = 2;
+     */
+    serverHlc: bigint;
+    /**
+     * @generated from field: bool has_more = 3;
+     */
+    hasMore: boolean;
+};
+/**
+ * Describes the message lakesync.v1.SyncResponse.
+ * Use `create(SyncResponseSchema)` to create a new message.
+ */
+declare const SyncResponseSchema: GenMessage<SyncResponse>;
+/**
+ * @generated from message lakesync.v1.Action
+ */
+type Action = Message<"lakesync.v1.Action"> & {
+    /**
+     * @generated from field: string action_id = 1;
+     */
+    actionId: string;
+    /**
+     * @generated from field: string client_id = 2;
+     */
+    clientId: string;
+    /**
+     * @generated from field: fixed64 hlc = 3;
+     */
+    hlc: bigint;
+    /**
+     * @generated from field: string connector = 4;
+     */
+    connector: string;
+    /**
+     * @generated from field: string action_type = 5;
+     */
+    actionType: string;
+    /**
+     * @generated from field: bytes params = 6;
+     */
+    params: Uint8Array;
+    /**
+     * @generated from field: string idempotency_key = 7;
+     */
+    idempotencyKey: string;
+};
+/**
+ * Describes the message lakesync.v1.Action.
+ * Use `create(ActionSchema)` to create a new message.
+ */
+declare const ActionSchema: GenMessage<Action>;
+/**
+ * @generated from message lakesync.v1.ActionPush
+ */
+type ActionPush = Message<"lakesync.v1.ActionPush"> & {
+    /**
+     * @generated from field: string client_id = 1;
+     */
+    clientId: string;
+    /**
+     * @generated from field: repeated lakesync.v1.Action actions = 2;
+     */
+    actions: Action[];
+};
+/**
+ * Describes the message lakesync.v1.ActionPush.
+ * Use `create(ActionPushSchema)` to create a new message.
+ */
+declare const ActionPushSchema: GenMessage<ActionPush>;
+/**
+ * @generated from message lakesync.v1.ActionResultMsg
+ */
+type ActionResultMsg = Message<"lakesync.v1.ActionResultMsg"> & {
+    /**
+     * @generated from field: string action_id = 1;
+     */
+    actionId: string;
+    /**
+     * @generated from field: bytes data = 2;
+     */
+    data: Uint8Array;
+    /**
+     * @generated from field: fixed64 server_hlc = 3;
+     */
+    serverHlc: bigint;
+};
+/**
+ * @generated from message lakesync.v1.ActionErrorMsg
+ */
+type ActionErrorMsg = Message<"lakesync.v1.ActionErrorMsg"> & {
+    /**
+     * @generated from field: string action_id = 1;
+     */
+    actionId: string;
+    /**
+     * @generated from field: string code = 2;
+     */
+    code: string;
+    /**
+     * @generated from field: string message = 3;
+     */
+    message: string;
+    /**
+     * @generated from field: bool retryable = 4;
+     */
+    retryable: boolean;
+};
+/**
+ * @generated from message lakesync.v1.ActionResponseEntry
+ */
+type ActionResponseEntry = Message<"lakesync.v1.ActionResponseEntry"> & {
+    /**
+     * @generated from oneof lakesync.v1.ActionResponseEntry.result
+     */
+    result: {
+        /**
+         * @generated from field: lakesync.v1.ActionResultMsg success = 1;
+         */
+        value: ActionResultMsg;
+        case: "success";
+    } | {
+        /**
+         * @generated from field: lakesync.v1.ActionErrorMsg error = 2;
+         */
+        value: ActionErrorMsg;
+        case: "error";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * @generated from message lakesync.v1.ActionResponse
+ */
+type ActionResponse = Message<"lakesync.v1.ActionResponse"> & {
+    /**
+     * @generated from field: repeated lakesync.v1.ActionResponseEntry results = 1;
+     */
+    results: ActionResponseEntry[];
+    /**
+     * @generated from field: fixed64 server_hlc = 2;
+     */
+    serverHlc: bigint;
+};
+/**
+ * Describes the message lakesync.v1.ActionResponse.
+ * Use `create(ActionResponseSchema)` to create a new message.
+ */
+declare const ActionResponseSchema: GenMessage<ActionResponse>;
+/**
+ * @generated from enum lakesync.v1.DeltaOp
+ */
+declare enum DeltaOp {
+    /**
+     * @generated from enum value: DELTA_OP_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * @generated from enum value: DELTA_OP_INSERT = 1;
+     */
+    INSERT = 1,
+    /**
+     * @generated from enum value: DELTA_OP_UPDATE = 2;
+     */
+    UPDATE = 2,
+    /**
+     * @generated from enum value: DELTA_OP_DELETE = 3;
+     */
+    DELETE = 3
+}
+/**
+ * Describes the enum lakesync.v1.DeltaOp.
+ */
+declare const DeltaOpSchema: GenEnum<DeltaOp>;
+
+export { ActionPushSchema, ActionResponseSchema, ActionSchema, CodecError, ColumnDeltaSchema, DeltaOpSchema, type Action as ProtoAction, type ActionPush as ProtoActionPush, type ActionResponse as ProtoActionResponse, type ColumnDelta as ProtoColumnDelta, DeltaOp as ProtoDeltaOp, type RowDelta as ProtoRowDelta, type SyncPull as ProtoSyncPull, type SyncPush as ProtoSyncPush, type SyncResponse as ProtoSyncResponse, RowDeltaSchema, type SyncPullPayload, SyncPullSchema, type SyncPushPayload, SyncPushSchema, type SyncResponsePayload, SyncResponseSchema, TAG_ACTION_PUSH, TAG_ACTION_RESPONSE, TAG_BROADCAST, TAG_SYNC_PULL, TAG_SYNC_PUSH, decodeActionPush, decodeActionResponse, decodeBroadcastFrame, decodeRowDelta, decodeSyncPull, decodeSyncPush, decodeSyncResponse, encodeActionPush, encodeActionResponse, encodeBroadcastFrame, encodeRowDelta, encodeSyncPull, encodeSyncPush, encodeSyncResponse };

package/dist/proto.js

@@ -0,0 +1,67 @@
+import {
+  ActionPushSchema,
+  ActionResponseSchema,
+  ActionSchema,
+  CodecError,
+  ColumnDeltaSchema,
+  DeltaOp,
+  DeltaOpSchema,
+  RowDeltaSchema,
+  SyncPullSchema,
+  SyncPushSchema,
+  SyncResponseSchema,
+  TAG_ACTION_PUSH,
+  TAG_ACTION_RESPONSE,
+  TAG_BROADCAST,
+  TAG_SYNC_PULL,
+  TAG_SYNC_PUSH,
+  decodeActionPush,
+  decodeActionResponse,
+  decodeBroadcastFrame,
+  decodeRowDelta,
+  decodeSyncPull,
+  decodeSyncPush,
+  decodeSyncResponse,
+  encodeActionPush,
+  encodeActionResponse,
+  encodeBroadcastFrame,
+  encodeRowDelta,
+  encodeSyncPull,
+  encodeSyncPush,
+  encodeSyncResponse
+} from "./chunk-BNJOGBYK.js";
+import "./chunk-ICNT7I3K.js";
+import "./chunk-7D4SUZUM.js";
+export {
+  ActionPushSchema,
+  ActionResponseSchema,
+  ActionSchema,
+  CodecError,
+  ColumnDeltaSchema,
+  DeltaOpSchema,
+  DeltaOp as ProtoDeltaOp,
+  RowDeltaSchema,
+  SyncPullSchema,
+  SyncPushSchema,
+  SyncResponseSchema,
+  TAG_ACTION_PUSH,
+  TAG_ACTION_RESPONSE,
+  TAG_BROADCAST,
+  TAG_SYNC_PULL,
+  TAG_SYNC_PUSH,
+  decodeActionPush,
+  decodeActionResponse,
+  decodeBroadcastFrame,
+  decodeRowDelta,
+  decodeSyncPull,
+  decodeSyncPush,
+  decodeSyncResponse,
+  encodeActionPush,
+  encodeActionResponse,
+  encodeBroadcastFrame,
+  encodeRowDelta,
+  encodeSyncPull,
+  encodeSyncPush,
+  encodeSyncResponse
+};
+//# sourceMappingURL=proto.js.map

package/dist/proto.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react.d.ts

@@ -0,0 +1,147 @@
+import * as react from 'react';
+import { f as SyncCoordinator, j as SyncTracker, D as DbError } from './coordinator-CxckTzYW.js';
+import { L as LakeSyncError, R as Result } from './result-CojzlFE2.js';
+import { c as ActionDescriptor, k as ActionResult, e as ActionErrorResult } from './types-Bs-QyOe-.js';
+import './hlc-DiD8QNG3.js';
+import './types-V_jVu2sA.js';
+
+/** Internal context value shared across all hooks. */
+interface LakeSyncContextValue {
+    coordinator: SyncCoordinator;
+    tracker: SyncTracker;
+    /** Monotonically increasing counter — bumped on every data change. */
+    dataVersion: number;
+    /** Increment dataVersion to trigger query re-runs. */
+    invalidate: () => void;
+}
+/** Props for the LakeSyncProvider component. */
+interface LakeSyncProviderProps {
+    /** An already-constructed SyncCoordinator instance. */
+    coordinator: SyncCoordinator;
+    children: React.ReactNode;
+}
+/**
+ * Provides LakeSync context to the component tree.
+ *
+ * Subscribes to `onChange` events from the coordinator and maintains a
+ * `dataVersion` counter that increments on every remote delta application,
+ * triggering reactive query re-runs in `useQuery`.
+ */
+declare function LakeSyncProvider(props: LakeSyncProviderProps): react.FunctionComponentElement<react.ProviderProps<LakeSyncContextValue | null>>;
+/**
+ * Access the raw LakeSync SDK instances from context.
+ *
+ * @throws if called outside a `<LakeSyncProvider>`.
+ */
+declare function useLakeSync(): LakeSyncContextValue;
+
+/** Parameters for a single action execution. */
+interface ActionParams {
+    connector: string;
+    actionType: string;
+    params: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+/** Return type of `useAction`. */
+interface UseActionResult {
+    /** Execute an action against a connector via the gateway. */
+    execute: (params: ActionParams) => Promise<void>;
+    /** Last action result (success or error). Null before first execution. */
+    lastResult: ActionResult | ActionErrorResult | null;
+    /** Whether an action is currently in flight. */
+    isPending: boolean;
+}
+/**
+ * Execute imperative actions against external systems via the gateway.
+ *
+ * Wraps `SyncCoordinator.executeAction()` and subscribes to
+ * `onActionComplete` events to track the latest result.
+ *
+ * ```ts
+ * const { execute, lastResult, isPending } = useAction();
+ *
+ * await execute({
+ *   connector: "slack",
+ *   actionType: "send_message",
+ *   params: { channel: "#general", text: "Hello" },
+ * });
+ * ```
+ */
+declare function useAction(): UseActionResult;
+/** Return type of `useActionDiscovery`. */
+interface UseActionDiscoveryResult {
+    /** Map of connector name to supported action descriptors. */
+    connectors: Record<string, ActionDescriptor[]>;
+    /** Whether discovery is loading. */
+    isLoading: boolean;
+    /** Error from the last fetch, or null. */
+    error: LakeSyncError | null;
+    /** Manually re-fetch available actions. */
+    refetch: () => void;
+}
+/**
+ * Discover available connectors and their supported action types.
+ *
+ * Calls `transport.describeActions()` on mount and returns the result
+ * reactively. Use this to build dynamic UI based on available actions.
+ *
+ * ```ts
+ * const { connectors, isLoading } = useActionDiscovery();
+ *
+ * for (const [name, actions] of Object.entries(connectors)) {
+ *   console.log(name, actions.map(a => a.actionType));
+ * }
+ * ```
+ */
+declare function useActionDiscovery(): UseActionDiscoveryResult;
+
+/** Return type of `useMutation`. */
+interface UseMutationResult {
+    insert: (table: string, rowId: string, data: Record<string, unknown>) => Promise<Result<void, LakeSyncError>>;
+    update: (table: string, rowId: string, data: Record<string, unknown>) => Promise<Result<void, LakeSyncError>>;
+    remove: (table: string, rowId: string) => Promise<Result<void, LakeSyncError>>;
+}
+/**
+ * Wraps SyncTracker mutations with automatic query invalidation.
+ *
+ * After each successful mutation, `dataVersion` is incremented so all
+ * active `useQuery` hooks re-run.
+ */
+declare function useMutation(): UseMutationResult;
+
+/** Return type of `useQuery`. */
+interface UseQueryResult<T> {
+    data: T[];
+    error: DbError | null;
+    isLoading: boolean;
+    refetch: () => void;
+}
+/**
+ * Reactive SQL query hook.
+ *
+ * Re-runs automatically when:
+ * - Remote deltas are applied (via `onChange`)
+ * - A local mutation completes (via `invalidate()`)
+ * - The `sql` or `params` arguments change
+ *
+ * @param sql - SQL query string
+ * @param params - Optional bind parameters
+ */
+declare function useQuery<T>(sql: string, params?: unknown[]): UseQueryResult<T>;
+
+/** Return type of `useSyncStatus`. */
+interface UseSyncStatusResult {
+    isSyncing: boolean;
+    lastSyncTime: Date | null;
+    queueDepth: number;
+    error: Error | null;
+}
+/**
+ * Observe the sync lifecycle.
+ *
+ * Tracks whether a sync is in progress, last successful sync time,
+ * outbox queue depth, and the most recent sync error (cleared on success).
+ */
+declare function useSyncStatus(): UseSyncStatusResult;
+
+export { type ActionParams, type LakeSyncContextValue, LakeSyncProvider, type LakeSyncProviderProps, type UseActionDiscoveryResult, type UseActionResult, type UseMutationResult, type UseQueryResult, type UseSyncStatusResult, useAction, useActionDiscovery, useLakeSync, useMutation, useQuery, useSyncStatus };