@hardlydifficult/collections 1.0.2 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/collections
 
-Array and path-manipulation utilities for batched parallel processing.
+Array chunking and path depth grouping utilities for batched parallel processing.
 
 ## Installation
 
@@ -10,6 +10,23 @@ npm install @hardlydifficult/collections
 
 ## Quick Start
 
+```typescript
+import { chunk, groupByDepth } from "@hardlydifficult/collections";
+
+// Split an array into fixed-size chunks
+const items = [1, 2, 3, 4, 5];
+const chunks = chunk(items, 2);
+// => [[1, 2], [3, 4], [5]]
+
+// Group filesystem paths by directory depth (deepest first)
+const paths = ["src/app", "src", "src/utils/helper"];
+const grouped = groupByDepth(paths);
+// => [
+//      { depth: 3, paths: ["src/app"] },
+//      { depth: 1, paths: ["src"] }
+//    ]
+```
+
 Process items in parallel batches using chunking:
 
 ```typescript
@@ -24,60 +41,58 @@ for (const batch of batches) {
 }
 ```
 
-## Chunking Arrays
+## Array Utilities
 
-### `chunk<T>(arr: readonly T[], size: number): T[][]`
+### chunk
 
-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.
+Splits an array into sub-arrays of a specified maximum size.
 
 ```typescript
-import { chunk } from "@hardlydifficult/collections";
-
-const items = [1, 2, 3, 4, 5, 6, 7];
-const batches = chunk(items, 3);
-// [[1, 2, 3], [4, 5, 6], [7]]
-
-for (const batch of batches) {
-  await Promise.allSettled(batch.map(processItem));
-}
+chunk<T>(arr: readonly T[], size: number): T[][]
 ```
 
-#### Examples
+| Parameter | Type              | Description                         |
+|-----------|-------------------|-------------------------------------|
+| `arr`     | `readonly T[]`    | The array to split                  |
+| `size`    | `number`          | Maximum size of each sub-array      |
 
+The final chunk may be smaller than the specified size. Useful for limiting concurrency in batched operations.
+
+**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
+```typescript
+import { chunk } from "@hardlydifficult/collections";
 
-### `groupByDepth(paths: readonly string[]): { depth: number; paths: string[] }[]`
+const result = chunk([1, 2, 3, 4, 5, 6, 7], 3);
+// => [[1, 2, 3], [4, 5, 6], [7]]
+```
 
-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.
+## Path Utilities
 
-```typescript
-import { groupByDepth } from "@hardlydifficult/collections";
+### groupByDepth
 
-const dirs = ["src/services/summarize", "src/services", "src", "src/utils"];
-const grouped = groupByDepth(dirs);
-// [
-//   { depth: 3, paths: ["src/services/summarize"] },
-//   { depth: 2, paths: ["src/services", "src/utils"] },
-//   { depth: 1, paths: ["src"] },
-// ]
+Groups path strings by their slash-separated depth, sorted deepest-first for bottom-up directory processing.
 
-for (const { paths: dirsAtDepth } of grouped) {
-  await Promise.allSettled(dirsAtDepth.map(summarizeDir));
-}
+```typescript
+groupByDepth(paths: readonly string[]): { depth: number; paths: string[] }[]
 ```
 
-#### Depth Rules
+| Parameter | Type              | Description                        |
+|-----------|-------------------|------------------------------------|
+| `paths`   | `readonly string[]` | Filesystem paths to group         |
 
+The depth is determined by counting slash-separated segments (e.g., `"a/b/c"` has depth `3`). Empty string `""` is treated as depth `0`.
+
+**Rules:**
 - 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
+**Examples:**
 
 - **Mixed depths**:
   ```typescript
@@ -96,4 +111,20 @@ for (const { paths: dirsAtDepth } of grouped) {
   // [{ depth: 2, paths: ["x/y", "a/b", "m/n"] }]
   ```
 
-- **Empty input**: `groupByDepth([])` → `[]`
+- **Empty input**: `groupByDepth([])` → `[]`
+
+```typescript
+import { groupByDepth } from "@hardlydifficult/collections";
+
+const dirs = ["src/services/summarize", "src/services", "src", "src/utils"];
+const grouped = groupByDepth(dirs);
+// [
+//   { depth: 3, paths: ["src/services/summarize"] },
+//   { depth: 2, paths: ["src/services", "src/utils"] },
+//   { depth: 1, paths: ["src"] },
+// ]
+
+for (const { paths: dirsAtDepth } of grouped) {
+  await Promise.allSettled(dirsAtDepth.map(summarizeDir));
+}
+```

package/package.json

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