simple-backups 1.0.1 → 1.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Kartik
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Kartik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,6 +16,7 @@ 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
 - CPU & Memory Efficient
@@ -82,6 +83,19 @@ backups.on('error', (error) => {
 });
 ```
 
+## TypeScript
+SimpleBackups includes first-party TypeScript declarations. No separate `@types` package is required.
+
+```typescript
+import {
+    SimpleBackups,
+    type Backup,
+    type BackupAdapters,
+    type BackupWindow,
+    type SimpleBackupsOptions
+} from 'simple-backups';
+```
+
 ## SimpleBackups
 Below is a breakdown of the `SimpleBackups` class.
 
@@ -89,9 +103,9 @@ Below is a breakdown of the `SimpleBackups` class.
 * `new SimpleBackups(Object: options)`: Creates a new SimpleBackups instance with the provided `options`.
   * `options` [`Object`]: Constructor options for this instance.
     * `adapters` [`BackupAdapters`]: Adapter methods used to list, create and delete backups from the upstream storage mechanism.
-    * `windows` [`BackupWindow[]`]: Retention windows used to determine when backups should be created and which backups should be kept.
+    * `windows` [`BackupWindow[]`]: Retention windows used to determine the backup creation cadence and which backups should be kept.
   * **Note!** the SimpleBackups instance starts automatically when constructed.
-  * **Note!** the smallest `interval_ms` from the provided windows is used as the internal tick interval.
+  * **Note!** the smallest `interval_ms` from the provided windows is used as the backup creation cadence and internal tick interval. Larger windows retain backups created at that cadence instead of creating additional backups.
   * **Note!** all window `interval_ms` and `limit` values must be positive finite integers.
 
 #### SimpleBackups Properties
@@ -129,7 +143,7 @@ Below is a breakdown of the `SimpleBackups` class.
 ### BackupWindow Properties
 | Property  | Type     | Description                |
 | :-------- | :------- | :------------------------- |
-| `interval_ms`   | `Number`    | The interval at which this window's backups should be created in milliseconds.   |
+| `interval_ms`   | `Number`    | The width of each retention slot in this window in milliseconds.   |
 | `limit`   | `Number`    | The maximum number of backups to keep in this window.   |
 
 ### Backup Properties
@@ -139,7 +153,11 @@ Below is a breakdown of the `SimpleBackups` class.
 | `timestamp`   | `Number`    | The timestamp at which the backup was created in milliseconds.   |
 
 ## Retention Behavior
-SimpleBackups creates a new backup when no existing backup exists within the smallest configured backup window interval. During each tick, every backup window independently selects the best backup for each time slot and stale backups which are not selected by any window are deleted.
+SimpleBackups creates a new backup when no existing backup exists within the smallest configured backup window interval. During each tick, every backup window independently selects one backup for each populated retention slot and stale backups which are not selected by any window are deleted.
+
+Retention slots are fixed and derived only from each backup's timestamp using `Math.floor(timestamp / interval_ms)`. The earliest available backup in a slot is retained because it is closest to the start of that slot. A backup therefore remains in the same slot as time passes, allowing an hourly backup selected by a daily window to remain available for later daily slots instead of being replaced and deleted every hour.
+
+Slots are anchored to the Unix epoch. As a result, `day` in the example represents consecutive fixed 24-hour periods rather than local calendar days, and is not affected by time zones or daylight saving time.
 
 For example, the following windows will attempt to keep up to 24 hourly backups and up to 30 daily backups.
 
@@ -150,9 +168,18 @@ windows: [
 ]
 ```
 
+With uninterrupted hourly backups, this configuration converges to 24 populated hourly slots and 30 populated daily slots (the current slot plus the previous 29 slots). Because one backup can satisfy both windows at the same time, this normally represents 53 unique stored backups rather than 54.
+
 * **Note** backups can satisfy multiple windows at the same time.
 * **Note** SimpleBackups can only keep backups that exist and cannot create missed backups for time periods where the process was offline.
 * **Note** backups are selected by timestamp and not by filename or storage order.
 
+## Testing
+The test suite uses the built-in Node.js test runner and does not require any additional dependencies.
+
+```bash
+npm test
+```
+
 ## License
 [MIT](./LICENSE)

package/package.json

@@ -1,33 +1,41 @@
-{
-    "name": "simple-backups",
-    "version": "1.0.1",
-    "description": "Simple yet unopinionated zero-dependency package to easily setup automatic backups for any data source that persists to any storage mechanism.",
-    "type": "module",
-    "main": "./src/index.js",
-    "exports": {
-        ".": "./src/index.js"
-    },
-    "files": [
-        "src",
-        "README.md",
-        "LICENSE"
-    ],
-    "scripts": {
-        "test": "node --test"
-    },
-    "keywords": [
-        "backup",
-        "backups",
-        "storage",
-        "scheduler",
-        "nodejs",
-        "javascript",
-        "s3-bucket",
-        "unopinionated",
-        "zero-dependency"
-    ],
-    "license": "MIT",
-    "engines": {
-        "node": ">=20"
-    }
-}
+{
+    "name": "simple-backups",
+    "version": "1.1.1",
+    "description": "Simple yet unopinionated zero-dependency package to easily setup automatic backups for any data source that persists to any storage mechanism.",
+    "type": "module",
+    "main": "./src/index.js",
+    "types": "./src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./src/index.js",
+            "default": "./src/index.js"
+        }
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "test": "node --test && tsc --project tsconfig.json"
+    },
+    "keywords": [
+        "backup",
+        "backups",
+        "storage",
+        "scheduler",
+        "nodejs",
+        "javascript",
+        "s3-bucket",
+        "unopinionated",
+        "zero-dependency"
+    ],
+    "license": "MIT",
+    "engines": {
+        "node": ">=20"
+    },
+    "devDependencies": {
+        "typescript": "7.0.2"
+    }
+}

package/src/SimpleBackups.js

@@ -1,370 +1,381 @@
-import EventEmitter from 'node:events';
-
-/**
- * @typedef {Object} Backup
- * @property {string} id The unique identifier of the backup.
- * @property {number} timestamp The timestamp at which the backup was created (in milliseconds).
- */
-
-/**
- * @typedef {Object} BackupWindow
- * @property {number} interval_ms The interval at which this window's backups should be created (in milliseconds).
- * @property {number} limit The maximum number of backups to keep in this window.
- */
-
-/**
- * @typedef {Object} BackupAdapters
- * @property {function():Backup[]|Promise<Backup[]>} list This method **must** return an array of all backups from the upstream storage mechanism.
- * @property {function():Backup|Promise<Backup>} create This method **must** create a new backup and persist it to the upstream storage mechanism.
- * @property {function(Backup):boolean|Promise<boolean>} delete This method **must** attempt to delete the specified backups from the upstream storage mechanism and return a boolean indicating whether the operation was successful.
- */
-
-/**
- * @typedef {Object} SimpleBackupsOptions
- * @property {BackupAdapters} adapters The backup adapters to use.
- * @property {BackupWindow[]} windows The backup windows to use.
- */
-
-/**
- * @typedef {'create'|'delete'} SimpleBackupsBackupEvent
- */
-
-/**
- * @typedef {'error'} SimpleBackupsErrorEvent
- */
-
-/**
- * @typedef {(backup: Backup) => void} SimpleBackupsBackupListener
- */
-
-/**
- * @typedef {(error: Error) => void} SimpleBackupsErrorListener
- */
-
-export class SimpleBackups extends EventEmitter {
-    #destroyed = false;
-    #initialized = false;
-
-    /**
-     * The options for the SimpleBackups instance.
-     * @type {SimpleBackupsOptions}
-     */
-    #options;
-
-    /**
-     * The intervals for the backup windows.
-     * @type {Map<string, ReturnType<typeof setInterval>>}
-     */
-    #intervals = new Map();
-
-    /**
-     * The most recently listed backups from the upstream storage mechanism.
-     * @type {Backup[]}
-     */
-    #backups = [];
-
-    /**
-     * The smallest backup window interval.
-     * @type {number}
-     */
-    #smallest_interval_ms = Infinity;
-
-    /**
-     * Constructs a new SimpleBackups instance.
-     * @param {SimpleBackupsOptions} options
-     */
-    constructor(options) {
-        super();
-        this.#options = options;
-
-        // Enforce valid options
-        if (!Array.isArray(this.#options?.windows) || !this.#options?.windows?.length)
-            throw new Error('You must specify at least one backup window.');
-        if (typeof this.#options?.adapters?.list !== 'function')
-            throw new Error('You must specify a backup adapters list method.');
-        if (typeof this.#options?.adapters?.create !== 'function')
-            throw new Error('You must specify a backup adapters create method.');
-        if (typeof this.#options?.adapters?.delete !== 'function')
-            throw new Error('You must specify a backup adapters delete method.');
-
-        // Find the most frequent backup interval
-        for (const window of this.#options.windows) {
-            if (
-                Number.isNaN(window?.limit) ||
-                !Number.isFinite(window?.limit) ||
-                !Number.isInteger(window?.limit) ||
-                window?.limit <= 0
-            )
-                throw new Error('Backup windows must have a positive finite limit.');
-
-            if (
-                Number.isNaN(window?.interval_ms) ||
-                !Number.isFinite(window?.interval_ms) ||
-                !Number.isInteger(window?.interval_ms) ||
-                window?.interval_ms <= 0
-            )
-                throw new Error('Backup windows must have a positive finite interval_ms.');
-
-            if (window?.interval_ms <= this.#smallest_interval_ms) this.#smallest_interval_ms = window?.interval_ms;
-        }
-
-        // Create a tick interval with the smallest interval (aka. most precision)
-        this.#intervals.set(
-            'tick',
-            setInterval(() => this.__tick(), this.#smallest_interval_ms),
-        );
-        setTimeout(() => this.__tick(), 0); // Schedule an immediate tick
-    }
-
-    #tick_in_flight = false;
-    /**
-     * Ticks the SimpleBackups instance.
-     */
-    async __tick() {
-        if (this.#destroyed || this.#tick_in_flight) return;
-        this.#tick_in_flight = true;
-        try {
-            // If we have not initialized yet, then list all available backups from the upstream storage mechanism and cache them in memory
-            if (!this.#initialized) {
-                try {
-                    this.#backups = await this.#options.adapters.list();
-                    if (!Array.isArray(this.#backups))
-                        throw new Error('Backup adapters list method must return an array of backups.');
-
-                    // Validate the backups
-                    const seen_ids = new Set();
-                    for (const backup of this.#backups) {
-                        if (!backup?.id || typeof backup?.id !== 'string' || seen_ids.has(backup?.id))
-                            throw new Error(
-                                'Backup adapters list method must return an array of backups with unique IDs.',
-                            );
-                        seen_ids.add(backup.id);
-
-                        if (
-                            typeof backup?.timestamp !== 'number' ||
-                            !Number.isFinite(backup?.timestamp) ||
-                            backup?.timestamp < 0
-                        )
-                            throw new Error(
-                                'Backup adapters list method must return an array of backups with finite timestamps.',
-                            );
-                    }
-
-                    this.#backups.sort((a, b) => a.timestamp - b.timestamp); // Sort by ascending timestamp (oldest to newest)
-                    this.#initialized = true;
-                    if (this.#destroyed) return; // If the instance has been destroyed, then we should stop ticking
-                } catch (error) {
-                    this.emit('error', error); // Emit the error which may have occurred when listing the backups
-                    return;
-                }
-            }
-
-            let now = Date.now();
-            let should_create_backup = true; // Scan all existing backups to determine if we have a backup within the smallest interval slot to determine whether we need to create a new backup
-            for (let i = 0; i < this.#backups.length; i++) {
-                const backup = this.#backups[i];
-                const backup_age = now - backup.timestamp; // Measure the age of the backup (in milliseconds)
-                if (backup_age >= 0 && backup_age < this.#smallest_interval_ms) {
-                    should_create_backup = false; // We already have a backup within the smallest interval, so we don't need to create another one
-                    break;
-                }
-            }
-            if (should_create_backup) {
-                try {
-                    const backup = await this.#options.adapters.create(); // Create a new backup
-
-                    let already_exists = false; // Determine if a backup with the same ID already exists
-                    for (const _backup of this.#backups) {
-                        if (_backup.id === backup?.id) {
-                            already_exists = true;
-                            break;
-                        }
-                    }
-                    if (!backup?.id || typeof backup?.id !== 'string' || already_exists)
-                        throw new Error('Backup adapters create method must return a backup with a unique ID.');
-                    if (
-                        typeof backup.timestamp !== 'number' ||
-                        !Number.isFinite(backup.timestamp) ||
-                        backup.timestamp < 0
-                    )
-                        throw new Error('Backup adapters create method must return a backup with a finite timestamp.');
-
-                    this.#backups.push(backup); // Add the new backup to the list of backups in cache
-                    this.#backups.sort((a, b) => a.timestamp - b.timestamp); // Sort by ascending timestamp (oldest to newest)
-                    now = Date.now(); // Update the current time since we did a potentially asynchronous operation
-                    this.emit('create', backup); // Emit this backup as being created
-                    if (this.#destroyed) return; // If the instance has been destroyed, then we should stop ticking
-                } catch (error) {
-                    this.emit('error', error); // Emit the error which may have occurred when creating the backup
-                    return;
-                }
-            }
-
-            const keep_backups_ids = new Set(); // Determine which backup IDs to keep
-            for (let i = 0; i < this.#options.windows.length; i++) {
-                const best_by_slot = new Map();
-                const window = this.#options.windows[i];
-                for (let j = 0; j < this.#backups.length; j++) {
-                    const backup = this.#backups[j];
-                    const backup_age_ms = now - backup.timestamp;
-                    if (backup_age_ms < 0) continue; // Ignore future backups (this should not even be possible?)
-
-                    const slot = Math.floor(backup_age_ms / window.interval_ms); // Calculate the window slot for the backup
-                    if (slot >= window.limit) continue; // Ignore backups outside this window
-
-                    const target_timestamp = now - slot * window.interval_ms; // Calculate the target timestamp for this backup's ideal slot
-                    const distance_to_target_ms = Math.abs(backup.timestamp - target_timestamp); // Calculate the distance between the backup's timestamp and the target timestamp
-
-                    const candidate = best_by_slot.get(slot); // Measure and track the best or lowest distance to target timestamp for a given slot
-                    if (!candidate || distance_to_target_ms < candidate.distance_to_target_ms) {
-                        best_by_slot.set(slot, { backup, distance_to_target_ms });
-                    }
-                }
-
-                for (const [_, { backup }] of best_by_slot) keep_backups_ids.add(backup.id); // Add the remaining best backup slot candidates to the list of backups to keep
-            }
-
-            const stale_backups = []; // Determine which backups are stale and need to be deleted
-            const deleted_backups_ids = new Set(); // Determine which backup IDs have been deleted
-            for (let i = 0; i < this.#backups.length; i++) {
-                const backup = this.#backups[i];
-                if (!keep_backups_ids.has(backup.id)) stale_backups.push(backup);
-            }
-            for (const backup of stale_backups) {
-                try {
-                    const deleted = await this.#options.adapters.delete(backup); // Attempt to delete the stale backup
-                    if (deleted) {
-                        this.emit('delete', backup); // Emit this backup as being deleted
-                        deleted_backups_ids.add(backup.id); // If the deletion was successful, add the backup ID to the list of deleted backups
-                    }
-                    if (this.#destroyed) return; // If the instance has been destroyed, then we should stop ticking
-                } catch (error) {
-                    this.emit('error', error); // Emit the error which may have occurred when deleting the backup
-                }
-            }
-            if (deleted_backups_ids.size > 0) {
-                const remaining_backups = [];
-                for (let i = 0; i < this.#backups.length; i++) {
-                    const backup = this.#backups[i];
-                    if (!deleted_backups_ids.has(backup.id)) remaining_backups.push(backup);
-                }
-                this.#backups = remaining_backups; // Rebuild and overwrite the backups array with the remaining backups
-            }
-        } catch (error) {
-            this.emit('error', error);
-        } finally {
-            this.#tick_in_flight = false;
-        }
-    }
-
-    /**
-     * @overload
-     * @param {SimpleBackupsBackupEvent} event
-     * @param {SimpleBackupsBackupListener} listener
-     * @returns {this}
-     */
-    /**
-     * @overload
-     * @param {SimpleBackupsErrorEvent} event
-     * @param {SimpleBackupsErrorListener} listener
-     * @returns {this}
-     */
-    /**
-     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
-     * @param {SimpleBackupsBackupListener|SimpleBackupsErrorListener} listener
-     * @returns {this}
-     */
-    on(event, listener) {
-        return super.on(event, listener);
-    }
-
-    /**
-     * @overload
-     * @param {SimpleBackupsBackupEvent} event
-     * @param {SimpleBackupsBackupListener} listener
-     * @returns {this}
-     */
-    /**
-     * @overload
-     * @param {SimpleBackupsErrorEvent} event
-     * @param {SimpleBackupsErrorListener} listener
-     * @returns {this}
-     */
-    /**
-     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
-     * @param {SimpleBackupsBackupListener|SimpleBackupsErrorListener} listener
-     * @returns {this}
-     */
-    once(event, listener) {
-        return super.once(event, listener);
-    }
-
-    /**
-     * @overload
-     * @param {SimpleBackupsBackupEvent} event
-     * @param {SimpleBackupsBackupListener} listener
-     * @returns {this}
-     */
-    /**
-     * @overload
-     * @param {SimpleBackupsErrorEvent} event
-     * @param {SimpleBackupsErrorListener} listener
-     * @returns {this}
-     */
-    /**
-     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
-     * @param {SimpleBackupsBackupListener|SimpleBackupsErrorListener} listener
-     * @returns {this}
-     */
-    off(event, listener) {
-        return super.off(event, listener);
-    }
-
-    /**
-     * @overload
-     * @param {SimpleBackupsBackupEvent} event
-     * @param {Backup} backup
-     * @returns {boolean}
-     */
-    /**
-     * @overload
-     * @param {SimpleBackupsErrorEvent} event
-     * @param {Error} error
-     * @returns {boolean}
-     */
-    /**
-     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
-     * @param {Backup|Error} value
-     * @returns {boolean}
-     */
-    emit(event, value) {
-        return super.emit(event, value);
-    }
-
-    /**
-     * Destroys the SimpleBackups instance and stops all intervals.
-     */
-    destroy() {
-        if (this.#destroyed) return;
-        this.#destroyed = true; // Only destroy once
-
-        for (const [_, interval] of this.#intervals) clearInterval(interval);
-        this.#intervals.clear(); // Clear all intervals
-
-        super.removeAllListeners(); // Remove all event listeners (which effectively destroys the EventEmitter)
-    }
-
-    /**
-     * Returns the current list of backups (if in cache).
-     */
-    get backups() {
-        return [...this.#backups]; // Return a copy of the backups array
-    }
-
-    /**
-     * Whether the SimpleBackups instance has been destroyed.
-     */
-    get destroyed() {
-        return this.#destroyed;
-    }
-}
+import EventEmitter from 'node:events';
+
+/**
+ * @typedef {Object} Backup
+ * @property {string} id The unique identifier of the backup.
+ * @property {number} timestamp The timestamp at which the backup was created (in milliseconds).
+ */
+
+/**
+ * @typedef {Object} BackupWindow
+ * @property {number} interval_ms The width of each retention slot in this window (in milliseconds).
+ * @property {number} limit The maximum number of backups to keep in this window.
+ */
+
+/**
+ * @typedef {Object} BackupAdapters
+ * @property {function():Backup[]|Promise<Backup[]>} list This method **must** return an array of all backups from the upstream storage mechanism.
+ * @property {function():Backup|Promise<Backup>} create This method **must** create a new backup and persist it to the upstream storage mechanism.
+ * @property {function(Backup):boolean|Promise<boolean>} delete This method **must** attempt to delete the specified backups from the upstream storage mechanism and return a boolean indicating whether the operation was successful.
+ */
+
+/**
+ * @typedef {Object} SimpleBackupsOptions
+ * @property {BackupAdapters} adapters The backup adapters to use.
+ * @property {BackupWindow[]} windows The backup windows to use.
+ */
+
+/**
+ * @typedef {'create'|'delete'} SimpleBackupsBackupEvent
+ */
+
+/**
+ * @typedef {'error'} SimpleBackupsErrorEvent
+ */
+
+/**
+ * @typedef {(backup: Backup) => void} SimpleBackupsBackupListener
+ */
+
+/**
+ * @typedef {(error: Error) => void} SimpleBackupsErrorListener
+ */
+
+export class SimpleBackups extends EventEmitter {
+    #destroyed = false;
+    #initialized = false;
+
+    /**
+     * The options for the SimpleBackups instance.
+     * @type {SimpleBackupsOptions}
+     */
+    #options;
+
+    /**
+     * The intervals for the backup windows.
+     * @type {Map<string, ReturnType<typeof setInterval>>}
+     */
+    #intervals = new Map();
+
+    /**
+     * The most recently listed backups from the upstream storage mechanism.
+     * @type {Backup[]}
+     */
+    #backups = [];
+
+    /**
+     * The smallest backup window interval.
+     * @type {number}
+     */
+    #smallest_interval_ms = Infinity;
+
+    /**
+     * Constructs a new SimpleBackups instance.
+     * @param {SimpleBackupsOptions} options
+     */
+    constructor(options) {
+        super();
+        this.#options = options;
+
+        // Enforce valid options
+        if (!Array.isArray(this.#options?.windows) || !this.#options?.windows?.length)
+            throw new Error('You must specify at least one backup window.');
+        if (typeof this.#options?.adapters?.list !== 'function')
+            throw new Error('You must specify a backup adapters list method.');
+        if (typeof this.#options?.adapters?.create !== 'function')
+            throw new Error('You must specify a backup adapters create method.');
+        if (typeof this.#options?.adapters?.delete !== 'function')
+            throw new Error('You must specify a backup adapters delete method.');
+
+        // Find the most frequent backup interval
+        for (const window of this.#options.windows) {
+            if (
+                Number.isNaN(window?.limit) ||
+                !Number.isFinite(window?.limit) ||
+                !Number.isInteger(window?.limit) ||
+                window?.limit <= 0
+            )
+                throw new Error('Backup windows must have a positive finite limit.');
+
+            if (
+                Number.isNaN(window?.interval_ms) ||
+                !Number.isFinite(window?.interval_ms) ||
+                !Number.isInteger(window?.interval_ms) ||
+                window?.interval_ms <= 0
+            )
+                throw new Error('Backup windows must have a positive finite interval_ms.');
+
+            if (window?.interval_ms <= this.#smallest_interval_ms) this.#smallest_interval_ms = window?.interval_ms;
+        }
+
+        // Create a tick interval with the smallest interval (aka. most precision)
+        this.#intervals.set(
+            'tick',
+            setInterval(() => this.__tick(), this.#smallest_interval_ms),
+        );
+        setTimeout(() => this.__tick(), 0); // Schedule an immediate tick
+    }
+
+    #tick_in_flight = false;
+
+    /**
+     * Determines which backup IDs should be kept by the configured backup windows.
+     * @param {number} now The current timestamp (in milliseconds).
+     * @returns {Set<string>}
+     */
+    _get_keep_backups_ids(now) {
+        /** @type {Set<string>} */
+        const keep_backups_ids = new Set();
+        for (let i = 0; i < this.#options.windows.length; i++) {
+            /** @type {Map<number, Backup>} */
+            const best_by_slot = new Map();
+            const window = this.#options.windows[i];
+            const current_slot = Math.floor(now / window.interval_ms); // Anchor slots to timestamps instead of their ever-changing age
+            const oldest_slot = current_slot - window.limit + 1;
+
+            for (let j = 0; j < this.#backups.length; j++) {
+                const backup = this.#backups[j];
+                if (backup.timestamp > now) continue; // Ignore future backups (this should not even be possible?)
+
+                const slot = Math.floor(backup.timestamp / window.interval_ms); // A backup always belongs to the same slot as it ages
+                if (slot < oldest_slot || slot > current_slot) continue; // Ignore backups outside this window
+
+                // Backups are sorted from oldest to newest, so the first backup is the closest one to the start of this slot
+                if (!best_by_slot.has(slot)) best_by_slot.set(slot, backup);
+            }
+
+            for (const [_, backup] of best_by_slot) keep_backups_ids.add(backup.id); // Add the remaining best backup slot candidates to the list of backups to keep
+        }
+
+        return keep_backups_ids;
+    }
+
+    /**
+     * Ticks the SimpleBackups instance.
+     */
+    async __tick() {
+        if (this.#destroyed || this.#tick_in_flight) return;
+        this.#tick_in_flight = true;
+        try {
+            // If we have not initialized yet, then list all available backups from the upstream storage mechanism and cache them in memory
+            if (!this.#initialized) {
+                try {
+                    this.#backups = await this.#options.adapters.list();
+                    if (!Array.isArray(this.#backups))
+                        throw new Error('Backup adapters list method must return an array of backups.');
+
+                    // Validate the backups
+                    const seen_ids = new Set();
+                    for (const backup of this.#backups) {
+                        if (!backup?.id || typeof backup?.id !== 'string' || seen_ids.has(backup?.id))
+                            throw new Error(
+                                'Backup adapters list method must return an array of backups with unique IDs.',
+                            );
+                        seen_ids.add(backup.id);
+
+                        if (
+                            typeof backup?.timestamp !== 'number' ||
+                            !Number.isFinite(backup?.timestamp) ||
+                            backup?.timestamp < 0
+                        )
+                            throw new Error(
+                                'Backup adapters list method must return an array of backups with finite timestamps.',
+                            );
+                    }
+
+                    this.#backups.sort((a, b) => a.timestamp - b.timestamp); // Sort by ascending timestamp (oldest to newest)
+                    this.#initialized = true;
+                    if (this.#destroyed) return; // If the instance has been destroyed, then we should stop ticking
+                } catch (error) {
+                    this.emit('error', error); // Emit the error which may have occurred when listing the backups
+                    return;
+                }
+            }
+
+            let now = Date.now();
+            let should_create_backup = true; // Scan all existing backups to determine if we have a backup within the smallest interval slot to determine whether we need to create a new backup
+            for (let i = 0; i < this.#backups.length; i++) {
+                const backup = this.#backups[i];
+                const backup_age = now - backup.timestamp; // Measure the age of the backup (in milliseconds)
+                if (backup_age >= 0 && backup_age < this.#smallest_interval_ms) {
+                    should_create_backup = false; // We already have a backup within the smallest interval, so we don't need to create another one
+                    break;
+                }
+            }
+            if (should_create_backup) {
+                try {
+                    const backup = await this.#options.adapters.create(); // Create a new backup
+
+                    let already_exists = false; // Determine if a backup with the same ID already exists
+                    for (const _backup of this.#backups) {
+                        if (_backup.id === backup?.id) {
+                            already_exists = true;
+                            break;
+                        }
+                    }
+                    if (!backup?.id || typeof backup?.id !== 'string' || already_exists)
+                        throw new Error('Backup adapters create method must return a backup with a unique ID.');
+                    if (
+                        typeof backup.timestamp !== 'number' ||
+                        !Number.isFinite(backup.timestamp) ||
+                        backup.timestamp < 0
+                    )
+                        throw new Error('Backup adapters create method must return a backup with a finite timestamp.');
+
+                    this.#backups.push(backup); // Add the new backup to the list of backups in cache
+                    this.#backups.sort((a, b) => a.timestamp - b.timestamp); // Sort by ascending timestamp (oldest to newest)
+                    now = Date.now(); // Update the current time since we did a potentially asynchronous operation
+                    this.emit('create', backup); // Emit this backup as being created
+                    if (this.#destroyed) return; // If the instance has been destroyed, then we should stop ticking
+                } catch (error) {
+                    this.emit('error', error); // Emit the error which may have occurred when creating the backup
+                    return;
+                }
+            }
+
+            const keep_backups_ids = this._get_keep_backups_ids(now); // Determine which backup IDs to keep
+
+            const stale_backups = []; // Determine which backups are stale and need to be deleted
+            const deleted_backups_ids = new Set(); // Determine which backup IDs have been deleted
+            for (let i = 0; i < this.#backups.length; i++) {
+                const backup = this.#backups[i];
+                if (!keep_backups_ids.has(backup.id)) stale_backups.push(backup);
+            }
+            for (const backup of stale_backups) {
+                try {
+                    const deleted = await this.#options.adapters.delete(backup); // Attempt to delete the stale backup
+                    if (deleted) {
+                        this.emit('delete', backup); // Emit this backup as being deleted
+                        deleted_backups_ids.add(backup.id); // If the deletion was successful, add the backup ID to the list of deleted backups
+                    }
+                    if (this.#destroyed) return; // If the instance has been destroyed, then we should stop ticking
+                } catch (error) {
+                    this.emit('error', error); // Emit the error which may have occurred when deleting the backup
+                }
+            }
+            if (deleted_backups_ids.size > 0) {
+                const remaining_backups = [];
+                for (let i = 0; i < this.#backups.length; i++) {
+                    const backup = this.#backups[i];
+                    if (!deleted_backups_ids.has(backup.id)) remaining_backups.push(backup);
+                }
+                this.#backups = remaining_backups; // Rebuild and overwrite the backups array with the remaining backups
+            }
+        } catch (error) {
+            this.emit('error', error);
+        } finally {
+            this.#tick_in_flight = false;
+        }
+    }
+
+    /**
+     * @overload
+     * @param {SimpleBackupsBackupEvent} event
+     * @param {SimpleBackupsBackupListener} listener
+     * @returns {this}
+     */
+    /**
+     * @overload
+     * @param {SimpleBackupsErrorEvent} event
+     * @param {SimpleBackupsErrorListener} listener
+     * @returns {this}
+     */
+    /**
+     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
+     * @param {SimpleBackupsBackupListener|SimpleBackupsErrorListener} listener
+     * @returns {this}
+     */
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+
+    /**
+     * @overload
+     * @param {SimpleBackupsBackupEvent} event
+     * @param {SimpleBackupsBackupListener} listener
+     * @returns {this}
+     */
+    /**
+     * @overload
+     * @param {SimpleBackupsErrorEvent} event
+     * @param {SimpleBackupsErrorListener} listener
+     * @returns {this}
+     */
+    /**
+     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
+     * @param {SimpleBackupsBackupListener|SimpleBackupsErrorListener} listener
+     * @returns {this}
+     */
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+
+    /**
+     * @overload
+     * @param {SimpleBackupsBackupEvent} event
+     * @param {SimpleBackupsBackupListener} listener
+     * @returns {this}
+     */
+    /**
+     * @overload
+     * @param {SimpleBackupsErrorEvent} event
+     * @param {SimpleBackupsErrorListener} listener
+     * @returns {this}
+     */
+    /**
+     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
+     * @param {SimpleBackupsBackupListener|SimpleBackupsErrorListener} listener
+     * @returns {this}
+     */
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+
+    /**
+     * @overload
+     * @param {SimpleBackupsBackupEvent} event
+     * @param {Backup} backup
+     * @returns {boolean}
+     */
+    /**
+     * @overload
+     * @param {SimpleBackupsErrorEvent} event
+     * @param {Error} error
+     * @returns {boolean}
+     */
+    /**
+     * @param {SimpleBackupsBackupEvent|SimpleBackupsErrorEvent} event
+     * @param {Backup|Error} value
+     * @returns {boolean}
+     */
+    emit(event, value) {
+        return super.emit(event, value);
+    }
+
+    /**
+     * Destroys the SimpleBackups instance and stops all intervals.
+     */
+    destroy() {
+        if (this.#destroyed) return;
+        this.#destroyed = true; // Only destroy once
+
+        for (const [_, interval] of this.#intervals) clearInterval(interval);
+        this.#intervals.clear(); // Clear all intervals
+
+        super.removeAllListeners(); // Remove all event listeners (which effectively destroys the EventEmitter)
+    }
+
+    /**
+     * Returns the current list of backups (if in cache).
+     */
+    get backups() {
+        return [...this.#backups]; // Return a copy of the backups array
+    }
+
+    /**
+     * Whether the SimpleBackups instance has been destroyed.
+     */
+    get destroyed() {
+        return this.#destroyed;
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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;
+}

package/src/index.js

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