@powersync/common 0.0.0-dev-20260202162549 → 0.0.0-dev-20260202163643

package/lib/index.d.ts

@@ -0,0 +1,62 @@
+export * from './attachments/AttachmentContext.js';
+export * from './attachments/AttachmentErrorHandler.js';
+export * from './attachments/AttachmentQueue.js';
+export * from './attachments/AttachmentService.js';
+export * from './attachments/LocalStorageAdapter.js';
+export * from './attachments/RemoteStorageAdapter.js';
+export * from './attachments/Schema.js';
+export * from './attachments/SyncingService.js';
+export * from './attachments/WatchedAttachmentItem.js';
+export * from './client/AbstractPowerSyncDatabase.js';
+export * from './client/AbstractPowerSyncOpenFactory.js';
+export { compilableQueryWatch, CompilableQueryWatchHandler } from './client/compilableQueryWatch.js';
+export * from './client/connection/PowerSyncBackendConnector.js';
+export * from './client/connection/PowerSyncCredentials.js';
+export { MAX_OP_ID } from './client/constants.js';
+export { runOnSchemaChange } from './client/runOnSchemaChange.js';
+export * from './client/SQLOpenFactory.js';
+export * from './client/sync/bucket/BucketStorageAdapter.js';
+export * from './client/sync/bucket/CrudBatch.js';
+export { CrudEntry, OpId, UpdateType } from './client/sync/bucket/CrudEntry.js';
+export * from './client/sync/bucket/CrudTransaction.js';
+export * from './client/sync/bucket/OplogEntry.js';
+export * from './client/sync/bucket/OpType.js';
+export * from './client/sync/bucket/SqliteBucketStorage.js';
+export * from './client/sync/bucket/SyncDataBatch.js';
+export * from './client/sync/bucket/SyncDataBucket.js';
+export * from './client/sync/stream/AbstractRemote.js';
+export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
+export * from './client/sync/stream/streaming-sync-types.js';
+export * from './client/sync/sync-streams.js';
+export * from './client/ConnectionManager.js';
+export * from './db/ConnectionClosedError.js';
+export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
+export * from './db/crud/SyncStatus.js';
+export * from './db/crud/UploadQueueStatus.js';
+export * from './db/DBAdapter.js';
+export * from './db/schema/Column.js';
+export * from './db/schema/Index.js';
+export * from './db/schema/IndexedColumn.js';
+export * from './db/schema/RawTable.js';
+export * from './db/schema/Schema.js';
+export * from './db/schema/Table.js';
+export * from './db/schema/TableV2.js';
+export * from './client/Query.js';
+export { MEMORY_TRIGGER_CLAIM_MANAGER } from './client/triggers/MemoryTriggerClaimManager.js';
+export * from './client/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
+export { TriggerManagerImpl } from './client/triggers/TriggerManagerImpl.js';
+export * from './client/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
+export * from './utils/AbortOperation.js';
+export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
+export * from './utils/DataStream.js';
+export * from './utils/Logger.js';
+export * from './utils/mutex.js';
+export * from './utils/parseQuery.js';
+export * from './types/types.js';

package/lib/index.js

@@ -0,0 +1,63 @@
+export * from './attachments/AttachmentContext.js';
+export * from './attachments/AttachmentErrorHandler.js';
+export * from './attachments/AttachmentQueue.js';
+export * from './attachments/AttachmentService.js';
+export * from './attachments/LocalStorageAdapter.js';
+export * from './attachments/RemoteStorageAdapter.js';
+export * from './attachments/Schema.js';
+export * from './attachments/SyncingService.js';
+export * from './attachments/WatchedAttachmentItem.js';
+export * from './client/AbstractPowerSyncDatabase.js';
+export * from './client/AbstractPowerSyncOpenFactory.js';
+export { compilableQueryWatch } from './client/compilableQueryWatch.js';
+export * from './client/connection/PowerSyncBackendConnector.js';
+export * from './client/connection/PowerSyncCredentials.js';
+export { MAX_OP_ID } from './client/constants.js';
+export { runOnSchemaChange } from './client/runOnSchemaChange.js';
+export * from './client/SQLOpenFactory.js';
+export * from './client/sync/bucket/BucketStorageAdapter.js';
+export * from './client/sync/bucket/CrudBatch.js';
+export { CrudEntry, UpdateType } from './client/sync/bucket/CrudEntry.js';
+export * from './client/sync/bucket/CrudTransaction.js';
+export * from './client/sync/bucket/OplogEntry.js';
+export * from './client/sync/bucket/OpType.js';
+export * from './client/sync/bucket/SqliteBucketStorage.js';
+export * from './client/sync/bucket/SyncDataBatch.js';
+export * from './client/sync/bucket/SyncDataBucket.js';
+export * from './client/sync/stream/AbstractRemote.js';
+export * from './client/sync/stream/AbstractStreamingSyncImplementation.js';
+export * from './client/sync/stream/streaming-sync-types.js';
+export * from './client/sync/sync-streams.js';
+export * from './client/ConnectionManager.js';
+export * from './db/ConnectionClosedError.js';
+export { SyncProgress } from './db/crud/SyncProgress.js';
+export * from './db/crud/SyncStatus.js';
+export * from './db/crud/UploadQueueStatus.js';
+export * from './db/DBAdapter.js';
+export * from './db/schema/Column.js';
+export * from './db/schema/Index.js';
+export * from './db/schema/IndexedColumn.js';
+export * from './db/schema/RawTable.js';
+export * from './db/schema/Schema.js';
+export * from './db/schema/Table.js';
+export * from './db/schema/TableV2.js';
+export * from './client/Query.js';
+export { MEMORY_TRIGGER_CLAIM_MANAGER } from './client/triggers/MemoryTriggerClaimManager.js';
+export * from './client/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
+export { TriggerManagerImpl } from './client/triggers/TriggerManagerImpl.js';
+export * from './client/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
+export * from './utils/AbortOperation.js';
+export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
+export * from './utils/DataStream.js';
+export * from './utils/Logger.js';
+export * from './utils/mutex.js';
+export * from './utils/parseQuery.js';
+export * from './types/types.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,wCAAwC,CAAC;AAEvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8CAA8C,CAAC;AAC7D,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAE,SAAS,EAAQ,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC;AAE9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAA0B,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACjF,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,4BAA4B,EAAE,MAAM,gDAAgD,CAAC;AAC9F,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,cAAc,iCAAiC,CAAC;AAChD,cAAc,uDAAuD,CAAC;AACtE,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAEjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,kBAAkB,CAAC"}

package/lib/types/types.d.ts

@@ -0,0 +1,8 @@
+export interface CompilableQuery<T> {
+    execute(): Promise<T[]>;
+    compile(): CompiledQuery;
+}
+export interface CompiledQuery {
+    readonly sql: string;
+    readonly parameters: ReadonlyArray<unknown>;
+}

package/lib/types/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types/types.ts"],"names":[],"mappings":""}

package/lib/utils/AbortOperation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calls to Abortcontroller.abort(reason: any) will result in the
+ * `reason` being thrown. This is not necessarily an error,
+ *  but extends error for better logging purposes.
+ */
+export declare class AbortOperation extends Error {
+    protected reason: string;
+    constructor(reason: string);
+}

package/lib/utils/AbortOperation.js

@@ -0,0 +1,19 @@
+/**
+ * Calls to Abortcontroller.abort(reason: any) will result in the
+ * `reason` being thrown. This is not necessarily an error,
+ *  but extends error for better logging purposes.
+ */
+export class AbortOperation extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        // Set the prototype explicitly
+        Object.setPrototypeOf(this, AbortOperation.prototype);
+        // Capture stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AbortOperation);
+        }
+    }
+}
+//# sourceMappingURL=AbortOperation.js.map

package/lib/utils/AbortOperation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbortOperation.js","sourceRoot":"","sources":["../../src/utils/AbortOperation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACjB;IAAtB,YAAsB,MAAc;QAClC,KAAK,CAAC,MAAM,CAAC,CAAC;QADM,WAAM,GAAN,MAAM,CAAQ;QAElC,+BAA+B;QAC/B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;QAEtD,sBAAsB;QACtB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;CACF"}

package/lib/utils/BaseObserver.d.ts

@@ -0,0 +1,18 @@
+export interface Disposable {
+    dispose: () => Promise<void> | void;
+}
+export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
+export interface BaseObserverInterface<T extends BaseListener> {
+    registerListener(listener: Partial<T>): () => void;
+}
+export declare class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
+    protected listeners: Set<Partial<T>>;
+    constructor();
+    dispose(): void;
+    /**
+     * Register a listener for updates to the PowerSync client.
+     */
+    registerListener(listener: Partial<T>): () => void;
+    iterateListeners(cb: (listener: Partial<T>) => any): void;
+    iterateAsyncListeners(cb: (listener: Partial<T>) => Promise<any>): Promise<void>;
+}

package/lib/utils/BaseObserver.js

@@ -0,0 +1,27 @@
+export class BaseObserver {
+    listeners = new Set();
+    constructor() { }
+    dispose() {
+        this.listeners.clear();
+    }
+    /**
+     * Register a listener for updates to the PowerSync client.
+     */
+    registerListener(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    iterateListeners(cb) {
+        for (const listener of this.listeners) {
+            cb(listener);
+        }
+    }
+    async iterateAsyncListeners(cb) {
+        for (let i of Array.from(this.listeners.values())) {
+            await cb(i);
+        }
+    }
+}
+//# sourceMappingURL=BaseObserver.js.map

package/lib/utils/BaseObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseObserver.js","sourceRoot":"","sources":["../../src/utils/BaseObserver.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,YAAY;IACb,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAE5C,gBAAe,CAAC;IAEhB,OAAO;QACL,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,QAAoB;QACnC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,gBAAgB,CAAC,EAAiC;QAChD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,EAAE,CAAC,QAAQ,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,EAA0C;QACpE,KAAK,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YAClD,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/lib/utils/ControlledExecutor.d.ts

@@ -0,0 +1,25 @@
+export interface ControlledExecutorOptions {
+    /**
+     * If throttling is enabled, it ensures only one task runs at a time,
+     * and only one additional task can be scheduled to run after the current task completes. The pending task will be overwritten by the latest task.
+     * Enabled by default.
+     */
+    throttleEnabled?: boolean;
+}
+export declare class ControlledExecutor<T> {
+    private task;
+    /**
+     * Represents the currently running task, which could be a Promise or undefined if no task is running.
+     */
+    private runningTask;
+    private pendingTaskParam;
+    /**
+     * Flag to determine if throttling is enabled, which controls whether tasks are queued or run immediately.
+     */
+    private isThrottling;
+    private closed;
+    constructor(task: (param: T) => Promise<void> | void, options?: ControlledExecutorOptions);
+    schedule(param: T): void;
+    dispose(): void;
+    private execute;
+}

package/lib/utils/ControlledExecutor.js

@@ -0,0 +1,51 @@
+export class ControlledExecutor {
+    task;
+    /**
+     * Represents the currently running task, which could be a Promise or undefined if no task is running.
+     */
+    runningTask;
+    pendingTaskParam;
+    /**
+     * Flag to determine if throttling is enabled, which controls whether tasks are queued or run immediately.
+     */
+    isThrottling;
+    closed;
+    constructor(task, options) {
+        this.task = task;
+        const { throttleEnabled = true } = options ?? {};
+        this.isThrottling = throttleEnabled;
+        this.closed = false;
+    }
+    schedule(param) {
+        if (this.closed) {
+            return;
+        }
+        if (!this.isThrottling) {
+            this.task(param);
+            return;
+        }
+        if (this.runningTask) {
+            // set or replace the pending task param with latest one
+            this.pendingTaskParam = param;
+            return;
+        }
+        this.execute(param);
+    }
+    dispose() {
+        this.closed = true;
+        if (this.runningTask) {
+            this.runningTask = undefined;
+        }
+    }
+    async execute(param) {
+        this.runningTask = this.task(param);
+        await this.runningTask;
+        this.runningTask = undefined;
+        if (this.pendingTaskParam) {
+            const pendingParam = this.pendingTaskParam;
+            this.pendingTaskParam = undefined;
+            this.execute(pendingParam);
+        }
+    }
+}
+//# sourceMappingURL=ControlledExecutor.js.map

package/lib/utils/ControlledExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ControlledExecutor.js","sourceRoot":"","sources":["../../src/utils/ControlledExecutor.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,kBAAkB;IACrB,IAAI,CAAqC;IAEjD;;OAEG;IACK,WAAW,CAAqC;IAEhD,gBAAgB,CAAgB;IAExC;;OAEG;IACK,YAAY,CAAU;IAEtB,MAAM,CAAU;IAExB,YAAY,IAAwC,EAAE,OAAmC;QACvF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,EAAE,eAAe,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QACjD,IAAI,CAAC,YAAY,GAAG,eAAe,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,QAAQ,CAAC,KAAQ;QACf,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,wDAAwD;YACxD,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC;YAC9B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QAEnB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,KAAQ;QAC5B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,IAAI,CAAC,WAAW,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAE7B,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,CAAC;YAC3C,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;YAElC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;CACF"}

package/lib/utils/DataStream.d.ts

@@ -0,0 +1,62 @@
+import { ILogger } from 'js-logger';
+import { BaseListener, BaseObserver } from './BaseObserver.js';
+export type DataStreamOptions<ParsedData, SourceData> = {
+    mapLine?: (line: SourceData) => ParsedData;
+    /**
+     * Close the stream if any consumer throws an error
+     */
+    closeOnError?: boolean;
+    pressure?: {
+        highWaterMark?: number;
+        lowWaterMark?: number;
+    };
+    logger?: ILogger;
+};
+export type DataStreamCallback<Data extends any = any> = (data: Data) => Promise<void>;
+export interface DataStreamListener<Data extends any = any> extends BaseListener {
+    data: (data: Data) => Promise<void>;
+    closed: () => void;
+    error: (error: Error) => void;
+    highWater: () => Promise<void>;
+    lowWater: () => Promise<void>;
+}
+export declare const DEFAULT_PRESSURE_LIMITS: {
+    highWater: number;
+    lowWater: number;
+};
+/**
+ * A very basic implementation of a data stream with backpressure support which does not use
+ * native JS streams or async iterators.
+ * This is handy for environments such as React Native which need polyfills for the above.
+ */
+export declare class DataStream<ParsedData, SourceData = any> extends BaseObserver<DataStreamListener<ParsedData>> {
+    protected options?: DataStreamOptions<ParsedData, SourceData> | undefined;
+    dataQueue: SourceData[];
+    protected isClosed: boolean;
+    protected processingPromise: Promise<void> | null;
+    protected notifyDataAdded: (() => void) | null;
+    protected logger: ILogger;
+    protected mapLine: (line: SourceData) => ParsedData;
+    constructor(options?: DataStreamOptions<ParsedData, SourceData> | undefined);
+    get highWatermark(): number;
+    get lowWatermark(): number;
+    get closed(): boolean;
+    close(): Promise<void>;
+    /**
+     * Enqueues data for the consumers to read
+     */
+    enqueueData(data: SourceData): void;
+    /**
+     * Reads data once from the data stream
+     * @returns a Data payload or Null if the stream closed.
+     */
+    read(): Promise<ParsedData | null>;
+    /**
+     * Executes a callback for each data item in the stream
+     */
+    forEach(callback: DataStreamCallback<ParsedData>): () => void;
+    protected processQueue(): Promise<void> | undefined;
+    protected hasDataReader(): boolean;
+    protected _processQueue(): Promise<void>;
+    protected iterateAsyncErrored(cb: (l: Partial<DataStreamListener<ParsedData>>) => Promise<void>): Promise<void>;
+}

package/lib/utils/DataStream.js

@@ -0,0 +1,169 @@
+import Logger from 'js-logger';
+import { BaseObserver } from './BaseObserver.js';
+export const DEFAULT_PRESSURE_LIMITS = {
+    highWater: 10,
+    lowWater: 0
+};
+/**
+ * A very basic implementation of a data stream with backpressure support which does not use
+ * native JS streams or async iterators.
+ * This is handy for environments such as React Native which need polyfills for the above.
+ */
+export class DataStream extends BaseObserver {
+    options;
+    dataQueue;
+    isClosed;
+    processingPromise;
+    notifyDataAdded;
+    logger;
+    mapLine;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.processingPromise = null;
+        this.isClosed = false;
+        this.dataQueue = [];
+        this.mapLine = options?.mapLine ?? ((line) => line);
+        this.logger = options?.logger ?? Logger.get('DataStream');
+        if (options?.closeOnError) {
+            const l = this.registerListener({
+                error: (ex) => {
+                    l?.();
+                    this.close();
+                }
+            });
+        }
+    }
+    get highWatermark() {
+        return this.options?.pressure?.highWaterMark ?? DEFAULT_PRESSURE_LIMITS.highWater;
+    }
+    get lowWatermark() {
+        return this.options?.pressure?.lowWaterMark ?? DEFAULT_PRESSURE_LIMITS.lowWater;
+    }
+    get closed() {
+        return this.isClosed;
+    }
+    async close() {
+        this.isClosed = true;
+        await this.processingPromise;
+        this.iterateListeners((l) => l.closed?.());
+        // Discard any data in the queue
+        this.dataQueue = [];
+        this.listeners.clear();
+    }
+    /**
+     * Enqueues data for the consumers to read
+     */
+    enqueueData(data) {
+        if (this.isClosed) {
+            throw new Error('Cannot enqueue data into closed stream.');
+        }
+        this.dataQueue.push(data);
+        this.notifyDataAdded?.();
+        this.processQueue();
+    }
+    /**
+     * Reads data once from the data stream
+     * @returns a Data payload or Null if the stream closed.
+     */
+    async read() {
+        if (this.closed) {
+            return null;
+        }
+        // Wait for any pending processing to complete first.
+        // This ensures we register our listener before calling processQueue(),
+        // avoiding a race where processQueue() sees no reader and returns early.
+        if (this.processingPromise) {
+            await this.processingPromise;
+        }
+        // Re-check after await - stream may have closed while we were waiting
+        if (this.closed) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const l = this.registerListener({
+                data: async (data) => {
+                    resolve(data);
+                    // Remove the listener
+                    l?.();
+                },
+                closed: () => {
+                    resolve(null);
+                    l?.();
+                },
+                error: (ex) => {
+                    reject(ex);
+                    l?.();
+                }
+            });
+            this.processQueue();
+        });
+    }
+    /**
+     * Executes a callback for each data item in the stream
+     */
+    forEach(callback) {
+        if (this.dataQueue.length <= this.lowWatermark) {
+            this.iterateAsyncErrored(async (l) => l.lowWater?.());
+        }
+        return this.registerListener({
+            data: callback
+        });
+    }
+    processQueue() {
+        if (this.processingPromise) {
+            return;
+        }
+        const promise = (this.processingPromise = this._processQueue());
+        promise.finally(() => {
+            this.processingPromise = null;
+        });
+        return promise;
+    }
+    hasDataReader() {
+        return Array.from(this.listeners.values()).some((l) => !!l.data);
+    }
+    async _processQueue() {
+        /**
+         * Allow listeners to mutate the queue before processing.
+         * This allows for operations such as dropping or compressing data
+         * on high water or requesting more data on low water.
+         */
+        if (this.dataQueue.length >= this.highWatermark) {
+            await this.iterateAsyncErrored(async (l) => l.highWater?.());
+        }
+        if (this.isClosed || !this.hasDataReader()) {
+            return;
+        }
+        if (this.dataQueue.length) {
+            const data = this.dataQueue.shift();
+            const mapped = this.mapLine(data);
+            await this.iterateAsyncErrored(async (l) => l.data?.(mapped));
+        }
+        if (this.dataQueue.length <= this.lowWatermark) {
+            const dataAdded = new Promise((resolve) => {
+                this.notifyDataAdded = resolve;
+            });
+            await Promise.race([this.iterateAsyncErrored(async (l) => l.lowWater?.()), dataAdded]);
+            this.notifyDataAdded = null;
+        }
+        if (this.dataQueue.length > 0) {
+            setTimeout(() => this.processQueue());
+        }
+    }
+    async iterateAsyncErrored(cb) {
+        // Important: We need to copy the listeners, as calling a listener could result in adding another
+        // listener, resulting in infinite loops.
+        const listeners = Array.from(this.listeners.values());
+        for (let i of listeners) {
+            try {
+                await cb(i);
+            }
+            catch (ex) {
+                this.logger.error(ex);
+                this.iterateListeners((l) => l.error?.(ex));
+            }
+        }
+    }
+}
+//# sourceMappingURL=DataStream.js.map

package/lib/utils/DataStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataStream.js","sourceRoot":"","sources":["../../src/utils/DataStream.ts"],"names":[],"mappings":"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"}

package/lib/utils/Logger.d.ts

@@ -0,0 +1,31 @@
+import Logger, { type ILogger, type ILogLevel } from 'js-logger';
+export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-logger';
+export declare const LogLevel: {
+    TRACE: Logger.ILogLevel;
+    DEBUG: Logger.ILogLevel;
+    INFO: Logger.ILogLevel;
+    TIME: Logger.ILogLevel;
+    WARN: Logger.ILogLevel;
+    ERROR: Logger.ILogLevel;
+    OFF: Logger.ILogLevel;
+};
+export interface CreateLoggerOptions {
+    logLevel?: ILogLevel;
+}
+/**
+ * Retrieves the base (default) logger instance.
+ *
+ * This base logger controls the default logging configuration and is shared
+ * across all loggers created with `createLogger`. Adjusting settings on this
+ * base logger affects all loggers derived from it unless explicitly overridden.
+ *
+ */
+export declare function createBaseLogger(): typeof Logger;
+/**
+ * Creates and configures a new named logger based on the base logger.
+ *
+ * Named loggers allow specific modules or areas of your application to have
+ * their own logging levels and behaviors. These loggers inherit configuration
+ * from the base logger by default but can override settings independently.
+ */
+export declare function createLogger(name: string, options?: CreateLoggerOptions): ILogger;

package/lib/utils/Logger.js

@@ -0,0 +1,37 @@
+import Logger from 'js-logger';
+const TypedLogger = Logger;
+export const LogLevel = {
+    TRACE: TypedLogger.TRACE,
+    DEBUG: TypedLogger.DEBUG,
+    INFO: TypedLogger.INFO,
+    TIME: TypedLogger.TIME,
+    WARN: TypedLogger.WARN,
+    ERROR: TypedLogger.ERROR,
+    OFF: TypedLogger.OFF
+};
+/**
+ * Retrieves the base (default) logger instance.
+ *
+ * This base logger controls the default logging configuration and is shared
+ * across all loggers created with `createLogger`. Adjusting settings on this
+ * base logger affects all loggers derived from it unless explicitly overridden.
+ *
+ */
+export function createBaseLogger() {
+    return Logger;
+}
+/**
+ * Creates and configures a new named logger based on the base logger.
+ *
+ * Named loggers allow specific modules or areas of your application to have
+ * their own logging levels and behaviors. These loggers inherit configuration
+ * from the base logger by default but can override settings independently.
+ */
+export function createLogger(name, options = {}) {
+    const logger = Logger.get(name);
+    if (options.logLevel) {
+        logger.setLevel(options.logLevel);
+    }
+    return logger;
+}
+//# sourceMappingURL=Logger.js.map

package/lib/utils/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../../src/utils/Logger.ts"],"names":[],"mappings":"AAAA,OAAO,MAAwC,MAAM,WAAW,CAAC;AAIjE,MAAM,WAAW,GAAY,MAAa,CAAC;AAE3C,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,KAAK,EAAE,WAAW,CAAC,KAAK;IACxB,KAAK,EAAE,WAAW,CAAC,KAAK;IACxB,IAAI,EAAE,WAAW,CAAC,IAAI;IACtB,IAAI,EAAE,WAAW,CAAC,IAAI;IACtB,IAAI,EAAE,WAAW,CAAC,IAAI;IACtB,KAAK,EAAE,WAAW,CAAC,KAAK;IACxB,GAAG,EAAE,WAAW,CAAC,GAAG;CACrB,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAA+B,EAAE;IAC1E,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}