@hardlydifficult/collections 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/collections
 
-Array and collection utilities for batched parallel processing.
+Array and path-manipulation utilities for batched parallel processing.
 
 ## Installation
 
@@ -10,7 +10,7 @@ npm install @hardlydifficult/collections
 
 ## Quick Start
 
-Split an array into chunks for parallel batch processing:
+Process items in parallel batches using chunking:
 
 ```typescript
 import { chunk } from "@hardlydifficult/collections";
@@ -28,7 +28,7 @@ for (const batch of batches) {
 
 ### `chunk<T>(arr: readonly T[], size: number): T[][]`
 
-Split an array into chunks of a given size. The final chunk may be smaller than the specified size. Useful for processing items in parallel batches with a concurrency limit.
+Split an array into subarrays of a specified maximum size. The final chunk may be smaller than the specified size. Useful for limiting concurrency in batched operations.
 
 ```typescript
 import { chunk } from "@hardlydifficult/collections";
@@ -37,17 +37,23 @@ const items = [1, 2, 3, 4, 5, 6, 7];
 const batches = chunk(items, 3);
 // [[1, 2, 3], [4, 5, 6], [7]]
 
-// Process in parallel batches
 for (const batch of batches) {
   await Promise.allSettled(batch.map(processItem));
 }
 ```
 
+#### Examples
+
+- **Full-sized chunks only**: `chunk([1,2,3,4,5,6], 2)` → `[[1,2], [3,4], [5,6]]`
+- **Final smaller chunk**: `chunk([1,2,3,4,5], 3)` → `[[1,2,3], [4,5]]`
+- **Single oversized chunk**: `chunk([1,2,3], 5)` → `[[1,2,3]]`
+- **Empty input**: `chunk([], 3)` → `[]`
+
 ## Grouping by Depth
 
 ### `groupByDepth(paths: readonly string[]): { depth: number; paths: string[] }[]`
 
-Group `/`-separated path strings by their depth, sorted deepest-first. Useful for bottom-up directory processing where children must be handled before parents.
+Group `/`-separated path strings by their directory depth (number of `/`-separated segments), sorted deepest-first. Useful for bottom-up directory processing where child directories must be handled before parents.
 
 ```typescript
 import { groupByDepth } from "@hardlydifficult/collections";
@@ -60,20 +66,34 @@ const grouped = groupByDepth(dirs);
 //   { depth: 1, paths: ["src"] },
 // ]
 
-// Process directories bottom-up, parallelizing within each depth level
 for (const { paths: dirsAtDepth } of grouped) {
   await Promise.allSettled(dirsAtDepth.map(summarizeDir));
 }
 ```
 
-Depth is calculated by counting `/`-separated segments. An empty string is treated as depth 0 (root).
+#### Depth Rules
 
-```typescript
-groupByDepth(["a/b/c", "a/b", "a", ""]);
-// [
-//   { depth: 3, paths: ["a/b/c"] },
-//   { depth: 2, paths: ["a/b"] },
-//   { depth: 1, paths: ["a"] },
-//   { depth: 0, paths: [""] },
-// ]
-```
+- An empty string (`""`) is treated as depth `0` (root)
+- Each `/` increases depth by 1
+- Paths are grouped by depth, and groups are sorted deepest-first
+
+#### Examples
+
+- **Mixed depths**:
+  ```typescript
+  groupByDepth(["a/b/c", "a/b", "a", ""]);
+  // [
+  //   { depth: 3, paths: ["a/b/c"] },
+  //   { depth: 2, paths: ["a/b"] },
+  //   { depth: 1, paths: ["a"] },
+  //   { depth: 0, paths: [""] },
+  // ]
+  ```
+
+- **Same depth grouping**:
+  ```typescript
+  groupByDepth(["x/y", "a/b", "m/n"]);
+  // [{ depth: 2, paths: ["x/y", "a/b", "m/n"] }]
+  ```
+
+- **Empty input**: `groupByDepth([])` → `[]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/collections",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [