Add backupActivityJSONAsFinished(…) to get a value of type FinishedBackupActivityJSON for finished backups.

Author: lgarron

README.md

@@ -9,9 +9,8 @@ This package is published as TypeScript source files. You will need to use a com
 ## API
 
 ````ts
-interface BackupActivityJSON {
+interface CommonBackupActivityJSONFields {
     aborted: boolean;
-    abortReason?: string;
     activityLogPath: string;
     backupPlanDbId: number;
     backupSetUUID: string;
@@ -23,12 +22,22 @@ interface BackupActivityJSON {
     dataVersion: number;
     errorCount: number;
     finishedTime: number;
-    message: string;
     subType: string;
     type: string;
     updatedTime: number;
     uuid: string;
 }
+interface InProgressBackupActivityJSON extends CommonBackupActivityJSONFields {
+    message: string;
+}
+interface FinishedBackupActivityJSON extends CommonBackupActivityJSONFields {
+    message: "Idle";
+    abortReason?: string;
+    totalBytes: 0;
+    totalFiles: 0;
+}
+type BackupActivityJSON = InProgressBackupActivityJSON & FinishedBackupActivityJSON;
+declare function backupActivityJSONAsFinished(backupActivityJSON: BackupActivityJSON): FinishedBackupActivityJSON | null;
 interface ArqBackupPlanConfig {
     backupSetUUID: string;
     name?: string;
@@ -52,5 +61,5 @@ declare function listBackupPlans(): Promise<ArqBackupPlan[]>;
 
 declare function setArqcCommandPath(newPath: string): void;
 
-export { ArqBackupPlan, type ArqBackupPlanConfig, type BackupActivityJSON, acceptLicenseAgreement, listBackupPlans, pauseBackups, resumeBackups, setArqcCommandPath };
+export { ArqBackupPlan, type ArqBackupPlanConfig, type BackupActivityJSON, type FinishedBackupActivityJSON, type InProgressBackupActivityJSON, acceptLicenseAgreement, backupActivityJSONAsFinished, listBackupPlans, pauseBackups, resumeBackups, setArqcCommandPath };
 ````

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "arqc",
-	"version": "0.3.2",
+	"version": "0.3.3",
 	"license": "MIT",
 	"author": "Lucas Garron",
 	"description": "A wrapper for the `arqc` command.",

src/ArqBackupPlan.ts

@@ -1,10 +1,9 @@
 import { $, type ShellPromise } from "bun";
 import { arqcCommand } from "./arqcCommand";
 
-export interface BackupActivityJSON {
+interface CommonBackupActivityJSONFields {
 	// Note: `"aborted"` may still be `false` for an aborted activity when the post-backup script is running.
 	aborted: boolean;
-	abortReason?: string;
 	activityLogPath: string;
 	backupPlanDbId: number;
 	backupSetUUID: string;
@@ -16,12 +15,45 @@ export interface BackupActivityJSON {
 	dataVersion: number;
 	errorCount: number;
 	finishedTime: number;
-	message: string;
 	subType: string;
 	type: string;
 	updatedTime: number;
 	uuid: string;
 }
+export interface InProgressBackupActivityJSON
+	extends CommonBackupActivityJSONFields {
+	// We'd use `Exclude<string, "Idle">`, but that is currently treated as `string` in TypeScript
+	message: string;
+}
+
+export interface FinishedBackupActivityJSON
+	extends CommonBackupActivityJSONFields {
+	message: "Idle";
+	abortReason?: string;
+	totalBytes: 0;
+	totalFiles: 0;
+}
+
+// Note: this should be `|` rather than `&`, but this is `&` due to TypeScript
+// limitations.
+//
+// This means that `if (backupActivityJSON.message === "Idle")` unfortunately
+// cannot type narrow the type of backupActivityJSON from `BackupActivityJSON`
+// to `FinishedBackupActivityJSON` inside the `if` block where the condition is
+// true. We provide the `backupActivityJSONAsFinished(…)` function for this.
+export type BackupActivityJSON = InProgressBackupActivityJSON &
+	FinishedBackupActivityJSON;
+
+// Applies a heuristic to return `FinishedBackupActivityJSON` if and only if the backup has finished.
+// Current heuristic: check if the `"message"` field is `"Idle"`.
+export function backupActivityJSONAsFinished(
+	backupActivityJSON: BackupActivityJSON,
+): FinishedBackupActivityJSON | null {
+	if (backupActivityJSON.message === "Idle") {
+		return backupActivityJSON as FinishedBackupActivityJSON;
+	}
+	return null;
+}
 
 export interface ArqBackupPlanConfig {
 	backupSetUUID: string;

src/index.ts

@@ -2,6 +2,9 @@ export {
 	type BackupActivityJSON,
 	type ArqBackupPlanConfig,
 	ArqBackupPlan,
+	backupActivityJSONAsFinished,
+	FinishedBackupActivityJSON,
+	InProgressBackupActivityJSON,
 } from "./ArqBackupPlan";
 export {
 	acceptLicenseAgreement,