@huggingface/hub/dist/src/lib/copy-files.d.ts

Utilities to interact with the Hugging Face hub

import type { BucketDesignation, CredentialsParams, RepoDesignation } from "../types/public";
import type { CommitParams } from "./commit";
/**
 * Progress events yielded by {@link copyFileIter} / {@link copyFilesIter} / {@link copyFolderIter}.
 *
 * Currently only `fileDownloaded` is emitted: one event per source file that had to be downloaded
 * (small git-stored files that can't be copied server-side). Xet-backed files are copied
 * server-side and do not produce events.
 */
export interface CopyProgressEvent {
    event: "fileDownloaded";
    /** Source path of the file that was just downloaded. */
    path: string;
    /** Number of files downloaded so far (including this one). */
    downloaded: number;
    /** Total number of files that will be downloaded. */
    total: number;
}
/**
 * Source location of a file in {@link copyFile} / {@link copyFiles} / {@link copyFolder}.
 */
export interface CopySource {
    repo: RepoDesignation;
    /**
     * Path of the file (or folder, for {@link copyFolder}) inside the source repo.
     * Leave empty in {@link copyFolder} to copy the whole repo.
     */
    path: string;
    /**
     * Git revision to read the source from. Ignored for bucket sources.
     *
     * @default "main"
     */
    revision?: string;
}
/**
 * Destination location for {@link copyFile} / {@link copyFolder}.
 *
 * The destination repo must be a bucket — server-side copy is currently only supported
 * towards buckets.
 */
export interface CopyDestination {
    repo: BucketDesignation;
    /**
     * Exact destination path within the destination bucket. For {@link copyFolder},
     * acts as a prefix; leave empty to copy under the bucket root.
     */
    path: string;
}
/**
 * One file to copy in a {@link copyFiles} call.
 */
export interface CopyFilesEntry {
    source: CopySource;
    /**
     * Exact path within the destination bucket. The bucket itself is shared with the
     * other entries via the top-level {@link copyFiles} `destination` parameter.
     */
    destinationPath: string;
}
type SharedParams = {
    hubUrl?: CommitParams["hubUrl"];
    fetch?: CommitParams["fetch"];
    abortSignal?: CommitParams["abortSignal"];
} & Partial<CredentialsParams>;
/**
 * Copy a single file from a source repo/bucket to the destination bucket.
 *
 * The copy is server-side (no data transfer) when the source file is xet-backed.
 * For small non-xet repo files (e.g. `config.json`) the file is downloaded and
 * re-uploaded to the destination bucket in the same commit.
 *
 * LFS pointer files that have not been migrated to xet are rejected up front
 * (they would otherwise require downloading the full LFS blob).
 *
 * @example
 * ```ts
 * await copyFile({
 *   source: {
 *     repo: { type: "model", name: "username/my-model" },
 *     path: "model.safetensors",
 *   },
 *   destination: {
 *     repo: { type: "bucket", name: "username/my-bucket" },
 *     path: "models/my-model/model.safetensors",
 *   },
 *   accessToken: "hf_...",
 * });
 * ```
 */
export declare function copyFile(params: {
    source: CopySource;
    destination: CopyDestination;
} & SharedParams): Promise<undefined>;
/**
 * Async-iterator variant of {@link copyFile} that yields {@link CopyProgressEvent}s while
 * downloading non-xet source files (xet-backed files are copied server-side and do not
 * emit events). See {@link copyFile} for the semantics.
 *
 * @example
 * ```ts
 * for await (const event of copyFileIter({ source, destination, accessToken })) {
 *   console.log(`downloaded ${event.path} (${event.downloaded}/${event.total})`);
 * }
 * ```
 */
export declare function copyFileIter(params: {
    source: CopySource;
    destination: CopyDestination;
} & SharedParams): AsyncGenerator<CopyProgressEvent, undefined>;
/**
 * Copy multiple files (potentially from different source repos/buckets) to the destination
 * bucket in a single commit.
 *
 * For xet-backed source files, the copy is performed server-side with no data transfer.
 * For non-xet source files (typically small git-stored repo files), the file is
 * downloaded and re-uploaded as part of the same commit.
 *
 * LFS pointer files that have not been migrated to xet are rejected up front.
 *
 * @example
 * ```ts
 * await copyFiles({
 *   destination: { type: "bucket", name: "username/my-bucket" },
 *   files: [
 *     {
 *       source: {
 *         repo: { type: "bucket", name: "username/other-bucket" },
 *         path: "data.bin",
 *       },
 *       destinationPath: "data.bin",
 *     },
 *     {
 *       source: {
 *         repo: { type: "model", name: "username/my-model" },
 *         path: "model.safetensors",
 *       },
 *       destinationPath: "models/my-model/model.safetensors",
 *     },
 *   ],
 *   accessToken: "hf_...",
 * });
 * ```
 */
export declare function copyFiles(params: {
    destination: BucketDesignation;
    files: CopyFilesEntry[];
} & SharedParams): Promise<undefined>;
/**
 * Async-iterator variant of {@link copyFiles} that yields {@link CopyProgressEvent}s while
 * downloading non-xet source files (xet-backed files are copied server-side and do not
 * emit events). See {@link copyFiles} for the semantics.
 */
export declare function copyFilesIter(params: {
    destination: BucketDesignation;
    files: CopyFilesEntry[];
} & SharedParams): AsyncGenerator<CopyProgressEvent, undefined>;
/**
 * Copy a folder (recursively) from a source repo/bucket to the destination bucket
 * in a single commit.
 *
 * Per-file paths are resolved relative to {@link CopySource.path}; the source folder
 * itself is not preserved in the destination unless {@link CopyDestination.path}
 * keeps it.
 *
 * @example
 * ```ts
 * // Copy an entire dataset under "datasets/my-dataset/" in the bucket
 * await copyFolder({
 *   source: { repo: { type: "dataset", name: "username/my-dataset" } },
 *   destination: {
 *     repo: { type: "bucket", name: "username/my-bucket" },
 *     path: "datasets/my-dataset/",
 *   },
 *   accessToken: "hf_...",
 * });
 *
 * // Copy a subfolder
 * await copyFolder({
 *   source: {
 *     repo: { type: "bucket", name: "username/src-bucket" },
 *     path: "models/",
 *   },
 *   destination: {
 *     repo: { type: "bucket", name: "username/dst-bucket" },
 *     path: "backup/",
 *   },
 *   accessToken: "hf_...",
 * });
 * ```
 */
export declare function copyFolder(params: {
    source: Omit<CopySource, "path"> & {
        path?: string;
    };
    destination: Omit<CopyDestination, "path"> & {
        path?: string;
    };
} & SharedParams): Promise<undefined>;
/**
 * Async-iterator variant of {@link copyFolder} that yields {@link CopyProgressEvent}s while
 * downloading non-xet source files (xet-backed files are copied server-side and do not
 * emit events). See {@link copyFolder} for the semantics.
 */
export declare function copyFolderIter(params: {
    source: Omit<CopySource, "path"> & {
        path?: string;
    };
    destination: Omit<CopyDestination, "path"> & {
        path?: string;
    };
} & SharedParams): AsyncGenerator<CopyProgressEvent, undefined>;
/**
 * Compute the path of `filePath` relative to `folderPath`. Used to map source paths
 * under a folder being copied to destination paths under the new prefix.
 */
export declare function relativeUnderFolder(filePath: string, folderPath: string): string;
export {};
//# sourceMappingURL=copy-files.d.ts.map