@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/{chunk-JQWGHSEH.mjs → chunk-NVSQ2T5Q.mjs}

@@ -1,8 +1,8 @@
 import { startCopyWithoutHoldingWriter } from './chunk-W67A4H2E.mjs';
-import { readLogPosition } from './chunk-E6IMX7RS.mjs';
-import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, assertDeadline, withinDeadline, reportQuietly } from './chunk-GYCEJNU4.mjs';
+import { readLogPosition } from './chunk-KJLNYOOL.mjs';
+import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, assertDeadline, withinDeadline, reportQuietly } from './chunk-R7GBXNTO.mjs';
 import { randomHex, invokeCallerCallback } from './chunk-QBBLSQHQ.mjs';
-import { BackupError, SirannonError } from './chunk-PBRXXISQ.mjs';
+import { BackupError, SirannonError } from './chunk-KINDFBQP.mjs';
 import { existsSync, mkdirSync, statSync, readdirSync, lstatSync, rmSync } from 'fs';
 import { resolve, dirname, join, basename, extname } from 'path';
 import { open, mkdtemp, rm } from 'fs/promises';
@@ -367,12 +367,12 @@ var BackupStreamHost = class _BackupStreamHost {
     this.statements = statements;
   }
   /**
-   * Opens a connection, loads the compiled extension into it, and compiles the
-   * statements one run needs.
+   * Opens a connection, loads the compiled extension into it, and prepares the
+   * statements that one backup needs.
    *
-   * @param openConnection - Opens the connection the statements run on.
-   * @param extensionPath - Absolute path of the compiled extension.
-   * @returns A host ready to open a stream.
+   * @param openConnection - Opens the connection that Sirannon runs the statements on.
+   * @param extensionPath - The absolute path of the compiled extension.
+   * @returns A host that is ready to open a stream.
    */
   static async start(openConnection, extensionPath) {
     const connection = await openConnection();
@@ -391,13 +391,13 @@ var BackupStreamHost = class _BackupStreamHost {
     }
   }
   /**
-   * Opens one stream and returns the identifier that names it in the
+   * Opens one stream and returns the identifier that appears in the
    * destination URI.
    *
-   * @param pieceBytes - Bytes one whole piece holds.
-   * @param maxQueuedPieces - Pieces the extension holds before it stops taking more.
-   * @param waitWhenFull - Whether the copy waits for the destination to catch up rather than queueing further pieces.
-   * @param stoppedTakerMicroseconds - How long the extension waits without a report from {@link BackupStreamHost.reportStillTaking} before it lets a piece through anyway.
+   * @param pieceBytes - The size of one whole piece, in bytes.
+   * @param maxQueuedPieces - The number of queued pieces at which the extension pauses the copy, when `waitWhenFull` is true.
+   * @param waitWhenFull - Whether the extension pauses the copy while the queue is full. When false, the extension queues every piece without a limit.
+   * @param stoppedTakerMicroseconds - The time in microseconds without a report from {@link BackupStreamHost.reportStillTaking} after which the extension lets one piece past the full queue.
    * @returns The identifier of the open stream.
    */
   async open(pieceBytes, maxQueuedPieces, waitWhenFull, stoppedTakerMicroseconds) {
@@ -413,65 +413,65 @@ var BackupStreamHost = class _BackupStreamHost {
     return streamId;
   }
   /**
-   * Takes the next whole piece the copy has produced.
+   * Takes the next whole piece of the copy from the queue.
    *
-   * @param streamId - Stream to take from.
-   * @returns The piece, or null where the copy has produced none since the last call.
+   * @param streamId - The stream to take from.
+   * @returns The piece, or null where the queue is empty.
    */
   async take(streamId) {
     const framed = await this.statements.selectNextPiece(streamId);
     return framed ? decodePiece(framed) : null;
   }
   /**
-   * Reports that this run is still taking pieces. SQLite holds the database's
-   * own lock for the whole of a copy step, so a run that stopped reporting
-   * would leave every other statement on that database waiting behind that
-   * step. The extension therefore lets one piece past its cap once these
-   * reports stop arriving.
+   * Tells the extension that Sirannon is still taking pieces. SQLite holds the
+   * lock of the database for a whole copy step, so if Sirannon stopped taking
+   * pieces while the copy waited on a full queue, every other statement on that
+   * database would wait behind that step. The extension therefore lets one
+   * piece past the full queue once these reports stop.
    *
-   * @param streamId - Stream to report against.
-   * @returns The pieces the extension is holding.
+   * @param streamId - The stream to report on.
+   * @returns The number of pieces in the queue.
    */
   reportStillTaking(streamId) {
     return this.statements.selectQueuedPieces(streamId);
   }
   /**
-   * Reports how many bytes of the copy have reached the extension.
+   * Returns the number of bytes that SQLite has written to a stream.
    *
-   * @param streamId - Stream to ask about.
-   * @returns Bytes SQLite has written to this stream.
+   * @param streamId - The stream to query.
+   * @returns The number of bytes that SQLite has written to this stream.
    */
   written(streamId) {
     return this.statements.selectBytesWritten(streamId);
   }
   /**
-   * Reports what stopped a stream, where anything did.
+   * Returns the failure that stopped a stream, if any.
    *
-   * @param streamId - Stream to ask about.
-   * @returns The failure the extension recorded, or null where it recorded none.
+   * @param streamId - The stream to query.
+   * @returns The failure that the extension recorded, or null where it recorded none.
    */
   failure(streamId) {
     return this.statements.selectFailure(streamId);
   }
   /**
-   * Closes the file to further writes and queues the pieces the extension was
-   * still holding, which are the first piece and the last one.
+   * Closes the file to further writes and queues the two pieces that the
+   * extension still holds, which are the first piece and the most recent one.
    *
-   * @param streamId - Stream to finish.
-   * @returns Bytes the finished file holds.
+   * @param streamId - The stream to finish.
+   * @returns The size of the finished file, in bytes.
    */
   finish(streamId) {
     return this.statements.selectFinishedBytes(streamId);
   }
   /**
-   * Releases a stream and everything it still held.
+   * Releases a stream and every piece that it still holds.
    *
-   * @param streamId - Stream to release.
+   * @param streamId - The stream to release.
    */
   async close(streamId) {
     await this.statements.selectReleasedBytes(streamId);
   }
-  /** Closes the connection the statements ran on. */
+  /** Closes the connection that Sirannon runs the statements on. */
   async stop() {
     await this.connection.close();
   }
@@ -705,13 +705,13 @@ var BackupManager = class {
     this.streaming = streaming;
   }
   /**
-   * Copies the database behind a connection to a file, while that database
-   * stays open for reads and writes.
+   * Copies the database that a connection has open to a file, while other
+   * callers go on reading from and writing to that database.
    *
-   * @param conn - Connection the copy runs on, which must be the connection that writes.
-   * @param destPath - Path to write the copy to. A file already there stops the copy.
-   * @param onFirstStep - Called once the copy's first step is done, so the caller can hand the writer back.
-   * @returns What the copy moved, how long it took, and how often it restarted.
+   * @param conn - The writer connection, which SQLite runs the copy on.
+   * @param destPath - The path to write the copy to. Sirannon refuses a path where a file already exists.
+   * @param onFirstStep - Called once after the first step of the copy, so that the caller can release the writer.
+   * @returns The pages that SQLite copies, the time that the copy takes, and the number of times that SQLite restarts it from page one.
    */
   async backup(conn, destPath, onFirstStep) {
     if (hasControlCharacters(destPath)) {
@@ -757,11 +757,11 @@ var BackupManager = class {
     };
   }
   /**
-   * Reads the size of the file a copy wrote.
+   * Reads the size of the file that a copy writes.
    *
-   * @param resolved - Absolute path of that file.
-   * @param destPath - Path the caller named, which the error states.
-   * @returns Bytes it holds.
+   * @param resolved - The absolute path of that file.
+   * @param destPath - The path that the caller names, which Sirannon quotes in any error.
+   * @returns The size of the file, in bytes.
    */
   fileBytes(resolved, destPath) {
     try {
@@ -771,17 +771,16 @@ var BackupManager = class {
     }
   }
   /**
-   * Runs the copy, and removes the file it was writing where that copy fails, so
-   * that a database missing its later pages never stays on disk as though the
-   * copy had finished. Sirannon would otherwise count that half-written file
-   * among the copies it keeps, and it would evict a whole copy to make room for
-   * one nothing can restore.
+   * Runs the copy and deletes its file when the copy fails, so that a partly
+   * written database never stays on disk. Rotation would otherwise count that
+   * file among the copies it keeps, and it would delete a complete copy to make
+   * room for it.
    *
-   * Sirannon stops waiting on a copy once the stall deadline passes, and SQLite
-   * keeps writing that copy to the file. A removal that raced a live copy would
-   * leave a truncated file in place, and on Windows it would fail outright.
-   * Sirannon therefore removes the file only once the copy stops, while the
-   * caller receives the failure at once and waits for none of that.
+   * When the stall deadline passes, Sirannon stops waiting on the copy while
+   * SQLite goes on writing to the file. Deleting the file under a live copy
+   * would leave a truncated file in place, and on Windows the delete would fail.
+   * Sirannon therefore deletes the file once the copy stops, although the caller
+   * receives the failure straight away.
    */
   async copyOrClearUp(conn, resolved, destPath, onFirstStep) {
     const abandoned = { copy: null };
@@ -1155,8 +1154,8 @@ var BackupScheduler = class {
   /**
    * Starts repeating backups and returns a function that stops them.
    *
-   * @param conn - Connection to the database being copied.
-   * @param request - Cron expression, destination directory, retention, and time zone, along with the callbacks and the database the copies come from.
+   * @param conn - The connection to the database that Sirannon copies.
+   * @param request - The cron expression, destination directory, retention, and time zone, with the callbacks and the details of the source database.
    * @returns A function that stops the schedule.
    */
   schedule(conn, request) {
@@ -1191,16 +1190,17 @@ var BackupScheduler = class {
     return this.run(conn, { ...request, cron, resolvedDir, maxFiles, timezone, onBackupTimeoutMs });
   }
   /**
-   * Works out the database and the file every report names. A caller may supply
-   * either of them, and Sirannon reads the file SQLite has open where the caller
-   * named none. Sirannon puts that question to the connection that writes, so it
-   * asks with nothing else holding the writer.
+   * Returns the database identifier and the source file that every report
+   * names. The caller can supply either of them. Where the caller names no
+   * source file, Sirannon reads the path of the file that SQLite has open, and
+   * it runs that query on the writer connection while no other operation holds
+   * the writer.
    *
-   * @param conn - Connection the copies come from.
-   * @param run - The schedule, which holds whichever of the two the caller named.
-   * @param runExclusive - Runs the question with nothing else holding the writer.
-   * @returns The database identifier and the path of the file the copies come from.
-   * @throws A `BACKUP_ERROR` where the caller named no source file and SQLite has none open.
+   * @param conn - The connection that Sirannon copies from.
+   * @param run - The schedule, which holds whichever of the two the caller names.
+   * @param runExclusive - Runs the query while no other operation holds the writer.
+   * @returns The database identifier and the path of the source file.
+   * @throws A `BACKUP_ERROR` where the caller names no source file and SQLite reports no file open on the connection.
    */
   async namesFor(conn, run, runExclusive) {
     if (run.databaseId !== void 0 && run.sourcePath !== void 0) {
@@ -1220,10 +1220,11 @@ var BackupScheduler = class {
     return { databaseId: run.databaseId ?? basename(sourcePath, extname(sourcePath)), sourcePath };
   }
   /**
-   * Passes one finished copy to the caller's completion callback, and stops
-   * waiting on that callback once its deadline passes.
+   * Passes the report of one finished copy to the completion callback of the
+   * caller, and fails with `BACKUP_ERROR` once the deadline of that callback
+   * passes. A deadline of zero waits for the callback without a limit.
    *
-   * @param report - What the copy produced.
+   * @param report - The report of the finished copy.
    * @param run - The schedule, which holds the callback and its deadline.
    */
   async handToCaller(report, run) {