@electric-sql/client 1.0.9 → 1.0.11

package/dist/index.d.ts

@@ -6,17 +6,30 @@ type Value<Extensions = never> = string | number | boolean | bigint | null | Ext
     [key: string]: Value<Extensions>;
 };
 type Row<Extensions = never> = Record<string, Value<Extensions>>;
-type GetExtensions<T extends Row<unknown>> = T extends Row<infer Extensions> ? Extensions : never;
-type Offset = `-1` | `${number}_${number}` | `${bigint}_${number}`;
+type GetExtensions<T> = [T] extends [Row<never>] ? never : [T] extends [Row<infer E>] ? E : never;
+type Offset = `-1` | `now` | `${number}_${number}` | `${bigint}_${number}`;
+/** Information about transaction visibility for a snapshot. All fields are encoded as strings, but should be treated as uint64. */
+type PostgresSnapshot = {
+    xmin: `${bigint}`;
+    xmax: `${bigint}`;
+    xip_list: `${bigint}`[];
+};
+type NormalizedPgSnapshot = {
+    xmin: bigint;
+    xmax: bigint;
+    xip_list: bigint[];
+};
 interface Header {
     [key: Exclude<string, `operation` | `control`>]: Value;
 }
 type Operation = `insert` | `update` | `delete`;
 type ControlMessage = {
-    headers: Header & {
+    headers: (Header & {
         control: `up-to-date` | `must-refetch`;
         global_last_seen_lsn?: string;
-    };
+    }) | (Header & {
+        control: `snapshot-end`;
+    } & PostgresSnapshot);
 };
 type ChangeMessage<T extends Row<unknown> = Row> = {
     key: string;
@@ -24,6 +37,7 @@ type ChangeMessage<T extends Row<unknown> = Row> = {
     old_value?: Partial<T>;
     headers: Header & {
         operation: Operation;
+        txids?: number[];
     };
 };
 type Message<T extends Row<unknown> = Row> = ControlMessage | ChangeMessage<T>;
@@ -78,6 +92,20 @@ type TypedMessages<T extends Row<unknown> = Row> = {
     schema: ColumnInfo;
 };
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * Metadata that allows the consumer to know which changes have been incorporated into this snapshot.
+ *
+ * For any data that has a known transaction ID `xid` (and e.g. a key that's part of the snapshot):
+ * - if `xid` < `xmin` - included, change can be skipped
+ * - if `xid` < `xmax` AND `xid` not in `xip` - included, change can be skipped
+ * - if `xid` < `xmax` AND `xid` in `xip` - parallel, not included, change must be processed
+ * - if `xid` >= `xmax` - not included, change must be processed, and we can stop filtering after we see this
+ */
+type SnapshotMetadata = {
+    /** Random number that's reflected in the `snapshot_mark` header on the snapshot items. */
+    snapshot_mark: number;
+    database_lsn: string;
+} & PostgresSnapshot;
 
 type Token = string;
 type ParseFunction<Extensions = never> = (value: Token, additionalInfo?: Omit<ColumnInfo, `type` | `dims`>) => Value<Extensions>;
@@ -88,6 +116,7 @@ type ParseFunction<Extensions = never> = (value: Token, additionalInfo?: Omit<Co
 type Parser<Extensions = never> = {
     [key: string]: ParseFunction<Extensions>;
 };
+type TransformFunction<Extensions = never> = (message: Row<Extensions>) => Row<Extensions>;
 
 declare class FetchError extends Error {
     url: string;
@@ -125,6 +154,7 @@ declare const OFFSET_QUERY_PARAM = "offset";
 declare const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 type Replica = `full` | `default`;
+type LogMode = `changes_only` | `full`;
 /**
  * PostgreSQL-specific shape parameters that can be provided externally
  */
@@ -174,7 +204,14 @@ type ExternalParamsRecord<T extends Row<unknown> = Row> = {
 } & Partial<PostgresParams<T>> & {
     [K in ReservedParamKeys]?: never;
 };
-type ReservedParamKeys = typeof LIVE_CACHE_BUSTER_QUERY_PARAM | typeof SHAPE_HANDLE_QUERY_PARAM | typeof LIVE_QUERY_PARAM | typeof OFFSET_QUERY_PARAM;
+type SubsetParams = {
+    where?: string;
+    params?: Record<string, string>;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+};
+type ReservedParamKeys = typeof LIVE_CACHE_BUSTER_QUERY_PARAM | typeof SHAPE_HANDLE_QUERY_PARAM | typeof LIVE_QUERY_PARAM | typeof OFFSET_QUERY_PARAM | `subset__${string}`;
 /**
  * External headers type - what users provide.
  * Allows string or function values for any header.
@@ -244,10 +281,15 @@ interface ShapeStreamOptions<T = never> {
      * Experimental support for Server-Sent Events (SSE) for live updates.
      */
     experimentalLiveSse?: boolean;
+    /**
+     * Initial data loading mode
+     */
+    mode?: LogMode;
     signal?: AbortSignal;
     fetchClient?: typeof fetch;
     backoffOptions?: BackoffOptions;
     parser?: Parser<T>;
+    transformer?: TransformFunction<T>;
     /**
      * A function for handling shapestream errors.
      * This is optional, when it is not provided any shapestream errors will be thrown.
@@ -271,7 +313,18 @@ interface ShapeStreamInterface<T extends Row<unknown> = Row> {
     lastOffset: Offset;
     shapeHandle?: string;
     error?: unknown;
+    mode: LogMode;
     forceDisconnectAndRefresh(): Promise<void>;
+    requestSnapshot(params: {
+        where?: string;
+        params?: Record<string, string>;
+        limit: number;
+        offset?: number;
+        orderBy: string;
+    }): Promise<{
+        metadata: SnapshotMetadata;
+        data: Array<Message<T>>;
+    }>;
 }
 /**
  * Reads updates to a shape from Electric using HTTP requests and long polling or
@@ -324,6 +377,7 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
     get error(): unknown;
     get isUpToDate(): boolean;
     get lastOffset(): Offset;
+    get mode(): LogMode;
     subscribe(callback: (messages: Message<T>[]) => MaybePromise<void>, onError?: (error: Error) => void): () => void;
     unsubscribeAll(): void;
     /** Unix time at which we last synced. Undefined when `isLoading` is true. */
@@ -343,6 +397,24 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
      * latest LSN from Postgres at that point in time.
      */
     forceDisconnectAndRefresh(): Promise<void>;
+    /**
+     * Request a snapshot for subset of data.
+     *
+     * Only available when mode is `changes_only`.
+     * Returns the insertion point & the data, but more importantly injects the data
+     * into the subscribed data stream. Returned value is unlikely to be useful for the caller,
+     * unless the caller has complicated additional logic.
+     *
+     * Data will be injected in a way that's also tracking further incoming changes, and it'll
+     * skip the ones that are already in the snapshot.
+     *
+     * @param opts - The options for the snapshot request.
+     * @returns The metadata and the data for the snapshot.
+     */
+    requestSnapshot(opts: SubsetParams): Promise<{
+        metadata: SnapshotMetadata;
+        data: Array<ChangeMessage<T>>;
+    }>;
 }
 
 type ShapeData<T extends Row<unknown> = Row> = Map<string, T>;
@@ -406,6 +478,13 @@ declare class Shape<T extends Row<unknown> = Row> {
     isLoading(): boolean;
     /** Indicates if we are connected to the Electric sync service. */
     isConnected(): boolean;
+    /** Current log mode of the underlying stream */
+    get mode(): LogMode;
+    /**
+     * Request a snapshot for subset of data. Only available when mode is changes_only.
+     * Returns void; data will be emitted via the stream and processed by this Shape.
+     */
+    requestSnapshot(params: Parameters<ShapeStreamInterface<T>[`requestSnapshot`]>[0]): Promise<void>;
     subscribe(callback: ShapeChangedCallback<T>): () => void;
     unsubscribeAll(): void;
     get numSubscribers(): number;
@@ -447,5 +526,13 @@ declare function isChangeMessage<T extends Row<unknown> = Row>(message: Message<
  * ```
  */
 declare function isControlMessage<T extends Row<unknown> = Row>(message: Message<T>): message is ControlMessage;
+/**
+ * Checks if a transaction is visible in a snapshot.
+ *
+ * @param txid - the transaction id to check
+ * @param snapshot - the information about the snapshot
+ * @returns true if the transaction is visible in the snapshot
+ */
+declare function isVisibleInSnapshot(txid: number | bigint | `${bigint}`, snapshot: PostgresSnapshot | NormalizedPgSnapshot): boolean;
 
-export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type MaybePromise, type Message, type NumericColumn, type Offset, type Operation, type PostgresParams, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, isChangeMessage, isControlMessage, resolveValue };
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue };