feat(async-stack): implement StackItem.progress

Author: vnphanquang

.changeset/healthy-cows-matter.md

@@ -0,0 +1,5 @@
+---
+'@svelte-put/async-stack': minor
+---
+
+expose `StackItem['progress']` as a number from 0 to 1, indicating how far until the timeout is reached, if any

packages/async-stack/src/stack-item.svelte.d.ts

@@ -19,6 +19,12 @@ export class StackItem<
 
 	constructor(config: StackItemInstanceConfig<string, UserComponent>);
 
+	/**
+	 * progress of the timeout, from 0 to 1
+	 * or null if item has no timeout.
+	 * This property is not reactive!
+	 */
+	readonly progress: number | null;
 	/** resume the stack item, if it has been paused */
 	resume: () => void;
 	/** pause the stack item, if it has a timeout */

packages/async-stack/src/stack-item.svelte.js

@@ -37,6 +37,19 @@ export class StackItem {
 		});
 	}
 
+	/**
+	 * @returns {number | null}
+	 */
+	get progress() {
+		if (this.config.timeout === 0) return null;
+		if (this.state === 'elapsing') {
+			const elapsedMs = Date.now() - this.#internals.lastStartedTime;
+			const actualMsToTimeout = this.#internals.msToTimeout - elapsedMs;
+			return (this.config.timeout - actualMsToTimeout) / this.config.timeout;
+		}
+		return (this.config.timeout - this.#internals.msToTimeout) / this.config.timeout;
+	}
+
 	resume = () => {
 		if (this.#internals.msToTimeout <= 0 || this.state === 'elapsing') return;
 		clearTimeout(this.#internals.timeoutId);

packages/async-stack/src/stack.svelte.js

@@ -124,17 +124,17 @@ export class Stack {
 			instanceConfig.id = idResolver(instanceConfig);
 		}
 
-		// STEP 4: preparing the `StackItem` instance
+		// STEP 3: preparing the `StackItem` instance
 		/** @type {StackItem<any>} */
 		let pushed = new StackItem(instanceConfig);
 		pushed.resolution.then(() => {
 			this.items = this.items.filter((n) => n.config.id !== pushed.config.id);
 		});
 
-		// STEP 5: push to store
+		// STEP 4: push to store
 		this.items.push(pushed);
 
-		// STEP 6: start timer if any
+		// STEP 5: start timer if any
 		pushed.resume();
 
 		return pushed;