@hardlydifficult/collections 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/collections
 
-A TypeScript utility library providing array chunking and path depth grouping utilities for batched parallel processing.
+A TypeScript utility library for array chunking and path depth grouping.
 
 ## Installation
 
@@ -13,115 +13,81 @@ npm install @hardlydifficult/collections
 ```typescript
 import { chunk, groupByDepth } from "@hardlydifficult/collections";
 
-// Split an array into fixed-size chunks
-const result = chunk([1, 2, 3, 4, 5], 2);
-// → [[1, 2], [3, 4], [5]]
-
-// Group filesystem paths by directory depth (deepest-first)
-const paths = ["src/a/b", "src", "src/c"];
-const grouped = groupByDepth(paths);
-// → [{ depth: 2, paths: ["src/a/b"] }, { depth: 1, paths: ["src", "src/c"] }]
+// Split an array into chunks of fixed size
+const numbers = [1, 2, 3, 4, 5, 6, 7];
+console.log(chunk(numbers, 3));
+// Output: [[1, 2, 3], [4, 5, 6], [7]]
+
+// Group file paths by directory depth (deepest-first)
+const paths = ["src/components", "src", "src/components/Button"];
+console.log(groupByDepth(paths));
+// Output: [
+//   { depth: 2, paths: ["src/components", "src/components/Button"] },
+//   { depth: 1, paths: ["src"] }
+// ]
 ```
 
-Process items in parallel batches using chunking:
+## Array Chunking
 
-```typescript
-import { chunk } from "@hardlydifficult/collections";
+Splits arrays into subarrays of a specified maximum size.
 
-const items = [1, 2, 3, 4, 5, 6, 7];
-const batches = chunk(items, 3);
-// [[1, 2, 3], [4, 5, 6], [7]]
+### `chunk`
 
-for (const batch of batches) {
-  await Promise.allSettled(batch.map(processItem));
-}
-```
+Splits a readonly array into chunks of the given size.
 
-## Array Chunking (`chunk`)
+**Signature:**
+```typescript
+function chunk<T>(arr: readonly T[], size: number): T[][]
+```
 
-Splits an array into sub-arrays of a specified maximum size, preserving order.
+| Parameter | Type              | Description                   |
+|-----------|-------------------|-------------------------------|
+| `arr`     | `readonly T[]`    | The array to split            |
+| `size`    | `number`          | Maximum size of each chunk    |
 
+**Example:**
 ```typescript
 import { chunk } from "@hardlydifficult/collections";
 
-const numbers = [1, 2, 3, 4, 5, 6, 7];
-console.log(chunk(numbers, 3));
-// → [[1, 2, 3], [4, 5, 6], [7]]
-```
+const items = ["a", "b", "c", "d", "e"];
+console.log(chunk(items, 2));
+// Output: [["a", "b"], ["c", "d"], ["e"]]
 
-| Parameter | Type | Description |
-|---------|------|-------------|
-| `arr` | `readonly T[]` | Input array to split (supports readonly arrays) |
-| `size` | `number` | Maximum chunk size (must be ≥1) |
+console.log(chunk([1, 2, 3], 5));
+// Output: [[1, 2, 3]]
+```
 
-Returns `T[][]`: An array of chunks, where the last chunk may be smaller if the input length is not evenly divisible by `size`.
+## Path Depth Grouping
 
-**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)` → `[]`
+Groups file paths by their slash-separated depth, sorted deepest-first.
 
-## Path Depth Grouping (`groupByDepth`)
+### `groupByDepth`
 
-Groups filesystem paths by slash-delimited depth, sorted deepest-first to support bottom-up directory processing.
+Groups path strings by the number of `/`-separated segments, returning results in descending depth order.
 
+**Signature:**
 ```typescript
-import { groupByDepth } from "@hardlydifficult/collections";
-
-const paths = ["src/a/b", "src", "src/c", ""];
-const result = groupByDepth(paths);
-// → [
-//      { depth: 3, paths: ["src/a/b"] },
-//      { depth: 2, paths: ["src", "src/c"] },
-//      { depth: 0, paths: [""] }
-//    ]
+function groupByDepth(paths: readonly string[]): { depth: number; paths: string[] }[]
 ```
 
-| Parameter | Type | Description |
-|---------|------|-------------|
-| `paths` | `readonly string[]` | Array of path strings (slashes `/` delimit depth) |
-
-Returns `{ depth: number; paths: string[] }[]`: An array of depth groups sorted in descending order by depth. Empty string `""` is treated as depth `0` (root). Order of paths within each group is preserved from the input.
+| Parameter | Type               | Description                          |
+|-----------|--------------------|--------------------------------------|
+| `paths`   | `readonly string[]`| Array of path strings to group       |
 
-**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:**
-
-- **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([])` → `[]`
+Returns an array of objects with:
+- `depth`: number of slash-separated segments (empty string has depth 0)
+- `paths`: array of paths at that depth, in original order
 
+**Example:**
 ```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"] },
+const paths = ["a/b/c", "a/b", "a", "", "x/y"];
+console.log(groupByDepth(paths));
+// Output: [
+//   { depth: 3, paths: ["a/b/c"] },
+//   { depth: 2, paths: ["a/b", "x/y"] },
+//   { depth: 1, paths: ["a"] },
+//   { depth: 0, paths: [""] }
 // ]
-
-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.5",
+  "version": "1.0.7",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [