@electric-sql/client 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+type Value = string | number | boolean | bigint | null | Value[] | {
+    [key: string]: Value;
+};
+type Offset = `-1` | `${number}_${number}`;
+interface Header {
+    [key: string]: Value;
+}
+type ControlMessage = {
+    headers: Header;
+};
+type ChangeMessage<T> = {
+    key: string;
+    value: T;
+    headers: Header & {
+        action: `insert` | `update` | `delete`;
+    };
+    offset: Offset;
+};
+type Message<T extends Value = {
+    [key: string]: Value;
+}> = ControlMessage | ChangeMessage<T>;
+type RegularColumn = {
+    type: string;
+    dims: number;
+};
+type VarcharColumn = {
+    type: `varchar`;
+    dims: number;
+    max_length?: number;
+};
+type BpcharColumn = {
+    type: `bpchar`;
+    dims: number;
+    length?: number;
+};
+type TimeColumn = {
+    type: `time` | `timetz` | `timestamp` | `timestamptz`;
+    dims: number;
+    precision?: number;
+};
+type IntervalColumn = {
+    type: `interval`;
+    dims: number;
+    fields?: `YEAR` | `MONTH` | `DAY` | `HOUR` | `MINUTE` | `YEAR TO MONTH` | `DAY TO HOUR` | `DAY TO MINUTE` | `DAY TO SECOND` | `HOUR TO MINUTE` | `HOUR TO SECOND` | `MINUTE TO SECOND`;
+};
+type IntervalColumnWithPrecision = {
+    type: `interval`;
+    dims: number;
+    precision?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    fields?: `SECOND`;
+};
+type BitColumn = {
+    type: `bit`;
+    dims: number;
+    length: number;
+};
+type NumericColumn = {
+    type: `numeric`;
+    dims: number;
+    precision?: number;
+    scale?: number;
+};
+type ColumnInfo = RegularColumn | VarcharColumn | BpcharColumn | TimeColumn | IntervalColumn | IntervalColumnWithPrecision | BitColumn | NumericColumn;
+type Schema = {
+    [key: string]: ColumnInfo;
+};
+type TypedMessages<T extends Value = {
+    [key: string]: Value;
+}> = {
+    messages: Array<Message<T>>;
+    schema: ColumnInfo;
+};
+
+type ParseFunction = (value: string, additionalInfo?: Omit<ColumnInfo, `type` | `dims`>) => Value;
+type Parser = {
+    [key: string]: ParseFunction;
+};
+
+type ShapeData = Map<string, {
+    [key: string]: Value;
+}>;
+type ShapeChangedCallback = (value: ShapeData) => void;
+interface BackoffOptions {
+    initialDelay: number;
+    maxDelay: number;
+    multiplier: number;
+}
+declare const BackoffDefaults: {
+    initialDelay: number;
+    maxDelay: number;
+    multiplier: number;
+};
+/**
+ * Options for constructing a ShapeStream.
+ */
+interface ShapeStreamOptions {
+    /**
+     * The full URL to where the Shape is hosted. This can either be the Electric server
+     * directly or a proxy. E.g. for a local Electric instance, you might set `http://localhost:3000/v1/shape/foo`
+     */
+    url: string;
+    /**
+     * where clauses for the shape.
+     */
+    where?: string;
+    /**
+     * The "offset" on the shape log. This is typically not set as the ShapeStream
+     * will handle this automatically. A common scenario where you might pass an offset
+     * is if you're maintaining a local cache of the log. If you've gone offline
+     * and are re-starting a ShapeStream to catch-up to the latest state of the Shape,
+     * you'd pass in the last offset and shapeId you'd seen from the Electric server
+     * so it knows at what point in the shape to catch you up from.
+     */
+    offset?: Offset;
+    /**
+     * Similar to `offset`, this isn't typically used unless you're maintaining
+     * a cache of the shape log.
+     */
+    shapeId?: string;
+    backoffOptions?: BackoffOptions;
+    /**
+     * Automatically fetch updates to the Shape. If you just want to sync the current
+     * shape and stop, pass false.
+     */
+    subscribe?: boolean;
+    signal?: AbortSignal;
+    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>;
+}
+/**
+ * Reads updates to a shape from Electric using HTTP requests and long polling. Notifies subscribers
+ * when new messages come in. Doesn't maintain any history of the
+ * log but does keep track of the offset position and is the best way
+ * to consume the HTTP `GET /v1/shape` api.
+ *
+ * @constructor
+ * @param {ShapeStreamOptions} options
+ *
+ * Register a callback function to subscribe to the messages.
+ *
+ *     const stream = new ShapeStream(options)
+ *     stream.subscribe(messages => {
+ *       // messages is 1 or more row updates
+ *     })
+ *
+ * To abort the stream, abort the `signal`
+ * passed in via the `ShapeStreamOptions`.
+ *
+ *   const aborter = new AbortController()
+ *   const issueStream = new ShapeStream({
+ *     url: `${BASE_URL}/${table}`
+ *     subscribe: true,
+ *     signal: aborter.signal,
+ *   })
+ *   // Later...
+ *   aborter.abort()
+ */
+declare class ShapeStream {
+    private options;
+    private backoffOptions;
+    private fetchClient;
+    private schema?;
+    private subscribers;
+    private upToDateSubscribers;
+    private lastOffset;
+    private messageParser;
+    isUpToDate: boolean;
+    shapeId?: string;
+    constructor(options: ShapeStreamOptions);
+    start(): Promise<void>;
+    subscribe(callback: (messages: Message[]) => void | Promise<void>, onError?: (error: FetchError | Error) => void): () => void;
+    unsubscribeAll(): void;
+    private publish;
+    private sendErrorToSubscribers;
+    subscribeOnceToUpToDate(callback: () => void | Promise<void>, error: (err: FetchError | Error) => void): () => void;
+    unsubscribeAllUpToDateSubscribers(): void;
+    private notifyUpToDateSubscribers;
+    private sendErrorToUpToDateSubscribers;
+    /**
+     * Resets the state of the stream, optionally with a provided
+     * shape ID
+     */
+    private reset;
+    private validateOptions;
+    private fetchWithBackoff;
+}
+/**
+ * A Shape is an object that subscribes to a shape log,
+ * keeps a materialised shape `.value` in memory and
+ * notifies subscribers when the value has changed.
+ *
+ * It can be used without a framework and as a primitive
+ * to simplify developing framework hooks.
+ *
+ * @constructor
+ * @param {Shape}
+ *
+ *     const shapeStream = new ShapeStream(url: 'http://localhost:3000/v1/shape/foo'})
+ *     const shape = new Shape(shapeStream)
+ *
+ * `value` returns a promise that resolves the Shape data once the Shape has been
+ * fully loaded (and when resuming from being offline):
+ *
+ *     const value = await shape.value
+ *
+ * `valueSync` returns the current data synchronously:
+ *
+ *     const value = shape.valueSync
+ *
+ *  Subscribe to updates. Called whenever the shape updates in Postgres.
+ *
+ *     shape.subscribe(shapeData => {
+ *       console.log(shapeData)
+ *     })
+ */
+declare class Shape {
+    private stream;
+    private data;
+    private subscribers;
+    error: FetchError | false;
+    private hasNotifiedSubscribersUpToDate;
+    constructor(stream: ShapeStream);
+    get isUpToDate(): boolean;
+    get value(): Promise<ShapeData>;
+    get valueSync(): ShapeData;
+    subscribe(callback: ShapeChangedCallback): () => void;
+    unsubscribeAll(): void;
+    get numSubscribers(): number;
+    private process;
+    private handleError;
+    private notify;
+}
+
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type ControlMessage, FetchError, type IntervalColumn, type IntervalColumnWithPrecision, type Message, type NumericColumn, type Offset, type RegularColumn, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamOptions, type TimeColumn, type TypedMessages, type Value, type VarcharColumn };

package/dist/index.legacy-esm.js

@@ -0,0 +1,450 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+
+// src/parser.ts
+var parseNumber = (value) => Number(value);
+var parseBool = (value) => value === `true` || value === `t`;
+var parseBigInt = (value) => BigInt(value);
+var parseJson = (value) => JSON.parse(value);
+var defaultParser = {
+  int2: parseNumber,
+  int4: parseNumber,
+  int8: parseBigInt,
+  bool: parseBool,
+  float4: parseNumber,
+  float8: parseNumber,
+  json: parseJson,
+  jsonb: parseJson
+};
+function pgArrayParser(value, parser) {
+  let i = 0;
+  let char = null;
+  let str = ``;
+  let quoted = false;
+  let last = 0;
+  let p = void 0;
+  function loop(x) {
+    const xs = [];
+    for (; i < x.length; i++) {
+      char = x[i];
+      if (quoted) {
+        if (char === `\\`) {
+          str += x[++i];
+        } else if (char === `"`) {
+          xs.push(parser ? parser(str) : str);
+          str = ``;
+          quoted = x[i + 1] === `"`;
+          last = i + 2;
+        } else {
+          str += char;
+        }
+      } else if (char === `"`) {
+        quoted = true;
+      } else if (char === `{`) {
+        last = ++i;
+        xs.push(loop(x));
+      } else if (char === `}`) {
+        quoted = false;
+        last < i && xs.push(parser ? parser(x.slice(last, i)) : x.slice(last, i));
+        last = i + 1;
+        break;
+      } else if (char === `,` && p !== `}` && p !== `"`) {
+        xs.push(parser ? parser(x.slice(last, i)) : x.slice(last, i));
+        last = i + 1;
+      }
+      p = char;
+    }
+    last < i && xs.push(parser ? parser(x.slice(last, i + 1)) : x.slice(last, i + 1));
+    return xs;
+  }
+  return loop(value)[0];
+}
+var MessageParser = class {
+  constructor(parser) {
+    this.parser = __spreadValues(__spreadValues({}, defaultParser), parser);
+  }
+  parse(messages, schema) {
+    return JSON.parse(messages, (key, value) => {
+      if (key === `value` && typeof value === `object`) {
+        const row = value;
+        Object.keys(row).forEach((key2) => {
+          row[key2] = this.parseRow(key2, row[key2], schema);
+        });
+      }
+      return value;
+    });
+  }
+  // Parses the message values using the provided parser based on the schema information
+  parseRow(key, value, schema) {
+    const columnInfo = schema[key];
+    if (!columnInfo) {
+      return value;
+    }
+    const parser = this.parser[columnInfo.type];
+    const _a = columnInfo, { type: _typ, dims: dimensions } = _a, additionalInfo = __objRest(_a, ["type", "dims"]);
+    if (dimensions > 0) {
+      const identityParser = (v) => v;
+      return pgArrayParser(value, parser != null ? parser : identityParser);
+    }
+    if (!parser) {
+      return value;
+    }
+    return parser(value, additionalInfo);
+  }
+};
+
+// src/client.ts
+var BackoffDefaults = {
+  initialDelay: 100,
+  maxDelay: 1e4,
+  multiplier: 1.3
+};
+var MessageProcessor = class {
+  constructor(callback) {
+    this.messageQueue = [];
+    this.isProcessing = false;
+    this.callback = callback;
+  }
+  process(messages) {
+    this.messageQueue.push(messages);
+    if (!this.isProcessing) {
+      this.processQueue();
+    }
+  }
+  async processQueue() {
+    this.isProcessing = true;
+    while (this.messageQueue.length > 0) {
+      const messages = this.messageQueue.shift();
+      await this.callback(messages);
+    }
+    this.isProcessing = false;
+  }
+};
+var FetchError = class _FetchError extends Error {
+  constructor(status, text, json, headers, url, message) {
+    super(
+      message || `HTTP Error ${status} at ${url}: ${text != null ? text : JSON.stringify(json)}`
+    );
+    this.url = url;
+    this.name = `FetchError`;
+    this.status = status;
+    this.text = text;
+    this.json = json;
+    this.headers = headers;
+  }
+  static async fromResponse(response, url) {
+    const status = response.status;
+    const headers = Object.fromEntries([...response.headers.entries()]);
+    let text = void 0;
+    let json = void 0;
+    const contentType = response.headers.get(`content-type`);
+    if (contentType && contentType.includes(`application/json`)) {
+      json = await response.json();
+    } else {
+      text = await response.text();
+    }
+    return new _FetchError(status, text, json, headers, url);
+  }
+};
+var ShapeStream = class {
+  constructor(options) {
+    this.subscribers = /* @__PURE__ */ new Map();
+    this.upToDateSubscribers = /* @__PURE__ */ new Map();
+    this.isUpToDate = false;
+    var _a, _b, _c;
+    this.validateOptions(options);
+    this.options = __spreadValues({ subscribe: true }, options);
+    this.lastOffset = (_a = this.options.offset) != null ? _a : `-1`;
+    this.shapeId = this.options.shapeId;
+    this.messageParser = new MessageParser(options.parser);
+    this.backoffOptions = (_b = options.backoffOptions) != null ? _b : BackoffDefaults;
+    this.fetchClient = (_c = options.fetchClient) != null ? _c : (...args) => fetch(...args);
+    this.start();
+  }
+  async start() {
+    var _a, _b;
+    this.isUpToDate = false;
+    const { url, where, signal } = this.options;
+    while (!(signal == null ? void 0 : signal.aborted) && !this.isUpToDate || this.options.subscribe) {
+      const fetchUrl = new URL(url);
+      if (where) fetchUrl.searchParams.set(`where`, where);
+      fetchUrl.searchParams.set(`offset`, this.lastOffset);
+      if (this.isUpToDate) {
+        fetchUrl.searchParams.set(`live`, `true`);
+      }
+      if (this.shapeId) {
+        fetchUrl.searchParams.set(`shape_id`, this.shapeId);
+      }
+      let response;
+      try {
+        const maybeResponse = await this.fetchWithBackoff(fetchUrl);
+        if (maybeResponse) response = maybeResponse;
+        else break;
+      } catch (e) {
+        if (!(e instanceof FetchError)) throw e;
+        if (e.status == 409) {
+          const newShapeId = e.headers[`x-electric-shape-id`];
+          this.reset(newShapeId);
+          this.publish(e.json);
+          continue;
+        } else if (e.status >= 400 && e.status < 500) {
+          this.sendErrorToUpToDateSubscribers(e);
+          this.sendErrorToSubscribers(e);
+          throw e;
+        }
+      }
+      const { headers, status } = response;
+      const shapeId = headers.get(`X-Electric-Shape-Id`);
+      if (shapeId) {
+        this.shapeId = shapeId;
+      }
+      const lastOffset = headers.get(`X-Electric-Chunk-Last-Offset`);
+      if (lastOffset) {
+        this.lastOffset = lastOffset;
+      }
+      const getSchema = () => {
+        const schemaHeader = headers.get(`X-Electric-Schema`);
+        return schemaHeader ? JSON.parse(schemaHeader) : {};
+      };
+      this.schema = (_a = this.schema) != null ? _a : getSchema();
+      const messages = status === 204 ? `[]` : await response.text();
+      const batch = this.messageParser.parse(messages, this.schema);
+      if (batch.length > 0) {
+        const lastMessage = batch[batch.length - 1];
+        if (((_b = lastMessage.headers) == null ? void 0 : _b[`control`]) === `up-to-date` && !this.isUpToDate) {
+          this.isUpToDate = true;
+          this.notifyUpToDateSubscribers();
+        }
+        this.publish(batch);
+      }
+    }
+  }
+  subscribe(callback, onError) {
+    const subscriptionId = Math.random();
+    const subscriber = new MessageProcessor(callback);
+    this.subscribers.set(subscriptionId, [subscriber, onError]);
+    return () => {
+      this.subscribers.delete(subscriptionId);
+    };
+  }
+  unsubscribeAll() {
+    this.subscribers.clear();
+  }
+  publish(messages) {
+    this.subscribers.forEach(([subscriber, _]) => {
+      subscriber.process(messages);
+    });
+  }
+  sendErrorToSubscribers(error) {
+    this.subscribers.forEach(([_, errorFn]) => {
+      errorFn == null ? void 0 : errorFn(error);
+    });
+  }
+  subscribeOnceToUpToDate(callback, error) {
+    const subscriptionId = Math.random();
+    this.upToDateSubscribers.set(subscriptionId, [callback, error]);
+    return () => {
+      this.upToDateSubscribers.delete(subscriptionId);
+    };
+  }
+  unsubscribeAllUpToDateSubscribers() {
+    this.upToDateSubscribers.clear();
+  }
+  notifyUpToDateSubscribers() {
+    this.upToDateSubscribers.forEach(([callback]) => {
+      callback();
+    });
+  }
+  sendErrorToUpToDateSubscribers(error) {
+    this.upToDateSubscribers.forEach(
+      ([_, errorCallback]) => errorCallback(error)
+    );
+  }
+  /**
+   * Resets the state of the stream, optionally with a provided
+   * shape ID
+   */
+  reset(shapeId) {
+    this.lastOffset = `-1`;
+    this.shapeId = shapeId;
+    this.isUpToDate = false;
+    this.schema = void 0;
+  }
+  validateOptions(options) {
+    if (!options.url) {
+      throw new Error(`Invalid shape option. It must provide the url`);
+    }
+    if (options.signal && !(options.signal instanceof AbortSignal)) {
+      throw new Error(
+        `Invalid signal option. It must be an instance of AbortSignal.`
+      );
+    }
+    if (options.offset !== void 0 && options.offset !== `-1` && !options.shapeId) {
+      throw new Error(
+        `shapeId is required if this isn't an initial fetch (i.e. offset > -1)`
+      );
+    }
+  }
+  async fetchWithBackoff(url) {
+    const { initialDelay, maxDelay, multiplier } = this.backoffOptions;
+    const signal = this.options.signal;
+    let delay = initialDelay;
+    let attempt = 0;
+    while (true) {
+      try {
+        const result = await this.fetchClient(url.toString(), { signal });
+        if (result.ok) return result;
+        else throw await FetchError.fromResponse(result, url.toString());
+      } catch (e) {
+        if (signal == null ? void 0 : signal.aborted) {
+          return void 0;
+        } else if (e instanceof FetchError && e.status >= 400 && e.status < 500) {
+          throw e;
+        } else {
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          delay = Math.min(delay * multiplier, maxDelay);
+          attempt++;
+          console.log(`Retry attempt #${attempt} after ${delay}ms`);
+        }
+      }
+    }
+  }
+};
+var Shape = class {
+  constructor(stream) {
+    this.data = /* @__PURE__ */ new Map();
+    this.subscribers = /* @__PURE__ */ new Map();
+    this.error = false;
+    this.hasNotifiedSubscribersUpToDate = false;
+    this.stream = stream;
+    this.stream.subscribe(this.process.bind(this), this.handleError.bind(this));
+    const unsubscribe = this.stream.subscribeOnceToUpToDate(
+      () => {
+        unsubscribe();
+      },
+      (e) => {
+        this.handleError(e);
+        throw e;
+      }
+    );
+  }
+  get isUpToDate() {
+    return this.stream.isUpToDate;
+  }
+  get value() {
+    return new Promise((resolve) => {
+      if (this.stream.isUpToDate) {
+        resolve(this.valueSync);
+      } else {
+        const unsubscribe = this.stream.subscribeOnceToUpToDate(
+          () => {
+            unsubscribe();
+            resolve(this.valueSync);
+          },
+          (e) => {
+            throw e;
+          }
+        );
+      }
+    });
+  }
+  get valueSync() {
+    return this.data;
+  }
+  subscribe(callback) {
+    const subscriptionId = Math.random();
+    this.subscribers.set(subscriptionId, callback);
+    return () => {
+      this.subscribers.delete(subscriptionId);
+    };
+  }
+  unsubscribeAll() {
+    this.subscribers.clear();
+  }
+  get numSubscribers() {
+    return this.subscribers.size;
+  }
+  process(messages) {
+    let dataMayHaveChanged = false;
+    let isUpToDate = false;
+    let newlyUpToDate = false;
+    messages.forEach((message) => {
+      var _a, _b;
+      if (`key` in message) {
+        dataMayHaveChanged = [`insert`, `update`, `delete`].includes(
+          message.headers.action
+        );
+        switch (message.headers.action) {
+          case `insert`:
+            this.data.set(message.key, message.value);
+            break;
+          case `update`:
+            this.data.set(message.key, __spreadValues(__spreadValues({}, this.data.get(message.key)), message.value));
+            break;
+          case `delete`:
+            this.data.delete(message.key);
+            break;
+        }
+      }
+      if (((_a = message.headers) == null ? void 0 : _a[`control`]) === `up-to-date`) {
+        isUpToDate = true;
+        if (!this.hasNotifiedSubscribersUpToDate) {
+          newlyUpToDate = true;
+        }
+      }
+      if (((_b = message.headers) == null ? void 0 : _b[`control`]) === `must-refetch`) {
+        this.data.clear();
+        this.error = false;
+        isUpToDate = false;
+        newlyUpToDate = false;
+      }
+    });
+    if (newlyUpToDate || isUpToDate && dataMayHaveChanged) {
+      this.hasNotifiedSubscribersUpToDate = true;
+      this.notify();
+    }
+  }
+  handleError(e) {
+    if (e instanceof FetchError) {
+      this.error = e;
+    }
+  }
+  notify() {
+    this.subscribers.forEach((callback) => {
+      callback(this.valueSync);
+    });
+  }
+};
+export {
+  BackoffDefaults,
+  FetchError,
+  Shape,
+  ShapeStream
+};
+//# sourceMappingURL=index.legacy-esm.js.map