lean-s3/dist/index.d.ts

A server-side S3 API for the regular user.

import { Readable } from 'node:stream';
import * as stream_web from 'stream/web';
import { Dispatcher } from 'undici';

/**
 * @internal Normally, we'd use an interface for that, but having a class with pre-defined fields makes it easier for V8 top optimize hidden classes.
 */
declare class S3BucketEntry {
    readonly key: string;
    readonly size: number;
    readonly lastModified: Date;
    readonly etag: string;
    readonly storageClass: StorageClass;
    readonly checksumAlgorithm: ChecksumAlgorithm | undefined;
    readonly checksumType: ChecksumType | undefined;
    constructor(key: string, size: number, lastModified: Date, etag: string, storageClass: StorageClass, checksumAlgorithm: ChecksumAlgorithm | undefined, checksumType: ChecksumType | undefined);
    /**
     * @internal
     */
    static parse(source: any): S3BucketEntry;
}

declare const __brand: unique symbol;
type Brand<B> = {
    [__brand]: B;
};
type Branded<T, B> = T & Brand<B>;
type BucketName = Branded<string, "BucketName">;
type ObjectKey = Branded<string, "ObjectKey">;

declare const write: unique symbol;
declare const stream: unique symbol;
declare const signedRequest: unique symbol;
interface S3ClientOptions {
    bucket: string;
    region: string;
    endpoint: string;
    accessKeyId: string;
    secretAccessKey: string;
    sessionToken?: string;
}
type OverridableS3ClientOptions = Pick<S3ClientOptions, "region" | "bucket" | "endpoint">;
type CreateFileInstanceOptions = {};
type DeleteObjectsOptions = {
    bucket?: string;
    signal?: AbortSignal;
};
interface S3FilePresignOptions {
    contentHash: Buffer;
    /** Seconds. */
    expiresIn: number;
    method: PresignableHttpMethod;
    contentLength: number;
    storageClass: StorageClass;
    acl: Acl;
}
type ListObjectsOptions = {
    bucket?: string;
    prefix?: string;
    maxKeys?: number;
    startAfter?: string;
    continuationToken?: string;
    signal?: AbortSignal;
};
type ListObjectsIteratingOptions = {
    bucket?: string;
    prefix?: string;
    startAfter?: string;
    signal?: AbortSignal;
    internalPageSize?: number;
};
type ListMultipartUploadsOptions = {
    bucket?: string;
    delimiter?: string;
    keyMarker?: string;
    maxUploads?: number;
    prefix?: string;
    uploadIdMarker?: string;
    signal?: AbortSignal;
};
type ListMultipartUploadsResult = {
    bucket?: string;
    keyMarker?: string;
    uploadIdMarker?: string;
    nextKeyMarker?: string;
    prefix?: string;
    delimiter?: string;
    nextUploadIdMarker?: string;
    maxUploads?: number;
    isTruncated?: boolean;
    uploads: MultipartUpload[];
};
type MultipartUpload = {
    checksumAlgorithm?: ChecksumAlgorithm;
    checksumType?: ChecksumType;
    initiated?: Date;
    /**
     * Key of the object for which the multipart upload was initiated.
     * Length Constraints: Minimum length of 1.
     */
    key?: string;
    storageClass?: StorageClass;
    /**
     * Upload ID identifying the multipart upload.
     */
    uploadId?: string;
};
type CreateMultipartUploadOptions = {
    bucket?: string;
    signal?: AbortSignal;
};
type CreateMultipartUploadResult = {
    bucket: string;
    key: string;
    uploadId: string;
};
type AbortMultipartUploadOptions = {
    bucket?: string;
    signal?: AbortSignal;
};
type CompleteMultipartUploadOptions = {
    bucket?: string;
    signal?: AbortSignal;
};
type CompleteMultipartUploadResult = {
    location?: string;
    bucket?: string;
    key?: string;
    etag?: string;
    checksumCRC32?: string;
    checksumCRC32C?: string;
    checksumCRC64NVME?: string;
    checksumSHA1?: string;
    checksumSHA256?: string;
    checksumType?: ChecksumType;
};
type MultipartUploadPart = {
    partNumber: number;
    etag: string;
};
type UploadPartOptions = {
    bucket?: string;
    signal?: AbortSignal;
};
type UploadPartResult = {
    partNumber: number;
    etag: string;
};
type ListPartsOptions = {
    maxParts?: number;
    partNumberMarker?: string;
    bucket?: string;
    signal?: AbortSignal;
};
type ListPartsResult = {
    bucket: string;
    key: string;
    uploadId: string;
    partNumberMarker?: string;
    nextPartNumberMarker?: string;
    maxParts?: number;
    isTruncated: boolean;
    parts: Array<{
        checksumCRC32?: string;
        checksumCRC32C?: string;
        checksumCRC64NVME?: string;
        checksumSHA1?: string;
        checksumSHA256?: string;
        etag: string;
        lastModified: Date;
        partNumber: number;
        size: number;
    }>;
    storageClass?: StorageClass;
    checksumAlgorithm?: ChecksumAlgorithm;
    checksumType?: ChecksumType;
};
type ListObjectsResult = {
    name: string;
    prefix: string | undefined;
    startAfter: string | undefined;
    isTruncated: boolean;
    continuationToken: string | undefined;
    maxKeys: number;
    keyCount: number;
    nextContinuationToken: string | undefined;
    contents: readonly S3BucketEntry[];
};
type BucketCreationOptions = {
    locationConstraint?: string;
    location?: BucketLocationInfo;
    info?: BucketInfo;
    signal?: AbortSignal;
};
type BucketDeletionOptions = {
    signal?: AbortSignal;
};
type BucketExistsOptions = {
    signal?: AbortSignal;
};
/**
 * A configured S3 bucket instance for managing files.
 *
 * @example
 * ```js
 * // Basic bucket setup
 * const bucket = new S3Client({
 *   bucket: "my-bucket",
 *   accessKeyId: "key",
 *   secretAccessKey: "secret"
 * });
 * // Get file instance
 * const file = bucket.file("image.jpg");
 * await file.delete();
 * ```
 */
declare class S3Client {
    #private;
    /**
     * Create a new instance of an S3 bucket so that credentials can be managed from a single instance instead of being passed to every method.
     *
     * @param  options The default options to use for the S3 client.
     */
    constructor(options: S3ClientOptions);
    /**
     * Creates an S3File instance for the given path.
     *
     * @param {string} path The path to the object in the bucket. Also known as [object key](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html).
     * We recommend not using the following characters in a key name because of significant special character handling, which isn't consistent across all applications (see [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html)):
     * - Backslash (`\\`)
     * - Left brace (`{`)
     * - Non-printable ASCII characters (128–255 decimal characters)
     * - Caret or circumflex (`^`)
     * - Right brace (`}`)
     * - Percent character (`%`)
     * - Grave accent or backtick (`\``)
     * - Right bracket (`]`)
     * - Quotation mark (`"`)
     * - Greater than sign (`>`)
     * - Left bracket (`[`)
     * - Tilde (`~`)
     * - Less than sign (`<`)
     * - Pound sign (`#`)
     * - Vertical bar or pipe (`|`)
     *
     * lean-s3 does not enforce these restrictions.
     *
     * @param {Partial<CreateFileInstanceOptions>} [_options] TODO
     * @example
     * ```js
     * const file = client.file("image.jpg");
     * await file.write(imageData);
     *
     * const configFile = client.file("config.json", {
     *   type: "application/json",
     *   acl: "private"
     * });
     * ```
     */
    file(path: string, _options?: Partial<CreateFileInstanceOptions>): S3File;
    /**
     * Generate a presigned URL for temporary access to a file.
     * Useful for generating upload/download URLs without exposing credentials.
     * @returns The operation on {@link S3Client#presign.path} as a pre-signed URL.
     *
     * @example
     * ```js
     * const downloadUrl = client.presign("file.pdf", {
     *   expiresIn: 3600 // 1 hour
     * });
     * ```
     */
    presign(path: string, { method, expiresIn, // TODO: Maybe rename this to expiresInSeconds
    storageClass, contentLength, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
    createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<CreateMultipartUploadResult>;
    /**
     * @remarks Uses [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html).
     * @throws {RangeError} If `options.maxKeys` is not between `1` and `1000`.
     */
    listMultipartUploads(options?: ListMultipartUploadsOptions): Promise<ListMultipartUploadsResult>;
    /**
     * @remarks Uses [`AbortMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html).
     * @throws {RangeError} If `key` is not at least 1 character long.
     * @throws {Error} If `uploadId` is not provided.
     */
    abortMultipartUpload(path: string, uploadId: string, options?: AbortMultipartUploadOptions): Promise<void>;
    /**
     * @remarks Uses [`CompleteMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html).
     * @throws {RangeError} If `key` is not at least 1 character long.
     * @throws {Error} If `uploadId` is not provided.
     */
    completeMultipartUpload(path: string, uploadId: string, parts: readonly MultipartUploadPart[], options?: CompleteMultipartUploadOptions): Promise<CompleteMultipartUploadResult>;
    /**
     * @remarks Uses [`UploadPart`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html).
     * @throws {RangeError} If `key` is not at least 1 character long.
     * @throws {Error} If `uploadId` is not provided.
     */
    uploadPart(path: string, uploadId: string, data: UndiciBodyInit, partNumber: number, options?: UploadPartOptions): Promise<UploadPartResult>;
    /**
     * @remarks Uses [`ListParts`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html).
     * @throws {RangeError} If `key` is not at least 1 character long.
     * @throws {Error} If `uploadId` is not provided.
     * @throws {TypeError} If `options.maxParts` is not a `number`.
     * @throws {RangeError} If `options.maxParts` is <= 0.
     * @throws {TypeError} If `options.partNumberMarker` is not a `string`.
     */
    listParts(path: string, uploadId: string, options?: ListPartsOptions): Promise<ListPartsResult>;
    /**
     * Creates a new bucket on the S3 server.
     *
     * @param name The name of the bucket to create. AWS the name according to [some rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html). The most important ones are:
     * - Bucket names must be between `3` (min) and `63` (max) characters long.
     * - Bucket names can consist only of lowercase letters, numbers, periods (`.`), and hyphens (`-`).
     * - Bucket names must begin and end with a letter or number.
     * - Bucket names must not contain two adjacent periods.
     * - Bucket names must not be formatted as an IP address (for example, `192.168.5.4`).
     *
     * @throws {Error} If the bucket name is invalid.
     * @throws {S3Error} If the bucket could not be created, e.g. if it already exists.
     * @remarks Uses [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)
     */
    createBucket(name: string, options?: BucketCreationOptions): Promise<void>;
    /**
     * Deletes a bucket from the S3 server.
     * @param name The name of the bucket to delete. Same restrictions as in {@link S3Client#createBucket}.
     * @throws {Error} If the bucket name is invalid.
     * @throws {S3Error} If the bucket could not be deleted, e.g. if it is not empty.
     * @remarks Uses [`DeleteBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html).
     */
    deleteBucket(name: string, options?: BucketDeletionOptions): Promise<void>;
    /**
     * Checks if a bucket exists.
     * @param name The name of the bucket to delete. Same restrictions as in {@link S3Client#createBucket}.
     * @throws {Error} If the bucket name is invalid.
     * @remarks Uses [`HeadBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html).
     */
    bucketExists(name: string, options?: BucketExistsOptions): Promise<boolean>;
    /**
     * Uses [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys. Pagination and continuation is handled internally.
     */
    listIterating(options: ListObjectsIteratingOptions): AsyncGenerator<S3BucketEntry>;
    /**
     * Implements [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys.
     *
     * @throws {RangeError} If `maxKeys` is not between `1` and `1000`.
     */
    list(options?: ListObjectsOptions): Promise<ListObjectsResult>;
    /**
     * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
     */
    deleteObjects(objects: readonly S3BucketEntry[] | readonly string[], options?: DeleteObjectsOptions): Promise<{
        errors: any;
    } | null>;
    /**
     * Do not use this. This is an internal method.
     * TODO: Maybe move this into a separate free function?
     * @internal
     */
    [signedRequest](method: HttpMethod, pathWithoutBucket: ObjectKey, query: string | undefined, body: UndiciBodyInit | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, bucket: BucketName | undefined, signal?: AbortSignal | undefined): Promise<Dispatcher.ResponseData<null>>;
    /**
     * @internal
     * @param {import("./index.d.ts").UndiciBodyInit} data TODO
     */
    [write](path: string, data: UndiciBodyInit, contentType: string, contentLength: number | undefined, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined, signal?: AbortSignal | undefined): Promise<void>;
    /**
     * @internal
     */
    [stream](path: string, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined): stream_web.ReadableStream<Uint8Array<ArrayBufferLike>>;
}

declare class S3Stat {
    readonly etag: string;
    readonly lastModified: Date;
    readonly size: number;
    readonly type: string;
    constructor(etag: string, lastModified: Date, size: number, type: string);
    static tryParseFromHeaders(headers: Record<string, string | string[] | undefined>): S3Stat | undefined;
}

declare class S3File {
    #private;
    /**
     * @internal
     */
    constructor(client: S3Client, path: ObjectKey, start: number | undefined, end: number | undefined, contentType: string | undefined);
    slice(start?: number | undefined, end?: number | undefined, contentType?: string | undefined): S3File;
    /**
     *  Get the stat of a file in the bucket. Uses `HEAD` request to check existence.
     *
     * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
     * @throws {S3Error} If the file does not exist or the server has some other issues.
     * @throws {Error} If the server returns an invalid response.
     */
    stat({ signal }?: Partial<S3StatOptions>): Promise<S3Stat>;
    /**
     * Check if a file exists in the bucket. Uses `HEAD` request to check existence.
     *
     * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
     */
    exists({ signal, }?: Partial<S3FileExistsOptions>): Promise<boolean>;
    /**
     * Delete a file from the bucket.
     *
     * @remarks - Uses [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html).
     *          - `versionId` not supported.
     *
     * @param {Partial<S3FileDeleteOptions>} [options]
     *
     * @example
     * ```js
     * // Simple delete
     * await client.unlink("old-file.txt");
     *
     * // With error handling
     * try {
     *   await client.unlink("file.dat");
     *   console.log("File deleted");
     * } catch (err) {
     *   console.error("Delete failed:", err);
     * }
     * ```
     */
    delete({ signal }?: Partial<S3FileDeleteOptions>): Promise<void>;
    toString(): string;
    json(): Promise<unknown>;
    bytes(): Promise<Uint8Array>;
    arrayBuffer(): Promise<ArrayBuffer>;
    text(): Promise<string>;
    blob(): Promise<Blob>;
    /** @returns {ReadableStream<Uint8Array>} */
    stream(): ReadableStream<Uint8Array>;
    /**
     * @param {ByteSource} data
     * @returns {Promise<void>}
     */
    write(data: ByteSource): Promise<void>;
}
interface S3FileDeleteOptions extends OverridableS3ClientOptions {
    signal: AbortSignal;
}
interface S3StatOptions extends OverridableS3ClientOptions {
    signal: AbortSignal;
}
interface S3FileExistsOptions extends OverridableS3ClientOptions {
    signal: AbortSignal;
}

declare class S3Error extends Error {
    readonly code: string;
    readonly path: string;
    readonly message: string;
    readonly requestId: string | undefined;
    readonly hostId: string | undefined;
    constructor(code: string, path: string, { message, requestId, hostId, cause, }?: S3ErrorOptions);
}
type S3ErrorOptions = {
    message?: string | undefined;
    requestId?: string | undefined;
    hostId?: string | undefined;
    cause?: unknown;
};

type Acl = "private" | "public-read" | "public-read-write" | "aws-exec-read" | "authenticated-read" | "bucket-owner-read" | "bucket-owner-full-control" | "log-delivery-write";
type StorageClass = "STANDARD" | "DEEP_ARCHIVE" | "EXPRESS_ONEZONE" | "GLACIER" | "GLACIER_IR" | "INTELLIGENT_TIERING" | "ONEZONE_IA" | "OUTPOSTS" | "REDUCED_REDUNDANCY" | "SNOW" | "STANDARD_IA";
type ChecksumAlgorithm = "CRC32" | "CRC32C" | "CRC64NVME" | "SHA1" | "SHA256";
type ChecksumType = "COMPOSITE" | "FULL_OBJECT";
type PresignableHttpMethod = "GET" | "DELETE" | "PUT" | "HEAD";
type HttpMethod = PresignableHttpMethod | "POST";
/** Body values supported by undici. */
type UndiciBodyInit = string | Buffer | Uint8Array | Readable;
type ByteSource = UndiciBodyInit | Blob;
/**
 * Implements [LocationInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_LocationInfo.html)
 */
type BucketLocationInfo = {
    name?: string;
    type?: string;
};
/**
 * Implements [BucketInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_BucketInfo.html)
 */
type BucketInfo = {
    dataRedundancy?: string;
    type?: string;
};

export { type AbortMultipartUploadOptions, type Acl, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CompleteMultipartUploadOptions, type CompleteMultipartUploadResult, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteObjectsOptions, type HttpMethod, type ListMultipartUploadsOptions, type ListMultipartUploadsResult, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListPartsResult, type MultipartUpload, type MultipartUploadPart, type OverridableS3ClientOptions, type PresignableHttpMethod, S3BucketEntry, S3Client, type S3ClientOptions, S3Error, type S3ErrorOptions, S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3FilePresignOptions, S3Stat, type S3StatOptions, type StorageClass, type UndiciBodyInit, type UploadPartOptions, type UploadPartResult };