Merge pull request #8 from ieedan/improved-documentation

feat: Add tests that can optionally ship with the code

.changeset/fast-students-heal.md

@@ -0,0 +1,5 @@
+---
+"ts-blocks": minor
+---
+
+Fix `init` command in CLI to allow for fully automated use.

.changeset/hip-pens-whisper.md

@@ -0,0 +1,5 @@
+---
+"ts-blocks": minor
+---
+
+Add tests to code and optionally allow including them when adding blocks

.github/workflows/ci.yml

@@ -12,8 +12,6 @@ jobs:
         steps:
             - uses: actions/checkout@v4
             - uses: pnpm/action-setup@v4
-              with:
-                  version: 9
             - uses: actions/setup-node@v4
               with:
                   node-version: '20'
@@ -24,5 +22,8 @@ jobs:
             - name: Lint
               run: pnpm check
 
+            - name: Lint
+              run: pnpm test
+
             - name: Build
               run: pnpm build

.github/workflows/publish.yaml

@@ -16,8 +16,6 @@ jobs:
         steps:
             - uses: actions/checkout@v4
             - uses: pnpm/action-setup@v4
-              with:
-                  version: 9
             - uses: actions/setup-node@v4
               with:
                   node-version: '20'

README.md

@@ -1,6 +1,6 @@
 # ts-blocks
 
-Well documented self owned building blocks for typescript applications.
+**Well documented**, **tested**, **self owned** building blocks for typescript applications.
 
 ```bash
 npx ts-blocks init
@@ -16,19 +16,56 @@ npx ts-blocks init
 
 ## Adding Blocks
 
+### Single
+
 ```bash
 npx ts-blocks add result
 
-┌  ts-block
+┌  ts-blocks
+│
+◇  Added result
+│
+└  All done!
+```
+
+### Multiple
+
+```bash
+npx ts-blocks add result array-sum
+
+┌  ts-blocks
 │
 ◇  Added result
 │
+◇  Added array-sum
+│
 └  All done!
 ```
 
 # Blocks
 
-All blocks can be found under `./blocks` and are shipped with documentation.
+All blocks can be found under `./blocks`.
+
+## Documentation
+
+Each block is well documented including examples of usage.
+
+## Tests
+
+Each block is tested using [vitest](https://vitest.dev/). By default we add these tests to your repository to disable this behavior configure `includeTests` in your `blocks.json` file.
+
+> [!NOTE]
+> If [vitest](https://vitest.dev/) isn't already installed in your project we will attempt to install it for you.
+
+```json
+{
+	"$schema": "https://unpkg.com/[email protected]/schema.json",
+	// ...
+	"includeTests": false // disable including tests
+}
+```
+
+# Development
 
 ## Adding New Blocks
 

blocks/types/result.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from 'vitest';
+import { Err, Ok, type Result } from './result';
+
+const failingFunction = <E>(err: E): Result<boolean, E> => Err(err);
+
+const passingFunction = <T>(val: T): Result<T, string> => Ok(val);
+
+test('Expect correct passed result', () => {
+	const [val, err] = passingFunction(true);
+
+	expect(val).toBe(true);
+	expect(err).toBe(null);
+});
+
+test('Expect correct failed result', () => {
+	const [val, err] = failingFunction('I failed!');
+
+	expect(val).toBe(null);
+	expect(err).toBe('I failed!');
+});

blocks/utilities/array-sum.test.ts

@@ -0,0 +1,14 @@
+import { expect, test } from 'vitest';
+import { arraySum } from './array-sum';
+
+test('Correct Sum Of All Elements', () => {
+	const total = arraySum([1, 2, 3, 4, 5], (num) => num);
+
+	expect(total).toBe(15);
+});
+
+test('Expect 0 on empty', () => {
+	const total = arraySum([], (num) => num);
+
+	expect(total).toBe(0);
+});

blocks/utilities/array-sum.ts

@@ -3,6 +3,14 @@
  * @param arr Array of items to be summed.
  * @param fn Summing function
  * @returns
+ *
+ * ## Examples
+ *
+ * ```ts
+ * const total = arraySum([1, 2, 3, 4, 5], (num) => num);
+ *
+ * console.log(total); // 15
+ * ```
  */
 const arraySum = <T>(arr: T[], fn: (item: T) => number): number => {
 	let total = 0;

blocks/utilities/array-to-map.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from 'vitest';
+import { arrayToMap } from './array-to-map';
+
+test('Correct returned map', () => {
+	const expected = new Map();
+	expected.set(0, 1);
+	expected.set(1, 2);
+	expected.set(2, 3);
+
+	const map = arrayToMap([1, 2, 3], (item, index) => [index, item]);
+
+	expect(map).toStrictEqual(expected);
+});
+
+test('Expect empty map', () => {
+	const expected = new Map();
+
+	const map = arrayToMap([], (item, index) => [index, item]);
+
+	expect(map).toStrictEqual(expected);
+});

blocks/utilities/array-to-map.ts

@@ -6,7 +6,7 @@
  *
  * ## Example
  * ```ts
- * const map = arrayToMap([5,4,3,2,1], (item, i) => [i, item]);
+ * const map = arrayToMap([5, 4, 3, 2, 1], (item, i) => [i, item]);
  *
  * console.log(map); // Map(5) { 0 => 5, 1 => 4, 2 => 3, 3 => 2, 4 => 1 }
  * ```

blocks/utilities/map-to-array.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from 'vitest';
+import { mapToArray } from './map-to-array';
+
+test('Correct Sum Of All Elements', () => {
+	const initialMap = new Map<number, number>();
+	initialMap.set(0, 1);
+	initialMap.set(1, 2);
+	initialMap.set(2, 3);
+
+	const arr = mapToArray(initialMap, (_, value) => value);
+
+	expect(arr).toStrictEqual([1, 2, 3]);
+});
+
+test('Returns empty array', () => {
+	const initialMap = new Map<number, number>();
+
+	const arr = mapToArray(initialMap, (_, value) => value);
+
+	expect(arr).toStrictEqual([]);
+});

blocks/utilities/map-to-array.ts

@@ -3,6 +3,15 @@
  * @param map Map to be entered into an array
  * @param fn A mapping function to transform each pair into an item
  * @returns
+ *
+ * ## Example
+ * ```ts
+ * console.log(map); // Map(5) { 0 => 5, 1 => 4, 2 => 3, 3 => 2, 4 => 1 }
+ *
+ * const arr = mapToArray(map, (_, value) => value);
+ *
+ * console.log(arr); // [5, 4, 3, 2, 1]
+ * ```
  */
 const mapToArray = <K, V, T>(map: Map<K, V>, fn: (key: K, value: V) => T): T[] => {
 	const items: T[] = [];

blocks/utilities/sleep.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from 'vitest';
+import { sleep } from './sleep';
+
+// This test takes a bit and its a very simple function so feel free to take it out
+test('Expect time elapsed', async () => {
+	const start = Date.now();
+
+	const duration = 25;
+
+	await sleep(duration);
+
+	const end = Date.now();
+
+	expect(end - start).toBeGreaterThanOrEqual(duration);
+});

blocks/utilities/truncate.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from 'vitest';
+import { truncate } from './truncate';
+
+test('Correct forward', () => {
+	const str = truncate('Hello World!', 5);
+
+	expect(str).toBe('Hello');
+});
+
+test('Correct reverse', () => {
+	const str = truncate('Hello World!', 6, { reverse: true });
+
+	expect(str).toBe('World!');
+});
+
+test('Correct forward with ending', () => {
+	const str = truncate('Hello World!', 5, { ending: '...' });
+
+	expect(str).toBe('Hello...');
+});
+
+test('Correct reverse with ending', () => {
+	const str = truncate('Hello World!', 6, { ending: '...', reverse: true });
+
+	expect(str).toBe('...World!');
+});

blocks/utilities/truncate.ts

@@ -11,11 +11,25 @@ type Options = {
  * @param maxLength Max length of the string
  * @param param2
  * @returns
+ *
+ * ## Examples
+ * ```ts
+ * const str = truncate('Hello World!', 5, { ending: '...' });
+ *
+ * console.log(str); // 'hello...'
+ * ```
+ *
+ * ### Reverse
+ * ```ts
+ * const str = truncate('Hello World!', 6, { ending: '...', reverse: true });
+ *
+ * console.log(str); // '...World!'
+ * ```
  */
 const truncate = (
 	str: string,
 	maxLength: number,
-	{ reverse = false, ending = '' }: Partial<Options>
+	{ reverse = false, ending = '' }: Partial<Options> = { reverse: false, ending: '' }
 ) => {
 	if (str.length <= maxLength) return str;
 

package.json

@@ -1,15 +1,13 @@
 {
 	"name": "ts-blocks",
-	"description": "A CLI to add ts-blocks code to your project.",
+	"description": "A CLI to blocks to your project.",
 	"version": "0.1.0",
+	"packageManager": "[email protected]",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/ieedan/ts-blocks"
 	},
-	"keywords": [
-		"changelog",
-		"date"
-	],
+	"keywords": ["changelog", "date"],
 	"author": "Aidan Bleser",
 	"license": "MIT",
 	"bugs": {
@@ -36,19 +34,23 @@
 		"lint": "biome lint --write",
 		"check": "pnpm biome check",
 		"ci:release": "unbuild && changeset publish",
-		"changeset": "changeset"
+		"changeset": "changeset",
+		"test": "vitest"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.8.3",
 		"@types/node": "^22.5.4",
 		"typescript": "^5.5.3",
-		"unbuild": "^2.0.0"
+		"unbuild": "^2.0.0",
+		"vitest": "^2.0.5"
 	},
 	"dependencies": {
 		"@changesets/cli": "^2.27.8",
 		"@clack/prompts": "^0.7.0",
 		"chalk": "^5.3.0",
 		"commander": "^12.1.0",
+		"execa": "^9.3.1",
+		"package-manager-detector": "^0.2.0",
 		"ts-morph": "^23.0.0",
 		"valibot": "^0.41.0"
 	}