### Start Local MinIO Server

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Docker command to start a local MinIO server with specified credentials, region, and bucket. Exposes ports for S3 and MinIO console access.

```sh
docker run --rm -e MINIO_ROOT_USER=AKIA_DEV -e MINIO_ROOT_PASSWORD=secretkey -e MINIO_REGION_NAME=dev-region -p 9000:9000 -p 9001:9001 --entrypoint /bin/sh minio/minio:RELEASE.2025-02-28T09-55-16Z -c 'mkdir -p /data/dev-bucket && minio server --console-address ":9001" /data'
```

--------------------------------

### Run Integration Tests with MinIO

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Instructions to run integration tests for the S3 Lite Client after starting a local MinIO server. Requires network access and specific Deno permissions.

```sh
deno test --allow-net integration.ts
```

--------------------------------

### Import S3Client in Deno (No Install)

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Import the S3Client directly from a JSR URL for use in Deno projects without prior installation.

```typescript
import { S3Client } from "jsr:@bradenmacdonald/s3-lite-client@0.9.6";
```

--------------------------------

### Generate Presigned URLs for Any Method

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Generates presigned URLs for GET, PUT, HEAD, and DELETE requests, offering granular control for advanced use cases.

```APIDOC
## GET /presignedUrl

### Description
Generates a presigned URL for a specified HTTP method (GET, PUT, HEAD, DELETE) and object key. This method provides more control than convenience methods for advanced use cases.

### Method
POST

### Endpoint
/presignedUrl

### Parameters
#### Request Body
- **method** (string) - Required - The HTTP method for which to generate the presigned URL (e.g., "PUT", "GET", "HEAD", "DELETE").
- **key** (string) - Required - The object key (path) within the bucket.
- **options** (object) - Optional - Configuration options for the presigned URL.
  - **expirySeconds** (number) - Optional - The duration in seconds for which the URL will be valid. Defaults to 900.
  - **parameters** (object) - Optional - Custom query parameters to include in the presigned URL (e.g., versionId, response-content-type).
  - **requestDate** (Date) - Optional - A specific date and time to use for generating the signature, ensuring reproducible URLs.

### Request Example
```json
{
  "method": "PUT",
  "key": "uploads/new-file.txt",
  "options": {
    "expirySeconds": 3600
  }
}
```

### Response
#### Success Response (200)
- **url** (string) - The generated presigned URL.

#### Response Example
```json
{
  "url": "http://localhost:9000/dev-bucket/uploads/new-file.txt?AWSAccessKeyId=AKIA_DEV&Signature=...&Expires=..."
}
```
```

--------------------------------

### Import S3Client in Browser via ESM

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Import the S3Client into a browser environment using an ES module URL. This example shows two common import syntaxes.

```javascript
<script type="module">
  import { S3Client } from "https://esm.sh/jsr/@bradenmacdonald/s3-lite-client@0.9.6";
  // Or:
  const { S3Client } = await import("https://esm.sh/jsr/@bradenmacdonald/s3-lite-client@0.9.6");
</script>
```

--------------------------------

### Presigned Get Object URL API

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Generates a presigned URL for temporary, authenticated download access to an object.

```APIDOC
## GET /api/objects/presigned-url/{key}

### Description
Generates a presigned URL that allows temporary, authenticated access to download an object. The URL includes a cryptographic signature and can be shared with users who don't have direct S3 credentials.

### Method
GET

### Endpoint
`/api/objects/presigned-url/{key}`

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the object to generate a presigned URL for.

#### Query Parameters
- **expirySeconds** (integer) - Optional - The duration in seconds for which the presigned URL will be valid. Defaults to 604800 (7 days).
- **versionId** (string) - Optional - The version ID of the object to generate a presigned URL for.
- **bucketName** (string) - Optional - The name of the bucket from which to generate the presigned URL. Defaults to the client's configured bucket.
- **responseParams** (object) - Optional - Parameters to override response headers for the download.
  - **response-content-type** (string) - Optional - Overrides the Content-Type header.
  - **response-content-disposition** (string) - Optional - Overrides the Content-Disposition header (e.g., 'attachment; filename="report.pdf"').
  - **response-cache-control** (string) - Optional - Overrides the Cache-Control header.

### Request Example
```json
{
  "key": "document.pdf"
}
```

### Response
#### Success Response (200)
- **url** (string) - The generated presigned URL for downloading the object.

#### Response Example
```json
{
  "url": "http://localhost:9000/dev-bucket/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
}
```
```

--------------------------------

### GET /listObjects

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Lists objects in the bucket with optional prefix filtering. Returns an async generator that handles pagination transparently, yielding S3Object entries with key, etag, size, and lastModified properties.

```APIDOC
## GET /listObjects

### Description
Lists objects within an S3 bucket, with support for filtering by prefix and controlling pagination.

### Method
GET

### Endpoint
`/bucketName` (Implicitly handled by the client)

### Parameters
#### Query Parameters
- **prefix** (string) - Optional - Filters objects to include only those whose keys start with this prefix.
- **maxResults** (number) - Optional - The maximum number of objects to return in total. Note: This is a client-side limit; the API may fetch more per request to satisfy pagination.
- **pageSize** (number) - Optional - The number of objects to request per API call. Maximum is typically 1000.
- **bucketName** (string) - Optional - Specifies a different bucket to list objects from. If not provided, the default bucket configured in the client is used.

### Request Example
```typescript
// Iterate over all objects with prefix
for await (const obj of client.listObjects({ prefix: "data/concepts/" })) {
  console.log(obj);
  // { type: "Object", key: "...", etag: "...", size: ..., lastModified: ... }
}

// Collect all keys as an array
const keys = await Array.fromAsync(
  client.listObjects({ prefix: "data/authors/" }),
  (entry) => entry.key
);
console.log(keys);

// Limit total results
const limited = client.listObjects({
  prefix: "logs/",
  maxResults: 100,
});
const first100 = await Array.fromAsync(limited);

// Control page size for efficiency
const withPageSize = client.listObjects({
  prefix: "files/",
  pageSize: 100, // Fetch 100 per HTTP request (max 1000)
});

// List from different bucket
for await (const obj of client.listObjects({
  prefix: "backups/",
  bucketName: "archive-bucket",
})) {
  console.log(obj.key);
}
```

### Response
#### Success Response (200)
- **async generator** - An asynchronous generator that yields objects matching the criteria. Each yielded object has the following properties:
  - **type** (string) - The type of the entry (e.g., "Object").
  - **key** (string) - The key (name) of the object.
  - **etag** (string) - The ETag of the object.
  - **size** (number) - The size of the object in bytes.
  - **lastModified** (Date) - The last modified date of the object.

#### Response Example
```json
{
  "example": "{\n  type: \"Object\",\n  key: \"data/concepts/updated_date=2024-01-25/part_000.gz\",\n  etag: \"2c9b2843c8d2e9057656e1af1c2a92ad\",\n  size: 44105,\n  lastModified: \"2024-01-25T22:57:43.000Z\"\n}"
}
```
```

--------------------------------

### Download Partial Object from Offset to End

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads a portion of an object starting from a specified offset to the end of the file. Set `length` to 0 to indicate reading to the end.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Download from offset to end of file (length: 0)
const fromOffset = await client.getPartialObject("large-file.dat", {
  offset: 1000000, // Start at 1MB
  length: 0, // Read to end
});
```

--------------------------------

### GET /getObject

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads an object and returns a standard HTTP Response object. The response can be consumed as text, JSON, blob, arrayBuffer, or streamed via the body property for memory-efficient handling of large files.

```APIDOC
## GET /getObject

### Description
Downloads an object from an S3 bucket. The response can be processed in various formats (text, JSON, blob, arrayBuffer) or streamed.

### Method
GET

### Endpoint
`/bucketName/objectKey` (Implicitly handled by the client)

### Parameters
#### Query Parameters
- **versionId** (string) - Optional - Specifies the version of the object to retrieve.
- **bucketName** (string) - Optional - Specifies a different bucket to retrieve the object from. If not provided, the default bucket configured in the client is used.

### Request Example
```typescript
const response = await client.getObject("hello.txt");
const text = await response.text();
console.log(text); // "Hello, World!"

const versionedResponse = await client.getObject("file.txt", {
  versionId: "abc123-version-uuid",
});

const otherBucketResponse = await client.getObject("file.txt", {
  bucketName: "other-bucket",
});
```

### Response
#### Success Response (200)
- **response** (HTTP Response) - An HTTP Response object containing the object data. Properties like `.text()`, `.json()`, `.blob()`, `.arrayBuffer()`, and `.body` (for streaming) are available.

#### Response Example
```json
{
  "example": "Response body content depends on the object type (e.g., text, JSON, binary data)"
}
```
```

--------------------------------

### GET /getPartialObject

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads a specific byte range of an object using HTTP Range requests. Useful for resumable downloads, seeking within large files, or streaming specific portions of media files.

```APIDOC
## GET /getPartialObject

### Description
Downloads a specific byte range of an object from an S3 bucket using HTTP Range requests.

### Method
GET

### Endpoint
`/bucketName/objectKey` (Implicitly handled by the client)

### Parameters
#### Query Parameters
- **offset** (number) - Required - The starting byte offset for the download.
- **length** (number) - Required - The number of bytes to download. A value of 0 indicates downloading to the end of the file.
- **bucketName** (string) - Optional - Specifies a different bucket to retrieve the object from. If not provided, the default bucket configured in the client is used.

### Request Example
```typescript
// Download bytes 12-19 (8 bytes starting at offset 12)
const partial = await client.getPartialObject("document.txt", {
  offset: 12,
  length: 8,
});
console.log(await partial.text()); // "contents"

// Download from offset to end of file
const fromOffset = await client.getPartialObject("large-file.dat", {
  offset: 1000000, // Start at 1MB
  length: 0, // Read to end
});

// Stream partial content
const videoChunk = await client.getPartialObject("video.mp4", {
  offset: 0,
  length: 1024 * 1024, // First 1MB
});
const chunk = await videoChunk.arrayBuffer();
```

### Response
#### Success Response (200)
- **response** (HTTP Response) - An HTTP Response object containing the specified byte range of the object data. Properties like `.text()`, `.json()`, `.blob()`, `.arrayBuffer()`, and `.body` (for streaming) are available.

#### Response Example
```json
{
  "example": "Partial content of the requested object"
}
```
```

--------------------------------

### Initialize S3 Client and List Objects

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Instantiate the S3Client with endpoint, region, and bucket details. Then, iterate through objects under a specified prefix, logging each object's data.

```javascript
const s3client = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "openalex",
});

// Log data about each object found under the 'data/concepts/' prefix:
for await (const obj of s3client.listObjects({ prefix: "data/concepts/" })) {
  console.log(obj);
}
```

--------------------------------

### Upload and Download File with MinIO

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Demonstrates uploading a file to and downloading it from a local MinIO server. The downloaded content can be streamed to a local file or consumed into memory.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

// Connecting to a local MinIO server:
const s3client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Upload a file:
await s3client.putObject("test.txt", "This is the contents of the file.");

// Now download it
const result = await s3client.getObject("test.txt");
// and stream the results to a local file:
const localOutFile = await Deno.open("test-out.txt", { write: true, createNew: true });
await result.body!.pipeTo(localOutFile.writable);
// or instead of streaming, you can consume the whole file into memory by awaiting
// result.text(), result.blob(), result.arrayBuffer(), or result.json()
```

--------------------------------

### Initialize S3Client for MinIO Local Server

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Instantiate an S3Client for a local MinIO server. Use the local endpoint, a development region, and the appropriate bucket and credentials.

```typescript
// MinIO local server
const minioClient = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});
```

--------------------------------

### Initialize S3Client for AWS S3

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Create an S3Client instance for AWS S3 using a full URL endpoint and authentication credentials. Ensure region and bucket are correctly specified.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

// AWS S3 with full URL endpoint (recommended)
const awsClient = new S3Client({
  endPoint: "https://s3.us-west-2.amazonaws.com",
  region: "us-west-2",
  bucket: "my-bucket",
  accessKey: "AKIAIOSFODNN7EXAMPLE",
  secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
});
```

--------------------------------

### Initialize S3Client with Virtual-Hosted Style

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Configure an S3Client to use virtual-hosted style access, where the bucket name is part of the subdomain. Set `pathStyle` to `false`.

```typescript
// Virtual-hosted style (bucket in subdomain)
const virtualHostedClient = new S3Client({
  endPoint: "https://s3.amazonaws.com",
  region: "us-east-1",
  bucket: "amazon-pqa",
  pathStyle: false, // Uses https://bucket.s3.amazonaws.com/key format
});
```

--------------------------------

### Get Object Metadata

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Use `statObject` to retrieve detailed metadata for an object. Supports custom request headers for operations like checksum verification and specifying a `versionId`.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Get object metadata
const stat = await client.statObject("document.pdf");
console.log(stat);
// {
//   type: "Object",
//   key: "document.pdf",
//   size: 1048576,
//   lastModified: 2024-01-15T10:30:00.000Z,
//   etag: "d41d8cd98f00b204e9800998ecf8427e",
//   versionId: null,
//   metadata: {
//     "Content-Type": "application/pdf",
//     "Cache-Control": "public, max-age=31536000",
//     "x-amz-meta-author": "John Doe"
//   }
// }

// Access specific metadata
console.log(`Size: ${stat.size} bytes`);
console.log(`Content-Type: ${stat.metadata["Content-Type"]}`);
console.log(`Custom Author: ${stat.metadata["x-amz-meta-author"]}`);
```

```typescript
// Get metadata with checksum verification
const statWithChecksum = await client.statObject("verified-file.dat", {
  headers: {
    "x-amz-checksum-mode": "ENABLED",
  },
});
console.log(statWithChecksum.metadata["x-amz-checksum-sha256"]);

// Stat specific version
const versionStat = await client.statObject("file.txt", {
  versionId: "abc123-version-uuid",
});
```

--------------------------------

### Initialize S3Client for Supabase Storage

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Set up an S3Client to connect to Supabase Storage's S3 endpoint. Provide the specific endpoint URL, region, and your Supabase access and secret keys.

```typescript
// Supabase Storage S3 endpoint
const supabaseClient = new S3Client({
  endPoint: "http://127.0.0.1:54321/storage/v1/s3",
  region: "local",
  accessKey: "your-access-key",
  secretKey: "your-secret-key",
});
```

--------------------------------

### S3Client Constructor

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Creates a new S3 client instance for connecting to S3-compatible storage services. The client supports full URL endpoints, optional authentication, custom regions, and path-style or virtual-hosted style requests.

```APIDOC
## S3Client Constructor

### Description
Creates a new S3 client instance for connecting to S3-compatible storage services. The client supports full URL endpoints, optional authentication, custom regions, and path-style or virtual-hosted style requests.

### Parameters
#### Request Body
- **endPoint** (string) - Required - The endpoint URL of the S3-compatible storage service.
- **region** (string) - Optional - The region of the S3 bucket.
- **bucket** (string) - Required - The name of the S3 bucket.
- **accessKey** (string) - Optional - The access key for authentication.
- **secretKey** (string) - Optional - The secret key for authentication.
- **sessionToken** (string) - Optional - The session token for temporary credentials.
- **pathStyle** (boolean) - Optional - Whether to use path-style or virtual-hosted style requests. Defaults to true (path-style).

### Request Example
```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

// AWS S3 with full URL endpoint (recommended)
const awsClient = new S3Client({
  endPoint: "https://s3.us-west-2.amazonaws.com",
  region: "us-west-2",
  bucket: "my-bucket",
  accessKey: "AKIAIOSFODNN7EXAMPLE",
  secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
});

// MinIO local server
const minioClient = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Unauthenticated access to public buckets
const publicClient = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "openalex",
});

// Supabase Storage S3 endpoint
const supabaseClient = new S3Client({
  endPoint: "http://127.0.0.1:54321/storage/v1/s3",
  region: "local",
  accessKey: "your-access-key",
  secretKey: "your-secret-key",
});

// Virtual-hosted style (bucket in subdomain)
const virtualHostedClient = new S3Client({
  endPoint: "https://s3.amazonaws.com",
  region: "us-east-1",
  bucket: "amazon-pqa",
  pathStyle: false, // Uses https://bucket.s3.amazonaws.com/key format
});

// Using temporary credentials with session token
const tempCredentialsClient = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "my-bucket",
  accessKey: "ASIAIOSFODNN7EXAMPLE",
  secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  sessionToken: "AQoDYXdzEJr...", // Required for temporary credentials
});
```
```

--------------------------------

### Initialize S3Client with Temporary Credentials

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Create an S3Client using temporary AWS credentials, including the session token. This is useful for short-lived access.

```typescript
// Using temporary credentials with session token
const tempCredentialsClient = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "my-bucket",
  accessKey: "ASIAIOSFODNN7EXAMPLE",
  secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  sessionToken: "AQoDYXdzEJr...", // Required for temporary credentials
});
```

--------------------------------

### statObject - Get Object Metadata

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Retrieves detailed metadata about an object including size, last modified date, etag, version ID, and custom metadata headers. Supports custom request headers for operations like checksum verification.

```APIDOC
## statObject - Get Object Metadata

### Description
Retrieves detailed metadata about an object including size, last modified date, etag, version ID, and custom metadata headers. Supports custom request headers for operations like checksum verification.

### Method
HEAD (or similar, depending on S3 implementation)

### Endpoint
`/[bucketName]/[objectKey]`

### Parameters
#### Path Parameters
- **objectKey** (string) - Required - The key of the object to get metadata for.

#### Query Parameters
- **versionId** (string) - Optional - Specifies a particular version of the object.
- **bucketName** (string) - Optional - Specifies a different bucket.

#### Request Body
- **headers** (object) - Optional - Custom request headers, e.g., for checksum verification.
  - **x-amz-checksum-mode** (string) - Optional - Enables checksum verification.

### Request Example
```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Get object metadata
const stat = await client.statObject("document.pdf");
console.log(stat);

// Get metadata with checksum verification
const statWithChecksum = await client.statObject("verified-file.dat", {
  headers: {
    "x-amz-checksum-mode": "ENABLED",
  },
});
console.log(statWithChecksum.metadata["x-amz-checksum-sha256"]);

// Stat specific version
const versionStat = await client.statObject("file.txt", {
  versionId: "abc123-version-uuid",
});
```

### Response
#### Success Response (200)
- **type** (string) - Type of the entry, always 'Object' for this method.
- **key** (string) - The key of the object.
- **size** (number) - The size of the object in bytes.
- **lastModified** (Date) - The last modified date of the object.
- **etag** (string) - The ETag of the object.
- **versionId** (string | null) - The version ID of the object, or null if versioning is not enabled or applicable.
- **metadata** (object) - An object containing custom metadata headers and standard headers like 'Content-Type'.
  - **Content-Type** (string) - The content type of the object.
  - **Cache-Control** (string) - The cache control directive.
  - **x-amz-meta-author** (string) - Example custom metadata field.
  - **x-amz-checksum-sha256** (string) - The SHA256 checksum of the object (if requested).

#### Response Example
```json
{
  "type": "Object",
  "key": "document.pdf",
  "size": 1048576,
  "lastModified": "2024-01-15T10:30:00.000Z",
  "etag": "d41d8cd98f00b204e9800998ecf8427e",
  "versionId": null,
  "metadata": {
    "Content-Type": "application/pdf",
    "Cache-Control": "public, max-age=31536000",
    "x-amz-meta-author": "John Doe"
  }
}
```
```

--------------------------------

### MinIO Debugging Commands

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Commands to set up a MinIO alias and trace traffic for debugging purposes. Useful for inspecting requests and responses between the client and the MinIO server.

```sh
mc alias set localdebug http://localhost:9000 AKIA_DEV secretkey
mc admin trace --verbose --all localdebug
```

--------------------------------

### Download Object as Binary (Blob)

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads an object and converts it to a Blob, useful for browser environments or further binary processing.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

const blob = await client.getObject("image.png").then((r) => r.blob());
```

--------------------------------

### Manage S3 Buckets: Create, Check, and Delete

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Perform essential bucket management operations including checking for bucket existence, creating new buckets, and removing empty buckets. Useful for setting up and cleaning up S3 resources.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Check if bucket exists
const exists = await client.bucketExists("my-bucket");
console.log(exists); // true or false

// Create a new bucket
await client.makeBucket("new-bucket");
console.log("Bucket created successfully");

// Remove an empty bucket
await client.removeBucket("empty-bucket");
console.log("Bucket removed");

// Complete workflow: create bucket if not exists
const bucketName = "app-data";
if (!(await client.bucketExists(bucketName))) {
  await client.makeBucket(bucketName);
  console.log(`Created bucket: ${bucketName}`);
}

// Use the bucket
const bucketClient = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: bucketName,
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});
await bucketClient.putObject("config.json", JSON.stringify({ version: 1 }));
```

--------------------------------

### Create Bucket with Supabase S3

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Creates a new bucket on the S3 service of a local Supabase development server using the S3 Lite Client.

```ts
const client = new S3Client({
  endPoint: "http://127.0.0.1:54321/storage/v1/s3",
  region: "local",
  accessKey: "paste from output of supabase start",
  secretKey: "paste from output of supabase start",
});
await client.makeBucket("my-bucket");
```

--------------------------------

### Deno Lint and Test Commands

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Commands to run code linting and tests for a Deno project. Ensures code quality and verifies functionality.

```sh
deno lint && deno test
```

--------------------------------

### List Objects with Prefix Filtering

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Lists objects in a bucket that match a given prefix. Returns an async generator that handles pagination automatically.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "openalex",
});

// Iterate over all objects with prefix
for await (const obj of client.listObjects({ prefix: "data/concepts/" })) {
  console.log(obj);
  // {
  //   type: "Object",
  //   key: "data/concepts/updated_date=2024-01-25/part_000.gz",
  //   etag: "2c9b2843c8d2e9057656e1af1c2a92ad",
  //   size: 44105,
  //   lastModified: 2024-01-25T22:57:43.000Z
  // }
}
```

--------------------------------

### Download Object as Binary (ArrayBuffer)

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads an object and returns its content as an ArrayBuffer, suitable for binary data.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Download as binary
const binaryResponse = await client.getObject("image.png");
const arrayBuffer = await binaryResponse.arrayBuffer();
```

--------------------------------

### Stream Large File to Disk (Deno)

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads a large object and streams its content directly to a local file using Deno's file system API. This is memory-efficient for very large files.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Stream large file to disk (Deno)
const largeFileResponse = await client.getObject("large-file.dat");
const localFile = await Deno.open("output.dat", { write: true, createNew: true });
await largeFileResponse.body!.pipeTo(localFile.writable);
```

--------------------------------

### Create Presigned POST Policy for Browser Uploads

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Generates a presigned POST policy for direct file uploads from a web browser to S3. Includes the upload URL and necessary form fields. The browser then uses this policy to upload the file directly.

```typescript
// Create a presigned POST policy
const { url, fields } = await s3client.presignedPostObject("my-file.txt", {
  expirySeconds: 3600, // URL expires in 1 hour
  fields: {
    "Content-Type": "text/plain",
  },
});

// In the browser, use the policy for direct uploads:
const formData = new FormData();
// Add all required fields from the presigned POST
Object.entries(fields).forEach(([key, value]) => {
  formData.append(key, value);
});
// Add the file content
formData.append("file", fileInput.files[0]);

// Upload the object using the presigned POST
const response = await fetch(url, {
  method: "POST",
  body: formData,
});

if (response.ok) {
  console.log("File uploaded successfully!");
}
```

--------------------------------

### Download Object as Text

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads an object and consumes its content as text. Ensure the object is text-based.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Download as text
const response = await client.getObject("hello.txt");
const text = await response.text();
console.log(text); // "Hello, World!"
```

--------------------------------

### Deno Format Code

Source: https://github.com/bradenmacdonald/s3-lite-client/blob/main/README.md

Command to format Deno project code according to standard conventions, ensuring consistent code style.

```sh
deno fmt
```

--------------------------------

### Control Page Size for Object Listing

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Lists objects with a prefix and controls the number of objects fetched per HTTP request using the `pageSize` option. This can improve efficiency for large buckets.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "openalex",
});

// Control page size for efficiency
const withPageSize = client.listObjects({
  prefix: "files/",
  pageSize: 100, // Fetch 100 per HTTP request (max 1000)
});
```

--------------------------------

### Generate Presigned POST for Browser Uploads

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Creates a presigned POST policy enabling direct uploads from browsers to S3 without server proxying. Returns a URL and form fields for HTML forms or JavaScript FormData.

```APIDOC
## POST /presigned-post

### Description
Generates a presigned POST policy that allows direct uploads from browsers to S3. It returns a URL and a set of form fields that can be used in an HTML form or with JavaScript's FormData object.

### Method
POST

### Endpoint
/presigned-post

### Parameters
#### Request Body
- **key** (string) - Required - The object key (path) within the bucket where the file will be uploaded.
- **options** (object) - Optional - Configuration options for the presigned POST policy.
  - **expirySeconds** (number) - Optional - The duration in seconds for which the policy will be valid. Defaults to 900.
  - **fields** (object) - Optional - Additional form fields to include in the policy, such as Content-Type or custom metadata (e.g., `x-amz-meta-uploaded-by`).
  - **conditions** (array) - Optional - An array of conditions that the uploaded object must satisfy (e.g., content-length-range, starts-with).

### Request Example
```json
{
  "key": "uploads/user-file.txt",
  "options": {
    "expirySeconds": 3600,
    "fields": {
      "Content-Type": "text/plain",
      "x-amz-meta-uploaded-by": "user123"
    }
  }
}
```

### Response
#### Success Response (200)
- **url** (string) - The URL to which the form should be posted.
- **fields** (object) - An object containing the form fields required for the POST request (e.g., policy, signature, key, and any additional fields specified).

#### Response Example
```json
{
  "url": "http://localhost:9000/dev-bucket",
  "fields": {
    "key": "uploads/user-file.txt",
    "policy": "...",
    "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
    "X-Amz-Credential": "...",
    "X-Amz-Date": "...",
    "X-Amz-Signature": "..."
  }
}
```
```

--------------------------------

### Handle Missing Credentials for Presigned URLs

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Catch errors that occur when attempting to generate presigned URLs without providing necessary credentials. This ensures that operations requiring authentication are properly guarded.

```typescript
// Check for presigned URL errors
try {
  const unauthClient = new S3Client({
    endPoint: "http://localhost:9000",
    region: "dev-region",
    bucket: "dev-bucket",
    // No credentials
  });
  await unauthClient.presignedGetObject("file.txt");
} catch (error) {
  if (error instanceof S3Errors.AccessKeyRequiredError) {
    console.log("Cannot create presigned URL without credentials");
  }
}
```

--------------------------------

### exists - Check Object Existence

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Checks if an object with the specified key exists in the bucket. Returns true if the object exists, false if it does not exist, and throws an error for other failures.

```APIDOC
## exists - Check Object Existence

### Description
Checks if an object with the specified key exists in the bucket. Returns true if the object exists, false if it does not exist, and throws an error for other failures.

### Method
HEAD (or similar, depending on S3 implementation)

### Endpoint
`/[bucketName]/[objectKey]`

### Parameters
#### Path Parameters
- **objectKey** (string) - Required - The key of the object to check for.

#### Query Parameters
- **versionId** (string) - Optional - Specifies a particular version of the object to check.
- **bucketName** (string) - Optional - Specifies a different bucket to check in.

### Request Example
```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Check if object exists
const exists = await client.exists("config.json");
if (exists) {
  const config = await client.getObject("config.json").then((r) => r.json());
  console.log(config);
} else {
  console.log("Config file not found, using defaults");
}

// Check specific version
const versionExists = await client.exists("document.txt", {
  versionId: "abc123-version-uuid",
});

// Check in different bucket
const backupExists = await client.exists("data.zip", {
  bucketName: "backup-bucket",
});
```

### Response
#### Success Response (200)
- **exists** (boolean) - True if the object exists, false otherwise.

#### Response Example
```json
true
```
```

--------------------------------

### Initialize S3Client for Unauthenticated Access

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Configure an S3Client for unauthenticated access to public S3 buckets. Only the endpoint, region, and bucket name are required.

```typescript
// Unauthenticated access to public buckets
const publicClient = new S3Client({
  endPoint: "https://s3.us-east-1.amazonaws.com",
  region: "us-east-1",
  bucket: "openalex",
});
```

--------------------------------

### Download Partial Object as Text

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Downloads a specific byte range of an object and returns the content as text. Ensure the specified range contains text data.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Download bytes 12-19 (8 bytes starting at offset 12)
const partial = await client.getPartialObject("document.txt", {
  offset: 12,
  length: 8,
});
console.log(await partial.text()); // "contents"
```

--------------------------------

### Generate Presigned Download URL for S3 Object

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Generates a temporary, authenticated URL for downloading an object. Supports custom expiry times, overriding response headers for downloads, specifying a version, and generating URLs for objects in different buckets.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Generate presigned URL (default 7 days expiry)
const downloadUrl = await client.presignedGetObject("document.pdf");
console.log(downloadUrl);
// http://localhost:9000/dev-bucket/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...

// Use the URL to download (works without credentials)
const response = await fetch(downloadUrl);
const content = await response.text();

// Custom expiry time
const shortLivedUrl = await client.presignedGetObject("sensitive.dat", {
  expirySeconds: 300, // 5 minutes
});

// Override response headers (useful for downloads)
const downloadableUrl = await client.presignedGetObject("report.pdf", {
  expirySeconds: 3600,
  responseParams: {
    "response-content-type": "application/pdf",
    "response-content-disposition": 'attachment; filename="monthly-report.pdf"',
    "response-cache-control": "no-cache",
  },
});

// Presigned URL for specific version
const versionUrl = await client.presignedGetObject("file.txt", {
  versionId: "abc123-version-uuid",
  expirySeconds: 86400, // 24 hours
});

// Presigned URL from different bucket
const archiveUrl = await client.presignedGetObject("backup.zip", {
  bucketName: "archive-bucket",
  expirySeconds: 3600,
});
```

--------------------------------

### Bucket Operations

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Provides methods to manage S3 buckets, including checking for existence, creating new buckets, and removing empty buckets.

```APIDOC
## Bucket Management API

### Description
This API provides endpoints for managing S3 buckets. You can check if a bucket exists, create a new bucket, and remove an empty bucket.

### Endpoints

#### Check Bucket Existence

##### Method
GET

##### Endpoint
`/buckets/{bucketName}`

##### Parameters
###### Path Parameters
- **bucketName** (string) - Required - The name of the bucket to check.

##### Response
###### Success Response (200)
- **exists** (boolean) - `true` if the bucket exists, `false` otherwise.

###### Response Example
```json
{
  "exists": true
}
```

#### Create Bucket

##### Method
PUT

##### Endpoint
`/buckets/{bucketName}`

##### Parameters
###### Path Parameters
- **bucketName** (string) - Required - The name of the bucket to create.

##### Response
###### Success Response (204)
No content, indicates successful creation.

#### Remove Bucket

##### Method
DELETE

##### Endpoint
`/buckets/{bucketName}`

##### Parameters
###### Path Parameters
- **bucketName** (string) - Required - The name of the empty bucket to remove.

##### Response
###### Success Response (204)
No content, indicates successful removal.

###### Error Response (409)
- **message** (string) - "Bucket is not empty" if the bucket contains objects.

###### Response Example (Error)
```json
{
  "message": "Bucket is not empty"
}
```
```

--------------------------------

### Generate Presigned URLs for Any Method

Source: https://context7.com/bradenmacdonald/s3-lite-client/llms.txt

Use getPresignedUrl for custom presigned URL generation with specific HTTP methods and optional parameters like expiry and custom headers. Useful for advanced upload, download, or metadata check scenarios.

```typescript
import { S3Client } from "@bradenmacdonald/s3-lite-client";

const client = new S3Client({
  endPoint: "http://localhost:9000",
  region: "dev-region",
  bucket: "dev-bucket",
  accessKey: "AKIA_DEV",
  secretKey: "secretkey",
});

// Presigned URL for PUT (upload)
const uploadUrl = await client.getPresignedUrl("PUT", "uploads/new-file.txt", {
  expirySeconds: 3600,
});

// Client can upload directly using the URL
await fetch(uploadUrl, {
  method: "PUT",
  body: "File content to upload",
  headers: {
    "Content-Type": "text/plain",
  },
});

// Presigned URL for HEAD (check metadata)
const headUrl = await client.getPresignedUrl("HEAD", "document.pdf", {
  expirySeconds: 300,
});

// Presigned URL for DELETE
const deleteUrl = await client.getPresignedUrl("DELETE", "temp-file.txt", {
  expirySeconds: 600,
});

// With custom query parameters
const customUrl = await client.getPresignedUrl("GET", "file.txt", {
  expirySeconds: 3600,
  parameters: {
    versionId: "abc123",
    "response-content-type": "text/plain",
  },
});

// Specify exact request date for reproducible URLs
const reproducibleUrl = await client.getPresignedUrl("GET", "file.txt", {
  expirySeconds: 3600,
  requestDate: new Date("2024-01-15T00:00:00Z"),
});
```