simple-backups 1.1.0 → 1.2.0

package/README.md

@@ -16,10 +16,12 @@ This package aims to simplify the task of automatically creating and pruning bac
 ## Features
 - Simple-to-use API
 - JSDoc Type Support
+- TypeScript Type Definitions
 - Automatic Backup Creation
 - Multi-Window Backup Retention
+- S3-Compatible Object Storage
 - CPU & Memory Efficient
-- No Dependencies
+- Dependency-Free Core
 
 ## Installation
 SimpleBackups can be installed using node package manager (`npm`)
@@ -82,6 +84,118 @@ backups.on('error', (error) => {
 });
 ```
 
+## TypeScript
+SimpleBackups includes first-party TypeScript declarations. No separate `@types` package is required.
+
+```typescript
+import {
+    SimpleBackups,
+    S3SimpleBackups,
+    type Backup,
+    type BackupAdapters,
+    type BackupWindow,
+    type S3SimpleBackupsOptions,
+    type SimpleBackupsOptions
+} from 'simple-backups';
+```
+
+## S3SimpleBackups
+`S3SimpleBackups` extends `SimpleBackups` and supplies its `list`, `create` and `delete` adapters using an S3-compatible object storage bucket. The user only needs to provide an asynchronous adapter which creates a local backup file and returns an object containing its path.
+
+The core `SimpleBackups` class remains dependency-free. S3 support uses the official modular [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) package as its only direct runtime dependency.
+
+The following example creates a MySQL dump in the operating system's temporary directory and returns an object containing its path and native S3 upload options. `S3SimpleBackups` determines the filename and file size, streams the file to Vultr Object Storage and removes the temporary file after the upload attempt.
+
+```javascript
+import { exec } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { S3SimpleBackups } from 'simple-backups';
+
+// Convert exec into a promise so the adapter can await mysqldump.
+const exec_async = promisify(exec);
+
+// Retention window intervals are expressed in milliseconds.
+const hour = 1000 * 60 * 60;
+const day = hour * 24;
+
+const backups = new S3SimpleBackups({
+    // Keep one backup per hour for 24 hours and one per day for 30 days.
+    windows: [
+        { interval_ms: hour, limit: 24 },
+        { interval_ms: day, limit: 30 }
+    ],
+
+    // The bucket name and connection properties used by the official AWS S3
+    // client. Vultr accepts us-east-1 as the request-signing region.
+    bucket: {
+        name: 'wuup-db-backups',
+        region: 'us-east-1',
+        endpoint: 'https://ewr1.vultrobjects.com',
+        credentials: {
+            accessKeyId: process.env.S3_ACCESS_KEY_ID,
+            secretAccessKey: process.env.S3_SECRET_ACCESS_KEY
+        }
+    },
+
+    // This is the only storage adapter the application needs to implement.
+    adapters: {
+        async create() {
+            // Include a timestamp so every temporary filename is unique.
+            const file_path = join(tmpdir(), `wuupdb_${Date.now()}.sql`);
+
+            // mysqldump runs as a child process. Awaiting it does not block the
+            // Node.js event loop; it only delays this backup until the dump exits.
+            await exec_async(`mysqldump wuupdb > "${file_path}"`);
+
+            // S3SimpleBackups opens, sizes, streams and removes this file. The
+            // options object is passed to the underlying S3 SDK as-is.
+            return {
+                path: file_path,
+                options: {
+                    ContentType: 'application/sql',
+                    StorageClass: 'STANDARD_IA',
+                    Metadata: {
+                        database: 'wuupdb'
+                    }
+                }
+            };
+        }
+    }
+});
+
+backups.on('create', (backup) => {
+    console.log('Created S3 backup:', backup.id);
+});
+
+backups.on('delete', (backup) => {
+    console.log('Deleted S3 backup:', backup.id);
+});
+
+backups.on('error', (error) => {
+    console.error(error);
+});
+```
+
+`S3SimpleBackups` uses the local backup file's basename as the S3 object key without adding or changing anything.
+
+```text
+wuupdb_1784230616789.sql
+```
+
+Every object in the configured bucket is treated as a backup managed by this instance. Backup timestamps are read from the standard S3 `LastModified` value returned by `ListObjectsV2`; timestamps are not encoded into object keys or custom metadata.
+
+S3 identifies an object by its key and does not assign a separate object ID. Uploading another file with the same name would overwrite the existing object unless bucket versioning is enabled. To protect retained backups consistently across S3-compatible providers, `S3SimpleBackups` rejects a filename which already exists. Backup creation adapters should therefore create unique filenames, commonly by including `Date.now()` as shown above.
+
+Files larger than the configured part size are streamed using bounded [S3 multipart uploads](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html). The default part size is 8 MiB and the default concurrency is four parts. These can be customized with `part_size` and `queue_size`. Memory use is bounded by the part size and upload concurrency rather than the total backup size.
+
+The creation adapter must return `{ path, options? }`. The optional `options` object is passed directly to the underlying S3 SDK, so it uses native SDK property names such as `ContentType`, `StorageClass`, `Metadata`, `ServerSideEncryption` and `SSEKMSKeyId`. `Bucket`, `Key`, `Body` and `ContentLength` are managed internally and cannot be overridden. Created local backup files are removed after every upload attempt.
+
+An existing `S3Client` can be provided using `client`. Injected clients are not destroyed by default; clients constructed from the `bucket` configuration are destroyed when the `S3SimpleBackups` instance is destroyed. This behavior can be overridden with `destroy_client`.
+
+The configured S3 identity needs permission to list the bucket and to create, upload, complete, abort and delete its objects.
+
 ## SimpleBackups
 Below is a breakdown of the `SimpleBackups` class.
 

package/package.json

@@ -1,11 +1,16 @@
 {
     "name": "simple-backups",
-    "version": "1.1.0",
-    "description": "Simple yet unopinionated zero-dependency package to easily setup automatic backups for any data source that persists to any storage mechanism.",
+    "version": "1.2.0",
+    "description": "Simple yet unopinionated package to automatically create and prune backups using custom adapters or S3-compatible storage.",
     "type": "module",
     "main": "./src/index.js",
+    "types": "./src/index.d.ts",
     "exports": {
-        ".": "./src/index.js"
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./src/index.js",
+            "default": "./src/index.js"
+        }
     },
     "files": [
         "src",
@@ -13,7 +18,7 @@
         "LICENSE"
     ],
     "scripts": {
-        "test": "node --test"
+        "test": "node --test && tsc --project tsconfig.json"
     },
     "keywords": [
         "backup",
@@ -24,10 +29,17 @@
         "javascript",
         "s3-bucket",
         "unopinionated",
-        "zero-dependency"
+        "s3-compatible"
     ],
     "license": "MIT",
     "engines": {
         "node": ">=20"
+    },
+    "dependencies": {
+        "@aws-sdk/client-s3": "3.1089.0"
+    },
+    "devDependencies": {
+        "@types/node": "20.19.43",
+        "typescript": "7.0.2"
     }
 }

package/src/S3SimpleBackups.js

@@ -0,0 +1,626 @@
+import { createReadStream } from 'node:fs';
+import { rm, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+
+import {
+    AbortMultipartUploadCommand,
+    CompleteMultipartUploadCommand,
+    CreateMultipartUploadCommand,
+    DeleteObjectCommand,
+    ListObjectsV2Command,
+    PutObjectCommand,
+    S3Client,
+    UploadPartCommand,
+} from '@aws-sdk/client-s3';
+
+import { SimpleBackups } from './SimpleBackups.js';
+
+const minimum_part_size = 1024 * 1024 * 5;
+const maximum_part_size = 1024 * 1024 * 1024 * 5;
+const maximum_parts = 10000;
+
+/**
+ * @typedef {Object} S3SimpleBackupsCreateResult
+ * @property {string} path The path of the backup file to upload.
+ * @property {S3SimpleBackupsUploadOptions} [options] S3 SDK options applied to the uploaded object.
+ */
+
+/**
+ * @typedef {Object} S3SimpleBackupsAdapters
+ * @property {() => Promise<S3SimpleBackupsCreateResult>} create Creates a backup file and returns its path and upload options.
+ */
+
+/**
+ * @typedef {Omit<import('@aws-sdk/client-s3').CreateMultipartUploadCommandInput, 'Bucket'|'Key'>} S3SimpleBackupsUploadOptions
+ */
+
+/**
+ * @typedef {import('@aws-sdk/client-s3').S3ClientConfig & {name: string}} S3SimpleBackupsBucket
+ */
+
+/**
+ * @typedef {Object} S3SimpleBackupsOptions
+ * @property {import('./SimpleBackups.js').BackupWindow[]} windows The backup windows to use.
+ * @property {S3SimpleBackupsBucket} bucket The S3 bucket and client configuration to use.
+ * @property {S3SimpleBackupsAdapters} adapters The backup creation adapter to use.
+ * @property {S3Client} [client] An existing S3 client to use.
+ * @property {boolean} [destroy_client] Whether the S3 client should be destroyed with this instance.
+ * @property {number} [part_size=8388608] The multipart upload part size in bytes.
+ * @property {number} [queue_size=4] The maximum number of parts to upload concurrently.
+ */
+
+/**
+ * Implements the S3 storage operations used by S3SimpleBackups.
+ */
+class S3BackupStorage {
+    /** @type {S3SimpleBackupsBucket} */
+    #bucket;
+
+    /** @type {S3Client|undefined} */
+    #client;
+
+    /** @type {S3SimpleBackupsAdapters} */
+    #adapters;
+
+    /** @type {Set<string>} */
+    #backup_keys = new Set();
+
+    /** @type {boolean} */
+    #destroy_client;
+
+    /** @type {number} */
+    #part_size;
+
+    /** @type {number} */
+    #queue_size;
+
+    /**
+     * @param {S3SimpleBackupsOptions} options
+     */
+    constructor(options) {
+        if (
+            !options?.bucket ||
+            typeof options.bucket !== 'object' ||
+            Array.isArray(options.bucket)
+        )
+            throw new Error('You must specify an S3 bucket configuration object.');
+        if (!options.bucket.name || typeof options.bucket.name !== 'string' || !options.bucket.name.trim())
+            throw new Error('You must specify a non-empty S3 bucket name.');
+        if (typeof options?.adapters?.create !== 'function')
+            throw new Error('You must specify an S3 backup adapters create method.');
+        if (options?.client !== undefined && typeof options.client?.send !== 'function')
+            throw new Error('S3 backup client must be an S3Client-compatible object.');
+        if (
+            options?.destroy_client !== undefined &&
+            typeof options.destroy_client !== 'boolean'
+        )
+            throw new Error('S3 backup destroy_client must be a boolean.');
+        if (
+            options?.part_size !== undefined &&
+            (!Number.isInteger(options.part_size) ||
+                options.part_size < minimum_part_size ||
+                options.part_size > maximum_part_size)
+        )
+            throw new Error(
+                `S3 backup part_size must be an integer between ${minimum_part_size} and ${maximum_part_size}.`,
+            );
+        if (
+            options?.queue_size !== undefined &&
+            (!Number.isInteger(options.queue_size) || options.queue_size <= 0)
+        )
+            throw new Error('S3 backup queue_size must be a positive integer.');
+        this.#adapters = options.adapters;
+        this.#bucket = options.bucket;
+        this.#client = options.client;
+        this.#destroy_client = options.destroy_client ?? !options.client;
+        this.#part_size = options.part_size ?? 1024 * 1024 * 8;
+        this.#queue_size = options.queue_size ?? 4;
+    }
+
+    /**
+     * Lists every backup stored in this instance's bucket.
+     * @returns {Promise<import('./SimpleBackups.js').Backup[]>}
+     */
+    async list() {
+        const backups = [];
+        let continuation_token;
+
+        do {
+            const response = await this.client.send(
+                new ListObjectsV2Command({
+                    Bucket: this.#bucket.name,
+                    ContinuationToken: continuation_token,
+                }),
+            );
+
+            for (const object of response.Contents || []) {
+                if (!object.Key) continue;
+                const timestamp = this._get_backup_timestamp(object.LastModified);
+                if (timestamp === undefined) continue;
+
+                backups.push({
+                    id: object.Key,
+                    timestamp,
+                });
+            }
+
+            continuation_token = response.IsTruncated ? response.NextContinuationToken : undefined;
+        } while (continuation_token);
+
+        this.#backup_keys = new Set(backups.map((backup) => backup.id));
+        return backups;
+    }
+
+    /**
+     * Creates a backup file using the user adapter and uploads it to S3.
+     * @returns {Promise<import('./SimpleBackups.js').Backup>}
+     */
+    async create() {
+        const source = await this.#adapters.create();
+        this._validate_create_result(source);
+
+        const file = await stat(source.path);
+        if (!file.isFile()) throw new Error('S3 backup path must reference a file.');
+
+        const timestamp = Date.now();
+        const key = this._get_backup_key(basename(source.path));
+        if (this.#backup_keys.has(key)) {
+            await rm(source.path, { force: true });
+            throw new Error(`An S3 backup named "${key}" already exists.`);
+        }
+        const upload_options = this._get_upload_options(source);
+
+        try {
+            await this._upload(key, source.path, file.size, upload_options);
+        } catch (upload_error) {
+            try {
+                await rm(source.path, { force: true });
+            } catch (cleanup_error) {
+                throw new AggregateError(
+                    [upload_error, cleanup_error],
+                    'S3 backup upload and cleanup both failed.',
+                );
+            }
+            throw upload_error;
+        }
+
+        try {
+            await rm(source.path, { force: true });
+        } catch (cleanup_error) {
+            try {
+                await this.client.send(
+                    new DeleteObjectCommand({
+                        Bucket: this.#bucket.name,
+                        Key: key,
+                        ExpectedBucketOwner: upload_options.ExpectedBucketOwner,
+                        RequestPayer: upload_options.RequestPayer,
+                    }),
+                );
+            } catch (rollback_error) {
+                throw new AggregateError(
+                    [cleanup_error, rollback_error],
+                    'S3 backup cleanup and upload rollback both failed.',
+                );
+            }
+            throw cleanup_error;
+        }
+
+        this.#backup_keys.add(key);
+        return {
+            id: key,
+            timestamp,
+        };
+    }
+
+    /**
+     * Deletes a backup from S3.
+     * @param {import('./SimpleBackups.js').Backup} backup
+     * @returns {Promise<boolean>}
+     */
+    async delete(backup) {
+        await this.client.send(
+            new DeleteObjectCommand({
+                Bucket: this.#bucket.name,
+                Key: backup.id,
+            }),
+        );
+        this.#backup_keys.delete(backup.id);
+        return true;
+    }
+
+    /**
+     * Destroys the internally managed S3 client when configured to do so.
+     */
+    destroy() {
+        if (this.#destroy_client) this.#client?.destroy();
+    }
+
+    /**
+     * Uploads a backup file using a single request or a bounded multipart upload.
+     * @param {string} key
+     * @param {string} path
+     * @param {number} content_length
+     * @param {S3SimpleBackupsUploadOptions} upload_options
+     */
+    async _upload(key, path, content_length, upload_options) {
+        if (content_length <= this.#part_size) {
+            await this._put_object(
+                key,
+                content_length ? createReadStream(path) : Buffer.alloc(0),
+                content_length,
+                upload_options,
+            );
+            return;
+        }
+
+        const required_part_size = Math.ceil(content_length / maximum_parts);
+        const part_size = Math.max(this.#part_size, required_part_size);
+        if (part_size > maximum_part_size)
+            throw new Error('S3 backup file exceeds the maximum multipart upload size.');
+
+        const iterator = this._get_parts(createReadStream(path), part_size)[Symbol.asyncIterator]();
+        const first = await iterator.next();
+        if (first.done) {
+            await this._put_object(key, Buffer.alloc(0), 0, upload_options);
+            return;
+        }
+        if (first.value.length < part_size) {
+            await this._put_object(key, first.value, first.value.length, upload_options);
+            return;
+        }
+
+        await this._multipart_upload(
+            key,
+            upload_options,
+            [first.value],
+            iterator,
+        );
+    }
+
+    /**
+     * Uploads a body using a single PutObject request.
+     * @param {string} key
+     * @param {NonNullable<import('@aws-sdk/client-s3').PutObjectCommandInput['Body']>} body
+     * @param {number} content_length
+     * @param {S3SimpleBackupsUploadOptions} upload_options
+     */
+    async _put_object(key, body, content_length, upload_options) {
+        await this.client.send(
+            new PutObjectCommand({
+                ...upload_options,
+                Bucket: this.#bucket.name,
+                Key: key,
+                Body: body,
+                ContentLength: content_length,
+            }),
+        );
+    }
+
+    /**
+     * Uploads buffered parts concurrently and completes or aborts the multipart upload.
+     * @param {string} key
+     * @param {S3SimpleBackupsUploadOptions} upload_options
+     * @param {Buffer[]} initial_parts
+     * @param {AsyncIterator<Buffer>} iterator
+     */
+    async _multipart_upload(key, upload_options, initial_parts, iterator) {
+        const create_response = await this.client.send(
+            new CreateMultipartUploadCommand({
+                ...upload_options,
+                Bucket: this.#bucket.name,
+                Key: key,
+            }),
+        );
+        if (!create_response.UploadId)
+            throw new Error('S3 did not return an upload ID for the multipart backup upload.');
+
+        const upload_id = create_response.UploadId;
+        const completed_parts = [];
+        const uploads = new Set();
+        let part_upload_error;
+        let part_number = 0;
+
+        const upload_part = (body) => {
+            part_number++;
+            if (part_number > maximum_parts)
+                throw new Error(`S3 backup uploads cannot exceed ${maximum_parts} parts.`);
+
+            const current_part_number = part_number;
+            const upload = this._upload_part(
+                key,
+                upload_id,
+                current_part_number,
+                body,
+                upload_options,
+            )
+                .then((completed_part) => {
+                    completed_parts[current_part_number - 1] = completed_part;
+                })
+                .catch((error) => {
+                    part_upload_error ??= error;
+                    throw error;
+                });
+
+            uploads.add(upload);
+            upload.then(
+                () => uploads.delete(upload),
+                () => uploads.delete(upload),
+            );
+        };
+
+        try {
+            for (const part of initial_parts) {
+                upload_part(part);
+                if (uploads.size >= this.#queue_size) await Promise.race(uploads);
+                if (part_upload_error) throw part_upload_error;
+            }
+
+            for (;;) {
+                const next = await iterator.next();
+                if (part_upload_error) throw part_upload_error;
+                if (next.done) break;
+
+                upload_part(next.value);
+                if (uploads.size >= this.#queue_size) await Promise.race(uploads);
+                if (part_upload_error) throw part_upload_error;
+            }
+
+            await Promise.all(uploads);
+            if (part_upload_error) throw part_upload_error;
+            await this.client.send(
+                new CompleteMultipartUploadCommand({
+                    Bucket: this.#bucket.name,
+                    Key: key,
+                    UploadId: upload_id,
+                    MultipartUpload: {
+                        Parts: completed_parts,
+                    },
+                    ExpectedBucketOwner: upload_options.ExpectedBucketOwner,
+                    RequestPayer: upload_options.RequestPayer,
+                }),
+            );
+        } catch (upload_error) {
+            await Promise.allSettled(uploads);
+            try {
+                await this.client.send(
+                    new AbortMultipartUploadCommand({
+                        Bucket: this.#bucket.name,
+                        Key: key,
+                        UploadId: upload_id,
+                        ExpectedBucketOwner: upload_options.ExpectedBucketOwner,
+                        RequestPayer: upload_options.RequestPayer,
+                    }),
+                );
+            } catch (abort_error) {
+                throw new AggregateError(
+                    [upload_error, abort_error],
+                    'S3 backup multipart upload and abort both failed.',
+                );
+            }
+            throw upload_error;
+        }
+    }
+
+    /**
+     * Uploads a single multipart body part.
+     * @param {string} key
+     * @param {string} upload_id
+     * @param {number} part_number
+     * @param {Buffer} body
+     * @param {S3SimpleBackupsUploadOptions} upload_options
+     * @returns {Promise<import('@aws-sdk/client-s3').CompletedPart>}
+     */
+    async _upload_part(key, upload_id, part_number, body, upload_options) {
+        const response = await this.client.send(
+            new UploadPartCommand({
+                Bucket: this.#bucket.name,
+                Key: key,
+                UploadId: upload_id,
+                PartNumber: part_number,
+                Body: body,
+                ContentLength: body.length,
+                ChecksumAlgorithm: upload_options.ChecksumAlgorithm,
+                ExpectedBucketOwner: upload_options.ExpectedBucketOwner,
+                RequestPayer: upload_options.RequestPayer,
+                SSECustomerAlgorithm: upload_options.SSECustomerAlgorithm,
+                SSECustomerKey: upload_options.SSECustomerKey,
+                SSECustomerKeyMD5: upload_options.SSECustomerKeyMD5,
+            }),
+        );
+        if (!response.ETag)
+            throw new Error(`S3 did not return an ETag for backup upload part ${part_number}.`);
+
+        const completed_part = {
+            ETag: response.ETag,
+            PartNumber: part_number,
+        };
+        for (const checksum of [
+            'ChecksumCRC32',
+            'ChecksumCRC32C',
+            'ChecksumCRC64NVME',
+            'ChecksumSHA1',
+            'ChecksumSHA256',
+        ]) {
+            if (response[checksum] !== undefined) completed_part[checksum] = response[checksum];
+        }
+        return completed_part;
+    }
+
+    /**
+     * Splits a backup file stream into fixed-size multipart buffers.
+     * @param {import('node:fs').ReadStream} body
+     * @param {number} part_size
+     * @returns {AsyncGenerator<Buffer>}
+     */
+    async *_get_parts(body, part_size) {
+        let buffers = [];
+        let buffered_bytes = 0;
+
+        for await (const chunk of body) {
+            const buffer = this._to_buffer(chunk);
+            let offset = 0;
+
+            while (offset < buffer.length) {
+                const available_bytes = part_size - buffered_bytes;
+                const bytes_to_copy = Math.min(available_bytes, buffer.length - offset);
+                buffers.push(buffer.subarray(offset, offset + bytes_to_copy));
+                buffered_bytes += bytes_to_copy;
+                offset += bytes_to_copy;
+
+                if (buffered_bytes === part_size) {
+                    yield Buffer.concat(buffers, part_size);
+                    buffers = [];
+                    buffered_bytes = 0;
+                }
+            }
+        }
+
+        if (buffered_bytes > 0) yield Buffer.concat(buffers, buffered_bytes);
+    }
+
+    /**
+     * Converts a streamed body chunk into a Buffer.
+     * @param {unknown} chunk
+     * @returns {Buffer}
+     */
+    _to_buffer(chunk) {
+        if (typeof chunk === 'string') return Buffer.from(chunk);
+        if (chunk instanceof Uint8Array)
+            return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+        if (chunk instanceof ArrayBuffer) return Buffer.from(chunk);
+        throw new Error('S3 backup streams must emit strings or byte arrays.');
+    }
+
+    /**
+     * Validates a backup creation adapter result.
+     * @param {S3SimpleBackupsCreateResult} source
+     */
+    _validate_create_result(source) {
+        if (!source || typeof source !== 'object' || Array.isArray(source))
+            throw new Error('S3 backup adapters create method must return an object.');
+        if (!source.path || typeof source.path !== 'string')
+            throw new Error('S3 backup adapters create method must return a non-empty path.');
+        if (
+            source.options !== undefined &&
+            (!source.options || typeof source.options !== 'object' || Array.isArray(source.options))
+        )
+            throw new Error('S3 backup options must be an object.');
+    }
+
+    /**
+     * Creates an object key using the backup filename.
+     * @param {string} filename
+     * @returns {string}
+     */
+    _get_backup_key(filename) {
+        return filename;
+    }
+
+    /**
+     * Gets a timestamp from an S3 modification date.
+     * @param {Date|undefined} last_modified
+     * @returns {number|undefined}
+     */
+    _get_backup_timestamp(last_modified) {
+        const timestamp = new Date(last_modified).getTime();
+        if (!Number.isFinite(timestamp) || timestamp < 0) return;
+        return timestamp;
+    }
+
+    /**
+     * Returns the protected S3 SDK options for a backup upload.
+     * @param {S3SimpleBackupsCreateResult} source
+     * @returns {S3SimpleBackupsUploadOptions}
+     */
+    _get_upload_options(source) {
+        return this._remove_protected_upload_options(source.options ?? {});
+    }
+
+    /**
+     * Removes request properties which are managed internally by this class.
+     * @param {S3SimpleBackupsUploadOptions} upload_options
+     * @returns {S3SimpleBackupsUploadOptions}
+     */
+    _remove_protected_upload_options(upload_options) {
+        const {
+            Body: _,
+            Bucket: __,
+            ContentLength: ___,
+            Key: ____,
+            ...remaining_upload_options
+        } = upload_options;
+        return remaining_upload_options;
+    }
+
+    /**
+     * Returns the configured S3 client, constructing it lazily when needed.
+     * @returns {S3Client}
+     */
+    get client() {
+        if (!this.#client) {
+            const { name: _, ...client_options } = this.#bucket;
+            this.#client = new S3Client({
+                requestChecksumCalculation: 'WHEN_REQUIRED',
+                responseChecksumValidation: 'WHEN_REQUIRED',
+                ...client_options,
+            });
+        }
+        return this.#client;
+    }
+
+    /**
+     * Returns the configured S3 bucket.
+     */
+    get bucket() {
+        return this.#bucket.name;
+    }
+}
+
+/**
+ * A SimpleBackups implementation which stores backups in any S3-compatible object storage bucket.
+ */
+export class S3SimpleBackups extends SimpleBackups {
+    /** @type {S3BackupStorage} */
+    #storage;
+
+    /**
+     * Constructs a new S3SimpleBackups instance.
+     * @param {S3SimpleBackupsOptions} options
+     */
+    constructor(options) {
+        const storage = new S3BackupStorage(options);
+        super({
+            windows: options?.windows,
+            adapters: {
+                list: () => storage.list(),
+                create: () => storage.create(),
+                delete: (backup) => storage.delete(backup),
+            },
+        });
+        this.#storage = storage;
+    }
+
+    /**
+     * Destroys this instance and its internally managed S3 client.
+     */
+    destroy() {
+        if (this.destroyed) return;
+        super.destroy();
+        this.#storage.destroy();
+    }
+
+    /**
+     * Returns the configured S3 client.
+     */
+    get client() {
+        return this.#storage.client;
+    }
+
+    /**
+     * Returns the configured S3 bucket.
+     */
+    get bucket() {
+        return this.#storage.bucket;
+    }
+
+}

package/src/index.d.ts

@@ -0,0 +1,157 @@
+import type {
+    CreateMultipartUploadCommandInput,
+    S3Client,
+    S3ClientConfig,
+} from '@aws-sdk/client-s3';
+
+/**
+ * A backup managed by SimpleBackups.
+ */
+export interface Backup {
+    /** The unique identifier of the backup. */
+    id: string;
+
+    /** The timestamp at which the backup was created (in milliseconds). */
+    timestamp: number;
+}
+
+/**
+ * A retention window used by SimpleBackups.
+ */
+export interface BackupWindow {
+    /** The width of each retention slot in this window (in milliseconds). */
+    interval_ms: number;
+
+    /** The maximum number of backups to keep in this window. */
+    limit: number;
+}
+
+/**
+ * Adapter methods used to persist backups in an upstream storage mechanism.
+ */
+export interface BackupAdapters {
+    /** Lists all backups from the upstream storage mechanism. */
+    list(): Backup[] | Promise<Backup[]>;
+
+    /** Creates and persists a new backup in the upstream storage mechanism. */
+    create(): Backup | Promise<Backup>;
+
+    /** Attempts to delete a backup and reports whether the deletion succeeded. */
+    delete(backup: Backup): boolean | Promise<boolean>;
+}
+
+/**
+ * Options used to construct a SimpleBackups instance.
+ */
+export interface SimpleBackupsOptions {
+    /** The backup adapters to use. */
+    adapters: BackupAdapters;
+
+    /** The backup retention windows to maintain. */
+    windows: BackupWindow[];
+}
+
+export type SimpleBackupsBackupEvent = 'create' | 'delete';
+export type SimpleBackupsErrorEvent = 'error';
+export type SimpleBackupsBackupListener = (backup: Backup) => void;
+export type SimpleBackupsErrorListener = (error: Error) => void;
+
+/**
+ * Automatically creates and prunes backups using the configured adapters and retention windows.
+ */
+export class SimpleBackups {
+    constructor(options: SimpleBackupsOptions);
+
+    on(event: SimpleBackupsBackupEvent, listener: SimpleBackupsBackupListener): this;
+    on(event: SimpleBackupsErrorEvent, listener: SimpleBackupsErrorListener): this;
+
+    once(event: SimpleBackupsBackupEvent, listener: SimpleBackupsBackupListener): this;
+    once(event: SimpleBackupsErrorEvent, listener: SimpleBackupsErrorListener): this;
+
+    off(event: SimpleBackupsBackupEvent, listener: SimpleBackupsBackupListener): this;
+    off(event: SimpleBackupsErrorEvent, listener: SimpleBackupsErrorListener): this;
+
+    emit(event: SimpleBackupsBackupEvent, backup: Backup): boolean;
+    emit(event: SimpleBackupsErrorEvent, error: Error): boolean;
+
+    /** Destroys this instance, stops its internal interval and removes its event listeners. */
+    destroy(): void;
+
+    /** The current cached backups, returned as a new array. */
+    readonly backups: Backup[];
+
+    /** Whether this instance has been destroyed. */
+    readonly destroyed: boolean;
+}
+
+/** S3 SDK upload options which can be applied without overriding internally managed fields. */
+export type S3SimpleBackupsUploadOptions = Omit<
+    CreateMultipartUploadCommandInput,
+    'Body' | 'Bucket' | 'ContentLength' | 'Key'
+>;
+
+/** The bucket name and native configuration used to construct the S3 client. */
+export type S3SimpleBackupsBucket = S3ClientConfig & {
+    /** The name of the S3 bucket in which backups should be stored. */
+    name: string;
+};
+
+/**
+ * A backup file and its optional S3 object properties.
+ */
+export interface S3SimpleBackupsCreateResult {
+    /** The path of the backup file to upload. */
+    path: string;
+
+    /** Native S3 SDK options applied to the uploaded object. */
+    options?: S3SimpleBackupsUploadOptions;
+}
+
+/**
+ * The backup creation adapter used by S3SimpleBackups.
+ */
+export interface S3SimpleBackupsAdapters {
+    /** Creates a backup file and returns its path and upload options. */
+    create(): Promise<S3SimpleBackupsCreateResult>;
+}
+
+/**
+ * Options used to construct an S3SimpleBackups instance.
+ */
+export interface S3SimpleBackupsOptions {
+    /** The backup retention windows to maintain. */
+    windows: BackupWindow[];
+
+    /** The S3 bucket and client configuration to use. */
+    bucket: S3SimpleBackupsBucket;
+
+    /** The backup creation adapter to use. */
+    adapters: S3SimpleBackupsAdapters;
+
+    /** An existing S3 client to use. */
+    client?: S3Client;
+
+    /** Whether the S3 client should be destroyed with this instance. */
+    destroy_client?: boolean;
+
+    /** The multipart upload part size in bytes. */
+    part_size?: number;
+
+    /** The maximum number of parts to upload concurrently. */
+    queue_size?: number;
+
+}
+
+/**
+ * A SimpleBackups implementation which stores backups in any S3-compatible object storage bucket.
+ */
+export class S3SimpleBackups extends SimpleBackups {
+    constructor(options: S3SimpleBackupsOptions);
+
+    /** The configured S3 client. */
+    readonly client: S3Client;
+
+    /** The configured S3 bucket. */
+    readonly bucket: string;
+
+}

package/src/index.js

@@ -1,3 +1,4 @@
 import { SimpleBackups } from './SimpleBackups.js';
+import { S3SimpleBackups } from './S3SimpleBackups.js';
 
-export { SimpleBackups };
+export { S3SimpleBackups, SimpleBackups };