Merge pull request #33 from ieedan/add-stopwatch

feat: Add stopwatch + `typedoc` documentation

.changeset/short-pugs-fail.md

@@ -0,0 +1,5 @@
+---
+"ts-blocks": minor
+---
+
+Add stopwatch utility.

.changeset/strong-chicken-promise.md

@@ -0,0 +1,5 @@
+---
+"ts-blocks": patch
+---
+
+Now generates documentation with `typedoc` to be hosted on gh-pages.

.github/workflows/gh-pages.yml

@@ -0,0 +1,35 @@
+name: GitHub Pages
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+
+jobs:
+    deploy:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+        concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}
+        steps:
+            - uses: actions/checkout@v4
+            - uses: pnpm/action-setup@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: "20"
+
+            # we have to do this to load the typedoc plugins
+            - name: Install Dependencies
+              run: pnpm install
+
+            - name: Generate Documentation
+              run: pnpm docs:generate
+
+            - name: Deploy
+              uses: peaceiris/actions-gh-pages@v4
+              if: github.ref == 'refs/heads/main'
+              with:
+                  github_token: ${{ secrets.GITHUB_TOKEN }}
+                  publish_dir: ./docs

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 
-dist
+# out
+dist
+docs

blocks/utilities/sleep.ts

@@ -1,6 +1,6 @@
 /** Await this to pause execution until the duration has passed.
  *
- * @param duration The duration in ms until the sleep in over
+ * @param durationMs The duration in ms until the sleep in over
  * @returns
  *
  * ## Example
@@ -12,7 +12,7 @@
  * console.log(Date.now()) // 1725739229744
  * ```
  */
-const sleep = async (duration: number): Promise<void> =>
-	new Promise((res) => setTimeout(res, duration));
+const sleep = async (durationMs: number): Promise<void> =>
+	new Promise((res) => setTimeout(res, durationMs));
 
 export { sleep };

blocks/utilities/stopwatch.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'vitest';
+import { stopwatch } from './stopwatch';
+
+// we add this here so that we have a 0 dependency test
+const sleep = async (durationMs: number): Promise<void> =>
+	new Promise((res) => setTimeout(res, durationMs));
+
+test('Expect correct elapsed time', async () => {
+	const w = stopwatch();
+
+	w.start();
+
+	await sleep(50);
+
+	expect(w.elapsed()).toBeGreaterThanOrEqual(25);
+});
+
+test('Expect error while accessing before start', async () => {
+	const w = stopwatch();
+
+	expect(w.elapsed).toThrow();
+});
+
+test('Expect reset to reset', async () => {
+	const w = stopwatch();
+
+	w.start();
+
+	w.stop();
+
+	w.elapsed();
+
+	w.reset();
+
+	expect(w.elapsed).toThrow();
+});

blocks/utilities/stopwatch.ts

@@ -0,0 +1,124 @@
+/** Allows you to time operations. */
+export type Stopwatch = {
+	/** Start the stopwatch.
+	 *
+	 * @returns
+	 *
+	 * # Usage
+	 *
+	 * ```ts
+	 * const w = stopwatch();
+	 *
+	 * w.start(); // start counting
+	 * ```
+	 */
+	start: () => void;
+	/** Stop the stopwatch.
+	 *
+	 * @returns
+	 *
+	 * # Usage
+	 *
+	 * ```ts
+	 * const w = stopwatch();
+	 *
+	 * w.start();
+	 *
+	 * await sleep(1000);
+	 *
+	 * w.stop(); // stop counting
+	 *
+	 * await sleep(1000);
+	 *
+	 * console.log(w.elapsed()); // 1000
+	 * ```
+	 */
+	stop: () => void;
+	/** Reset the stopwatch.
+	 *
+	 * @returns
+	 *
+	 * # Usage
+	 *
+	 * ```ts
+	 * const w = stopwatch();
+	 *
+	 * w.start();
+	 *
+	 * w.stop();
+	 *
+	 * w.reset();
+	 *
+	 * w.elapsed(); // Error: "Call `.start()` first!"
+	 * ```
+	 */
+	reset: () => void;
+	/** Tries to get the elapsed ms. Throws if the Stopwatch has not been started.
+	 *
+	 * @returns
+	 *
+	 * # Usage
+	 *
+	 * ```ts
+	 * const w = watch();
+	 *
+	 * w.start();
+	 *
+	 * await sleep(1000);
+	 *
+	 * // you don't have to call stop before accessing `.elapsed()`
+	 * console.log(w.elapsed()); // 1000
+	 * ```
+	 */
+	elapsed: () => number;
+};
+
+/** Creates a new stopwatch instance.
+ *
+ * @returns
+ *
+ * # Usage
+ * ```ts
+ * const w = stopwatch();
+ *
+ * w.start();
+ *
+ * await sleep(1000);
+ *
+ * console.log(w.elapsed()); // 1000
+ * ```
+ */
+const stopwatch = (): Stopwatch => {
+	let startedAt: number | undefined = undefined;
+	let endedAt: number | undefined = undefined;
+
+	return {
+		start: () => {
+			startedAt = Date.now();
+		},
+		stop: () => {
+			endedAt = Date.now();
+		},
+		elapsed: () => {
+			// if this hasn't been defined its always an error in the users code
+			if (!startedAt) {
+				throw new Error('Call `.start()` first!');
+			}
+
+			let tempEndedAt = endedAt;
+
+			// if the user hasn't called stop just give them the current time
+			if (!tempEndedAt) {
+				tempEndedAt = Date.now();
+			}
+
+			return tempEndedAt - startedAt;
+		},
+		reset: () => {
+			endedAt = undefined;
+			startedAt = undefined;
+		},
+	};
+};
+
+export { stopwatch };

package.json

@@ -7,10 +7,7 @@
 		"type": "git",
 		"url": "git+https://github.com/ieedan/ts-blocks"
 	},
-	"keywords": [
-		"changelog",
-		"date"
-	],
+	"keywords": ["changelog", "date"],
 	"author": "Aidan Bleser",
 	"license": "MIT",
 	"bugs": {
@@ -38,24 +35,27 @@
 		"check": "pnpm biome check",
 		"ci:release": "unbuild && changeset publish",
 		"changeset": "changeset",
-		"test": "vitest"
+		"test": "vitest",
+		"docs:generate": "typedoc"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "1.9.1",
-		"@types/node": "^22.5.5",
-		"typescript": "^5.6.2",
+		"@biomejs/biome": "1.9.4",
+		"@types/node": "^22.7.6",
+		"typedoc": "^0.26.10",
+		"typescript": "^5.6.3",
 		"unbuild": "^2.0.0",
-		"vitest": "^2.1.1"
+		"vitest": "^2.1.3"
 	},
 	"dependencies": {
-		"@changesets/cli": "^2.27.8",
+		"@changesets/cli": "^2.27.9",
 		"@clack/prompts": "^0.7.0",
 		"chalk": "^5.3.0",
 		"commander": "^12.1.0",
-		"execa": "^9.3.1",
-		"package-manager-detector": "^0.2.0",
+		"execa": "^9.4.1",
+		"package-manager-detector": "^0.2.2",
 		"result": "^2.0.9",
-		"ts-morph": "^23.0.0",
-		"valibot": "^0.42.0"
+		"ts-morph": "^24.0.0",
+		"typedoc-material-theme": "^1.1.0",
+		"valibot": "^0.42.1"
 	}
 }