S3 / R2 Utilities
S3 / R2 Utilities
Imported from @xenterprises/fastify-ximagepipeline/s3. These helpers wrap the AWS SDK v3 S3Client for use with Cloudflare R2 or any S3-compatible service. The plugin uses them internally for staging uploads and processed media storage; they are also available for standalone use in scripts or custom workers.
Usage
import {
initializeS3Client,
uploadToS3,
downloadFromS3,
deleteFromS3,
listFromS3,
getSignedUrlForS3,
getPublicUrl,
batchDeleteFromS3,
} from '@xenterprises/fastify-ximagepipeline/s3'
Functions
initializeS3Client(config)
Create a configured S3Client instance for R2 or an AWS-compatible endpoint.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
config.endpoint | string | Yes | R2 or S3-compatible endpoint URL. |
config.accessKeyId | string | Yes | Access key ID. |
config.secretAccessKey | string | Yes | Secret access key. |
config.bucket | string | Yes | Bucket name. |
config.region | string | No | AWS region. Default "auto" (correct for R2). |
Returns: S3Client — An initialized AWS SDK v3 S3Client.
uploadToS3(client, bucket, key, buffer, options?)
Upload a buffer to S3/R2 with optional metadata and cache control headers.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
client | S3Client | Yes | Initialized S3 client. |
bucket | string | Yes | Target bucket name. |
key | string | Yes | Object key (storage path). |
buffer | Buffer | Yes | File content to upload. |
options.contentType | string | No | MIME type. Defaults to "application/octet-stream". |
options.metadata | Record<string, string> | No | Custom S3 metadata key-value pairs. |
options.cacheControl | string | No | Cache-Control header value. |
options.acl | string | No | Object ACL (e.g. "public-read"). |
Returns: Promise<void>
downloadFromS3(client, bucket, key)
Download an object from S3/R2 as a buffer.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
client | S3Client | Yes | Initialized S3 client. |
bucket | string | Yes | Bucket name. |
key | string | Yes | Object key to download. |
Returns: Promise<Buffer>
deleteFromS3(client, bucket, key)
Delete a single object from S3/R2.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
client | S3Client | Yes | Initialized S3 client. |
bucket | string | Yes | Bucket name. |
key | string | Yes | Object key to delete. |
Returns: Promise<void>
listFromS3(client, bucket, prefix)
List all objects under a given key prefix.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
client | S3Client | Yes | Initialized S3 client. |
bucket | string | Yes | Bucket name. |
prefix | string | Yes | Key prefix to filter by (e.g. "staging/", "media/user-123/"). |
Returns: Promise<Array<{ key: string; size: number; lastModified: Date }>> — Objects matching the prefix.
getSignedUrlForS3(client, bucket, key, expiresIn?)
Generate a pre-signed URL for temporary access to a private object.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
client | S3Client | Yes | Initialized S3 client. |
bucket | string | Yes | Bucket name. |
key | string | Yes | Object key to sign. |
expiresIn | number | No | Expiry in seconds. Default 3600 (1 hour). |
Returns: Promise<string> — A pre-signed URL valid for expiresIn seconds.
getPublicUrl(r2Config, key)
Generate a public URL for an object without signing.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
r2Config | object | Yes | The r2 config object used to initialize the plugin (must include endpoint and bucket). |
key | string | Yes | Object key. |
Returns: string — Full public URL: https://<endpoint>/<bucket>/<key>.
batchDeleteFromS3(client, bucket, prefix)
Delete up to 1000 objects matching a key prefix in a single S3 batch-delete call.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
client | S3Client | Yes | Initialized S3 client. |
bucket | string | Yes | Bucket name. |
prefix | string | Yes | Key prefix — all matching objects will be deleted. |
Returns: Promise<{ deleted: number }> — Count of objects removed.
Examples
Initialize a client and upload a file
import { initializeS3Client, uploadToS3, getPublicUrl } from '@xenterprises/fastify-ximagepipeline/s3'
const r2Config = {
endpoint: process.env.R2_ENDPOINT,
accessKeyId: process.env.R2_ACCESS_KEY_ID,
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
bucket: process.env.R2_BUCKET,
}
const client = initializeS3Client(r2Config)
const buffer = fs.readFileSync('./thumbnail.webp')
await uploadToS3(client, r2Config.bucket, 'media/thumb.webp', buffer, {
contentType: 'image/webp',
cacheControl: 'public, max-age=31536000',
})
const url = getPublicUrl(r2Config, 'media/thumb.webp')
console.log(url) // https://r2.example.com/my-bucket/media/thumb.webp
Generate a signed URL for a private asset
import { initializeS3Client, getSignedUrlForS3 } from '@xenterprises/fastify-ximagepipeline/s3'
const client = initializeS3Client(r2Config)
fastify.get('/originals/:key', async (request, reply) => {
const url = await getSignedUrlForS3(
client,
r2Config.bucket,
`originals/${request.params.key}`,
900 // 15 minutes
)
return reply.redirect(url)
})
Clean up a user's staging files
import { initializeS3Client, batchDeleteFromS3 } from '@xenterprises/fastify-ximagepipeline/s3'
const client = initializeS3Client(r2Config)
const { deleted } = await batchDeleteFromS3(
client,
r2Config.bucket,
`staging/user-${userId}/`
)
console.log(`Removed ${deleted} staging objects`)
Download then reprocess
import { initializeS3Client, downloadFromS3, uploadToS3 } from '@xenterprises/fastify-ximagepipeline/s3'
import { processImage } from '@xenterprises/fastify-ximagepipeline/image'
const client = initializeS3Client(r2Config)
const original = await downloadFromS3(client, r2Config.bucket, 'originals/photo.jpg')
const { variants } = await processImage(original, 'gallery', pluginConfig)
for (const [name, buf] of Object.entries(variants)) {
await uploadToS3(client, r2Config.bucket, `media/photo-${name}.webp`, buf, {
contentType: 'image/webp',
})
}
AI Context
import: "@xenterprises/fastify-ximagepipeline/s3"
use-when: >
When you need direct S3/R2 operations (upload, download, delete, list, signed URLs)
outside of the plugin's automatic pipeline — e.g. in migration scripts, custom workers,
or tooling that shares the same R2 bucket as the image pipeline.
functions:
- initializeS3Client: Create an S3Client from R2/S3 config
- uploadToS3: Upload a buffer with metadata and cache headers
- downloadFromS3: Download an object as a Buffer
- deleteFromS3: Delete a single object by key
- listFromS3: List objects by key prefix
- getSignedUrlForS3: Generate a temporary pre-signed URL (default 1 hour)
- getPublicUrl: Build a public URL without signing
- batchDeleteFromS3: Delete up to 1000 objects by prefix in one call
