@aws-sdk/lib-transfer-manager 0.0.0-stage → 0.1.0

package/dist-types/submodules/transfer-manager/directory-transfer-utils.d.ts

@@ -0,0 +1,90 @@
+import type { _Object as S3Object } from "@aws-sdk/client-s3";
+import type { CannedFailurePolicy, DirectoryTransferFailureContext, FailurePolicy } from "./types";
+/**
+ * Weighted semaphore with a soft concurrency limit.
+ * Allows a job to start if in-flight weight is below the limit, even if
+ * that job pushes the total over. New jobs are paused until it drops back.
+ *
+ * @internal
+ */
+export declare class Semaphore {
+    private readonly limit;
+    private inFlightRequests;
+    private waiters;
+    constructor(limit: number);
+    acquire(count?: number): Promise<void>;
+    release(count?: number): void;
+}
+/**
+ * Validates that a path exists and is a directory.
+ * Resolves to absolute path.
+ *
+ * @param dirPath - The directory path to validate.
+ *
+ * @throws Error - If the path does not exist.
+ * @throws Error - If the path is not a directory.
+ *
+ * @internal
+ */
+export declare function validateDirectory(dirPath: string): Promise<string>;
+/**
+ * Executes the failure policy for a failed transfer (upload or download).
+ *
+ * @param policy - The failure policy to execute (canned or custom callback).
+ * @param context - The failure context containing the directory request, failed object request, and error.
+ * @param abortController - Controller to signal abort to all in-flight operations on terminate.
+ *
+ * @internal
+ */
+export declare function handleFailure(policy: FailurePolicy, context: DirectoryTransferFailureContext, abortController: AbortController): Promise<CannedFailurePolicy>;
+/**
+ * Prepares the destination directory for a directory download.
+ *
+ * If the path does not exist, it is created along with any missing parent
+ * directories, using the runtime's default file-creation permissions.
+ *
+ * @param dirPath - The destination directory path.
+ * @returns The resolved absolute path of the destination directory.
+ *
+ * @throws Error - If the path exists but is not a directory.
+ *
+ * @internal
+ */
+export declare function createDestinationDirectory(dirPath: string): Promise<string>;
+/**
+ * Determines whether an S3 object represents a folder placeholder rather than a
+ * file. Objects whose key ends with "/" and whose size is zero.
+ *
+ * @param object - The S3 object to check.
+ * @returns true if the object is a folder placeholder.
+ *
+ * @internal
+ */
+export declare function isFolderObject(object: S3Object): boolean;
+/**
+ * Derives the local absolute file path for an S3 object key, relative to the
+ * destination directory.
+ *
+ *
+ * @param destination - The resolved absolute destination directory.
+ * @param key - The S3 object key. Callers must pass a non-empty key.
+ * @returns The resolved absolute local file path.
+ *
+ * @throws Error - If the key is absolute, or resolves outside the destination directory.
+ *
+ * @internal
+ */
+export declare function deriveLocalPath(destination: string, key: string): string;
+/**
+ * Creates the parent directories for a local download path, verifying each
+ * component's canonical (symlink-resolved) location stays within the
+ * destination.
+ *
+ * @param destination - The resolved absolute destination directory.
+ * @param localPath - The resolved absolute local file path (from deriveLocalPath).
+ *
+ * @throws Error - If any parent component resolves outside the destination.
+ *
+ * @internal
+ */
+export declare function createLocalParentDirectories(destination: string, localPath: string): Promise<void>;

package/dist-types/submodules/transfer-manager/event-listener-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Function type for handling transfer events in the transfer manager.
+ * Represents a callback that receives event data during transfer operations.
+ *
+ * @param event - The event object containing transfer details and progress information.
+
+ * @alpha
+ */
+export type EventListenerFunction<E = Event> = (event: Event & E) => void;
+/**
+ * Union type for handling transfer events in the transfer manager.
+ * Can be a function or an object.
+ *
+ * @alpha
+ */
+export type EventListener<E = Event> = EventListenerFunction<E> | EventListenerObject<E>;
+/**
+ * Object type for handling transfer events in the transfer manager.
+ * Represents an object that implements the `handleEvent` method to handle transfer events.
+ *
+ * @alpha
+ */
+export type EventListenerObject<E = Event> = {
+    handleEvent: EventListenerFunction<E>;
+};
+/**
+ * Configuration options for registering event listeners in the transfer manager.
+ * Controls the behavior of event listeners for transfer events.
+ *
+ * @alpha
+ */
+export type AddEventListenerOptions = {
+    /**
+     * A boolean value indicating that the listener should be invoked at most once
+     * after being added. If true, the listener would be automatically removed when invoked.
+     * If not specified, defaults to false.
+     */
+    once?: boolean;
+    /**
+     * An AbortSignal. The listener will be removed when the abort() method of the
+     * AbortController which owns the AbortSignal is called. If not specified, no
+     * AbortSignal is associated with the listener.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * Configuration options for removing event listeners in the transfer manager.
+ * Controls the behavior of event listeners for transfer events.
+ *
+ * @alpha
+ */
+export type RemoveEventListenerOptions = {
+    capture?: boolean;
+};

package/dist-types/submodules/transfer-manager/file-manager.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility class responsible for temp-file lifecycle management during downloadToFile.
+ * Handles creation, pre-allocation, atomic rename, and cleanup of temp files.
+ *
+ * @internal
+ */
+export declare class FileManager {
+    private cleanupHandlers;
+    /**
+     * Creates a temporary file for the download with a unique identifier.
+     * Sets the file length to `totalSize` up front via truncate so concurrent
+     * part writes can target their offsets without coordination.
+     *
+     * @param destination - The final destination file path.
+     * @param totalSize - Total byte size to set as the file length.
+     * @returns The path to the created temp file.
+     */
+    createTempFile(destination: string, totalSize: number): Promise<string>;
+    /**
+     * Renames the temp file to the destination atomically.
+     * On platforms where rename doesn't overwrite, falls back to
+     * deleting the destination first.
+     *
+     * @param tempFilePath - Path to the temp file.
+     * @param destination - Final destination path.
+     */
+    atomicRename(tempFilePath: string, destination: string): Promise<void>;
+    /**
+     * Deletes the temp file and unregisters any associated cleanup handlers.
+     *
+     * @param tempFilePath - Path to the temp file to delete.
+     */
+    deleteTempFile(tempFilePath: string): Promise<void>;
+    /**
+     * Registers process-level cleanup handlers that remove the temp file
+     * if the process terminates unexpectedly.
+     *
+     * @param tempFilePath - Path to the temp file to clean up.
+     */
+    registerCleanupHandler(tempFilePath: string): void;
+    /**
+     * Removes the registered cleanup handlers for the given temp file.
+     *
+     * @param tempFilePath - Path to the temp file whose handlers should be removed.
+     */
+    unregisterCleanupHandler(tempFilePath: string): void;
+    /**
+     * Generates a unique identifier of at most 8 alphanumeric characters.
+     */
+    private generateUniqueId;
+}

package/dist-types/submodules/transfer-manager/index.browser.d.ts

@@ -0,0 +1,10 @@
+declare const S3TransferManager_base: import("./S3TransferManager").S3TransferManagerConstructor;
+/**
+ * Browser version of the TransferManager that uses fetch and ReadableStream.
+ * Worker-based multi-threading is currently not available for the browser implementation.
+ *
+ * @alpha
+ */
+export declare class S3TransferManager extends S3TransferManager_base {
+}
+export type { DownloadToFileRequest, DownloadToFileResponse, IS3TransferManager } from "./types";

package/dist-types/submodules/transfer-manager/index.d.ts

@@ -0,0 +1,10 @@
+declare const S3TransferManager_base: import("./S3TransferManager").S3TransferManagerConstructor;
+/**
+ * Node.js version of the TransferManager, providing high-level upload and download
+ * operations for Amazon S3 with multipart parallelism and worker-based multi-threading.
+ *
+ * @alpha
+ */
+export declare class S3TransferManager extends S3TransferManager_base {
+}
+export type { DownloadToFileRequest, DownloadToFileResponse, IS3TransferManager } from "./types";

package/dist-types/submodules/transfer-manager/join-streams.browser.d.ts

@@ -0,0 +1,21 @@
+import type { StreamingBlobPayloadOutputTypes } from "@smithy/types";
+import type { JoinStreamIterationEvents } from "./types";
+/**
+ * Joins multiple stream promises into a single stream with event callbacks.
+ *
+ * @internal
+ */
+export declare function joinStreams(streams: Promise<StreamingBlobPayloadOutputTypes>[], eventListeners?: JoinStreamIterationEvents): Promise<StreamingBlobPayloadOutputTypes>;
+/**
+ * Iterates through stream promises sequentially, yielding chunks with progress tracking.
+ *
+ * @internal
+ */
+export declare function iterateStreams(promises: Promise<StreamingBlobPayloadOutputTypes>[], eventListeners?: JoinStreamIterationEvents): AsyncIterable<Uint8Array, void, void>;
+/**
+ * Browser equivalent of the Node.js `destroyStreams`. Cancels any
+ * still-unconsumed response bodies so their underlying resources are released.
+ *
+ * @internal
+ */
+export declare function destroyStreams(promises: Promise<StreamingBlobPayloadOutputTypes>[]): Promise<void>;

package/dist-types/submodules/transfer-manager/join-streams.d.ts

@@ -0,0 +1,26 @@
+import type { StreamingBlobPayloadOutputTypes } from "@smithy/types";
+import type { JoinStreamIterationEvents } from "./types";
+/**
+ * Joins multiple stream promises into a single stream with event callbacks.
+ *
+ * @internal
+ */
+export declare function joinStreams(streams: Promise<StreamingBlobPayloadOutputTypes>[], eventListeners?: JoinStreamIterationEvents): Promise<StreamingBlobPayloadOutputTypes>;
+/**
+ * Iterates through stream promises sequentially, yielding chunks with progress tracking.
+ *
+ * @internal
+ */
+export declare function iterateStreams(promises: Promise<StreamingBlobPayloadOutputTypes>[], eventListeners?: JoinStreamIterationEvents): AsyncIterable<StreamingBlobPayloadOutputTypes, void, void>;
+/**
+ * Destroys/cancels a set of stream promises, swallowing any errors.
+ *
+ * Used to clean up response bodies that were received but never fully consumed
+ * (for example when a transfer is aborted). A no-op "error" handler is attached
+ * to Node streams before destroying so that a socket-level error raised while
+ * tearing down an unconsumed response body (e.g. "aborted"/ECONNRESET) does not
+ * surface as an uncaught exception.
+ *
+ * @internal
+ */
+export declare function destroyStreams(promises: Promise<StreamingBlobPayloadOutputTypes>[]): Promise<void>;

package/dist-types/submodules/transfer-manager/log-level.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from "@smithy/types";
+export declare class LogLevel implements Logger {
+    private minimum;
+    private logger;
+    private static LEVELS;
+    private readonly level;
+    constructor(minimum: keyof Logger, logger?: Logger);
+    trace(...args: any[]): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}

package/dist-types/submodules/transfer-manager/ordered-part-queue.d.ts

@@ -0,0 +1,73 @@
+export interface QueuedPart {
+    /**
+     * The transferred ArrayBuffer containing the part data.
+     */
+    buffer: ArrayBuffer;
+    /**
+     * Actual bytes written (may be less than buffer.byteLength for the last part).
+     */
+    byteLength: number;
+}
+/**
+ * Reorder buffer that accepts out-of-order part arrivals from parallel download
+ * workers and delivers them sequentially to a Readable stream consumer.
+ *
+ * @internal
+ */
+export declare class OrderedPartQueue {
+    /**
+     * Out-of-order parts waiting for their turn. Keyed by rangeIndex.
+     */
+    private pending;
+    /**
+     * Next sequential rangeIndex the consumer expects.
+     */
+    private nextExpected;
+    /**
+     * Total number of parts to deliver.
+     */
+    private readonly totalParts;
+    /**
+     * Resolve callback for the consumer waiting for the next part.
+     */
+    private waitingConsumer;
+    /**
+     * Error from a failed download.
+     */
+    private error;
+    constructor(totalParts: number);
+    /**
+     * Called when a worker delivers a part (may arrive out of order).
+     * If the consumer is waiting for this exact part, delivers immediately.
+     * Otherwise stores it until its turn.
+     */
+    enqueue(rangeIndex: number, buffer: ArrayBuffer, byteLength: number): void;
+    /**
+     * Called by the Readable stream's read() to get the next sequential part.
+     * Returns null when all parts have been consumed.
+     * Waits asynchronously if the next part hasn't arrived yet.
+     */
+    dequeue(): Promise<QueuedPart | null>;
+    /**
+     * Called when a worker part fails, when the dispatch loop throws
+     * or when the stream is destroyed. Unblocks the consumer
+     * if it's waiting so the stream can surface the error instead of hanging.
+     */
+    setError(error: unknown): void;
+    /**
+     * The dispatch loop
+     * checks this to stop launching new part requests,
+     * and the Readable stream checks it to distinguish completion from failure
+     * when dequeue() returns null.
+     */
+    hasError(): boolean;
+    /**
+     * Called by the Readable stream's read() to pass the error to stream.destroy(err).
+     */
+    getError(): unknown;
+    /**
+     * Returns the number of parts currently held (arrived but not yet delivered).
+     * Useful for monitoring reorder buffer depth.
+     */
+    get pendingCount(): number;
+}