disk 0.8.13 → 0.8.15

package/dist/index.d.ts

@@ -1553,6 +1553,171 @@ interface ListObjectsResult {
     /** The prefix the listing was filtered by, echoed back by the server. */
     prefix?: string;
 }
+/** A part to list in {@link Disk.completeMultipartUpload}. */
+interface UploadPart {
+    /** 1-based part number (1..=10000), strictly increasing across the list. */
+    partNumber: number;
+    /** Entity tag returned by {@link Disk.uploadPart} for this part. */
+    etag: string;
+}
+/** Handle to an in-progress multipart upload, returned by {@link Disk.createMultipartUpload}. */
+interface MultipartUpload {
+    /** Server-assigned upload id; pass to uploadPart/complete/abort/listParts. */
+    uploadId: string;
+    /** The object key this upload targets. */
+    key: string;
+    /** The bucket (disk id) the upload lives in. */
+    bucket: string;
+}
+/** The assembled object, returned by {@link Disk.completeMultipartUpload}. */
+interface CompletedMultipartUpload {
+    /** Multipart entity tag — S3's `md5(concat(partMd5s))-N` form. */
+    etag?: string;
+    /** Resource path of the completed object. */
+    location?: string;
+    /** The bucket (disk id). */
+    bucket?: string;
+    /** The object key. */
+    key?: string;
+}
+/** One part in a {@link Disk.listParts} listing. */
+interface PartInfo {
+    /** 1-based part number. */
+    partNumber: number;
+    /** Entity tag the server assigned to this part. */
+    etag?: string;
+    /** Size in bytes. */
+    size: number;
+    /** Time the part was uploaded, if reported. */
+    lastModified?: Date;
+}
+interface ListPartsOptions {
+    /** Cap parts returned in one page (server clamps to 1000). */
+    maxParts?: number;
+    /** Return parts after this part number (for pagination). */
+    partNumberMarker?: number;
+}
+interface PartListing {
+    /** The bucket (disk id), echoed by the server. */
+    bucket?: string;
+    /** The object key, echoed by the server. */
+    key?: string;
+    /** The upload id, echoed by the server. */
+    uploadId?: string;
+    /** Parts in this page, ascending by part number. */
+    parts: PartInfo[];
+    /** True if more parts exist beyond this page. */
+    isTruncated: boolean;
+    /** The part-number marker this page started after. */
+    partNumberMarker: number;
+    /** Pass back as `partNumberMarker` to fetch the next page. */
+    nextPartNumberMarker?: number;
+    /** Max parts the server was asked to return. */
+    maxParts: number;
+}
+/** One in-progress upload in a {@link Disk.listMultipartUploads} listing. */
+interface MultipartUploadSummary {
+    /** The object key the upload targets. */
+    key: string;
+    /** The upload id. */
+    uploadId: string;
+    /** When the upload was initiated, if reported. */
+    initiated?: Date;
+}
+interface ListMultipartUploadsOptions {
+    /** Only list uploads whose key begins with this prefix. */
+    prefix?: string;
+    /** Roll keys up to this delimiter into `commonPrefixes` (S3 supports "/"). */
+    delimiter?: string;
+    /** Resume listing keys after this one (with `uploadIdMarker`). */
+    keyMarker?: string;
+    /** Resume listing uploads after this upload id (requires `keyMarker`). */
+    uploadIdMarker?: string;
+    /** Cap uploads returned in one page (server clamps to 1000). */
+    maxUploads?: number;
+}
+interface MultipartUploadListing {
+    /** The bucket (disk id), echoed by the server. */
+    bucket?: string;
+    /** In-progress uploads in this page. */
+    uploads: MultipartUploadSummary[];
+    /** Key prefixes rolled up by `delimiter` (empty if no delimiter). */
+    commonPrefixes: string[];
+    /** True if more uploads exist beyond this page. */
+    isTruncated: boolean;
+    /** The key marker this page started after, echoed back. */
+    keyMarker?: string;
+    /** The upload-id marker this page started after, echoed back. */
+    uploadIdMarker?: string;
+    /** Pass back as `keyMarker` (with `nextUploadIdMarker`) for the next page. */
+    nextKeyMarker?: string;
+    /** Pass back as `uploadIdMarker` (with `nextKeyMarker`) for the next page. */
+    nextUploadIdMarker?: string;
+    /** The prefix the listing was filtered by, echoed back. */
+    prefix?: string;
+    /** The delimiter used, echoed back. */
+    delimiter?: string;
+    /** Max uploads the server was asked to return. */
+    maxUploads?: number;
+}
+interface DeleteObjectsOptions {
+    /**
+     * Quiet mode: the server omits the per-key success list and returns only
+     * failures, so the result's `deleted` array is empty. Cuts response size on
+     * large batches. Defaults to false.
+     */
+    quiet?: boolean;
+}
+/** A single per-key failure within a {@link Disk.deleteObjects} batch. */
+interface DeleteObjectsError {
+    /** The key that failed to delete. */
+    key: string;
+    /** S3 error code (e.g. "AccessDenied", "OperationAborted"), if provided. */
+    code?: string;
+    /** Human-readable failure detail, if provided. */
+    message?: string;
+}
+interface DeleteObjectsResult {
+    /** Keys the server confirmed deleted (empty in quiet mode). */
+    deleted: string[];
+    /** Per-key failures; empty when every key was deleted. */
+    errors: DeleteObjectsError[];
+}
+interface PutObjectOptions {
+    /** MIME type to store the object with. Default "application/octet-stream". */
+    contentType?: string;
+    /**
+     * Bodies larger than this take the multipart path; bodies at or below it take
+     * a single PutObject. Defaults to `partSize` (16 MiB), so by default the
+     * switch happens at the part size. Set it lower (e.g. 5 MiB) to start using
+     * multipart sooner, or to `Infinity` to force a single PutObject.
+     */
+    multipartThreshold?: number;
+    /**
+     * Bytes per part on the multipart path. Clamped to a minimum of 5 MiB (the S3
+     * floor for every part but the last). Default 16 MiB.
+     */
+    partSize?: number;
+    /** Max parts uploaded in parallel on the multipart path. Default 4. */
+    concurrency?: number;
+}
+/**
+ * The S3 transport function {@link DiskMultipart} uses, supplied by the owning
+ * {@link Disk} so the namespace shares the disk's credential and endpoint.
+ * @internal
+ */
+type S3RequestFn = (method: "GET" | "PUT" | "DELETE" | "HEAD" | "POST", key: string, opts?: {
+    body?: string | Uint8Array | ArrayBuffer;
+    contentType?: string;
+    query?: Record<string, string | number>;
+    retry?: boolean;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    body: Uint8Array;
+}>;
 declare class Disk {
     readonly id: string;
     readonly name: string;
@@ -1576,6 +1741,8 @@ declare class Disk {
     private readonly _archilRegion;
     /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
     private readonly _s3BaseUrl;
+    /** Lazily-constructed multipart namespace (see {@link multipart}). @internal */
+    private _multipart?;
     /** @internal */
     constructor(data: DiskResponse, client: ApiClient, archilRegion: string, s3BaseUrl?: string);
     toJSON(): DiskResponse;
@@ -1638,15 +1805,52 @@ declare class Disk {
     /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
     objectExists(key: string): Promise<boolean>;
     /**
-     * Write an object to the disk using the S3-compatible PutObject API. Faster
-     * than exec for large files — no container overhead, no command-length limits.
-     * Returns the entity tag the server assigned.
+     * Write an object to the disk via the S3-compatible API. Handles any size:
+     * bodies at or below `multipartThreshold` (defaults to `partSize`, i.e.
+     * 16 MiB) go through a single PutObject request; larger bodies are uploaded as
+     * a multipart upload — split into `partSize` parts, uploaded with bounded
+     * `concurrency` (default 4), and assembled. A failed part aborts the upload so
+     * nothing is left half-staged. For manual control over the multipart
+     * lifecycle, use the {@link multipart} namespace.
+     *
+     * Faster than exec for large files — no container overhead, no command-length
+     * limits. Returns the entity tag the server assigned (a multipart upload's tag
+     * is S3's `md5(concat(partMd5s))-N` form rather than a plain MD5).
      *
-     * @param key          Path on the disk (e.g. "reports/2026-01/data.json")
-     * @param body         Contents as a string, Uint8Array/Buffer, or ArrayBuffer
-     * @param contentType  MIME type (default: "application/octet-stream")
+     * @param key      Path on the disk (e.g. "reports/2026-01/data.json")
+     * @param body     Contents as a string, Uint8Array/Buffer, or ArrayBuffer
+     * @param options  Either a content-type string, or {@link PutObjectOptions}
+     *                 (`contentType`, `multipartThreshold`, `partSize`,
+     *                 `concurrency`). Content type defaults to
+     *                 "application/octet-stream".
      */
-    putObject(key: string, body: string | Uint8Array | ArrayBuffer, contentType?: string): Promise<PutObjectResult>;
+    putObject(key: string, body: string | Uint8Array | ArrayBuffer, options?: string | PutObjectOptions): Promise<PutObjectResult>;
+    /**
+     * Upload a large body through the multipart lifecycle: split into `partSize`
+     * parts, upload them with bounded concurrency, then complete — aborting the
+     * upload if any part fails so nothing is left half-staged. @internal
+     */
+    private _putMultipart;
+    /**
+     * Append bytes to an object via the S3-compatible PutObject append extension
+     * (`?append=true`). If the object already exists the bytes are appended to it;
+     * if it doesn't, it is created. Returns the entity tag of the full object
+     * after the append.
+     *
+     * Each call may append at most 1 MiB — the server rejects a larger body with
+     * `EntityTooLarge`. To grow an object past that, append in chunks (or use
+     * {@link putObject} for a one-shot large write).
+     *
+     * Unlike most operations this is NOT auto-retried on a transient error:
+     * append isn't idempotent, so retrying a succeeded-but-unacknowledged append
+     * would duplicate the bytes. On a transient failure, re-append yourself only
+     * after confirming the object's size.
+     *
+     * @param key          Path on the disk (e.g. "logs/app.log")
+     * @param body         Bytes to append (string, Uint8Array/Buffer, or ArrayBuffer)
+     * @param contentType  MIME type, applied only when the object is newly created.
+     */
+    appendObject(key: string, body: string | Uint8Array | ArrayBuffer, contentType?: string): Promise<PutObjectResult>;
     /**
      * Delete an object from the disk via the S3-compatible DeleteObject API.
      * Idempotent: deleting a key that doesn't exist resolves successfully, per
@@ -1683,6 +1887,29 @@ declare class Disk {
     listObjectsPages(prefix?: string, opts?: ListObjectsOptions): AsyncGenerator<ListObjectsResult>;
     /** Fetch a single ListObjectsV2 page. @internal */
     private _listObjectsPage;
+    /**
+     * Delete up to many objects in a single S3-compatible DeleteObjects request.
+     * Unlike {@link deleteObject}, failures are reported per key rather than
+     * thrown: the result's `deleted` lists the keys that were removed and
+     * `errors` lists the ones that weren't (with the server's code/message). A
+     * key that didn't exist still counts as deleted, per S3 semantics.
+     *
+     * The server caps a single request at 1000 keys; this method transparently
+     * splits larger inputs into 1000-key batches and merges the results.
+     *
+     * @param keys  Object keys to delete.
+     * @param opts  `quiet` suppresses the per-key success list server-side.
+     */
+    deleteObjects(keys: string[], opts?: DeleteObjectsOptions): Promise<DeleteObjectsResult>;
+    /**
+     * The advanced, opt-in multipart-upload API. Drive the raw lifecycle
+     * yourself — `create` → `uploadPart` → `complete` (or `abort`), plus
+     * `listParts` / `listUploads`. Most callers don't need this: {@link putObject}
+     * runs the whole lifecycle automatically for large bodies. Reach for it only
+     * when you need manual control (e.g. uploading parts from separate processes),
+     * and note you then own part-size, memory, and concurrency management.
+     */
+    get multipart(): DiskMultipart;
     /**
      * Send a single request to the disk's S3-compatible endpoint. This reuses the
      * control-plane client purely for its credential and transport — the same
@@ -1705,6 +1932,89 @@ declare class Disk {
      */
     mount(opts?: MountOptions): Promise<unknown>;
 }
+/**
+ * The advanced, opt-in multipart-upload namespace, reached via {@link Disk.multipart}.
+ * Drives the raw S3 multipart lifecycle — `create` → `uploadPart` → `complete`
+ * (or `abort`), plus `listParts` / `listUploads`. Prefer {@link Disk.putObject},
+ * which runs this lifecycle automatically for large bodies; use this only when
+ * you need manual control, in which case you own part-size, memory, and
+ * concurrency management.
+ */
+declare class DiskMultipart {
+    private readonly diskId;
+    private readonly s3Request;
+    /** @internal */
+    constructor(diskId: string, s3Request: S3RequestFn);
+    /**
+     * Start a multipart upload (CreateMultipartUpload) and return its `uploadId`.
+     *
+     * @param key          Path on the disk the finished object will live at.
+     * @param contentType  MIME type to store the object with.
+     */
+    create(key: string, contentType?: string): Promise<MultipartUpload>;
+    /**
+     * Upload one part (UploadPart) and return its entity tag, which you must
+     * collect (with its part number) and pass to {@link complete}. Every part
+     * except the last must be at least 5 MiB.
+     *
+     * @param key         The upload's object key.
+     * @param uploadId    The id from {@link create}.
+     * @param partNumber  1-based part number (1..=10000).
+     * @param body        Part contents as a string, Uint8Array/Buffer, or ArrayBuffer.
+     */
+    uploadPart(key: string, uploadId: string, partNumber: number, body: string | Uint8Array | ArrayBuffer): Promise<UploadPart>;
+    /**
+     * Finish a multipart upload (CompleteMultipartUpload), assembling the listed
+     * parts into one object. Parts are sorted by part number before submission
+     * (the server requires strictly-increasing order).
+     *
+     * Unlike the other operations this is NOT auto-retried on a transient error:
+     * the gateway isn't idempotent for completion, so a retry after a
+     * successful-but-unacknowledged complete would return a spurious NoSuchUpload.
+     * On a transient failure, re-drive completion yourself only after confirming
+     * the object isn't already present.
+     *
+     * @param key       The upload's object key.
+     * @param uploadId  The id from {@link create}.
+     * @param parts     The `{ partNumber, etag }` pairs from {@link uploadPart}.
+     */
+    complete(key: string, uploadId: string, parts: UploadPart[]): Promise<CompletedMultipartUpload>;
+    /**
+     * Abort a multipart upload (AbortMultipartUpload), discarding every staged
+     * part. Idempotent against an upload that's already gone (404 / NoSuchUpload
+     * resolves successfully).
+     *
+     * @param key       The upload's object key.
+     * @param uploadId  The id from {@link create}.
+     */
+    abort(key: string, uploadId: string): Promise<void>;
+    /**
+     * List the parts already uploaded for an in-progress upload (ListParts).
+     * Returns a single page; follow `nextPartNumberMarker` (when `isTruncated`)
+     * to page through the rest.
+     *
+     * @param key       The upload's object key.
+     * @param uploadId  The id from {@link create}.
+     * @param opts      `maxParts` / `partNumberMarker` pagination controls.
+     */
+    listParts(key: string, uploadId: string, opts?: ListPartsOptions): Promise<PartListing>;
+    /**
+     * List in-progress multipart uploads on the disk (ListMultipartUploads).
+     * Returns a single page; follow `nextKeyMarker` / `nextUploadIdMarker` (when
+     * `isTruncated`) for the rest.
+     *
+     * @param opts  Prefix/delimiter filter and pagination markers.
+     */
+    listUploads(opts?: ListMultipartUploadsOptions): Promise<MultipartUploadListing>;
+}
+/**
+ * Choose the part size for a `totalBytes` multipart upload. Returns
+ * `requestedPartSize` unless splitting at that size would exceed the server's
+ * 10,000-part cap, in which case it grows the part size (rounded up to a whole
+ * MiB) so the body fits in ≤ 10,000 parts — mirroring boto3's chunk-size
+ * adjustment. Parts only ever get larger, so they stay above the 5 MiB floor.
+ */
+declare function effectiveUploadPartSize(totalBytes: number, requestedPartSize: number): number;
 
 interface ListDisksOptions {
     limit?: number;
@@ -1877,4 +2187,4 @@ declare function deleteApiKey(id: string): Promise<void>;
  */
 declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
 
-export { type ApiTokenResponse, Archil, ArchilApiError, ArchilError, type ArchilOptions, ArchilS3Error, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListObjectsOptions, type ListObjectsResult, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type ObjectMetadata, type PutObjectResult, type R2Mount, type S3CompatibleMount, type S3Mount, type S3Object, type ShareUrlOptions, type ShareUrlResult, type TokenUser, Tokens, USER_AGENT, VERSION, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
+export { type ApiTokenResponse, Archil, ArchilApiError, ArchilError, type ArchilOptions, ArchilS3Error, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type CompletedMultipartUpload, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, Disk, type DiskMetrics, DiskMultipart, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListMultipartUploadsOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type MultipartUpload, type MultipartUploadListing, type MultipartUploadSummary, type ObjectMetadata, type PartInfo, type PartListing, type PutObjectOptions, type PutObjectResult, type R2Mount, type S3CompatibleMount, type S3Mount, type S3Object, type ShareUrlOptions, type ShareUrlResult, type TokenUser, Tokens, USER_AGENT, type UploadPart, VERSION, configure, createApiKey, createDisk, deleteApiKey, effectiveUploadPartSize, exec, getDisk, listApiKeys, listDisks };