TryGhost#1655 Database.backup() typings

Author: benallfree

lib/sqlite3.d.ts

@@ -139,6 +139,140 @@ export class Database extends events.EventEmitter {
     wait(callback?: (param: null) => void): this;
 
     interrupt(): void;
+
+    backup(path:string, callback?: ()=>void): Backup
+    backup(filename:string, destDbName:string, sourceDbName:string, filenameIsDest:boolean, callback?: ()=>void): Backup
+}
+
+/**
+ *
+ * A class for managing an sqlite3_backup object.  For consistency
+ * with other node-sqlite3 classes, it maintains an internal queue
+ * of calls.
+ *
+ * Intended usage from node:
+ *
+ *   var db = new sqlite3.Database('live.db');
+ *   var backup = db.backup('backup.db');
+ *   ...
+ *   // in event loop, move backup forward when we have time.
+ *   if (backup.idle) { backup.step(NPAGES); }
+ *   if (backup.completed) { ... success ... }
+ *   if (backup.failed)    { ... sadness ... }
+ *   // do other work in event loop - fine to modify live.db
+ *   ...
+ *
+ * Here is how sqlite's backup api is exposed:
+ *
+ *   - `sqlite3_backup_init`: This is implemented as
+ *     `db.backup(filename, [callback])` or
+ *     `db.backup(filename, destDbName, sourceDbName, filenameIsDest, [callback])`.
+ *   - `sqlite3_backup_step`: `backup.step(pages, [callback])`.
+ *   - `sqlite3_backup_finish`: `backup.finish([callback])`.
+ *   - `sqlite3_backup_remaining`: `backup.remaining`.
+ *   - `sqlite3_backup_pagecount`: `backup.pageCount`.
+ *
+ * There are the following read-only properties:
+ *
+ *   - `backup.completed` is set to `true` when the backup
+ *     succeeeds.
+ *   - `backup.failed` is set to `true` when the backup
+ *     has a fatal error.
+ *   - `backup.idle` is set to `true` when no operation
+ *     is currently in progress or queued for the backup.
+ *   - `backup.remaining` is an integer with the remaining
+ *     number of pages after the last call to `backup.step`
+ *     (-1 if `step` not yet called).
+ *   - `backup.pageCount` is an integer with the total number
+ *     of pages measured during the last call to `backup.step`
+ *     (-1 if `step` not yet called).
+ *
+ * There is the following writable property:
+ *
+ *   - `backup.retryErrors`: an array of sqlite3 error codes
+ *     that are treated as non-fatal - meaning, if they occur,
+ *     backup.failed is not set, and the backup may continue.
+ *     By default, this is `[sqlite3.BUSY, sqlite3.LOCKED]`.
+ *
+ * The `db.backup(filename, [callback])` shorthand is sufficient
+ * for making a backup of a database opened by node-sqlite3.  If
+ * using attached or temporary databases, or moving data in the
+ * opposite direction, the more complete (but daunting)
+ * `db.backup(filename, destDbName, sourceDbName, filenameIsDest, [callback])`
+ * signature is provided.
+ *
+ * A backup will finish automatically when it succeeds or a fatal
+ * error occurs, meaning it is not necessary to call `db.finish()`.
+ * By default, SQLITE_LOCKED and SQLITE_BUSY errors are not
+ * treated as failures, and the backup will continue if they
+ * occur.  The set of errors that are tolerated can be controlled
+ * by setting `backup.retryErrors`. To disable automatic
+ * finishing and stick strictly to sqlite's raw api, set
+ * `backup.retryErrors` to `[]`.  In that case, it is necessary
+ * to call `backup.finish()`.
+ *
+ * In the same way as node-sqlite3 databases and statements,
+ * backup methods can be called safely without callbacks, due
+ * to an internal call queue.  So for example this naive code
+ * will correctly back up a db, if there are no errors:
+ *
+ *   var backup = db.backup('backup.db');
+ *   backup.step(-1);
+ *   backup.finish();
+ *
+ */
+export class Backup extends events.EventEmitter {
+    /**
+     * `true` when the backup is idle and ready for `step()` to be called, `false` when busy.
+     */
+    idle: boolean
+
+    /**
+     * `true` when the backup has completed, `false` otherwise.
+     */
+    completed: boolean
+
+    /**
+     * `true` when the backup has failed, `false` otherwise.
+     */
+    failed: boolean
+
+    /**
+     * The number of remaining pages after the last call to `step()`, or `-1` if `step()` has never been called.
+     */
+    remaining: number
+
+    /**
+     * The total number of pages measured during the last call to `step()`, or `-1` if `step()` has never been called.
+     */
+    pageCount: number
+
+
+    /**
+     * An array of sqlite3 error codes that are treated as non-fatal - meaning, if they occur, `Backup.failed` is not set, and the backup may continue. By default, this is `[sqlite3.BUSY, sqlite3.LOCKED]`.
+     */
+    retryErrors: number[]
+
+    /**
+     * Asynchronously finalize the backup (required).
+     * 
+     * @param callback Called when the backup is finalized.
+     */
+    finish(callback?: ()=>void): void
+
+    /**
+     * Asynchronously perform an incremental segment of the backup.
+     * 
+     * Example:
+     * 
+     * ```
+     * backup.step(5)
+     * ```
+     * 
+     * @param nPages Number of pages to process (5 recommended).
+     * @param callback Called when the step is completed.
+     */
+    step(nPages: number,callback?: ()=>void): void
 }
 
 export function verbose(): sqlite3;
@@ -202,4 +336,4 @@ export interface sqlite3 {
     Statement: typeof Statement;
     Database: typeof Database;
     verbose(): this;
-}
+}