@wtasnorg/node-lib 0.0.5 → 0.0.7

package/docs/functions/createFindDirectories.md

@@ -0,0 +1,38 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../globals.md) / createFindDirectories
+
+# Function: createFindDirectories()
+
+> **createFindDirectories**(`deps`): (`root`, `options`) => `Promise`\<`string`[]\>
+
+Defined in: [find.ts:19](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L19)
+
+Factory that produces an async findDirectories function with
+injected filesystem dependencies for full testability.
+
+## Parameters
+
+### deps
+
+[`FileSystemDependencies`](../interfaces/FileSystemDependencies.md)
+
+## Returns
+
+> (`root`, `options`): `Promise`\<`string`[]\>
+
+### Parameters
+
+#### root
+
+`string`
+
+#### options
+
+[`FindDirectoriesOptions`](../interfaces/FindDirectoriesOptions.md) = `{}`
+
+### Returns
+
+`Promise`\<`string`[]\>

package/docs/functions/hello.md

@@ -8,7 +8,7 @@
 
 > **hello**(): `Promise`\<`string`\>
 
-Defined in: [hello.ts:6](https://github.com/wtasg/node-lib/blob/890fd5e866d9096470d56594a5788bf55e34bf7c/src/hello.ts#L6)
+Defined in: [hello.ts:6](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/hello.ts#L6)
 
 A sample function that should work to test if lib is installed correctly.
 

package/docs/functions/pojo.md

@@ -6,9 +6,9 @@
 
 # Function: pojo()
 
-> **pojo**\<`T`\>(`instance`): `Record`\<`string`, `any`\>
+> **pojo**\<`T`\>(`instance`): `Record`\<`string`, `unknown`\>
 
-Defined in: [pojo.ts:10](https://github.com/wtasg/node-lib/blob/890fd5e866d9096470d56594a5788bf55e34bf7c/src/pojo.ts#L10)
+Defined in: [pojo.ts:10](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/pojo.ts#L10)
 
 Convert a class instance into a plain JavaScript object.
 Copies only the instance's own enumerable data properties
@@ -30,6 +30,6 @@ A class instance to convert.
 
 ## Returns
 
-`Record`\<`string`, `any`\>
+`Record`\<`string`, `unknown`\>
 
 A plain JavaScript object containing only data fields.

package/docs/globals.md

@@ -4,7 +4,13 @@
 
 # @wtasnorg/node-lib
 
+## Interfaces
+
+- [FileSystemDependencies](interfaces/FileSystemDependencies.md)
+- [FindDirectoriesOptions](interfaces/FindDirectoriesOptions.md)
+
 ## Functions
 
+- [createFindDirectories](functions/createFindDirectories.md)
 - [hello](functions/hello.md)
 - [pojo](functions/pojo.md)

package/docs/interfaces/FileSystemDependencies.md

@@ -0,0 +1,51 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../globals.md) / FileSystemDependencies
+
+# Interface: FileSystemDependencies
+
+Defined in: [find.ts:3](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L3)
+
+## Properties
+
+### readdir()
+
+> **readdir**: (`path`, `opts`) => `Promise`\<`object`[]\>
+
+Defined in: [find.ts:4](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L4)
+
+#### Parameters
+
+##### path
+
+`string`
+
+##### opts
+
+###### withFileTypes
+
+`true`
+
+#### Returns
+
+`Promise`\<`object`[]\>
+
+***
+
+### stat()
+
+> **stat**: (`path`) => `Promise`\<\{ `isDirectory`: `boolean`; \}\>
+
+Defined in: [find.ts:5](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L5)
+
+#### Parameters
+
+##### path
+
+`string`
+
+#### Returns
+
+`Promise`\<\{ `isDirectory`: `boolean`; \}\>

package/docs/interfaces/FindDirectoriesOptions.md

@@ -0,0 +1,41 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../globals.md) / FindDirectoriesOptions
+
+# Interface: FindDirectoriesOptions
+
+Defined in: [find.ts:8](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L8)
+
+## Properties
+
+### allowlist?
+
+> `optional` **allowlist**: `string`[] \| (`absPath`, `name`) => `boolean`
+
+Defined in: [find.ts:11](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L11)
+
+***
+
+### blocklist?
+
+> `optional` **blocklist**: `string`[] \| (`absPath`, `name`) => `boolean`
+
+Defined in: [find.ts:12](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L12)
+
+***
+
+### followSymlinks?
+
+> `optional` **followSymlinks**: `boolean`
+
+Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L10)
+
+***
+
+### maxDepth?
+
+> `optional` **maxDepth**: `number`
+
+Defined in: [find.ts:9](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L9)

package/eslint.config.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import eslint from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import tseslint from "typescript-eslint";
+import prettier from "eslint-config-prettier";
+import globals from "globals";
+import stylistic from "@stylistic/eslint-plugin";
+
+export default defineConfig([
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    ...tseslint.configs.strict,
+    ...tseslint.configs.stylistic,
+    prettier,
+
+    {
+        languageOptions: {
+            globals: {
+                ...globals.node,
+            }
+        }
+    },
+
+    {
+        plugins: {
+            "@stylistic": stylistic
+        }
+    },
+
+    {
+        rules: {
+            "@typescript-eslint/no-unused-vars": [
+                "warn",
+                {
+                    argsIgnorePattern: "^_",
+                    varsIgnorePattern: "^_",
+                    caughtErrorsIgnorePattern: "^_"
+                }
+            ],
+
+            semi: ["error", "always"],
+            // "no-unused-vars": ["error", { varsIgnorePattern: "^[A-Z_]" }],
+            "@stylistic/quotes": ["error", "double"]
+        }
+    }
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtasnorg/node-lib",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "node library",
   "main": "src/index.js",
   "scripts": {
@@ -27,9 +27,15 @@
     "url": "git+https://github.com/wtasg/node-lib.git"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@stylistic/eslint-plugin": "^5.6.1",
     "@types/node": "^24.10.1",
-    "typedoc": "^0.28.14",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.5.0",
+    "typedoc": "^0.28.15",
     "typedoc-plugin-markdown": "^4.9.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1"
   }
 }

package/src/find.d.ts

@@ -0,0 +1,25 @@
+interface FileSystemDependencies {
+    readdir: (path: string, opts: {
+        withFileTypes: true;
+    }) => Promise<{
+        name: string;
+        isDirectory(): boolean;
+    }[]>;
+    stat: (path: string) => Promise<{
+        isDirectory(): boolean;
+    }>;
+}
+interface FindDirectoriesOptions {
+    maxDepth?: number;
+    followSymlinks?: boolean;
+    allowlist?: string[] | ((absPath: string, name: string) => boolean);
+    blocklist?: string[] | ((absPath: string, name: string) => boolean);
+}
+/**
+ * Factory that produces an async findDirectories function with
+ * injected filesystem dependencies for full testability.
+ */
+declare function createFindDirectories(deps: FileSystemDependencies): (root: string, options?: FindDirectoriesOptions) => Promise<string[]>;
+export { createFindDirectories, };
+export type { FileSystemDependencies, FindDirectoriesOptions, };
+//# sourceMappingURL=find.d.ts.map

package/src/find.js

@@ -0,0 +1,62 @@
+import { resolve, join } from "node:path";
+/**
+ * Factory that produces an async findDirectories function with
+ * injected filesystem dependencies for full testability.
+ */
+function createFindDirectories(deps) {
+    const { readdir } = deps;
+    return async function findDirectories(root, options = {}) {
+        const { maxDepth = 1, allowlist, blocklist } = options;
+        const absRoot = resolve(root);
+        const results = [];
+        function isAllowed(absPath, name) {
+            if (allowlist) {
+                if (Array.isArray(allowlist)) {
+                    if (!allowlist.includes(name))
+                        return false;
+                }
+                else if (!allowlist(absPath, name)) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        function isBlocked(absPath, name) {
+            if (blocklist) {
+                if (Array.isArray(blocklist)) {
+                    if (blocklist.includes(name))
+                        return true;
+                }
+                else if (blocklist(absPath, name)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        async function walk(currentPath, depth) {
+            if (depth > maxDepth)
+                return;
+            const entries = await readdir(currentPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const childPath = resolve(join(currentPath, entry.name));
+                const isDirectory = entry.isDirectory();
+                if (!isDirectory)
+                    continue;
+                if (isBlocked(childPath, entry.name))
+                    continue;
+                if (!isAllowed(childPath, entry.name))
+                    continue;
+                results.push(childPath);
+                if (depth < maxDepth) {
+                    await walk(childPath, depth + 1);
+                }
+            }
+        }
+        // match find(1): root is always included
+        results.push(absRoot);
+        await walk(absRoot, 1);
+        return results;
+    };
+}
+export { createFindDirectories, };
+//# sourceMappingURL=find.js.map

package/src/find.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=find.test.d.ts.map

package/src/find.test.js

@@ -0,0 +1,123 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createFindDirectories } from "./find.js";
+// Helper to build Dirent-like objects
+function dir(name) {
+    return { name, isDirectory: () => true };
+}
+function file(name) {
+    return { name, isDirectory: () => false };
+}
+test("find: findDirectories success", async () => {
+    // Minimal mock FS: /root contains one directory "a" and one file "b"
+    const mockFS = {
+        readdir: async (path) => {
+            if (path === "/root") {
+                return [
+                    { name: "a", isDirectory: () => true },
+                    { name: "b", isDirectory: () => false },
+                ];
+            }
+            return [];
+        },
+        stat: async (path) => ({
+            isDirectory: () => path === "/root" || path === "/root/a"
+        }),
+    };
+    const findDirectories = createFindDirectories(mockFS);
+    const result = await findDirectories("/root", { maxDepth: 1 });
+    assert.deepEqual(result, [
+        "/root",
+        "/root/a"
+    ]);
+});
+test("find: findDirectories symlink is NOT treated as a directory", async () => {
+    const mockFS = {
+        readdir: async (path) => {
+            if (path === "/root") {
+                return [
+                    {
+                        name: "linkToA",
+                        isDirectory: () => false
+                    }
+                ];
+            }
+            return [];
+        },
+        stat: async (path) => ({
+            isDirectory: () => path === "/root" // only root is a directory
+        }),
+        readlink: async () => {
+            throw new Error("readlink should not be called when symlink support is removed");
+        }
+    };
+    const findDirectories = createFindDirectories(mockFS);
+    const result = await findDirectories("/root", { maxDepth: 1 });
+    assert.deepEqual(result, [
+        "/root"
+    ]);
+});
+test("find: findDirectories at depth=2", async () => {
+    const deps = {
+        readdir: async (path) => {
+            switch (path) {
+                case "/root":
+                    return [dir("a"), dir("b"), file("ignore.txt")];
+                case "/root/a":
+                    return [dir("a1")];
+                case "/root/b":
+                    return [dir("b1")];
+                default:
+                    return [];
+            }
+        },
+        stat: async () => ({
+            isDirectory: () => false
+        })
+    };
+    const find = createFindDirectories(deps);
+    const result = await find("/root", { maxDepth: 2 });
+    assert.deepEqual(result.sort(), [
+        "/root",
+        "/root/a",
+        "/root/b",
+        "/root/a/a1",
+        "/root/b/b1"
+    ].sort());
+});
+test("find: findDirectories at depth=3", async () => {
+    const deps = {
+        readdir: async (path) => {
+            switch (path) {
+                case "/root":
+                    return [dir("a"), dir("b")];
+                case "/root/a":
+                    return [dir("a1")];
+                case "/root/b":
+                    return [dir("b1")];
+                case "/root/a/a1":
+                case "/root/b/b1":
+                    return [dir("c")];
+                case "/root/b/b1/c":
+                    return [dir("d"), file("fd")];
+                default:
+                    return [];
+            }
+        },
+        stat: async () => ({
+            isDirectory: () => false
+        })
+    };
+    const find = createFindDirectories(deps);
+    const result = await find("/root", { maxDepth: 3 });
+    assert.deepEqual(result.sort(), [
+        "/root",
+        "/root/a",
+        "/root/b",
+        "/root/a/a1",
+        "/root/a/a1/c",
+        "/root/b/b1",
+        "/root/b/b1/c",
+    ].sort());
+});
+//# sourceMappingURL=find.test.js.map

package/src/find.test.ts

@@ -0,0 +1,148 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createFindDirectories } from "./find.js";
+
+import type { FileSystemDependencies } from "./find.js";
+
+// Helper to build Dirent-like objects
+function dir(name: string): { name: string; isDirectory(): boolean } {
+    return { name, isDirectory: () => true };
+}
+function file(name: string): { name: string; isDirectory(): boolean } {
+    return { name, isDirectory: () => false };
+}
+
+test("find: findDirectories success", async () => {
+
+    // Minimal mock FS: /root contains one directory "a" and one file "b"
+    const mockFS = {
+        readdir: async (path: string) => {
+            if (path === "/root") {
+                return [
+                    { name: "a", isDirectory: () => true },
+                    { name: "b", isDirectory: () => false },
+                ];
+            }
+            return [];
+        },
+
+        stat: async (path: string) => ({
+            isDirectory: () => path === "/root" || path === "/root/a"
+        }),
+    };
+
+    const findDirectories = createFindDirectories(mockFS);
+
+    const result = await findDirectories("/root", { maxDepth: 1 });
+
+    assert.deepEqual(result, [
+        "/root",
+        "/root/a"
+    ]);
+});
+
+test("find: findDirectories symlink is NOT treated as a directory", async () => {
+
+    const mockFS = {
+        readdir: async (path: string) => {
+            if (path === "/root") {
+                return [
+                    {
+                        name: "linkToA",
+                        isDirectory: () => false
+                    }
+                ];
+            }
+            return [];
+        },
+
+        stat: async (path: string) => ({
+            isDirectory: () => path === "/root" // only root is a directory
+        }),
+
+        readlink: async () => {
+            throw new Error("readlink should not be called when symlink support is removed");
+        }
+    };
+
+    const findDirectories = createFindDirectories(mockFS);
+
+    const result = await findDirectories("/root", { maxDepth: 1 });
+
+    assert.deepEqual(result, [
+        "/root"
+    ]);
+});
+
+
+test("find: findDirectories at depth=2", async () => {
+    const deps: FileSystemDependencies = {
+        readdir: async (path: string): Promise<{ name: string; isDirectory(): boolean }[]> => {
+            switch (path) {
+                case "/root":
+                    return [dir("a"), dir("b"), file("ignore.txt")];
+                case "/root/a":
+                    return [dir("a1")];
+                case "/root/b":
+                    return [dir("b1")];
+                default:
+                    return [];
+            }
+        },
+        stat: async () => ({
+            isDirectory: () => false
+        })
+    };
+
+    const find = createFindDirectories(deps);
+
+    const result = await find("/root", { maxDepth: 2 });
+
+    assert.deepEqual(result.sort(), [
+        "/root",
+        "/root/a",
+        "/root/b",
+        "/root/a/a1",
+        "/root/b/b1"
+    ].sort());
+});
+
+test("find: findDirectories at depth=3", async () => {
+    const deps: FileSystemDependencies = {
+        readdir: async (path: string): Promise<{ name: string; isDirectory(): boolean }[]> => {
+            switch (path) {
+                case "/root":
+                    return [dir("a"), dir("b")];
+                case "/root/a":
+                    return [dir("a1")];
+                case "/root/b":
+                    return [dir("b1")];
+                case "/root/a/a1":
+                case "/root/b/b1":
+                    return [dir("c")];
+                case "/root/b/b1/c":
+                    return [dir("d"), file("fd")];
+                default:
+                    return [];
+            }
+        },
+        stat: async () => ({
+            isDirectory: () => false
+        })
+    };
+
+    const find = createFindDirectories(deps);
+
+    const result = await find("/root", { maxDepth: 3 });
+
+    assert.deepEqual(result.sort(), [
+        "/root",
+        "/root/a",
+        "/root/b",
+        "/root/a/a1",
+        "/root/a/a1/c",
+        "/root/b/b1",
+        "/root/b/b1/c",
+    ].sort());
+});