@hardlydifficult/collections 1.0.0 → 1.0.1

package/README.md

@@ -8,11 +8,27 @@ Array and collection utilities for batched parallel processing.
 npm install @hardlydifficult/collections
 ```
 
-## API
+## Quick Start
+
+Split an array into chunks for parallel batch processing:
+
+```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));
+}
+```
+
+## Chunking Arrays
 
 ### `chunk<T>(arr: readonly T[], size: number): T[][]`
 
-Split an array into chunks of a given size. Useful for processing items in parallel batches with a concurrency limit.
+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.
 
 ```typescript
 import { chunk } from "@hardlydifficult/collections";
@@ -21,11 +37,14 @@ 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));
 }
 ```
 
+## 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.
@@ -34,7 +53,7 @@ Group `/`-separated path strings by their depth, sorted deepest-first. Useful fo
 import { groupByDepth } from "@hardlydifficult/collections";
 
 const dirs = ["src/services/summarize", "src/services", "src", "src/utils"];
-groupByDepth(dirs);
+const grouped = groupByDepth(dirs);
 // [
 //   { depth: 3, paths: ["src/services/summarize"] },
 //   { depth: 2, paths: ["src/services", "src/utils"] },
@@ -42,7 +61,19 @@ groupByDepth(dirs);
 // ]
 
 // Process directories bottom-up, parallelizing within each depth level
-for (const { paths: dirsAtDepth } of groupByDepth(dirs)) {
+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).
+
+```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: [""] },
+// ]
+```

package/package.json

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