dazscript-framework 1.0.30 → 1.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",

package/src/helpers/progress-helper.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const started: Array<{
+    info: string
+    totalSteps: number
+    isCancellable: boolean
+    showTimeElapsed: boolean
+}> = []
+const steps: number[] = []
+
+const installProgressGlobals = (cancelled = false): void => {
+    vi.stubGlobal('startProgress', (info: string, totalSteps: number, isCancellable: boolean, showTimeElapsed: boolean) => {
+        started.push({ info, totalSteps, isCancellable, showTimeElapsed })
+    })
+    vi.stubGlobal('stepProgress', (count = 1) => {
+        steps.push(count)
+    })
+    vi.stubGlobal('finishProgress', vi.fn())
+    vi.stubGlobal('progressIsCancelled', () => cancelled)
+    vi.stubGlobal('processEvents', vi.fn())
+}
+
+beforeEach(() => {
+    started.length = 0
+    steps.length = 0
+    vi.resetModules()
+})
+
+afterEach(() => {
+    vi.unstubAllGlobals()
+})
+
+describe('withProgress', () => {
+    it('starts progress, exposes a manual step handle, and finishes after callback returns', async () => {
+        installProgressGlobals()
+        const { withProgress } = await import('./progress-helper')
+
+        const result = withProgress('Manual Work', 4, (progress) => {
+            progress.step()
+            progress.step(2)
+            return 'done'
+        })
+
+        expect(result).toBe('done')
+        expect(started).toEqual([
+            {
+                info: 'Manual Work',
+                totalSteps: 4,
+                isCancellable: true,
+                showTimeElapsed: true,
+            },
+        ])
+        expect(steps).toEqual([1, 2])
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+
+    it('finishes progress when the callback throws', async () => {
+        installProgressGlobals()
+        const { withProgress } = await import('./progress-helper')
+
+        expect(() => withProgress('Manual Work', 2, () => {
+            throw new Error('failed phase')
+        })).toThrow('failed phase')
+
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+
+    it('reports cancellation consistently with cancellable progress', async () => {
+        installProgressGlobals(true)
+        const { withProgress } = await import('./progress-helper')
+
+        let callbackCancelled = false
+        withProgress('Manual Work', 2, (progress) => {
+            callbackCancelled = progress.isCancelled()
+            progress.step()
+        })
+
+        expect(callbackCancelled).toBe(true)
+        expect(processEvents).toHaveBeenCalledTimes(1)
+        expect(steps).toEqual([])
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe('progress', () => {
+    it('finishes progress when an item callback stops the loop', async () => {
+        installProgressGlobals()
+        const { progress } = await import('./progress-helper')
+
+        progress('Array Work', [1, 2, 3], (item: number) => item !== 2)
+
+        expect(steps).toEqual([1])
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+})

package/src/helpers/progress-helper.ts

@@ -1,5 +1,29 @@
 import { status } from '@dsf/common/log';
 
+export type ProgressOptions = {
+    isCancellable?: boolean
+    showTimeElapsed?: boolean
+    totalSteps?: number
+}
+
+export type ProgressHandle = {
+    step: (count?: number) => boolean
+    isCancelled: () => boolean
+}
+
+const defaultProgressOptions = (totalSteps: number, options?: ProgressOptions): Required<ProgressOptions> => ({
+    isCancellable: true,
+    showTimeElapsed: true,
+    totalSteps,
+    ...options
+})
+
+const reportInfo = (info: string | string[]): string => {
+    const infoMessage = Array.isArray(info) ? '' : info;
+    if (Array.isArray(info)) info.forEach(line => status(line));
+    return infoMessage;
+}
+
 /**
  * Displays a progress dialog to the user if one is not already being displayed and starts a progress tracking operation.
  * @param info The string to display in the progress dialog as the current description of the operation.
@@ -10,43 +34,79 @@ import { status } from '@dsf/common/log';
  * @param totalSteps The number of progress steps for the operation to be complete.
  */
 export const progress = <T>(info: string | string[], items: T[], callback: (item: T) => boolean | void,
-    options?: { isCancellable?: boolean, showTimeElapsed?: boolean, totalSteps?: number }) => {
+    options?: ProgressOptions) => {
 
-    options = {
-        isCancellable: true,
-        showTimeElapsed: true,
-        totalSteps: items.length,
-        ...options
-    };
+    const resolvedOptions = defaultProgressOptions(items.length, options);
 
-    const infoMessage = Array.isArray(info) ? '' : info;
-    startProgress(infoMessage, options.totalSteps, options.isCancellable, options.showTimeElapsed);
+    const infoMessage = reportInfo(info);
+    startProgress(infoMessage, resolvedOptions.totalSteps, resolvedOptions.isCancellable, resolvedOptions.showTimeElapsed);
 
-    if (Array.isArray(info)) info.forEach(line => status(line));
+    try {
+        // const total = Math.max(1, options.totalSteps ?? items.length);
+        // let lastQuarter = -1; // -1 so first boundary triggers
+
+        for (let i = 0; i < items.length; i++) {
+            // cancellation
+            if (resolvedOptions.isCancellable && progressIsCancelled()) {
+                processEvents(); // flush once on cancel
+                break;
+            }
+
+            // work
+            if (callback && callback(items[i]) === false) break;
 
-    // const total = Math.max(1, options.totalSteps ?? items.length);
-    // let lastQuarter = -1; // -1 so first boundary triggers
+            // progress
+            stepProgress(1);
 
-    for (let i = 0; i < items.length; i++) {
-        // cancellation
-        if (options.isCancellable && progressIsCancelled()) {
-            processEvents(); // flush once on cancel
-            break;
+            // 25/50/75/100 checkpoints
+            // const quarter = Math.floor(((i + 1) * 2) / total); // 0..4
+            // if (quarter > lastQuarter) {
+            //     processEvents();
+            //     lastQuarter = quarter;
+            // }
         }
+    }
+    finally {
+        finishProgress();
+    }
+}
 
-        // work
-        if (callback && callback(items[i]) === false) return;
+/**
+ * Starts a progress operation for multi-phase work that does not map to a single item array.
+ * Uses script-level cleanup for normal returns and catchable script exceptions; host crashes or native aborts can still bypass script cleanup.
+ * @param info The string to display in the progress dialog as the current description of the operation.
+ * @param totalSteps The number of progress steps for the operation to be complete.
+ * @param callback The function to run with a manual progress handle.
+ * @param options Progress dialog options consistent with the array-driven progress helper.
+ */
+export const withProgress = <T>(info: string | string[], totalSteps: number, callback: (progress: ProgressHandle) => T,
+    options?: Omit<ProgressOptions, 'totalSteps'>): T => {
 
-        // progress
-        stepProgress(1);
+    const resolvedOptions = defaultProgressOptions(totalSteps, options);
+    const infoMessage = reportInfo(info);
+    startProgress(infoMessage, resolvedOptions.totalSteps, resolvedOptions.isCancellable, resolvedOptions.showTimeElapsed);
 
-        // 25/50/75/100 checkpoints
-        // const quarter = Math.floor(((i + 1) * 2) / total); // 0..4
-        // if (quarter > lastQuarter) {
-        //     processEvents();
-        //     lastQuarter = quarter;
-        // }
+    let flushedCancellation = false;
+    const handle: ProgressHandle = {
+        isCancelled: () => {
+            const cancelled = resolvedOptions.isCancellable && Boolean(progressIsCancelled());
+            if (cancelled && !flushedCancellation) {
+                processEvents();
+                flushedCancellation = true;
+            }
+            return cancelled;
+        },
+        step: (count: number = 1) => {
+            if (handle.isCancelled()) return false;
+            stepProgress(count);
+            return true;
+        }
     }
 
-    finishProgress();
-}
+    try {
+        return callback(handle);
+    }
+    finally {
+        finishProgress();
+    }
+}