@milaboratories/pl-model-common 1.21.3 → 1.21.4

package/dist/drivers/ChunkedStreamReader.cjs

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * ChunkedStreamReader creates a ReadableStream that reads data from a blob driver
+ * in fixed-size chunks. This is useful for streaming large files without loading
+ * them entirely into memory.
+ */
+class ChunkedStreamReader {
+    currentPosition = 0;
+    _read = true;
+    _canceled = false;
+    _errored = false;
+    abortController = null;
+    options;
+    /**
+     * Creates a new ChunkedStreamReader instance.
+     * Use the static `create` method instead.
+     */
+    constructor(options) {
+        // Normalize options with defaults
+        this.options = {
+            ...options,
+            chunkSize: options.chunkSize ?? 16 * 1024 * 1024,
+            onError: options.onError ?? (async () => {
+                // Default behavior: error (will automatically call controller.error)
+                return 'error';
+            }),
+        };
+        if (this.totalSize < 0) {
+            throw new Error('Total size must be non-negative');
+        }
+        if (this.chunkSize <= 0) {
+            throw new Error('Chunk size must be positive');
+        }
+    }
+    /**
+     * Gets the fetchChunk function from options
+     */
+    get fetchChunk() {
+        return this.options.fetchChunk;
+    }
+    /**
+     * Gets the total size from options
+     */
+    get totalSize() {
+        return this.options.totalSize;
+    }
+    /**
+     * Gets the chunk size from options
+     */
+    get chunkSize() {
+        return this.options.chunkSize;
+    }
+    /**
+     * Gets the onError callback from options
+     */
+    get onError() {
+        return this.options.onError;
+    }
+    /**
+     * Creates and returns a ReadableStream that reads data in chunks.
+     *
+     * @param options - Configuration options for the chunked stream reader
+     * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+     *
+     * @example
+     * ```typescript
+     * const stream = ChunkedStreamReader.create({
+     *   fetchChunk: async (range, signal) => {
+     *     const response = await fetch(`/api/data?from=${range.from}&to=${range.to}`, { signal });
+     *     return new Uint8Array(await response.arrayBuffer());
+     *   },
+     *   totalSize: 1024 * 1024, // 1MB
+     *   chunkSize: 64 * 1024,   // 64KB chunks
+     * });
+     * ```
+     */
+    static create(options) {
+        const reader = new ChunkedStreamReader(options);
+        return reader.createStream();
+    }
+    readStart() {
+        this._read = true;
+    }
+    readStop() {
+        this._read = false;
+    }
+    async tryRead(controller) {
+        if (this._canceled) {
+            return true;
+        }
+        // Check if we've read all data
+        if (this.isComplete()) {
+            controller.close();
+            return true;
+        }
+        try {
+            // Calculate the end position for this chunk
+            // Ensure we don't read beyond the total size
+            const endPosition = Math.min(this.currentPosition + this.chunkSize, this.totalSize);
+            // Fetch the chunk from the blob driver, passing the abort signal if available
+            const data = await this.fetchChunk({ from: this.currentPosition, to: endPosition }, this.abortController?.signal);
+            // Check if stream was cancelled during the fetch
+            if (this._canceled) {
+                return true;
+            }
+            // Enqueue the data into the stream
+            controller.enqueue(data);
+            // Update the current position for the next chunk
+            this.currentPosition = endPosition;
+            if (!controller.desiredSize || controller.desiredSize <= 0) {
+                // The internal queue is full, so propagate
+                // the backpressure signal to the underlying source.
+                this.readStop();
+            }
+        }
+        catch (error) {
+            // If any error occurs during chunk reading, call the error handler
+            const status = await this.onError(error);
+            if (status === 'error') {
+                this._errored = true;
+                // Error the stream and abort any ongoing fetch operations
+                controller.error(error);
+                this.abortController?.abort('Stream errored');
+                return true; // Stop reading
+            }
+            if (status === 'cancel') {
+                this._canceled = true;
+                // Close the stream gracefully and abort any ongoing fetch operations
+                controller.close();
+                this.abortController?.abort('Stream cancelled');
+                console.debug('ChunkedStreamReader cancelled due to error');
+                return true; // Stop reading
+            }
+        }
+        return false;
+    }
+    /**
+     * Creates and returns a ReadableStream that reads data in chunks.
+     * The stream will automatically close when all data has been read.
+     *
+     * @private - Use the static `create` method instead
+     * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+     */
+    createStream() {
+        // Create an AbortController for this stream
+        this.abortController = new AbortController();
+        return new ReadableStream({
+            start: async (controller) => {
+                while (true) {
+                    if (this._canceled || this._errored) {
+                        return;
+                    }
+                    if (!this._read) {
+                        await new Promise((r) => setTimeout(r, 0));
+                        if (controller.desiredSize) {
+                            this.readStart();
+                        }
+                    }
+                    else {
+                        const isDone = await this.tryRead(controller);
+                        if (isDone) {
+                            return;
+                        }
+                    }
+                }
+            },
+            pull: () => {
+                this.readStart();
+            },
+            cancel: (reason) => {
+                this._canceled = true;
+                // Abort any ongoing fetch operations
+                this.abortController?.abort(reason);
+                console.debug('ChunkedStreamReader cancelled:', reason);
+            },
+        });
+    }
+    /**
+     * Gets the current reading position in bytes.
+     *
+     * @returns Current position as number of bytes read
+     */
+    getCurrentPosition() {
+        return this.currentPosition;
+    }
+    /**
+     * Gets the remaining bytes to be read.
+     *
+     * @returns Number of bytes remaining
+     */
+    getRemainingBytes() {
+        return Math.max(0, this.totalSize - this.currentPosition);
+    }
+    /**
+     * Checks if the entire blob has been read.
+     *
+     * @returns True if all data has been read
+     */
+    isComplete() {
+        return this.currentPosition >= this.totalSize;
+    }
+}
+
+exports.ChunkedStreamReader = ChunkedStreamReader;
+//# sourceMappingURL=ChunkedStreamReader.cjs.map

package/dist/drivers/ChunkedStreamReader.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChunkedStreamReader.cjs","sources":["../../src/drivers/ChunkedStreamReader.ts"],"sourcesContent":["import type { RangeBytes } from './blob';\n\n/**\n * Status returned by onError handler to indicate what action to take\n * - 'continue': Retry the failed operation\n * - 'error': Error the stream (calls controller.error, aborts ongoing fetches)\n * - 'cancel': Cancel the stream gracefully (calls controller.close, aborts ongoing fetches)\n */\nexport type ErrorHandlerStatus = 'continue' | 'error' | 'cancel';\n\n/**\n * Options for creating a ChunkedStreamReader\n */\nexport interface ChunkedStreamReaderOptions {\n  /**\n   * Function to fetch a chunk of data. Optionally accepts an AbortSignal to cancel the fetch.\n   */\n  fetchChunk: (range: RangeBytes, signal?: AbortSignal) => Promise<Uint8Array>;\n\n  /**\n   * Total size of the blob in bytes\n   */\n  totalSize: number;\n\n  /**\n   * Size of each chunk to read in bytes (default: 16MB)\n   */\n  chunkSize?: number;\n\n  /**\n   * Error handler callback. Called when an error occurs during chunk fetching.\n   * Should return:\n   * - 'continue' to retry the operation\n   * - 'error' to error the stream (will call controller.error and abort ongoing fetches)\n   * - 'cancel' to cancel gracefully (will call controller.close and abort ongoing fetches)\n   * Default behavior: returns 'error'.\n   */\n  onError?: (error: unknown) => Promise<ErrorHandlerStatus>;\n}\n\n/**\n * ChunkedStreamReader creates a ReadableStream that reads data from a blob driver\n * in fixed-size chunks. This is useful for streaming large files without loading\n * them entirely into memory.\n */\nexport class ChunkedStreamReader {\n  private currentPosition: number = 0;\n  private _read = true;\n  private _canceled = false;\n  private _errored = false;\n  private abortController: AbortController | null = null;\n  private readonly options: Required<ChunkedStreamReaderOptions>;\n\n  /**\n   * Creates a new ChunkedStreamReader instance.\n   * Use the static `create` method instead.\n   */\n  private constructor(options: ChunkedStreamReaderOptions) {\n    // Normalize options with defaults\n    this.options = {\n      ...options,\n      chunkSize: options.chunkSize ?? 16 * 1024 * 1024,\n      onError: options.onError ?? (async () => {\n        // Default behavior: error (will automatically call controller.error)\n        return 'error';\n      }),\n    };\n\n    if (this.totalSize < 0) {\n      throw new Error('Total size must be non-negative');\n    }\n    if (this.chunkSize <= 0) {\n      throw new Error('Chunk size must be positive');\n    }\n  }\n\n  /**\n   * Gets the fetchChunk function from options\n   */\n  private get fetchChunk() {\n    return this.options.fetchChunk;\n  }\n\n  /**\n   * Gets the total size from options\n   */\n  private get totalSize() {\n    return this.options.totalSize;\n  }\n\n  /**\n   * Gets the chunk size from options\n   */\n  private get chunkSize() {\n    return this.options.chunkSize;\n  }\n\n  /**\n   * Gets the onError callback from options\n   */\n  private get onError() {\n    return this.options.onError;\n  }\n\n  /**\n   * Creates and returns a ReadableStream that reads data in chunks.\n   *\n   * @param options - Configuration options for the chunked stream reader\n   * @returns ReadableStream that can be consumed by zip.add or other stream consumers\n   *\n   * @example\n   * ```typescript\n   * const stream = ChunkedStreamReader.create({\n   *   fetchChunk: async (range, signal) => {\n   *     const response = await fetch(`/api/data?from=${range.from}&to=${range.to}`, { signal });\n   *     return new Uint8Array(await response.arrayBuffer());\n   *   },\n   *   totalSize: 1024 * 1024, // 1MB\n   *   chunkSize: 64 * 1024,   // 64KB chunks\n   * });\n   * ```\n   */\n  static create(options: ChunkedStreamReaderOptions): ReadableStream<Uint8Array> {\n    const reader = new ChunkedStreamReader(options);\n    return reader.createStream();\n  }\n\n  private readStart() {\n    this._read = true;\n  }\n\n  private readStop() {\n    this._read = false;\n  }\n\n  private async tryRead(controller: ReadableStreamDefaultController<Uint8Array>): Promise<boolean> {\n    if (this._canceled) {\n      return true;\n    }\n\n    // Check if we've read all data\n    if (this.isComplete()) {\n      controller.close();\n      return true;\n    }\n\n    try {\n      // Calculate the end position for this chunk\n      // Ensure we don't read beyond the total size\n      const endPosition = Math.min(this.currentPosition + this.chunkSize, this.totalSize);\n\n      // Fetch the chunk from the blob driver, passing the abort signal if available\n      const data = await this.fetchChunk(\n        { from: this.currentPosition, to: endPosition },\n        this.abortController?.signal,\n      );\n\n      // Check if stream was cancelled during the fetch\n      if (this._canceled) {\n        return true;\n      }\n\n      // Enqueue the data into the stream\n      controller.enqueue(data);\n\n      // Update the current position for the next chunk\n      this.currentPosition = endPosition;\n\n      if (!controller.desiredSize || controller.desiredSize <= 0) {\n        // The internal queue is full, so propagate\n        // the backpressure signal to the underlying source.\n        this.readStop();\n      }\n    } catch (error) {\n      // If any error occurs during chunk reading, call the error handler\n      const status = await this.onError(error);\n\n      if (status === 'error') {\n        this._errored = true;\n        // Error the stream and abort any ongoing fetch operations\n        controller.error(error);\n        this.abortController?.abort('Stream errored');\n        return true; // Stop reading\n      }\n\n      if (status === 'cancel') {\n        this._canceled = true;\n        // Close the stream gracefully and abort any ongoing fetch operations\n        controller.close();\n        this.abortController?.abort('Stream cancelled');\n        console.debug('ChunkedStreamReader cancelled due to error');\n        return true; // Stop reading\n      }\n    }\n\n    return false;\n  }\n\n  /**\n   * Creates and returns a ReadableStream that reads data in chunks.\n   * The stream will automatically close when all data has been read.\n   *\n   * @private - Use the static `create` method instead\n   * @returns ReadableStream that can be consumed by zip.add or other stream consumers\n   */\n  private createStream(): ReadableStream<Uint8Array> {\n    // Create an AbortController for this stream\n    this.abortController = new AbortController();\n\n    return new ReadableStream({\n      start: async (controller) => {\n        while (true) {\n          if (this._canceled || this._errored) {\n            return;\n          }\n\n          if (!this._read) {\n            await new Promise((r) => setTimeout(r, 0));\n            if (controller.desiredSize) {\n              this.readStart();\n            }\n          } else {\n            const isDone = await this.tryRead(controller);\n            if (isDone) {\n              return;\n            }\n          }\n        }\n      },\n\n      pull: () => {\n        this.readStart();\n      },\n\n      cancel: (reason) => {\n        this._canceled = true;\n        // Abort any ongoing fetch operations\n        this.abortController?.abort(reason);\n        console.debug('ChunkedStreamReader cancelled:', reason);\n      },\n    });\n  }\n\n  /**\n   * Gets the current reading position in bytes.\n   *\n   * @returns Current position as number of bytes read\n   */\n  getCurrentPosition(): number {\n    return this.currentPosition;\n  }\n\n  /**\n   * Gets the remaining bytes to be read.\n   *\n   * @returns Number of bytes remaining\n   */\n  getRemainingBytes(): number {\n    return Math.max(0, this.totalSize - this.currentPosition);\n  }\n\n  /**\n   * Checks if the entire blob has been read.\n   *\n   * @returns True if all data has been read\n   */\n  isComplete(): boolean {\n    return this.currentPosition >= this.totalSize;\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/drivers/ChunkedStreamReader.d.ts

@@ -0,0 +1,117 @@
+import type { RangeBytes } from './blob';
+/**
+ * Status returned by onError handler to indicate what action to take
+ * - 'continue': Retry the failed operation
+ * - 'error': Error the stream (calls controller.error, aborts ongoing fetches)
+ * - 'cancel': Cancel the stream gracefully (calls controller.close, aborts ongoing fetches)
+ */
+export type ErrorHandlerStatus = 'continue' | 'error' | 'cancel';
+/**
+ * Options for creating a ChunkedStreamReader
+ */
+export interface ChunkedStreamReaderOptions {
+    /**
+     * Function to fetch a chunk of data. Optionally accepts an AbortSignal to cancel the fetch.
+     */
+    fetchChunk: (range: RangeBytes, signal?: AbortSignal) => Promise<Uint8Array>;
+    /**
+     * Total size of the blob in bytes
+     */
+    totalSize: number;
+    /**
+     * Size of each chunk to read in bytes (default: 16MB)
+     */
+    chunkSize?: number;
+    /**
+     * Error handler callback. Called when an error occurs during chunk fetching.
+     * Should return:
+     * - 'continue' to retry the operation
+     * - 'error' to error the stream (will call controller.error and abort ongoing fetches)
+     * - 'cancel' to cancel gracefully (will call controller.close and abort ongoing fetches)
+     * Default behavior: returns 'error'.
+     */
+    onError?: (error: unknown) => Promise<ErrorHandlerStatus>;
+}
+/**
+ * ChunkedStreamReader creates a ReadableStream that reads data from a blob driver
+ * in fixed-size chunks. This is useful for streaming large files without loading
+ * them entirely into memory.
+ */
+export declare class ChunkedStreamReader {
+    private currentPosition;
+    private _read;
+    private _canceled;
+    private _errored;
+    private abortController;
+    private readonly options;
+    /**
+     * Creates a new ChunkedStreamReader instance.
+     * Use the static `create` method instead.
+     */
+    private constructor();
+    /**
+     * Gets the fetchChunk function from options
+     */
+    private get fetchChunk();
+    /**
+     * Gets the total size from options
+     */
+    private get totalSize();
+    /**
+     * Gets the chunk size from options
+     */
+    private get chunkSize();
+    /**
+     * Gets the onError callback from options
+     */
+    private get onError();
+    /**
+     * Creates and returns a ReadableStream that reads data in chunks.
+     *
+     * @param options - Configuration options for the chunked stream reader
+     * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+     *
+     * @example
+     * ```typescript
+     * const stream = ChunkedStreamReader.create({
+     *   fetchChunk: async (range, signal) => {
+     *     const response = await fetch(`/api/data?from=${range.from}&to=${range.to}`, { signal });
+     *     return new Uint8Array(await response.arrayBuffer());
+     *   },
+     *   totalSize: 1024 * 1024, // 1MB
+     *   chunkSize: 64 * 1024,   // 64KB chunks
+     * });
+     * ```
+     */
+    static create(options: ChunkedStreamReaderOptions): ReadableStream<Uint8Array>;
+    private readStart;
+    private readStop;
+    private tryRead;
+    /**
+     * Creates and returns a ReadableStream that reads data in chunks.
+     * The stream will automatically close when all data has been read.
+     *
+     * @private - Use the static `create` method instead
+     * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+     */
+    private createStream;
+    /**
+     * Gets the current reading position in bytes.
+     *
+     * @returns Current position as number of bytes read
+     */
+    getCurrentPosition(): number;
+    /**
+     * Gets the remaining bytes to be read.
+     *
+     * @returns Number of bytes remaining
+     */
+    getRemainingBytes(): number;
+    /**
+     * Checks if the entire blob has been read.
+     *
+     * @returns True if all data has been read
+     */
+    isComplete(): boolean;
+}
+//# sourceMappingURL=ChunkedStreamReader.d.ts.map

package/dist/drivers/ChunkedStreamReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChunkedStreamReader.d.ts","sourceRoot":"","sources":["../../src/drivers/ChunkedStreamReader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAE7E;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAE/D;;;OAGG;IACH,OAAO;IAmBP;;OAEG;IACH,OAAO,KAAK,UAAU,GAErB;IAED;;OAEG;IACH,OAAO,KAAK,SAAS,GAEpB;IAED;;OAEG;IACH,OAAO,KAAK,SAAS,GAEpB;IAED;;OAEG;IACH,OAAO,KAAK,OAAO,GAElB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,0BAA0B,GAAG,cAAc,CAAC,UAAU,CAAC;IAK9E,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;YAIF,OAAO;IA+DrB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAsCpB;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;;OAIG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;;;OAIG;IACH,UAAU,IAAI,OAAO;CAGtB"}

package/dist/drivers/ChunkedStreamReader.js

@@ -0,0 +1,204 @@
+/**
+ * ChunkedStreamReader creates a ReadableStream that reads data from a blob driver
+ * in fixed-size chunks. This is useful for streaming large files without loading
+ * them entirely into memory.
+ */
+class ChunkedStreamReader {
+    currentPosition = 0;
+    _read = true;
+    _canceled = false;
+    _errored = false;
+    abortController = null;
+    options;
+    /**
+     * Creates a new ChunkedStreamReader instance.
+     * Use the static `create` method instead.
+     */
+    constructor(options) {
+        // Normalize options with defaults
+        this.options = {
+            ...options,
+            chunkSize: options.chunkSize ?? 16 * 1024 * 1024,
+            onError: options.onError ?? (async () => {
+                // Default behavior: error (will automatically call controller.error)
+                return 'error';
+            }),
+        };
+        if (this.totalSize < 0) {
+            throw new Error('Total size must be non-negative');
+        }
+        if (this.chunkSize <= 0) {
+            throw new Error('Chunk size must be positive');
+        }
+    }
+    /**
+     * Gets the fetchChunk function from options
+     */
+    get fetchChunk() {
+        return this.options.fetchChunk;
+    }
+    /**
+     * Gets the total size from options
+     */
+    get totalSize() {
+        return this.options.totalSize;
+    }
+    /**
+     * Gets the chunk size from options
+     */
+    get chunkSize() {
+        return this.options.chunkSize;
+    }
+    /**
+     * Gets the onError callback from options
+     */
+    get onError() {
+        return this.options.onError;
+    }
+    /**
+     * Creates and returns a ReadableStream that reads data in chunks.
+     *
+     * @param options - Configuration options for the chunked stream reader
+     * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+     *
+     * @example
+     * ```typescript
+     * const stream = ChunkedStreamReader.create({
+     *   fetchChunk: async (range, signal) => {
+     *     const response = await fetch(`/api/data?from=${range.from}&to=${range.to}`, { signal });
+     *     return new Uint8Array(await response.arrayBuffer());
+     *   },
+     *   totalSize: 1024 * 1024, // 1MB
+     *   chunkSize: 64 * 1024,   // 64KB chunks
+     * });
+     * ```
+     */
+    static create(options) {
+        const reader = new ChunkedStreamReader(options);
+        return reader.createStream();
+    }
+    readStart() {
+        this._read = true;
+    }
+    readStop() {
+        this._read = false;
+    }
+    async tryRead(controller) {
+        if (this._canceled) {
+            return true;
+        }
+        // Check if we've read all data
+        if (this.isComplete()) {
+            controller.close();
+            return true;
+        }
+        try {
+            // Calculate the end position for this chunk
+            // Ensure we don't read beyond the total size
+            const endPosition = Math.min(this.currentPosition + this.chunkSize, this.totalSize);
+            // Fetch the chunk from the blob driver, passing the abort signal if available
+            const data = await this.fetchChunk({ from: this.currentPosition, to: endPosition }, this.abortController?.signal);
+            // Check if stream was cancelled during the fetch
+            if (this._canceled) {
+                return true;
+            }
+            // Enqueue the data into the stream
+            controller.enqueue(data);
+            // Update the current position for the next chunk
+            this.currentPosition = endPosition;
+            if (!controller.desiredSize || controller.desiredSize <= 0) {
+                // The internal queue is full, so propagate
+                // the backpressure signal to the underlying source.
+                this.readStop();
+            }
+        }
+        catch (error) {
+            // If any error occurs during chunk reading, call the error handler
+            const status = await this.onError(error);
+            if (status === 'error') {
+                this._errored = true;
+                // Error the stream and abort any ongoing fetch operations
+                controller.error(error);
+                this.abortController?.abort('Stream errored');
+                return true; // Stop reading
+            }
+            if (status === 'cancel') {
+                this._canceled = true;
+                // Close the stream gracefully and abort any ongoing fetch operations
+                controller.close();
+                this.abortController?.abort('Stream cancelled');
+                console.debug('ChunkedStreamReader cancelled due to error');
+                return true; // Stop reading
+            }
+        }
+        return false;
+    }
+    /**
+     * Creates and returns a ReadableStream that reads data in chunks.
+     * The stream will automatically close when all data has been read.
+     *
+     * @private - Use the static `create` method instead
+     * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+     */
+    createStream() {
+        // Create an AbortController for this stream
+        this.abortController = new AbortController();
+        return new ReadableStream({
+            start: async (controller) => {
+                while (true) {
+                    if (this._canceled || this._errored) {
+                        return;
+                    }
+                    if (!this._read) {
+                        await new Promise((r) => setTimeout(r, 0));
+                        if (controller.desiredSize) {
+                            this.readStart();
+                        }
+                    }
+                    else {
+                        const isDone = await this.tryRead(controller);
+                        if (isDone) {
+                            return;
+                        }
+                    }
+                }
+            },
+            pull: () => {
+                this.readStart();
+            },
+            cancel: (reason) => {
+                this._canceled = true;
+                // Abort any ongoing fetch operations
+                this.abortController?.abort(reason);
+                console.debug('ChunkedStreamReader cancelled:', reason);
+            },
+        });
+    }
+    /**
+     * Gets the current reading position in bytes.
+     *
+     * @returns Current position as number of bytes read
+     */
+    getCurrentPosition() {
+        return this.currentPosition;
+    }
+    /**
+     * Gets the remaining bytes to be read.
+     *
+     * @returns Number of bytes remaining
+     */
+    getRemainingBytes() {
+        return Math.max(0, this.totalSize - this.currentPosition);
+    }
+    /**
+     * Checks if the entire blob has been read.
+     *
+     * @returns True if all data has been read
+     */
+    isComplete() {
+        return this.currentPosition >= this.totalSize;
+    }
+}
+
+export { ChunkedStreamReader };
+//# sourceMappingURL=ChunkedStreamReader.js.map

package/dist/drivers/ChunkedStreamReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChunkedStreamReader.js","sources":["../../src/drivers/ChunkedStreamReader.ts"],"sourcesContent":["import type { RangeBytes } from './blob';\n\n/**\n * Status returned by onError handler to indicate what action to take\n * - 'continue': Retry the failed operation\n * - 'error': Error the stream (calls controller.error, aborts ongoing fetches)\n * - 'cancel': Cancel the stream gracefully (calls controller.close, aborts ongoing fetches)\n */\nexport type ErrorHandlerStatus = 'continue' | 'error' | 'cancel';\n\n/**\n * Options for creating a ChunkedStreamReader\n */\nexport interface ChunkedStreamReaderOptions {\n  /**\n   * Function to fetch a chunk of data. Optionally accepts an AbortSignal to cancel the fetch.\n   */\n  fetchChunk: (range: RangeBytes, signal?: AbortSignal) => Promise<Uint8Array>;\n\n  /**\n   * Total size of the blob in bytes\n   */\n  totalSize: number;\n\n  /**\n   * Size of each chunk to read in bytes (default: 16MB)\n   */\n  chunkSize?: number;\n\n  /**\n   * Error handler callback. Called when an error occurs during chunk fetching.\n   * Should return:\n   * - 'continue' to retry the operation\n   * - 'error' to error the stream (will call controller.error and abort ongoing fetches)\n   * - 'cancel' to cancel gracefully (will call controller.close and abort ongoing fetches)\n   * Default behavior: returns 'error'.\n   */\n  onError?: (error: unknown) => Promise<ErrorHandlerStatus>;\n}\n\n/**\n * ChunkedStreamReader creates a ReadableStream that reads data from a blob driver\n * in fixed-size chunks. This is useful for streaming large files without loading\n * them entirely into memory.\n */\nexport class ChunkedStreamReader {\n  private currentPosition: number = 0;\n  private _read = true;\n  private _canceled = false;\n  private _errored = false;\n  private abortController: AbortController | null = null;\n  private readonly options: Required<ChunkedStreamReaderOptions>;\n\n  /**\n   * Creates a new ChunkedStreamReader instance.\n   * Use the static `create` method instead.\n   */\n  private constructor(options: ChunkedStreamReaderOptions) {\n    // Normalize options with defaults\n    this.options = {\n      ...options,\n      chunkSize: options.chunkSize ?? 16 * 1024 * 1024,\n      onError: options.onError ?? (async () => {\n        // Default behavior: error (will automatically call controller.error)\n        return 'error';\n      }),\n    };\n\n    if (this.totalSize < 0) {\n      throw new Error('Total size must be non-negative');\n    }\n    if (this.chunkSize <= 0) {\n      throw new Error('Chunk size must be positive');\n    }\n  }\n\n  /**\n   * Gets the fetchChunk function from options\n   */\n  private get fetchChunk() {\n    return this.options.fetchChunk;\n  }\n\n  /**\n   * Gets the total size from options\n   */\n  private get totalSize() {\n    return this.options.totalSize;\n  }\n\n  /**\n   * Gets the chunk size from options\n   */\n  private get chunkSize() {\n    return this.options.chunkSize;\n  }\n\n  /**\n   * Gets the onError callback from options\n   */\n  private get onError() {\n    return this.options.onError;\n  }\n\n  /**\n   * Creates and returns a ReadableStream that reads data in chunks.\n   *\n   * @param options - Configuration options for the chunked stream reader\n   * @returns ReadableStream that can be consumed by zip.add or other stream consumers\n   *\n   * @example\n   * ```typescript\n   * const stream = ChunkedStreamReader.create({\n   *   fetchChunk: async (range, signal) => {\n   *     const response = await fetch(`/api/data?from=${range.from}&to=${range.to}`, { signal });\n   *     return new Uint8Array(await response.arrayBuffer());\n   *   },\n   *   totalSize: 1024 * 1024, // 1MB\n   *   chunkSize: 64 * 1024,   // 64KB chunks\n   * });\n   * ```\n   */\n  static create(options: ChunkedStreamReaderOptions): ReadableStream<Uint8Array> {\n    const reader = new ChunkedStreamReader(options);\n    return reader.createStream();\n  }\n\n  private readStart() {\n    this._read = true;\n  }\n\n  private readStop() {\n    this._read = false;\n  }\n\n  private async tryRead(controller: ReadableStreamDefaultController<Uint8Array>): Promise<boolean> {\n    if (this._canceled) {\n      return true;\n    }\n\n    // Check if we've read all data\n    if (this.isComplete()) {\n      controller.close();\n      return true;\n    }\n\n    try {\n      // Calculate the end position for this chunk\n      // Ensure we don't read beyond the total size\n      const endPosition = Math.min(this.currentPosition + this.chunkSize, this.totalSize);\n\n      // Fetch the chunk from the blob driver, passing the abort signal if available\n      const data = await this.fetchChunk(\n        { from: this.currentPosition, to: endPosition },\n        this.abortController?.signal,\n      );\n\n      // Check if stream was cancelled during the fetch\n      if (this._canceled) {\n        return true;\n      }\n\n      // Enqueue the data into the stream\n      controller.enqueue(data);\n\n      // Update the current position for the next chunk\n      this.currentPosition = endPosition;\n\n      if (!controller.desiredSize || controller.desiredSize <= 0) {\n        // The internal queue is full, so propagate\n        // the backpressure signal to the underlying source.\n        this.readStop();\n      }\n    } catch (error) {\n      // If any error occurs during chunk reading, call the error handler\n      const status = await this.onError(error);\n\n      if (status === 'error') {\n        this._errored = true;\n        // Error the stream and abort any ongoing fetch operations\n        controller.error(error);\n        this.abortController?.abort('Stream errored');\n        return true; // Stop reading\n      }\n\n      if (status === 'cancel') {\n        this._canceled = true;\n        // Close the stream gracefully and abort any ongoing fetch operations\n        controller.close();\n        this.abortController?.abort('Stream cancelled');\n        console.debug('ChunkedStreamReader cancelled due to error');\n        return true; // Stop reading\n      }\n    }\n\n    return false;\n  }\n\n  /**\n   * Creates and returns a ReadableStream that reads data in chunks.\n   * The stream will automatically close when all data has been read.\n   *\n   * @private - Use the static `create` method instead\n   * @returns ReadableStream that can be consumed by zip.add or other stream consumers\n   */\n  private createStream(): ReadableStream<Uint8Array> {\n    // Create an AbortController for this stream\n    this.abortController = new AbortController();\n\n    return new ReadableStream({\n      start: async (controller) => {\n        while (true) {\n          if (this._canceled || this._errored) {\n            return;\n          }\n\n          if (!this._read) {\n            await new Promise((r) => setTimeout(r, 0));\n            if (controller.desiredSize) {\n              this.readStart();\n            }\n          } else {\n            const isDone = await this.tryRead(controller);\n            if (isDone) {\n              return;\n            }\n          }\n        }\n      },\n\n      pull: () => {\n        this.readStart();\n      },\n\n      cancel: (reason) => {\n        this._canceled = true;\n        // Abort any ongoing fetch operations\n        this.abortController?.abort(reason);\n        console.debug('ChunkedStreamReader cancelled:', reason);\n      },\n    });\n  }\n\n  /**\n   * Gets the current reading position in bytes.\n   *\n   * @returns Current position as number of bytes read\n   */\n  getCurrentPosition(): number {\n    return this.currentPosition;\n  }\n\n  /**\n   * Gets the remaining bytes to be read.\n   *\n   * @returns Number of bytes remaining\n   */\n  getRemainingBytes(): number {\n    return Math.max(0, this.totalSize - this.currentPosition);\n  }\n\n  /**\n   * Checks if the entire blob has been read.\n   *\n   * @returns True if all data has been read\n   */\n  isComplete(): boolean {\n    return this.currentPosition >= this.totalSize;\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/drivers/index.d.ts

@@ -5,4 +5,5 @@ export * from './upload';
 export * from './log';
 export * from './ls';
 export * from './pframe';
+export * from './ChunkedStreamReader';
 //# sourceMappingURL=index.d.ts.map

package/dist/drivers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,MAAM,CAAC;AAErB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,MAAM,CAAC;AAErB,cAAc,UAAU,CAAC;AACzB,cAAc,uBAAuB,CAAC"}

package/dist/index.cjs

@@ -18,6 +18,7 @@ var filtered_column = require('./drivers/pframe/spec/filtered_column.cjs');
 var selectors = require('./drivers/pframe/spec/selectors.cjs');
 var native_id = require('./drivers/pframe/spec/native_id.cjs');
 var linker_columns = require('./drivers/pframe/linker_columns.cjs');
+var ChunkedStreamReader = require('./drivers/ChunkedStreamReader.cjs');
 var errors = require('./errors.cjs');
 var block_flags = require('./flags/block_flags.cjs');
 var flag_utils = require('./flags/flag_utils.cjs');
@@ -102,6 +103,7 @@ exports.matchPColumn = selectors.matchPColumn;
 exports.selectorsToPredicate = selectors.selectorsToPredicate;
 exports.deriveNativeId = native_id.deriveNativeId;
 exports.LinkerMap = linker_columns.LinkerMap;
+exports.ChunkedStreamReader = ChunkedStreamReader.ChunkedStreamReader;
 exports.AbortError = errors.AbortError;
 exports.PFrameDriverError = errors.PFrameDriverError;
 exports.PFrameError = errors.PFrameError;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.js

@@ -16,6 +16,7 @@ export { isFilteredPColumn } from './drivers/pframe/spec/filtered_column.js';
 export { matchAxis, matchPColumn, selectorsToPredicate } from './drivers/pframe/spec/selectors.js';
 export { deriveNativeId } from './drivers/pframe/spec/native_id.js';
 export { LinkerMap } from './drivers/pframe/linker_columns.js';
+export { ChunkedStreamReader } from './drivers/ChunkedStreamReader.js';
 export { AbortError, PFrameDriverError, PFrameError, UiError, deserializeError, deserializeResult, ensureError, hasAbortError, isAbortError, isAggregateError, isPFrameDriverError, isPFrameError, serializeError, serializeResult, unwrapResult, wrapAndSerialize, wrapAndSerializeAsync, wrapAsyncCallback, wrapCallback } from './errors.js';
 export { AllRequiresFeatureFlags, AllSupportsFeatureFlags } from './flags/block_flags.js';
 export { IncompatibleFlagsError, RuntimeCapabilities, checkBlockFlag, extractAllRequirements, extractAllSupports } from './flags/flag_utils.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-common",
-  "version": "1.21.3",
+  "version": "1.21.4",
   "description": "Platforma SDK Model",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -25,8 +25,8 @@
     "eslint": "^9.25.1",
     "typescript": "~5.6.3",
     "vitest": "^2.1.9",
-    "@milaboratories/ts-builder": "1.0.5",
     "@milaboratories/build-configs": "1.0.8",
+    "@milaboratories/ts-builder": "1.0.5",
     "@platforma-sdk/eslint-config": "1.1.0",
     "@milaboratories/ts-configs": "1.0.6"
   },

package/src/drivers/ChunkedStreamReader.ts

@@ -0,0 +1,270 @@
+import type { RangeBytes } from './blob';
+
+/**
+ * Status returned by onError handler to indicate what action to take
+ * - 'continue': Retry the failed operation
+ * - 'error': Error the stream (calls controller.error, aborts ongoing fetches)
+ * - 'cancel': Cancel the stream gracefully (calls controller.close, aborts ongoing fetches)
+ */
+export type ErrorHandlerStatus = 'continue' | 'error' | 'cancel';
+
+/**
+ * Options for creating a ChunkedStreamReader
+ */
+export interface ChunkedStreamReaderOptions {
+  /**
+   * Function to fetch a chunk of data. Optionally accepts an AbortSignal to cancel the fetch.
+   */
+  fetchChunk: (range: RangeBytes, signal?: AbortSignal) => Promise<Uint8Array>;
+
+  /**
+   * Total size of the blob in bytes
+   */
+  totalSize: number;
+
+  /**
+   * Size of each chunk to read in bytes (default: 16MB)
+   */
+  chunkSize?: number;
+
+  /**
+   * Error handler callback. Called when an error occurs during chunk fetching.
+   * Should return:
+   * - 'continue' to retry the operation
+   * - 'error' to error the stream (will call controller.error and abort ongoing fetches)
+   * - 'cancel' to cancel gracefully (will call controller.close and abort ongoing fetches)
+   * Default behavior: returns 'error'.
+   */
+  onError?: (error: unknown) => Promise<ErrorHandlerStatus>;
+}
+
+/**
+ * ChunkedStreamReader creates a ReadableStream that reads data from a blob driver
+ * in fixed-size chunks. This is useful for streaming large files without loading
+ * them entirely into memory.
+ */
+export class ChunkedStreamReader {
+  private currentPosition: number = 0;
+  private _read = true;
+  private _canceled = false;
+  private _errored = false;
+  private abortController: AbortController | null = null;
+  private readonly options: Required<ChunkedStreamReaderOptions>;
+
+  /**
+   * Creates a new ChunkedStreamReader instance.
+   * Use the static `create` method instead.
+   */
+  private constructor(options: ChunkedStreamReaderOptions) {
+    // Normalize options with defaults
+    this.options = {
+      ...options,
+      chunkSize: options.chunkSize ?? 16 * 1024 * 1024,
+      onError: options.onError ?? (async () => {
+        // Default behavior: error (will automatically call controller.error)
+        return 'error';
+      }),
+    };
+
+    if (this.totalSize < 0) {
+      throw new Error('Total size must be non-negative');
+    }
+    if (this.chunkSize <= 0) {
+      throw new Error('Chunk size must be positive');
+    }
+  }
+
+  /**
+   * Gets the fetchChunk function from options
+   */
+  private get fetchChunk() {
+    return this.options.fetchChunk;
+  }
+
+  /**
+   * Gets the total size from options
+   */
+  private get totalSize() {
+    return this.options.totalSize;
+  }
+
+  /**
+   * Gets the chunk size from options
+   */
+  private get chunkSize() {
+    return this.options.chunkSize;
+  }
+
+  /**
+   * Gets the onError callback from options
+   */
+  private get onError() {
+    return this.options.onError;
+  }
+
+  /**
+   * Creates and returns a ReadableStream that reads data in chunks.
+   *
+   * @param options - Configuration options for the chunked stream reader
+   * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+   *
+   * @example
+   * ```typescript
+   * const stream = ChunkedStreamReader.create({
+   *   fetchChunk: async (range, signal) => {
+   *     const response = await fetch(`/api/data?from=${range.from}&to=${range.to}`, { signal });
+   *     return new Uint8Array(await response.arrayBuffer());
+   *   },
+   *   totalSize: 1024 * 1024, // 1MB
+   *   chunkSize: 64 * 1024,   // 64KB chunks
+   * });
+   * ```
+   */
+  static create(options: ChunkedStreamReaderOptions): ReadableStream<Uint8Array> {
+    const reader = new ChunkedStreamReader(options);
+    return reader.createStream();
+  }
+
+  private readStart() {
+    this._read = true;
+  }
+
+  private readStop() {
+    this._read = false;
+  }
+
+  private async tryRead(controller: ReadableStreamDefaultController<Uint8Array>): Promise<boolean> {
+    if (this._canceled) {
+      return true;
+    }
+
+    // Check if we've read all data
+    if (this.isComplete()) {
+      controller.close();
+      return true;
+    }
+
+    try {
+      // Calculate the end position for this chunk
+      // Ensure we don't read beyond the total size
+      const endPosition = Math.min(this.currentPosition + this.chunkSize, this.totalSize);
+
+      // Fetch the chunk from the blob driver, passing the abort signal if available
+      const data = await this.fetchChunk(
+        { from: this.currentPosition, to: endPosition },
+        this.abortController?.signal,
+      );
+
+      // Check if stream was cancelled during the fetch
+      if (this._canceled) {
+        return true;
+      }
+
+      // Enqueue the data into the stream
+      controller.enqueue(data);
+
+      // Update the current position for the next chunk
+      this.currentPosition = endPosition;
+
+      if (!controller.desiredSize || controller.desiredSize <= 0) {
+        // The internal queue is full, so propagate
+        // the backpressure signal to the underlying source.
+        this.readStop();
+      }
+    } catch (error) {
+      // If any error occurs during chunk reading, call the error handler
+      const status = await this.onError(error);
+
+      if (status === 'error') {
+        this._errored = true;
+        // Error the stream and abort any ongoing fetch operations
+        controller.error(error);
+        this.abortController?.abort('Stream errored');
+        return true; // Stop reading
+      }
+
+      if (status === 'cancel') {
+        this._canceled = true;
+        // Close the stream gracefully and abort any ongoing fetch operations
+        controller.close();
+        this.abortController?.abort('Stream cancelled');
+        console.debug('ChunkedStreamReader cancelled due to error');
+        return true; // Stop reading
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Creates and returns a ReadableStream that reads data in chunks.
+   * The stream will automatically close when all data has been read.
+   *
+   * @private - Use the static `create` method instead
+   * @returns ReadableStream that can be consumed by zip.add or other stream consumers
+   */
+  private createStream(): ReadableStream<Uint8Array> {
+    // Create an AbortController for this stream
+    this.abortController = new AbortController();
+
+    return new ReadableStream({
+      start: async (controller) => {
+        while (true) {
+          if (this._canceled || this._errored) {
+            return;
+          }
+
+          if (!this._read) {
+            await new Promise((r) => setTimeout(r, 0));
+            if (controller.desiredSize) {
+              this.readStart();
+            }
+          } else {
+            const isDone = await this.tryRead(controller);
+            if (isDone) {
+              return;
+            }
+          }
+        }
+      },
+
+      pull: () => {
+        this.readStart();
+      },
+
+      cancel: (reason) => {
+        this._canceled = true;
+        // Abort any ongoing fetch operations
+        this.abortController?.abort(reason);
+        console.debug('ChunkedStreamReader cancelled:', reason);
+      },
+    });
+  }
+
+  /**
+   * Gets the current reading position in bytes.
+   *
+   * @returns Current position as number of bytes read
+   */
+  getCurrentPosition(): number {
+    return this.currentPosition;
+  }
+
+  /**
+   * Gets the remaining bytes to be read.
+   *
+   * @returns Number of bytes remaining
+   */
+  getRemainingBytes(): number {
+    return Math.max(0, this.totalSize - this.currentPosition);
+  }
+
+  /**
+   * Checks if the entire blob has been read.
+   *
+   * @returns True if all data has been read
+   */
+  isComplete(): boolean {
+    return this.currentPosition >= this.totalSize;
+  }
+}

package/src/drivers/index.ts

@@ -7,3 +7,4 @@ export * from './log';
 export * from './ls';
 
 export * from './pframe';
+export * from './ChunkedStreamReader';