@electric-sql/client 0.4.1 → 0.5.1

package/dist/index.d.ts

@@ -72,6 +72,7 @@ type TypedMessages<T extends Row = Row> = {
     messages: Array<Message<T>>;
     schema: ColumnInfo;
 };
+type MaybePromise<T> = T | Promise<T>;
 
 type NullToken = null | `NULL`;
 type Token = Exclude<string, NullToken>;
@@ -80,18 +81,35 @@ type Parser = {
     [key: string]: ParseFunction;
 };
 
-type ShapeData<T extends Row = Row> = Map<string, T>;
-type ShapeChangedCallback<T extends Row = Row> = (value: ShapeData<T>) => void;
+declare class FetchError extends Error {
+    url: string;
+    status: number;
+    text?: string;
+    json?: object;
+    headers: Record<string, string>;
+    constructor(status: number, text: string | undefined, json: object | undefined, headers: Record<string, string>, url: string, message?: string);
+    static fromResponse(response: Response, url: string): Promise<FetchError>;
+}
+
 interface BackoffOptions {
+    /**
+     * Initial delay before retrying in milliseconds
+     */
     initialDelay: number;
+    /**
+     * Maximum retry delay in milliseconds
+     */
     maxDelay: number;
     multiplier: number;
+    onFailedAttempt?: () => void;
+    debug?: boolean;
 }
 declare const BackoffDefaults: {
     initialDelay: number;
     maxDelay: number;
     multiplier: number;
 };
+
 /**
  * Options for constructing a ShapeStream.
  */
@@ -129,14 +147,17 @@ interface ShapeStreamOptions {
     fetchClient?: typeof fetch;
     parser?: Parser;
 }
-declare class FetchError extends Error {
-    url: string;
-    status: number;
-    text?: string;
-    json?: object;
-    headers: Record<string, string>;
-    constructor(status: number, text: string | undefined, json: object | undefined, headers: Record<string, string>, url: string, message?: string);
-    static fromResponse(response: Response, url: string): Promise<FetchError>;
+interface ShapeStreamInterface<T extends Row = Row> {
+    subscribe(callback: (messages: Message<T>[]) => MaybePromise<void>, onError?: (error: FetchError | Error) => void): void;
+    unsubscribeAllUpToDateSubscribers(): void;
+    unsubscribeAll(): void;
+    subscribeOnceToUpToDate(callback: () => MaybePromise<void>, error: (err: FetchError | Error) => void): () => void;
+    isLoading(): boolean;
+    lastSyncedAt(): number | undefined;
+    lastSynced(): number;
+    isConnected(): boolean;
+    isUpToDate: boolean;
+    shapeId?: string;
 }
 /**
  * Reads updates to a shape from Electric using HTTP requests and long polling. Notifies subscribers
@@ -168,40 +189,29 @@ declare class FetchError extends Error {
  * aborter.abort()
  * ```
  */
-declare class ShapeStream<T extends Row = Row> {
-    private options;
-    private backoffOptions;
-    private fetchClient;
-    private schema?;
-    private subscribers;
-    private upToDateSubscribers;
-    private lastOffset;
-    private messageParser;
-    private lastSyncedAt?;
-    isUpToDate: boolean;
-    private connected;
-    shapeId?: string;
+declare class ShapeStream<T extends Row = Row> implements ShapeStreamInterface<T> {
+    #private;
+    readonly options: ShapeStreamOptions;
     constructor(options: ShapeStreamOptions);
+    get shapeId(): string;
+    get isUpToDate(): boolean;
     start(): Promise<void>;
-    subscribe(callback: (messages: Message<T>[]) => void | Promise<void>, onError?: (error: FetchError | Error) => void): () => void;
+    subscribe(callback: (messages: Message<T>[]) => MaybePromise<void>, onError?: (error: FetchError | Error) => void): () => void;
     unsubscribeAll(): void;
-    private publish;
-    private sendErrorToSubscribers;
-    subscribeOnceToUpToDate(callback: () => void | Promise<void>, error: (err: FetchError | Error) => void): () => void;
+    subscribeOnceToUpToDate(callback: () => MaybePromise<void>, error: (err: FetchError | Error) => void): () => void;
     unsubscribeAllUpToDateSubscribers(): void;
+    /** Unix time at which we last synced. Undefined when `isLoading` is true. */
+    lastSyncedAt(): number | undefined;
     /** Time elapsed since last sync (in ms). Infinity if we did not yet sync. */
     lastSynced(): number;
+    /** Indicates if we are connected to the Electric sync service. */
     isConnected(): boolean;
-    private notifyUpToDateSubscribers;
-    private sendErrorToUpToDateSubscribers;
-    /**
-     * Resets the state of the stream, optionally with a provided
-     * shape ID
-     */
-    private reset;
-    private validateOptions;
-    private fetchWithBackoff;
+    /** True during initial fetch. False afterwise.  */
+    isLoading(): boolean;
 }
+
+type ShapeData<T extends Row = Row> = Map<string, T>;
+type ShapeChangedCallback<T extends Row = Row> = (value: ShapeData<T>) => void;
 /**
  * A Shape is an object that subscribes to a shape log,
  * keeps a materialised shape `.value` in memory and
@@ -234,22 +244,23 @@ declare class ShapeStream<T extends Row = Row> {
  *     })
  */
 declare class Shape<T extends Row = Row> {
-    private stream;
-    private data;
-    private subscribers;
-    error: FetchError | false;
-    private hasNotifiedSubscribersUpToDate;
-    constructor(stream: ShapeStream<T>);
-    lastSynced(): number;
-    isConnected(): boolean;
+    #private;
+    constructor(stream: ShapeStreamInterface<T>);
+    get isUpToDate(): boolean;
     get value(): Promise<ShapeData<T>>;
     get valueSync(): ShapeData<T>;
+    get error(): false | FetchError;
+    /** Unix time at which we last synced. Undefined when `isLoading` is true. */
+    lastSyncedAt(): number | undefined;
+    /** Time elapsed since last sync (in ms). Infinity if we did not yet sync. */
+    lastSynced(): number;
+    /** True during initial fetch. False afterwise.  */
+    isLoading(): boolean;
+    /** Indicates if we are connected to the Electric sync service. */
+    isConnected(): boolean;
     subscribe(callback: ShapeChangedCallback<T>): () => void;
     unsubscribeAll(): void;
     get numSubscribers(): number;
-    private process;
-    private handleError;
-    private notify;
 }
 
 /**
@@ -289,4 +300,4 @@ declare function isChangeMessage<T extends Row = Row>(message: Message<T>): mess
  */
 declare function isControlMessage<T extends Row = Row>(message: Message<T>): message is ControlMessage;
 
-export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, FetchError, type IntervalColumn, type IntervalColumnWithPrecision, type Message, type NumericColumn, type Offset, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamOptions, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, isChangeMessage, isControlMessage };
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, FetchError, type IntervalColumn, type IntervalColumnWithPrecision, type MaybePromise, type Message, type NumericColumn, type Offset, 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 };