@backblaze-labs/b2-sdk 0.1.0

package/dist/streams/source.d.cts

@@ -0,0 +1,140 @@
+/**
+ * Uniform adapter for upload content. Wraps File, Blob, Buffer, or ReadableStream
+ * behind a common interface so upload logic does not depend on the input type.
+ */
+export interface ContentSource {
+    /** Total size of the content in bytes. */
+    readonly size: number;
+    /** Pre-computed SHA-1 hex digest, if available. */
+    readonly sha1?: string;
+    /**
+     * Whether {@link slice} is safe to call on this source.
+     *
+     * `true` for in-memory / random-access sources (`BufferSource`,
+     * `BlobSource`) — the multipart upload engine can dispatch part reads
+     * in parallel by slicing the source into disjoint ranges. `false`
+     * for forward-only sources (`StreamSource`) — the engine must read
+     * sequentially, one `partSize` chunk at a time. Callers that branch
+     * on this flag are expected to fall back to the sequential path
+     * rather than call `slice()` and catch the throw.
+     */
+    readonly canSlice: boolean;
+    /** Return a sub-range of this source as a new ContentSource. */
+    slice(start: number, end: number): ContentSource;
+    /** Open the content as a ReadableStream. */
+    stream(): ReadableStream<Uint8Array>;
+    /** Read the entire content into an ArrayBuffer. */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/** ContentSource backed by a Blob or File. */
+export declare class BlobSource implements ContentSource {
+    private readonly blob;
+    /** {@inheritDoc} */
+    readonly size: number;
+    /** Random-access: `Blob.slice()` is cheap and returns a new Blob view. */
+    readonly canSlice = true;
+    /**
+     * Create a BlobSource wrapping the given Blob.
+     * @param blob - The Blob or File to use as the underlying content.
+     */
+    constructor(blob: Blob);
+    /**
+     * Return a new BlobSource covering the specified byte range.
+     * @param start - The zero-based byte offset to begin the slice.
+     * @param end - The exclusive byte offset where the slice ends.
+     *
+     * @returns A new ContentSource representing the requested sub-range.
+     */
+    slice(start: number, end: number): ContentSource;
+    /**
+     * Open the Blob content as a ReadableStream.
+     * @returns A ReadableStream of the Blob bytes.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read the entire Blob content into an ArrayBuffer.
+     * @returns A promise that resolves with the full content as an ArrayBuffer.
+     */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/** ContentSource backed by a Uint8Array buffer. */
+export declare class BufferSource implements ContentSource {
+    private readonly buffer;
+    /** {@inheritDoc} */
+    readonly size: number;
+    /** Random-access: the entire payload lives in memory. */
+    readonly canSlice = true;
+    /**
+     * Create a BufferSource wrapping the given Uint8Array.
+     * @param buffer - The byte buffer to use as the underlying content.
+     */
+    constructor(buffer: Uint8Array);
+    /**
+     * Return a new BufferSource covering the specified byte range.
+     * @param start - The zero-based byte offset to begin the slice.
+     * @param end - The exclusive byte offset where the slice ends.
+     *
+     * @returns A new ContentSource representing the requested sub-range.
+     */
+    slice(start: number, end: number): ContentSource;
+    /**
+     * Open the buffer content as a ReadableStream.
+     * @returns A ReadableStream that emits the buffer bytes in a single chunk.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read the entire buffer content into an ArrayBuffer.
+     * @returns A promise that resolves with the full content as an ArrayBuffer.
+     */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/** ContentSource backed by a ReadableStream. Can only be consumed once and does not support slicing. */
+export declare class StreamSource implements ContentSource {
+    private readonly readable;
+    /** {@inheritDoc} */
+    readonly size: number;
+    /**
+     * Forward-only: ReadableStreams cannot be repositioned, so multipart
+     * uploads must take the sequential path. See the interface comment on
+     * `canSlice` for what the engine does with this flag.
+     */
+    readonly canSlice = false;
+    /** Whether the stream has already been read. */
+    private consumed;
+    /**
+     * Create a StreamSource wrapping the given ReadableStream with a known byte size.
+     * @param readable - The ReadableStream to wrap as a content source.
+     * @param size - The total number of bytes the stream will produce.
+     */
+    constructor(readable: ReadableStream<Uint8Array>, size: number);
+    /**
+     * Always throws because streams cannot be sliced. Buffer the stream first.
+     *
+     * @throws If slicing is attempted on a stream-backed source.
+     */
+    slice(): ContentSource;
+    /**
+     * Open the underlying ReadableStream. Can only be called once.
+     * @returns The underlying ReadableStream of bytes.
+     *
+     * @throws If the stream has already been consumed.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read the entire stream into an ArrayBuffer.
+     * @returns A promise that resolves with the full content as an ArrayBuffer.
+     */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Convert a Uint8Array, Blob, or ReadableStream into a {@link ContentSource}.
+ * When passing a ReadableStream, the `size` parameter is required.
+ * @param input - The content to wrap, as a Uint8Array, Blob, or ReadableStream.
+ * @param size - The total byte length, required when input is a ReadableStream.
+ *
+ * @returns A ContentSource adapter for the given input.
+ *
+ * @throws If input is a ReadableStream and size is not provided.
+ */
+export declare function toContentSource(input: Uint8Array | Blob | ReadableStream<Uint8Array>, size?: number): ContentSource;
+//# sourceMappingURL=source.d.ts.map

package/dist/streams/source.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/streams/source.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;IAChD,4CAA4C;IAC5C,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAA;IACpC,mDAAmD;IACnD,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACtC;AAED,8CAA8C;AAC9C,qBAAa,UAAW,YAAW,aAAa;IAUlC,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,QAAO;IAExB;;;OAGG;gBAC0B,IAAI,EAAE,IAAI;IAIvC;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAIhD;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAIpC;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAGtC;AAED,mDAAmD;AACnD,qBAAa,YAAa,YAAW,aAAa;IAUpC,OAAO,CAAC,QAAQ,CAAC,MAAM;IATnC,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,QAAO;IAExB;;;OAGG;gBAC0B,MAAM,EAAE,UAAU;IAI/C;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAIhD;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAUpC;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAQtC;AAED,wGAAwG;AACxG,qBAAa,YAAa,YAAW,aAAa;IAkB9C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjB3B,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,SAAQ;IACzB,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;;OAIG;gBAEgB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EACrD,IAAI,EAAE,MAAM;IAKd;;;;OAIG;IACH,KAAK,IAAI,aAAa;IAItB;;;;;OAKG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAMpC;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAI5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,EACrD,IAAI,CAAC,EAAE,MAAM,GACZ,aAAa,CAWf"}

package/dist/streams/source.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Uniform adapter for upload content. Wraps File, Blob, Buffer, or ReadableStream
+ * behind a common interface so upload logic does not depend on the input type.
+ */
+export interface ContentSource {
+    /** Total size of the content in bytes. */
+    readonly size: number;
+    /** Pre-computed SHA-1 hex digest, if available. */
+    readonly sha1?: string;
+    /**
+     * Whether {@link slice} is safe to call on this source.
+     *
+     * `true` for in-memory / random-access sources (`BufferSource`,
+     * `BlobSource`) — the multipart upload engine can dispatch part reads
+     * in parallel by slicing the source into disjoint ranges. `false`
+     * for forward-only sources (`StreamSource`) — the engine must read
+     * sequentially, one `partSize` chunk at a time. Callers that branch
+     * on this flag are expected to fall back to the sequential path
+     * rather than call `slice()` and catch the throw.
+     */
+    readonly canSlice: boolean;
+    /** Return a sub-range of this source as a new ContentSource. */
+    slice(start: number, end: number): ContentSource;
+    /** Open the content as a ReadableStream. */
+    stream(): ReadableStream<Uint8Array>;
+    /** Read the entire content into an ArrayBuffer. */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/** ContentSource backed by a Blob or File. */
+export declare class BlobSource implements ContentSource {
+    private readonly blob;
+    /** {@inheritDoc} */
+    readonly size: number;
+    /** Random-access: `Blob.slice()` is cheap and returns a new Blob view. */
+    readonly canSlice = true;
+    /**
+     * Create a BlobSource wrapping the given Blob.
+     * @param blob - The Blob or File to use as the underlying content.
+     */
+    constructor(blob: Blob);
+    /**
+     * Return a new BlobSource covering the specified byte range.
+     * @param start - The zero-based byte offset to begin the slice.
+     * @param end - The exclusive byte offset where the slice ends.
+     *
+     * @returns A new ContentSource representing the requested sub-range.
+     */
+    slice(start: number, end: number): ContentSource;
+    /**
+     * Open the Blob content as a ReadableStream.
+     * @returns A ReadableStream of the Blob bytes.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read the entire Blob content into an ArrayBuffer.
+     * @returns A promise that resolves with the full content as an ArrayBuffer.
+     */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/** ContentSource backed by a Uint8Array buffer. */
+export declare class BufferSource implements ContentSource {
+    private readonly buffer;
+    /** {@inheritDoc} */
+    readonly size: number;
+    /** Random-access: the entire payload lives in memory. */
+    readonly canSlice = true;
+    /**
+     * Create a BufferSource wrapping the given Uint8Array.
+     * @param buffer - The byte buffer to use as the underlying content.
+     */
+    constructor(buffer: Uint8Array);
+    /**
+     * Return a new BufferSource covering the specified byte range.
+     * @param start - The zero-based byte offset to begin the slice.
+     * @param end - The exclusive byte offset where the slice ends.
+     *
+     * @returns A new ContentSource representing the requested sub-range.
+     */
+    slice(start: number, end: number): ContentSource;
+    /**
+     * Open the buffer content as a ReadableStream.
+     * @returns A ReadableStream that emits the buffer bytes in a single chunk.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read the entire buffer content into an ArrayBuffer.
+     * @returns A promise that resolves with the full content as an ArrayBuffer.
+     */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/** ContentSource backed by a ReadableStream. Can only be consumed once and does not support slicing. */
+export declare class StreamSource implements ContentSource {
+    private readonly readable;
+    /** {@inheritDoc} */
+    readonly size: number;
+    /**
+     * Forward-only: ReadableStreams cannot be repositioned, so multipart
+     * uploads must take the sequential path. See the interface comment on
+     * `canSlice` for what the engine does with this flag.
+     */
+    readonly canSlice = false;
+    /** Whether the stream has already been read. */
+    private consumed;
+    /**
+     * Create a StreamSource wrapping the given ReadableStream with a known byte size.
+     * @param readable - The ReadableStream to wrap as a content source.
+     * @param size - The total number of bytes the stream will produce.
+     */
+    constructor(readable: ReadableStream<Uint8Array>, size: number);
+    /**
+     * Always throws because streams cannot be sliced. Buffer the stream first.
+     *
+     * @throws If slicing is attempted on a stream-backed source.
+     */
+    slice(): ContentSource;
+    /**
+     * Open the underlying ReadableStream. Can only be called once.
+     * @returns The underlying ReadableStream of bytes.
+     *
+     * @throws If the stream has already been consumed.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read the entire stream into an ArrayBuffer.
+     * @returns A promise that resolves with the full content as an ArrayBuffer.
+     */
+    toArrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Convert a Uint8Array, Blob, or ReadableStream into a {@link ContentSource}.
+ * When passing a ReadableStream, the `size` parameter is required.
+ * @param input - The content to wrap, as a Uint8Array, Blob, or ReadableStream.
+ * @param size - The total byte length, required when input is a ReadableStream.
+ *
+ * @returns A ContentSource adapter for the given input.
+ *
+ * @throws If input is a ReadableStream and size is not provided.
+ */
+export declare function toContentSource(input: Uint8Array | Blob | ReadableStream<Uint8Array>, size?: number): ContentSource;
+//# sourceMappingURL=source.d.ts.map

package/dist/streams/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/streams/source.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;IAChD,4CAA4C;IAC5C,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAA;IACpC,mDAAmD;IACnD,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACtC;AAED,8CAA8C;AAC9C,qBAAa,UAAW,YAAW,aAAa;IAUlC,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,QAAO;IAExB;;;OAGG;gBAC0B,IAAI,EAAE,IAAI;IAIvC;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAIhD;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAIpC;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAGtC;AAED,mDAAmD;AACnD,qBAAa,YAAa,YAAW,aAAa;IAUpC,OAAO,CAAC,QAAQ,CAAC,MAAM;IATnC,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,QAAO;IAExB;;;OAGG;gBAC0B,MAAM,EAAE,UAAU;IAI/C;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAIhD;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAUpC;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAQtC;AAED,wGAAwG;AACxG,qBAAa,YAAa,YAAW,aAAa;IAkB9C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjB3B,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,SAAQ;IACzB,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;;OAIG;gBAEgB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EACrD,IAAI,EAAE,MAAM;IAKd;;;;OAIG;IACH,KAAK,IAAI,aAAa;IAItB;;;;;OAKG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAMpC;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAI5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,EACrD,IAAI,CAAC,EAAE,MAAM,GACZ,aAAa,CAWf"}

package/dist/streams/source.js

@@ -0,0 +1,155 @@
+import { collectStream } from "./collect.js";
+class BlobSource {
+  /**
+   * Create a BlobSource wrapping the given Blob.
+   * @param blob - The Blob or File to use as the underlying content.
+   */
+  constructor(blob) {
+    this.blob = blob;
+    this.size = blob.size;
+  }
+  /** {@inheritDoc} */
+  size;
+  /** Random-access: `Blob.slice()` is cheap and returns a new Blob view. */
+  canSlice = true;
+  /**
+   * Return a new BlobSource covering the specified byte range.
+   * @param start - The zero-based byte offset to begin the slice.
+   * @param end - The exclusive byte offset where the slice ends.
+   *
+   * @returns A new ContentSource representing the requested sub-range.
+   */
+  slice(start, end) {
+    return new BlobSource(this.blob.slice(start, end));
+  }
+  /**
+   * Open the Blob content as a ReadableStream.
+   * @returns A ReadableStream of the Blob bytes.
+   */
+  stream() {
+    return this.blob.stream();
+  }
+  /**
+   * Read the entire Blob content into an ArrayBuffer.
+   * @returns A promise that resolves with the full content as an ArrayBuffer.
+   */
+  toArrayBuffer() {
+    return this.blob.arrayBuffer();
+  }
+}
+class BufferSource {
+  /**
+   * Create a BufferSource wrapping the given Uint8Array.
+   * @param buffer - The byte buffer to use as the underlying content.
+   */
+  constructor(buffer) {
+    this.buffer = buffer;
+    this.size = buffer.byteLength;
+  }
+  /** {@inheritDoc} */
+  size;
+  /** Random-access: the entire payload lives in memory. */
+  canSlice = true;
+  /**
+   * Return a new BufferSource covering the specified byte range.
+   * @param start - The zero-based byte offset to begin the slice.
+   * @param end - The exclusive byte offset where the slice ends.
+   *
+   * @returns A new ContentSource representing the requested sub-range.
+   */
+  slice(start, end) {
+    return new BufferSource(this.buffer.slice(start, end));
+  }
+  /**
+   * Open the buffer content as a ReadableStream.
+   * @returns A ReadableStream that emits the buffer bytes in a single chunk.
+   */
+  stream() {
+    const buffer = this.buffer;
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(buffer);
+        controller.close();
+      }
+    });
+  }
+  /**
+   * Read the entire buffer content into an ArrayBuffer.
+   * @returns A promise that resolves with the full content as an ArrayBuffer.
+   */
+  toArrayBuffer() {
+    return Promise.resolve(
+      this.buffer.buffer.slice(
+        this.buffer.byteOffset,
+        this.buffer.byteOffset + this.buffer.byteLength
+      )
+    );
+  }
+}
+class StreamSource {
+  /**
+   * Create a StreamSource wrapping the given ReadableStream with a known byte size.
+   * @param readable - The ReadableStream to wrap as a content source.
+   * @param size - The total number of bytes the stream will produce.
+   */
+  constructor(readable, size) {
+    this.readable = readable;
+    this.size = size;
+  }
+  /** {@inheritDoc} */
+  size;
+  /**
+   * Forward-only: ReadableStreams cannot be repositioned, so multipart
+   * uploads must take the sequential path. See the interface comment on
+   * `canSlice` for what the engine does with this flag.
+   */
+  canSlice = false;
+  /** Whether the stream has already been read. */
+  consumed = false;
+  /**
+   * Always throws because streams cannot be sliced. Buffer the stream first.
+   *
+   * @throws If slicing is attempted on a stream-backed source.
+   */
+  slice() {
+    throw new Error("StreamSource does not support slicing. Buffer the stream first.");
+  }
+  /**
+   * Open the underlying ReadableStream. Can only be called once.
+   * @returns The underlying ReadableStream of bytes.
+   *
+   * @throws If the stream has already been consumed.
+   */
+  stream() {
+    if (this.consumed) throw new Error("StreamSource can only be consumed once.");
+    this.consumed = true;
+    return this.readable;
+  }
+  /**
+   * Read the entire stream into an ArrayBuffer.
+   * @returns A promise that resolves with the full content as an ArrayBuffer.
+   */
+  async toArrayBuffer() {
+    const bytes = await collectStream(this.stream());
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  }
+}
+function toContentSource(input, size) {
+  if (input instanceof Uint8Array) {
+    return new BufferSource(input);
+  }
+  if (input instanceof Blob) {
+    return new BlobSource(input);
+  }
+  if (size === void 0) {
+    throw new Error("size is required when using a ReadableStream as input.");
+  }
+  return new StreamSource(input, size);
+}
+export {
+  BlobSource,
+  BufferSource,
+  StreamSource,
+  toContentSource
+};
+//# sourceMappingURL=source.js.map

package/dist/streams/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sources":["../../src/streams/source.ts"],"sourcesContent":["import { collectStream } from './collect.ts'\n\n/**\n * Uniform adapter for upload content. Wraps File, Blob, Buffer, or ReadableStream\n * behind a common interface so upload logic does not depend on the input type.\n */\nexport interface ContentSource {\n  /** Total size of the content in bytes. */\n  readonly size: number\n  /** Pre-computed SHA-1 hex digest, if available. */\n  readonly sha1?: string\n  /**\n   * Whether {@link slice} is safe to call on this source.\n   *\n   * `true` for in-memory / random-access sources (`BufferSource`,\n   * `BlobSource`) — the multipart upload engine can dispatch part reads\n   * in parallel by slicing the source into disjoint ranges. `false`\n   * for forward-only sources (`StreamSource`) — the engine must read\n   * sequentially, one `partSize` chunk at a time. Callers that branch\n   * on this flag are expected to fall back to the sequential path\n   * rather than call `slice()` and catch the throw.\n   */\n  readonly canSlice: boolean\n  /** Return a sub-range of this source as a new ContentSource. */\n  slice(start: number, end: number): ContentSource\n  /** Open the content as a ReadableStream. */\n  stream(): ReadableStream<Uint8Array>\n  /** Read the entire content into an ArrayBuffer. */\n  toArrayBuffer(): Promise<ArrayBuffer>\n}\n\n/** ContentSource backed by a Blob or File. */\nexport class BlobSource implements ContentSource {\n  /** {@inheritDoc} */\n  readonly size: number\n  /** Random-access: `Blob.slice()` is cheap and returns a new Blob view. */\n  readonly canSlice = true\n\n  /**\n   * Create a BlobSource wrapping the given Blob.\n   * @param blob - The Blob or File to use as the underlying content.\n   */\n  constructor(private readonly blob: Blob) {\n    this.size = blob.size\n  }\n\n  /**\n   * Return a new BlobSource covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return new BlobSource(this.blob.slice(start, end))\n  }\n\n  /**\n   * Open the Blob content as a ReadableStream.\n   * @returns A ReadableStream of the Blob bytes.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    return this.blob.stream() as ReadableStream<Uint8Array>\n  }\n\n  /**\n   * Read the entire Blob content into an ArrayBuffer.\n   * @returns A promise that resolves with the full content as an ArrayBuffer.\n   */\n  toArrayBuffer(): Promise<ArrayBuffer> {\n    return this.blob.arrayBuffer()\n  }\n}\n\n/** ContentSource backed by a Uint8Array buffer. */\nexport class BufferSource implements ContentSource {\n  /** {@inheritDoc} */\n  readonly size: number\n  /** Random-access: the entire payload lives in memory. */\n  readonly canSlice = true\n\n  /**\n   * Create a BufferSource wrapping the given Uint8Array.\n   * @param buffer - The byte buffer to use as the underlying content.\n   */\n  constructor(private readonly buffer: Uint8Array) {\n    this.size = buffer.byteLength\n  }\n\n  /**\n   * Return a new BufferSource covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return new BufferSource(this.buffer.slice(start, end))\n  }\n\n  /**\n   * Open the buffer content as a ReadableStream.\n   * @returns A ReadableStream that emits the buffer bytes in a single chunk.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    const buffer = this.buffer\n    return new ReadableStream({\n      start(controller) {\n        controller.enqueue(buffer)\n        controller.close()\n      },\n    })\n  }\n\n  /**\n   * Read the entire buffer content into an ArrayBuffer.\n   * @returns A promise that resolves with the full content as an ArrayBuffer.\n   */\n  toArrayBuffer(): Promise<ArrayBuffer> {\n    return Promise.resolve(\n      this.buffer.buffer.slice(\n        this.buffer.byteOffset,\n        this.buffer.byteOffset + this.buffer.byteLength,\n      ) as ArrayBuffer,\n    )\n  }\n}\n\n/** ContentSource backed by a ReadableStream. Can only be consumed once and does not support slicing. */\nexport class StreamSource implements ContentSource {\n  /** {@inheritDoc} */\n  readonly size: number\n  /**\n   * Forward-only: ReadableStreams cannot be repositioned, so multipart\n   * uploads must take the sequential path. See the interface comment on\n   * `canSlice` for what the engine does with this flag.\n   */\n  readonly canSlice = false\n  /** Whether the stream has already been read. */\n  private consumed = false\n\n  /**\n   * Create a StreamSource wrapping the given ReadableStream with a known byte size.\n   * @param readable - The ReadableStream to wrap as a content source.\n   * @param size - The total number of bytes the stream will produce.\n   */\n  constructor(\n    private readonly readable: ReadableStream<Uint8Array>,\n    size: number,\n  ) {\n    this.size = size\n  }\n\n  /**\n   * Always throws because streams cannot be sliced. Buffer the stream first.\n   *\n   * @throws If slicing is attempted on a stream-backed source.\n   */\n  slice(): ContentSource {\n    throw new Error('StreamSource does not support slicing. Buffer the stream first.')\n  }\n\n  /**\n   * Open the underlying ReadableStream. Can only be called once.\n   * @returns The underlying ReadableStream of bytes.\n   *\n   * @throws If the stream has already been consumed.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    if (this.consumed) throw new Error('StreamSource can only be consumed once.')\n    this.consumed = true\n    return this.readable\n  }\n\n  /**\n   * Read the entire stream into an ArrayBuffer.\n   * @returns A promise that resolves with the full content as an ArrayBuffer.\n   */\n  async toArrayBuffer(): Promise<ArrayBuffer> {\n    const bytes = await collectStream(this.stream())\n    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer\n  }\n}\n\n/**\n * Convert a Uint8Array, Blob, or ReadableStream into a {@link ContentSource}.\n * When passing a ReadableStream, the `size` parameter is required.\n * @param input - The content to wrap, as a Uint8Array, Blob, or ReadableStream.\n * @param size - The total byte length, required when input is a ReadableStream.\n *\n * @returns A ContentSource adapter for the given input.\n *\n * @throws If input is a ReadableStream and size is not provided.\n */\nexport function toContentSource(\n  input: Uint8Array | Blob | ReadableStream<Uint8Array>,\n  size?: number,\n): ContentSource {\n  if (input instanceof Uint8Array) {\n    return new BufferSource(input)\n  }\n  if (input instanceof Blob) {\n    return new BlobSource(input)\n  }\n  if (size === undefined) {\n    throw new Error('size is required when using a ReadableStream as input.')\n  }\n  return new StreamSource(input, size)\n}\n"],"names":[],"mappings":";AAgCO,MAAM,WAAoC;AAAA;AAAA;AAAA;AAAA;AAAA,EAU/C,YAA6B,MAAY;AAAZ,SAAA,OAAA;AAC3B,SAAK,OAAO,KAAK;AAAA,EACnB;AAAA;AAAA,EAVS;AAAA;AAAA,EAEA,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBpB,MAAM,OAAe,KAA4B;AAC/C,WAAO,IAAI,WAAW,KAAK,KAAK,MAAM,OAAO,GAAG,CAAC;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAqC;AACnC,WAAO,KAAK,KAAK,OAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,gBAAsC;AACpC,WAAO,KAAK,KAAK,YAAA;AAAA,EACnB;AACF;AAGO,MAAM,aAAsC;AAAA;AAAA;AAAA;AAAA;AAAA,EAUjD,YAA6B,QAAoB;AAApB,SAAA,SAAA;AAC3B,SAAK,OAAO,OAAO;AAAA,EACrB;AAAA;AAAA,EAVS;AAAA;AAAA,EAEA,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBpB,MAAM,OAAe,KAA4B;AAC/C,WAAO,IAAI,aAAa,KAAK,OAAO,MAAM,OAAO,GAAG,CAAC;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAqC;AACnC,UAAM,SAAS,KAAK;AACpB,WAAO,IAAI,eAAe;AAAA,MACxB,MAAM,YAAY;AAChB,mBAAW,QAAQ,MAAM;AACzB,mBAAW,MAAA;AAAA,MACb;AAAA,IAAA,CACD;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,gBAAsC;AACpC,WAAO,QAAQ;AAAA,MACb,KAAK,OAAO,OAAO;AAAA,QACjB,KAAK,OAAO;AAAA,QACZ,KAAK,OAAO,aAAa,KAAK,OAAO;AAAA,MAAA;AAAA,IACvC;AAAA,EAEJ;AACF;AAGO,MAAM,aAAsC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBjD,YACmB,UACjB,MACA;AAFiB,SAAA,WAAA;AAGjB,SAAK,OAAO;AAAA,EACd;AAAA;AAAA,EApBS;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,WAAW;AAAA;AAAA,EAEZ,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBnB,QAAuB;AACrB,UAAM,IAAI,MAAM,iEAAiE;AAAA,EACnF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,SAAqC;AACnC,QAAI,KAAK,SAAU,OAAM,IAAI,MAAM,yCAAyC;AAC5E,SAAK,WAAW;AAChB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,gBAAsC;AAC1C,UAAM,QAAQ,MAAM,cAAc,KAAK,QAAQ;AAC/C,WAAO,MAAM,OAAO,MAAM,MAAM,YAAY,MAAM,aAAa,MAAM,UAAU;AAAA,EACjF;AACF;AAYO,SAAS,gBACd,OACA,MACe;AACf,MAAI,iBAAiB,YAAY;AAC/B,WAAO,IAAI,aAAa,KAAK;AAAA,EAC/B;AACA,MAAI,iBAAiB,MAAM;AACzB,WAAO,IAAI,WAAW,KAAK;AAAA,EAC7B;AACA,MAAI,SAAS,QAAW;AACtB,UAAM,IAAI,MAAM,wDAAwD;AAAA,EAC1E;AACA,SAAO,IAAI,aAAa,OAAO,IAAI;AACrC;"}

package/dist/sync/actions/index.cjs

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class UploadAction {
+  /**
+   * Creates a new UploadAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param absolutePath - Absolute local filesystem path.
+   * @param size - File size in bytes.
+   * @param doUpload - Callback that performs the actual upload.
+   */
+  constructor(relativePath, absolutePath, size, doUpload) {
+    this.relativePath = relativePath;
+    this.absolutePath = absolutePath;
+    this.size = size;
+    this.doUpload = doUpload;
+  }
+  type = "upload";
+  /**
+   * Uploads the file (unless dryRun) and returns an 'upload-done' event.
+   * @param dryRun - Whether to simulate the action without making changes.
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(dryRun) {
+    if (!dryRun) {
+      await this.doUpload(this.absolutePath, this.relativePath);
+    }
+    return { type: "upload-done", path: this.relativePath, size: this.size };
+  }
+}
+class DownloadAction {
+  /**
+   * Creates a new DownloadAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param size - File size in bytes.
+   * @param doDownload - Callback that performs the actual download.
+   */
+  constructor(relativePath, size, doDownload) {
+    this.relativePath = relativePath;
+    this.size = size;
+    this.doDownload = doDownload;
+  }
+  type = "download";
+  /**
+   * Downloads the file (unless dryRun) and returns a 'download-done' event.
+   * @param dryRun - Whether to simulate the action without making changes.
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(dryRun) {
+    if (!dryRun) {
+      await this.doDownload(this.relativePath);
+    }
+    return { type: "download-done", path: this.relativePath, size: this.size };
+  }
+}
+class CopyAction {
+  /**
+   * Creates a new CopyAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param size - File size in bytes.
+   * @param doCopy - Callback that performs the server-side copy.
+   */
+  constructor(relativePath, size, doCopy) {
+    this.relativePath = relativePath;
+    this.size = size;
+    this.doCopy = doCopy;
+  }
+  type = "copy";
+  /**
+   * Copies the file (unless dryRun) and returns a 'copy-done' event.
+   * @param dryRun - Whether to simulate the action without making changes.
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(dryRun) {
+    if (!dryRun) {
+      await this.doCopy(this.relativePath);
+    }
+    return { type: "copy-done", path: this.relativePath, size: this.size };
+  }
+}
+class HideAction {
+  /**
+   * Creates a new HideAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param doHide - Callback that creates the hide marker.
+   */
+  constructor(relativePath, doHide) {
+    this.relativePath = relativePath;
+    this.doHide = doHide;
+  }
+  type = "hide";
+  size = 0;
+  /**
+   * Hides the file (unless dryRun) and returns a 'hide' event.
+   * @param dryRun - Whether to simulate the action without making changes.
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(dryRun) {
+    if (!dryRun) {
+      await this.doHide(this.relativePath);
+    }
+    return { type: "hide", path: this.relativePath, size: 0 };
+  }
+}
+class DeleteRemoteAction {
+  /**
+   * Creates a new DeleteRemoteAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param fileId - The B2 file version ID to delete.
+   * @param doDelete - Callback that performs the deletion.
+   */
+  constructor(relativePath, fileId, doDelete) {
+    this.relativePath = relativePath;
+    this.fileId = fileId;
+    this.doDelete = doDelete;
+  }
+  type = "delete-remote";
+  size = 0;
+  /**
+   * Deletes the remote file version (unless dryRun) and returns a 'delete-remote' event.
+   * @param dryRun - Whether to simulate the action without making changes.
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(dryRun) {
+    if (!dryRun) {
+      await this.doDelete(this.fileId, this.relativePath);
+    }
+    return { type: "delete-remote", path: this.relativePath, size: 0 };
+  }
+}
+class DeleteLocalAction {
+  /**
+   * Creates a new DeleteLocalAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param absolutePath - Absolute local filesystem path.
+   * @param doDelete - Callback that performs the deletion.
+   */
+  constructor(relativePath, absolutePath, doDelete) {
+    this.relativePath = relativePath;
+    this.absolutePath = absolutePath;
+    this.doDelete = doDelete;
+  }
+  type = "delete-local";
+  size = 0;
+  /**
+   * Deletes the local file (unless dryRun) and returns a 'delete-local' event.
+   * @param dryRun - Whether to simulate the action without making changes.
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(dryRun) {
+    if (!dryRun) {
+      await this.doDelete(this.absolutePath);
+    }
+    return { type: "delete-local", path: this.relativePath, size: 0 };
+  }
+}
+class SkipAction {
+  /**
+   * Creates a new SkipAction for the given relative path.
+   * @param relativePath - Path relative to the sync root.
+   * @param reason - Human-readable explanation for why the file was skipped.
+   */
+  constructor(relativePath, reason) {
+    this.relativePath = relativePath;
+    this.reason = reason;
+  }
+  type = "skip";
+  size = 0;
+  /**
+   * Returns a 'skip' event with the reason message. No I/O is performed.
+   * @param _dryRun - Whether to simulate the action (unused for no-op).
+   *
+   * @returns An async generator yielding sync progress events.
+   */
+  async execute(_dryRun) {
+    return { type: "skip", path: this.relativePath, size: 0, message: this.reason };
+  }
+}
+exports.CopyAction = CopyAction;
+exports.DeleteLocalAction = DeleteLocalAction;
+exports.DeleteRemoteAction = DeleteRemoteAction;
+exports.DownloadAction = DownloadAction;
+exports.HideAction = HideAction;
+exports.SkipAction = SkipAction;
+exports.UploadAction = UploadAction;
+//# sourceMappingURL=index.cjs.map