lean-s3 0.2.0 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # lean-s3 [![npm badge](https://img.shields.io/npm/v/lean-s3)](https://www.npmjs.com/package/lean-s3)
 
-A server-side S3 API for the regular user. lean-s3 tries to provide the 80% of S3 that most people use. It is heavily inspired by [Bun's S3 API](https://bun.sh/docs/api/s3). Requires a Node.js version that supports `fetch`.
+A server-side S3 API for the regular user. lean-s3 tries to provide the 80% of S3 that most people use. It is heavily inspired by [Bun's S3 API](https://bun.sh/docs/api/s3). Requires a supported Node.js version.
 
 ## Elevator Pitch
 ```js
@@ -77,7 +77,7 @@ $ du -sh node_modules
 `lean-s3` is _so_ lean that it is ~1.8MB just to do a couple of HTTP requests <img src="https://cdn.frankerfacez.com/emoticon/480839/1" width="20" height="20">
 BUT...
 
-Due to its scalability, portability and AWS integrations, pre-signing URLs is `async` and performs poorly in high-performance scenarios. By taking different trade-offs, lean-s3 can presign URLs much faster. I promise! This is the reason you cannot use lean-s3 in the browser.
+Due to the scalability, portability and AWS integrations of @aws-sdk/client-s3, pre-signing URLs is `async` and performs poorly in high-performance scenarios. By taking different trade-offs, lean-s3 can presign URLs much faster. I promise! This is the reason you cannot use lean-s3 in the browser.
 
 lean-s3 is currently about 30x faster than AWS SDK when it comes to pre-signing URLs[^1]:
 ```
@@ -121,6 +121,20 @@ We try to keep this library small. If you happen to need something that is not s
 
 See [DESIGN_DECISIONS.md](./DESIGN_DECISIONS.md) to read about why this library is the way it is.
 
+## Supported Operations
+
+### Bucket Operations
+- ✅ [`CreateBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) via `.createBucket`
+- ✅ [`DeleteBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html) via `.deleteBucket`
+- ✅ [`HeadBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html) via `.bucketExists`
+
+### Object Operations
+- ✅ [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) via `.list`/`.listIterating`
+- ✅ [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) via `.deleteObjects`
+- ✅ [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) via `S3File.delete`
+- ✅ [`PutObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) via `S3File.write`
+- ✅ [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) via `S3File.exists`/`S3File.stat`
+
 ## Example Configurations
 ### Hetzner Object Storage
 ```js

package/dist/S3BucketEntry.d.ts

@@ -14,5 +14,6 @@ export default class S3BucketEntry {
     /**
      * @internal
      */
+    // biome-ignore lint/suspicious/noExplicitAny: internal use only, any is ok here
     static parse(source: any): S3BucketEntry;
 }

package/dist/S3Client.d.ts

@@ -1,7 +1,8 @@
+import { type Dispatcher } from "undici";
 import S3File from "./S3File.ts";
 import S3BucketEntry from "./S3BucketEntry.ts";
 import * as amzDate from "./AmzDate.ts";
-import type { Acl, PresignableHttpMethod, StorageClass, UndiciBodyInit } from "./index.ts";
+import type { Acl, BucketInfo, BucketLocationInfo, HttpMethod, PresignableHttpMethod, StorageClass, UndiciBodyInit } from "./index.ts";
 export declare const write: unique symbol;
 export declare const stream: unique symbol;
 export interface S3ClientOptions {
@@ -13,15 +14,34 @@ export interface S3ClientOptions {
     sessionToken?: string;
 }
 export type OverridableS3ClientOptions = Pick<S3ClientOptions, "region" | "bucket" | "endpoint">;
-export type CreateFileInstanceOptions = {};
+// biome-ignore lint/complexity/noBannedTypes: TODO
+export type CreateFileInstanceOptions = {}; // TODO
+export type DeleteObjectsOptions = {
+    signal?: AbortSignal;
+};
 export interface S3FilePresignOptions {
     contentHash: Buffer;
     /** Seconds. */
-    expiresIn: number;
+    expiresIn: number; // TODO: Maybe support Temporal.Duration once major support arrives
     method: PresignableHttpMethod;
     storageClass: StorageClass;
     acl: Acl;
 }
+export type ListObjectsOptions = {
+    bucket?: string;
+    prefix?: string;
+    maxKeys?: number;
+    startAfter?: string;
+    continuationToken?: string;
+    signal?: AbortSignal;
+};
+export type ListObjectsIteratingOptions = {
+    bucket?: string;
+    prefix?: string;
+    startAfter?: string;
+    signal?: AbortSignal;
+    internalPageSize?: number;
+};
 export type ListObjectsResponse = {
     name: string;
     prefix: string | undefined;
@@ -33,6 +53,18 @@ export type ListObjectsResponse = {
     nextContinuationToken: string | undefined;
     contents: readonly S3BucketEntry[];
 };
+export type BucketCreationOptions = {
+    locationConstraint?: string;
+    location?: BucketLocationInfo;
+    info?: BucketInfo;
+    signal?: AbortSignal;
+};
+export type BucketDeletionOptions = {
+    signal?: AbortSignal;
+};
+export type BucketExistsOptions = {
+    signal?: AbortSignal;
+};
 /**
  * A configured S3 bucket instance for managing files.
  *
@@ -60,9 +92,27 @@ export default class S3Client {
     /**
      * Creates an S3File instance for the given path.
      *
-     * @param {string} 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
-     * @returns {S3File}
      * @example
      * ```js
      * const file = client.file("image.jpg");
@@ -88,43 +138,73 @@ export default class S3Client {
      * ```
      */
     presign(path: string, { method, expiresIn, // TODO: Maybe rename this to expiresInSeconds
-    storageClass, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: Partial<S3FilePresignOptions & OverridableS3ClientOptions>): string;
-    deleteObjects(objects: readonly S3BucketEntry[] | readonly string[], options: unknown): Promise<void>;
+    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>;
     /**
-     * Uses `ListObjectsV2` to iterate over all keys. Pagination and continuation is handled internally.
+     * 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)
      */
-    listIterating(options: {
-        prefix?: string;
-        startAfter?: string;
-        signal?: AbortSignal;
-        internalPageSize?: number;
-    }): AsyncGenerator<S3BucketEntry>;
-    list(options?: {
-        prefix?: string;
-        maxKeys?: number;
-        startAfter?: string;
-        continuationToken?: string;
-        signal?: AbortSignal;
-    }): Promise<ListObjectsResponse>;
+    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>;
+    //#region list
+    /**
+     * 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>;
+    //#endregion
+    /**
+     * 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>;
+    // TODO: Support abortSignal
     /**
      * @internal
      */
     [stream](path: string, contentHash: Buffer | undefined, rageStart: number | undefined, rangeEndExclusive: number | undefined): import("stream/web").ReadableStream<Uint8Array<ArrayBufferLike>>;
 }
-/**
- * @param {string} amzCredential
- * @param {import("./AmzDate.ts").AmzDate} date
- * @param {number} expiresIn
- * @param {string} headerList
- * @param {StorageClass | null | undefined} storageClass
- * @param {string | null | undefined} sessionToken
- * @param {Acl | null | undefined} acl
- * @param {string | null | undefined} contentHashStr
- * @returns {string}
- */
 export declare function buildSearchParams(amzCredential: string, date: amzDate.AmzDate, expiresIn: number, headerList: string, contentHashStr: string | null | undefined, storageClass: StorageClass | null | undefined, sessionToken: string | null | undefined, acl: Acl | null | undefined): string;

package/dist/S3Client.js

@@ -7,10 +7,14 @@ import KeyCache from "./KeyCache.js";
 import * as amzDate from "./AmzDate.js";
 import * as sign from "./sign.js";
 import { buildRequestUrl, getRangeHeader, prepareHeadersForSigning, } from "./url.js";
+import { getResponseError } from "./error.js";
 export const write = Symbol("write");
 export const stream = Symbol("stream");
 const xmlParser = new XMLParser();
-const xmlBuilder = new XMLBuilder();
+const xmlBuilder = new XMLBuilder({
+    attributeNamePrefix: "$",
+    ignoreAttributes: false,
+});
 /**
  * A configured S3 bucket instance for managing files.
  *
@@ -28,11 +32,9 @@ const xmlBuilder = new XMLBuilder();
  * ```
  */
 export default class S3Client {
-    /** @type {Readonly<S3ClientOptions>} */
     #options;
     #keyCache = new KeyCache();
-    // TODO: pass options to this in client
-    /** @type {Dispatcher} */
+    // TODO: pass options to this in client? Do we want to expose tjhe internal use of undici?
     #dispatcher = new Agent();
     /**
      * 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.
@@ -71,9 +73,27 @@ export default class S3Client {
     /**
      * Creates an S3File instance for the given path.
      *
-     * @param {string} 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
-     * @returns {S3File}
      * @example
      * ```js
      * const file = client.file("image.jpg");
@@ -86,6 +106,7 @@ export default class S3Client {
      * ```
      */
     file(path, options) {
+        // TODO: Check max path length in bytes
         return new S3File(this, path, undefined, undefined, undefined);
     }
     /**
@@ -117,12 +138,155 @@ export default class S3Client {
         res.search = `${query}&X-Amz-Signature=${signature}`;
         return res.toString();
     }
-    async deleteObjects(objects, options) {
-        throw new Error("Not implemented");
+    /**
+     * Uses [`DeleteObjects`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) to delete multiple objects in a single request.
+     */
+    async deleteObjects(objects, options = {}) {
+        const body = xmlBuilder.build({
+            Delete: {
+                Quiet: true,
+                Object: objects.map(o => ({
+                    Key: typeof o === "string" ? o : o.key,
+                })),
+            },
+        });
+        const response = await this._signedRequest("POST", "", "delete=", // "=" is needed by minio for some reason
+        body, {
+            "content-md5": sign.md5Base64(body),
+        }, undefined, undefined, this.#options.bucket, options.signal);
+        if (response.statusCode === 200) {
+            const text = await response.body.text();
+            let res = undefined;
+            try {
+                // Quite mode omits all deleted elements, so it will be parsed as "", wich we need to coalasce to null/undefined
+                res = (xmlParser.parse(text)?.DeleteResult || undefined)?.Error ?? [];
+            }
+            catch (cause) {
+                // Possible according to AWS docs
+                throw new S3Error("Unknown", "", {
+                    message: "S3 service responded with invalid XML.",
+                    cause,
+                });
+            }
+            if (!res || !Array.isArray(res)) {
+                throw new S3Error("Unknown", "", {
+                    message: "Could not process response.",
+                });
+            }
+            const errors = res.map(e => ({
+                code: e.Code,
+                key: e.Key,
+                message: e.Message,
+                versionId: e.VersionId,
+            }));
+            return errors.length > 0 ? { errors } : null;
+        }
+        if (400 <= response.statusCode && response.statusCode < 500) {
+            throw await getResponseError(response, "");
+        }
+        response.body.dump(); // undici docs state that we should dump the body if not used
+        throw new Error(`Response code not implemented yet: ${response.statusCode}`);
+    }
+    /**
+     * 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)
+     */
+    async createBucket(name, options) {
+        ensureValidBucketName(name);
+        let body = undefined;
+        if (options) {
+            const location = options.location && (options.location.name || options.location.type)
+                ? {
+                    Name: options.location.name ?? undefined,
+                    Type: options.location.type ?? undefined,
+                }
+                : undefined;
+            const bucket = options.info && (options.info.dataRedundancy || options.info.type)
+                ? {
+                    DataRedundancy: options.info.dataRedundancy ?? undefined,
+                    Type: options.info.type ?? undefined,
+                }
+                : undefined;
+            body =
+                location || bucket || options.locationConstraint
+                    ? xmlBuilder.build({
+                        CreateBucketConfiguration: {
+                            $xmlns: "http://s3.amazonaws.com/doc/2006-03-01/",
+                            LocationConstraint: options.locationConstraint ?? undefined,
+                            Location: location,
+                            Bucket: bucket,
+                        },
+                    })
+                    : undefined;
+        }
+        const additionalSignedHeaders = body
+            ? { "content-md5": sign.md5Base64(body) }
+            : undefined;
+        const response = await this._signedRequest("PUT", "", undefined, body, additionalSignedHeaders, undefined, undefined, name, options?.signal);
+        if (400 <= response.statusCode && response.statusCode < 500) {
+            throw await getResponseError(response, "");
+        }
+        await response.body.dump(); // undici docs state that we should dump the body if not used
+        if (response.statusCode === 200) {
+            return;
+        }
+        throw new Error(`Response code not supported: ${response.statusCode}`);
+    }
+    /**
+     * 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).
+     */
+    async deleteBucket(name, options) {
+        ensureValidBucketName(name);
+        const response = await this._signedRequest("DELETE", "", undefined, undefined, undefined, undefined, undefined, name, options?.signal);
+        if (400 <= response.statusCode && response.statusCode < 500) {
+            throw await getResponseError(response, "");
+        }
+        await response.body.dump(); // undici docs state that we should dump the body if not used
+        if (response.statusCode === 204) {
+            return;
+        }
+        throw new Error(`Response code not supported: ${response.statusCode}`);
+    }
+    /**
+     * 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).
+     */
+    async bucketExists(name, options) {
+        ensureValidBucketName(name);
+        const response = await this._signedRequest("HEAD", "", undefined, undefined, undefined, undefined, undefined, name, options?.signal);
+        if (response.statusCode !== 404 &&
+            400 <= response.statusCode &&
+            response.statusCode < 500) {
+            throw await getResponseError(response, "");
+        }
+        await response.body.dump(); // undici docs state that we should dump the body if not used
+        if (response.statusCode === 200) {
+            return true;
+        }
+        if (response.statusCode === 404) {
+            return false;
+        }
+        throw new Error(`Response code not supported: ${response.statusCode}`);
     }
     //#region list
     /**
-     * Uses `ListObjectsV2` to iterate over all keys. Pagination and continuation is handled internally.
+     * Uses [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys. Pagination and continuation is handled internally.
      */
     async *listIterating(options) {
         // only used to get smaller pages, so we can test this properly
@@ -142,6 +306,9 @@ export default class S3Client {
             continuationToken = res.nextContinuationToken;
         } while (continuationToken);
     }
+    /**
+     * Implements [`ListObjectsV2`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) to iterate over all keys.
+     */
     async list(options = {}) {
         // See `benchmark-operations.js` on why we don't use URLSearchParams but string concat
         // tldr: This is faster and we know the params exactly, so we can focus our encoding
@@ -174,7 +341,7 @@ export default class S3Client {
             }
             query += `&start-after=${encodeURIComponent(options.startAfter)}`;
         }
-        const response = await this.#signedRequest("GET", "", query, undefined, undefined, undefined, undefined, options.signal);
+        const response = await this._signedRequest("GET", "", query, undefined, undefined, undefined, undefined, options.bucket ?? this.#options.bucket, options.signal);
         if (response.statusCode === 200) {
             const text = await response.body.text();
             let res = undefined;
@@ -211,16 +378,20 @@ export default class S3Client {
                 contents,
             };
         }
-        // undici docs state that we shoul dump the body if not used
-        response.body.dump();
+        response.body.dump(); // undici docs state that we should dump the body if not used
         throw new Error(`Response code not implemented yet: ${response.statusCode}`);
     }
     //#endregion
-    async #signedRequest(method, pathWithoutBucket, query, body, additionalSignedHeaders, additionalUnsignedHeaders, contentHash, signal = undefined) {
-        const bucket = this.#options.bucket;
+    /**
+     * Do not use this. This is an internal method.
+     * TODO: Maybe move this into a separate free function?
+     * @internal
+     */
+    async _signedRequest(method, pathWithoutBucket, query, body, additionalSignedHeaders, additionalUnsignedHeaders, contentHash, bucket, signal = undefined) {
         const endpoint = this.#options.endpoint;
         const region = this.#options.region;
-        const url = buildRequestUrl(endpoint, bucket, region, pathWithoutBucket);
+        const effectiveBucket = bucket ?? this.#options.bucket;
+        const url = buildRequestUrl(endpoint, effectiveBucket, region, pathWithoutBucket);
         if (query) {
             url.search = query;
         }
@@ -304,34 +475,7 @@ export default class S3Client {
             // everything seemed to work, no need to process response body
             return;
         }
-        let body = undefined;
-        try {
-            body = await response.body.text();
-        }
-        catch (cause) {
-            throw new S3Error("Unknown", path, {
-                message: "Could not read response body.",
-                cause,
-            });
-        }
-        if (response.headers["content-type"] === "application/xml") {
-            let error = undefined;
-            try {
-                error = xmlParser.parse(body);
-            }
-            catch (cause) {
-                throw new S3Error("Unknown", path, {
-                    message: "Could not parse XML error response.",
-                    cause,
-                });
-            }
-            throw new S3Error(error.Code || "Unknown", path, {
-                message: error.Message || undefined, // Message might be "",
-            });
-        }
-        throw new S3Error("Unknown", path, {
-            message: "Unknown error during S3 request.",
-        });
+        throw await getResponseError(response, path);
     }
     // TODO: Support abortSignal
     /**
@@ -445,17 +589,6 @@ export default class S3Client {
         return `AWS4-HMAC-SHA256 Credential=${credentialSpec}, SignedHeaders=${signedHeadersSpec}, Signature=${signature}`;
     }
 }
-/**
- * @param {string} amzCredential
- * @param {import("./AmzDate.ts").AmzDate} date
- * @param {number} expiresIn
- * @param {string} headerList
- * @param {StorageClass | null | undefined} storageClass
- * @param {string | null | undefined} sessionToken
- * @param {Acl | null | undefined} acl
- * @param {string | null | undefined} contentHashStr
- * @returns {string}
- */
 export function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHashStr, storageClass, sessionToken, acl) {
     // We tried to make these query params entirely lower-cased, just like the headers
     // but Cloudflare R2 requires them to have this exact casing
@@ -483,3 +616,17 @@ export function buildSearchParams(amzCredential, date, expiresIn, headerList, co
     }
     return res;
 }
+function ensureValidBucketName(name) {
+    if (name.length < 3 || name.length > 63) {
+        throw new Error("`name` must be between 3 and 63 characters long.");
+    }
+    if (name.startsWith(".") || name.endsWith(".")) {
+        throw new Error("`name` must not start or end with a period (.)");
+    }
+    if (!/^[a-z0-9.-]+$/.test(name)) {
+        throw new Error("`name` can only contain lowercase letters, numbers, periods (.), and hyphens (-).");
+    }
+    if (name.includes("..")) {
+        throw new Error("`name` must not contain two adjacent periods (..)");
+    }
+}

package/dist/S3Error.d.ts

@@ -4,7 +4,7 @@ export default class S3Error extends Error {
     readonly message: string;
     readonly requestId: string | undefined;
     readonly hostId: string | undefined;
-    constructor(code: string, path: string, { message, requestId, hostId, cause, }?: S3ErrorOptions);
+    constructor(code: string, path: string, { message, requestId, hostId, cause }?: S3ErrorOptions);
 }
 export type S3ErrorOptions = {
     message?: string | undefined;

package/dist/S3File.d.ts

@@ -1,32 +1,43 @@
-import S3Stat from "./S3Stat.ts";
 import type S3Client from "./S3Client.ts";
-import { type OverridableS3ClientOptions } from "./S3Client.ts";
 import type { ByteSource } from "./index.ts";
+import S3Stat from "./S3Stat.ts";
+import { type OverridableS3ClientOptions } from "./S3Client.ts";
+// TODO: If we want to hack around, we can use this to access the private implementation of the "get stream" algorithm used by Node.js's blob internally
+// We probably have to do this some day if the fetch implementation is moved to internals.
+// If this happens, fetch will probably use `[kHandle].getReader()` instead of .stream() to read the Blob
+// This would break our use-case of passing an S3File as a body
+// Using this hack would also make `.text()`, `.bytes()` etc. "just work" in every case, since these use `[kHandle]` internally as well.
+// We now resort back into overriding text/bytes/etc. But as soon as another internal Node.js API uses this functionality, this would probably also use `[kHandle]` and bypass our data.
+// const kHandle = Object.getOwnPropertySymbols(new Blob).find(s => s.toString() === 'Symbol(kHandle)');
 export default class S3File {
     #private;
     /**
      * @internal
      */
     constructor(client: S3Client, path: string, start: number | undefined, end: number | undefined, contentType: string | undefined);
+    // TODO: slice overloads
     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.
      *
-     * @throws {Error} If the file does not exist.
-     * @param {Partial<S3StatOptions>} [options]
-     * @returns {Promise<S3Stat>}
+     * @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.
-     * @param {Partial<S3FileExistsOptions>} [options]
-     * @returns {Promise<boolean>}
+     *
+     * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
      */
-    exists({ signal, }?: Partial<S3FileExistsOptions>): Promise<boolean>;
+    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).
+     * @remarks `versionId` not supported.
+     *
      * @param {Partial<S3FileDeleteOptions>} [options]
-     * @returns {Promise<void>}
      *
      * @example
      * ```js
@@ -46,6 +57,11 @@ export default class S3File {
     toString(): string;
     /** @returns {Promise<unknown>} */
     json(): Promise<unknown>;
+    // TODO
+    // /** @returns {Promise<Uint8Array>} */
+    // bytes() {
+    // 	return new Response(this.stream()).bytes(); // TODO: Does this exist?
+    // }
     /** @returns {Promise<ArrayBuffer>} */
     arrayBuffer(): Promise<ArrayBuffer>;
     /** @returns {Promise<string>} */

package/dist/S3File.js

@@ -3,6 +3,7 @@ import S3Error from "./S3Error.js";
 import S3Stat from "./S3Stat.js";
 import { write, stream } from "./S3Client.js";
 import { sha256 } from "./sign.js";
+import { fromStatusCode, getResponseError } from "./error.js";
 // TODO: If we want to hack around, we can use this to access the private implementation of the "get stream" algorithm used by Node.js's blob internally
 // We probably have to do this some day if the fetch implementation is moved to internals.
 // If this happens, fetch will probably use `[kHandle].getReader()` instead of .stream() to read the Blob
@@ -40,47 +41,51 @@ export default class S3File {
     /**
      *  Get the stat of a file in the bucket. Uses `HEAD` request to check existence.
      *
-     * @throws {Error} If the file does not exist.
-     * @param {Partial<S3StatOptions>} [options]
-     * @returns {Promise<S3Stat>}
+     * @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.
      */
     async stat({ signal } = {}) {
         // TODO: Support all options
-        // TODO: Don't use presign here
-        const url = this.#client.presign(this.#path, { method: "HEAD" });
-        const response = await fetch(url, { method: "HEAD", signal }); // TODO: Use undici
-        if (!response.ok) {
-            switch (response.status) {
-                case 404:
-                    // TODO: Process response body
-                    throw new S3Error("NoSuchKey", this.#path);
-                default:
-                    // TODO: Process response body
-                    throw new S3Error("Unknown", this.#path);
+        const response = await this.#client._signedRequest("HEAD", this.#path, undefined, undefined, undefined, undefined, undefined, undefined, signal);
+        // Heads don't have a body, but we still need to consume it to avoid leaks
+        await response.body.dump();
+        if (200 <= response.statusCode && response.statusCode < 300) {
+            const result = S3Stat.tryParseFromHeaders(response.headers);
+            if (!result) {
+                throw new Error("S3 server returned an invalid response for `HeadObject`");
             }
+            return result;
         }
-        const result = S3Stat.tryParseFromHeaders(response.headers);
-        if (!result) {
-            throw new Error("S3 server returned an invalid response for HEAD");
-        }
-        return result;
+        throw (fromStatusCode(response.statusCode, this.#path) ??
+            new Error(`S3 server returned an unsupported status code for \`HeadObject\`: ${response.statusCode}`));
     }
     /**
      * Check if a file exists in the bucket. Uses `HEAD` request to check existence.
-     * @param {Partial<S3FileExistsOptions>} [options]
-     * @returns {Promise<boolean>}
+     *
+     * @remarks Uses [`HeadObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
      */
     async exists({ signal, } = {}) {
         // TODO: Support all options
-        // TODO: Don't use presign here
-        const url = this.#client.presign(this.#path, { method: "HEAD" });
-        const res = await fetch(url, { method: "HEAD", signal }); // TODO: Use undici
-        return res.ok;
+        const response = await this.#client._signedRequest("HEAD", this.#path, undefined, undefined, undefined, undefined, undefined, undefined, signal);
+        // Heads don't have a body, but we still need to consume it to avoid leaks
+        await response.body.dump();
+        if (200 <= response.statusCode && response.statusCode < 300) {
+            return true;
+        }
+        if (response.statusCode === 404) {
+            return false;
+        }
+        throw (fromStatusCode(response.statusCode, this.#path) ??
+            new Error(`S3 server returned an unsupported status code for \`HeadObject\`: ${response.statusCode}`));
     }
     /**
      * Delete a file from the bucket.
+     *
+     * @remarks Uses [`DeleteObject`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html).
+     * @remarks `versionId` not supported.
+     *
      * @param {Partial<S3FileDeleteOptions>} [options]
-     * @returns {Promise<void>}
      *
      * @example
      * ```js
@@ -98,19 +103,12 @@ export default class S3File {
      */
     async delete({ signal } = {}) {
         // TODO: Support all options
-        // TODO: Don't use presign here
-        const url = this.#client.presign(this.#path, { method: "DELETE" });
-        const response = await fetch(url, { method: "DELETE", signal }); // TODO: Use undici
-        if (!response.ok) {
-            switch (response.status) {
-                case 404:
-                    // TODO: Process response body
-                    throw new S3Error("NoSuchKey", this.#path);
-                default:
-                    // TODO: Process response body
-                    throw new S3Error("Unknown", this.#path);
-            }
+        const response = await this.#client._signedRequest("DELETE", this.#path, undefined, undefined, undefined, undefined, undefined, undefined, signal);
+        if (response.statusCode === 204) {
+            await response.body.dump(); // Consume the body to avoid leaks
+            return;
         }
+        throw await getResponseError(response, this.#path);
     }
     toString() {
         return `S3File { path: "${this.#path}" }`;
@@ -143,14 +141,6 @@ export default class S3File {
         // This function is called for every operation on the blob
         return this.#client[stream](this.#path, undefined, this.#start, this.#end);
     }
-    /**
-     * @param {ByteSource} data
-     * @returns {Promise<[
-     *   buffer: import("./index.d.ts").UndiciBodyInit,
-     *   size: number | undefined,
-     *   hash: Buffer | undefined,
-     * ]>}
-     */
     async #transformData(data) {
         if (typeof data === "string") {
             const binary = new TextEncoder();
@@ -197,10 +187,6 @@ export default class S3File {
         return await this.#client[write](this.#path, bytes, this.#contentType, length, hash, this.#start, this.#end, signal);
     }
 }
-/**
- * @param {never} v
- * @returns {never}
- */
 function assertNever(v) {
     throw new TypeError(`Expected value not to have type ${typeof v}`);
 }

package/dist/S3Stat.d.ts

@@ -1,9 +1,8 @@
-import type { Headers } from "undici-types";
 export default 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: Headers): S3Stat | undefined;
+    static tryParseFromHeaders(headers: Record<string, string | string[] | undefined>): S3Stat | undefined;
 }

package/dist/S3Stat.js

@@ -10,15 +10,15 @@ export default class S3Stat {
         this.type = type;
     }
     static tryParseFromHeaders(headers) {
-        const lm = headers.get("last-modified");
-        if (lm === null) {
+        const lm = headers["last-modified"];
+        if (lm === null || typeof lm !== "string") {
             return undefined;
         }
-        const etag = headers.get("etag");
-        if (etag === null) {
+        const etag = headers.etag;
+        if (etag === null || typeof etag !== "string") {
             return undefined;
         }
-        const cl = headers.get("content-length");
+        const cl = headers["content-length"];
         if (cl === null) {
             return undefined;
         }
@@ -26,8 +26,8 @@ export default class S3Stat {
         if (!Number.isSafeInteger(size)) {
             return undefined;
         }
-        const ct = headers.get("content-type");
-        if (ct === null) {
+        const ct = headers["content-type"];
+        if (ct === null || typeof ct !== "string") {
             return undefined;
         }
         return new S3Stat(etag, new Date(lm), size, ct);

package/dist/error.d.ts

@@ -0,0 +1,4 @@
+import type { Dispatcher } from "undici";
+import S3Error from "./S3Error.ts";
+export declare function getResponseError(response: Dispatcher.ResponseData<unknown>, path: string): Promise<S3Error>;
+export declare function fromStatusCode(code: number, path: string): S3Error | undefined;

package/dist/error.js

@@ -0,0 +1,57 @@
+import { XMLParser } from "fast-xml-parser";
+import S3Error from "./S3Error.js";
+const xmlParser = new XMLParser();
+export async function getResponseError(response, path) {
+    let body = undefined;
+    try {
+        body = await response.body.text();
+    }
+    catch (cause) {
+        return new S3Error("Unknown", path, {
+            message: "Could not read response body.",
+            cause,
+        });
+    }
+    if (response.headers["content-type"] === "application/xml") {
+        return parseAndGetXmlError(body, path);
+    }
+    return new S3Error("Unknown", path, {
+        message: "Unknown error during S3 request.",
+    });
+}
+export function fromStatusCode(code, path) {
+    switch (code) {
+        case 404:
+            return new S3Error("NoSuchKey", path, {
+                message: "The specified key does not exist.",
+            });
+        case 403:
+            return new S3Error("AccessDenied", path, {
+                message: "Access denied to the key.",
+            });
+        // TODO: Add more status codes as needed
+        default:
+            return undefined;
+    }
+}
+function parseAndGetXmlError(body, path) {
+    let error = undefined;
+    try {
+        error = xmlParser.parse(body);
+    }
+    catch (cause) {
+        return new S3Error("Unknown", path, {
+            message: "Could not parse XML error response.",
+            cause,
+        });
+    }
+    if (error.Error) {
+        const e = error.Error;
+        return new S3Error(e.Code || "Unknown", path, {
+            message: e.Message || undefined, // Message might be "",
+        });
+    }
+    return new S3Error(error.Code || "Unknown", path, {
+        message: error.Message || undefined, // Message might be "",
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { Readable } from "node:stream";
 export { default as S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3StatOptions, } from "./S3File.ts";
-export { default as S3Client, type ListObjectsResponse, type CreateFileInstanceOptions, type OverridableS3ClientOptions, type S3ClientOptions, type S3FilePresignOptions, } from "./S3Client.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";
@@ -9,7 +9,29 @@ export type StorageClass = "STANDARD" | "DEEP_ARCHIVE" | "EXPRESS_ONEZONE" | "GL
 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";
+export type HttpMethod = PresignableHttpMethod | "POST"; // There are also others, but we don't want to support them yet
 /** 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>
+/**
+ * Implements [LocationInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_LocationInfo.html)
+ */
+export type BucketLocationInfo = {
+    name?: string;
+    type?: string;
+};
+/**
+ * Implements [BucketInfo](https://docs.aws.amazon.com/AmazonS3/latest/API/API_BucketInfo.html)
+ */
+export type BucketInfo = {
+    dataRedundancy?: string;
+    type?: string;
+};

package/dist/index.js

@@ -3,11 +3,3 @@ export { default as S3Client, } from "./S3Client.js";
 export { default as S3Error } from "./S3Error.js";
 export { default as S3Stat } from "./S3Stat.js";
 export { default as S3BucketEntry } from "./S3BucketEntry.js";
-// TODO
-// | ArrayBufferView
-// | ArrayBuffer
-// | SharedArrayBuffer
-// | Request
-// | Response
-// | S3File
-// | ReadableStream<Uint8Array>

package/dist/sign.d.ts

@@ -1,6 +1,8 @@
 import { type BinaryLike } from "node:crypto";
 import type { AmzDate } from "./AmzDate.ts";
 import type { HttpMethod, PresignableHttpMethod } from "./index.ts";
+// Spec:
+// https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html
 export declare function deriveSigningKey(date: string, region: string, secretAccessKey: string): Buffer;
 export declare function signCanonicalDataHash(signinKey: Buffer, canonicalDataHash: string, date: AmzDate, region: string): string;
 export declare const unsignedPayload = "UNSIGNED-PAYLOAD";
@@ -13,4 +15,4 @@ export declare const unsignedPayload = "UNSIGNED-PAYLOAD";
 export declare function createCanonicalDataDigestHostOnly(method: PresignableHttpMethod, path: string, query: string, host: string): string;
 export declare function createCanonicalDataDigest(method: HttpMethod, path: string, query: string, sortedHeaders: Record<string, string>, contentHashStr: string): string;
 export declare function sha256(data: BinaryLike): Buffer;
-export declare function md5Hex(data: BinaryLike): string;
+export declare function md5Base64(data: BinaryLike): string;

package/dist/sign.js

@@ -72,6 +72,6 @@ export function createCanonicalDataDigest(method, path, query, sortedHeaders, co
 export function sha256(data) {
     return createHash("sha256").update(data).digest();
 }
-export function md5Hex(data) {
-    return createHash("md5").update(data).digest("hex");
+export function md5Base64(data) {
+    return createHash("md5").update(data).digest("base64");
 }

package/dist/test-common.d.ts

@@ -1,4 +1 @@
-/**
- * @module Used by integration tests and unit tests.
- */
-export declare function runTests(runId: number, endpoint: string, forcePathStyle: boolean, accessKeyId: string, secretAccessKey: string, region: string, bucket: string): void;
+export declare function runTests(runId: number, endpoint: string, accessKeyId: string, secretAccessKey: string, region: string, bucket: string): void;

package/dist/test.integration.js

@@ -1,6 +1,8 @@
 // @ts-check
-import { describe } from "node:test";
+import { describe, before, after } from "node:test";
+import { expect } from "expect";
 import { runTests } from "./test-common.js";
+import { S3Client } from "./index.js";
 const env = process.env;
 const runId = Date.now();
 for (const provider of ["hetzner", "aws", "cloudflare"]) {
@@ -14,6 +16,29 @@ for (const provider of ["hetzner", "aws", "cloudflare"]) {
         if (!endpoint || !region || !bucket || !accessKeyId || !secretAccessKey) {
             throw new Error("Invalid config");
         }
-        runTests(runId, endpoint, false, accessKeyId, secretAccessKey, region, bucket);
+        {
+            const client = new S3Client({
+                endpoint,
+                accessKeyId,
+                secretAccessKey,
+                region,
+                bucket,
+            });
+            before(async () => {
+                expect(await client.bucketExists(bucket)).toBe(true);
+                const objects = (await client.list({ prefix: `${runId}/` })).contents;
+                expect(objects.length).toBe(0);
+            });
+            after(async () => {
+                expect(await client.bucketExists(bucket)).toBe(true);
+                const objects = (await client.list({ prefix: `${runId}/`, maxKeys: 1000 })).contents;
+                // clean up after all tests, but we want to fail because there are still objects
+                if (objects.length > 0) {
+                    await client.deleteObjects(objects);
+                }
+                expect(objects.length).toBe(0);
+            });
+        }
+        runTests(runId, endpoint, accessKeyId, secretAccessKey, region, bucket);
     });
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",
@@ -19,10 +19,10 @@
   "types": "./dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "tsgo",
     "clean": "rimraf dist",
-    "test": "tsc && node --test dist/*.test.js",
-    "test:integration": "tsc && node --test dist/test.integration.js",
+    "test": "tsgo && node --test dist/*.test.js",
+    "test:integration": "tsgo && node --test dist/test.integration.js",
     "ci": "biome ci ./src",
     "docs": "typedoc",
     "lint": "biome lint ./src",
@@ -30,11 +30,11 @@
     "prepublishOnly": "npm run clean && npm run build"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.828.0",
     "@biomejs/biome": "^1.9.4",
     "@testcontainers/localstack": "^11.0.3",
     "@testcontainers/minio": "^11.0.3",
     "@types/node": "^24.0.1",
+    "@typescript/native-preview": "^7.0.0-dev.20250613.1",
     "expect": "^30.0.0",
     "lefthook": "^1.11.13",
     "rimraf": "^6.0.1",