lean-s3 0.2.2 → 0.3.1

package/dist/index.d.ts

@@ -1,37 +1,343 @@
-import type { Readable } from "node:stream";
-export { default as S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3StatOptions, } from "./S3File.ts";
-export { default as S3Client, type ListObjectsOptions, type ListObjectsIteratingOptions, type ListObjectsResponse, type CreateFileInstanceOptions, type OverridableS3ClientOptions, type S3ClientOptions, type S3FilePresignOptions, type BucketCreationOptions, type DeleteObjectsOptions, } from "./S3Client.ts";
-export { default as S3Error, type S3ErrorOptions } from "./S3Error.ts";
-export { default as S3Stat } from "./S3Stat.ts";
-export { default as S3BucketEntry } from "./S3BucketEntry.ts";
-export type Acl = "private" | "public-read" | "public-read-write" | "aws-exec-read" | "authenticated-read" | "bucket-owner-read" | "bucket-owner-full-control" | "log-delivery-write";
-export type StorageClass = "STANDARD" | "DEEP_ARCHIVE" | "EXPRESS_ONEZONE" | "GLACIER" | "GLACIER_IR" | "INTELLIGENT_TIERING" | "ONEZONE_IA" | "OUTPOSTS" | "REDUCED_REDUNDANCY" | "SNOW" | "STANDARD_IA";
-export type ChecksumAlgorithm = "CRC32" | "CRC32C" | "CRC64NVME" | "SHA1" | "SHA256";
-export type ChecksumType = "COMPOSITE" | "FULL_OBJECT";
-export type PresignableHttpMethod = "GET" | "DELETE" | "PUT" | "HEAD";
-export type HttpMethod = PresignableHttpMethod | "POST"; // There are also others, but we don't want to support them yet
+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 write: unique symbol;
+declare const stream: 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 = {
+    signal?: AbortSignal;
+};
+interface S3FilePresignOptions {
+    contentHash: Buffer;
+    /** Seconds. */
+    expiresIn: number;
+    method: PresignableHttpMethod;
+    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 ListObjectsResponse = {
+    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, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
+    /**
+     * 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: {
+            code: any;
+            key: any;
+            message: any;
+            versionId: any;
+        }[];
+    } | null>;
+    /**
+     * 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.
+     */
+    list(options?: ListObjectsOptions): Promise<ListObjectsResponse>;
+    /**
+     * Do not use this. This is an internal method.
+     * TODO: Maybe move this into a separate free function?
+     * @internal
+     */
+    _signedRequest(method: HttpMethod, pathWithoutBucket: string, query: string | undefined, body: UndiciBodyInit | undefined, additionalSignedHeaders: Record<string, string> | undefined, additionalUnsignedHeaders: Record<string, string> | undefined, contentHash: Buffer | undefined, bucket: string | 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: string, 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;
+    /** @returns {Promise<unknown>} */
+    json(): Promise<unknown>;
+    /** @returns {Promise<ArrayBuffer>} */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** @returns {Promise<string>} */
+    text(): Promise<string>;
+    /** @returns {Promise<Blob>} */
+    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. */
-export type UndiciBodyInit = string | Buffer | Uint8Array | Readable;
-export type ByteSource = UndiciBodyInit | Blob;
-// TODO
-// | ArrayBufferView
-// | ArrayBuffer
-// | SharedArrayBuffer
-// | Request
-// | Response
-// | S3File
-// | ReadableStream<Uint8Array>
+type UndiciBodyInit = string | Buffer | Uint8Array | Readable;
+type ByteSource = UndiciBodyInit | Blob;
 /**
  * Implements [LocationInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_LocationInfo.html)
  */
-export type BucketLocationInfo = {
+type BucketLocationInfo = {
     name?: string;
     type?: string;
 };
 /**
  * Implements [BucketInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_BucketInfo.html)
  */
-export type BucketInfo = {
+type BucketInfo = {
     dataRedundancy?: string;
     type?: string;
 };
+
+export { type Acl, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CreateFileInstanceOptions, type DeleteObjectsOptions, type HttpMethod, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResponse, 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 };