s3-temp
v0.1.0
Published
Upload files to S3 with automatic cleanup
Readme
s3-temp
Upload files to S3 with automatic cleanup. Useful in tests and scripts that need to stage a file in S3 temporarily and remove it when done.
How it works
Each function uploads a file to S3 and returns a TempFileOnS3 object
containing the resolved key, the ETag from S3, and an async cleanup() function
that deletes the object when called.
If no key is provided, one is generated automatically: for file uploads the
original filename is preserved with a UUID suffix (e.g. report_3a9f...c1.pdf),
and for string uploads a plain UUID is used with an optional extension.
Installation
npm install s3-tempUsage
Upload a local file
import { tempFileOnS3 } from 's3-temp'
const { cleanup, key, eTag } = await tempFileOnS3({
localPath: '/tmp/report.pdf',
bucket: 'my-bucket',
})
try {
// Work with `key` and optionally `eTag`.
} finally {
await cleanup()
}Provide a key to use a fixed path instead of a generated one:
const key = 'uploads/report.pdf'
const { cleanup, eTag } = await tempFileOnS3({
localPath: '/tmp/report.pdf',
bucket: 'my-bucket',
key,
})
try {
// Work with `key` and optionally `eTag`.
} finally {
await cleanup()
}Upload a string
import { tempFileOnS3FromString } from 's3-temp'
const { cleanup, key, eTag } = await tempFileOnS3FromString({
contents: '<html>hello</html>',
bucket: 'my-bucket',
extension: '.html',
})
try {
// Work with `key` and optionally eTag.
} finally {
await cleanup()
}API
tempFileOnS3(options): Promise<TempFileOnS3>
| Option | Type | Required | Description |
| ----------- | ---------------- | -------- | ----------------------------------------- |
| localPath | string | yes | Path to the local file to upload |
| bucket | string | yes | S3 bucket name |
| key | string | no | S3 object key (auto-generated if omitted) |
| encoding | BufferEncoding | no | File encoding passed to fs.readFile |
| verbose | boolean | no | Log upload/removal to stderr |
tempFileOnS3FromString(options): Promise<TempFileOnS3>
| Option | Type | Required | Description |
| ----------- | --------- | -------- | ---------------------------------------------------- |
| contents | string | yes | String content to upload |
| bucket | string | yes | S3 bucket name |
| key | string | no | S3 object key (auto-generated if omitted) |
| extension | string | no | Extension appended to generated key (e.g. '.json') |
| verbose | boolean | no | Log upload/removal to stderr |
TempFileOnS3
| Property | Type | Description |
| ----------- | --------------------- | ----------------------------- |
| key | string | The S3 object key |
| eTag | string | ETag returned by S3 on upload |
| cleanup() | () => Promise<void> | Deletes the object from S3 |
Development
Environment variables
The integration tests upload real objects to S3. Copy .env.example to .env
and fill in the values before running tests.
| Variable | Description |
| ------------- | ---------------------------------------------------- |
| AWS_PROFILE | AWS credentials profile to use for local development |
| AWS_REGION | AWS region (e.g. us-east-1) |
| TEST_BUCKET | S3 bucket to use for integration tests |
For local development, set AWS_PROFILE and AWS_REGION to use a credentials
profile from ~/.aws/credentials. In CI, omit these and set AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY directly.
Running tests
npm test