@wtasnorg/node-lib 0.0.6 → 0.0.8

package/docs/functions/createFindDirectories.md

@@ -2,13 +2,13 @@
 
 ***
 
-[@wtasnorg/node-lib](../globals.md) / createFindDirectories
+[@wtasnorg/node-lib](../README.md) / createFindDirectories
 
 # Function: createFindDirectories()
 
 > **createFindDirectories**(`deps`): (`root`, `options`) => `Promise`\<`string`[]\>
 
-Defined in: [find.ts:19](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L19)
+Defined in: [find.ts:19](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L19)
 
 Factory that produces an async findDirectories function with
 injected filesystem dependencies for full testability.

package/docs/functions/hello.md

@@ -2,13 +2,13 @@
 
 ***
 
-[@wtasnorg/node-lib](../globals.md) / hello
+[@wtasnorg/node-lib](../README.md) / hello
 
 # Function: hello()
 
 > **hello**(): `Promise`\<`string`\>
 
-Defined in: [hello.ts:6](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/hello.ts#L6)
+Defined in: [hello.ts:6](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/hello.ts#L6)
 
 A sample function that should work to test if lib is installed correctly.
 

package/docs/functions/parseUserAgent.md

@@ -0,0 +1,42 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../README.md) / parseUserAgent
+
+# Function: parseUserAgent()
+
+> **parseUserAgent**(`ua`): [`UserAgentInfo`](../interfaces/UserAgentInfo.md)
+
+Defined in: [user-agent.ts:48](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L48)
+
+Parses a user-agent string into a UserAgentInfo object.
+
+## Parameters
+
+### ua
+
+`string`
+
+The user-agent string to parse.
+
+## Returns
+
+[`UserAgentInfo`](../interfaces/UserAgentInfo.md)
+
+An object containing the extracted information.
+
+## Examples
+
+```typescript
+// Success Example (Chrome on Windows)
+const ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+const info = parseUserAgent(ua);
+// { browser: "Chrome", version: "120.0.0.0", os: "Windows", device: "Desktop", engine: "Blink" }
+```
+
+```typescript
+// Error/Fallback Example (Empty string)
+const info = parseUserAgent("");
+// { browser: "Other", version: "0", os: "Other", device: "Desktop", engine: "Other" }
+```

package/docs/functions/pojo.md

@@ -2,13 +2,13 @@
 
 ***
 
-[@wtasnorg/node-lib](../globals.md) / pojo
+[@wtasnorg/node-lib](../README.md) / pojo
 
 # 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/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/pojo.ts#L10)
+Defined in: [pojo.ts:10](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/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/interfaces/FileSystemDependencies.md

@@ -2,27 +2,27 @@
 
 ***
 
-[@wtasnorg/node-lib](../globals.md) / FileSystemDependencies
+[@wtasnorg/node-lib](../README.md) / FileSystemDependencies
 
 # Interface: FileSystemDependencies
 
-Defined in: [find.ts:3](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L3)
+Defined in: [find.ts:3](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L3)
 
 ## Properties
 
 ### readdir()
 
-> **readdir**: (`path`, `opts`) => `Promise`\<`object`[]\>
+> **readdir**: (`_path`, `_opts`) => `Promise`\<`object`[]\>
 
-Defined in: [find.ts:4](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L4)
+Defined in: [find.ts:4](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L4)
 
 #### Parameters
 
-##### path
+##### \_path
 
 `string`
 
-##### opts
+##### \_opts
 
 ###### withFileTypes
 
@@ -36,13 +36,13 @@ Defined in: [find.ts:4](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc345
 
 ### stat()
 
-> **stat**: (`path`) => `Promise`\<\{ `isDirectory`: `boolean`; \}\>
+> **stat**: (`_path`) => `Promise`\<\{ `isDirectory`: `boolean`; \}\>
 
-Defined in: [find.ts:5](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L5)
+Defined in: [find.ts:5](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L5)
 
 #### Parameters
 
-##### path
+##### \_path
 
 `string`
 

package/docs/interfaces/FindDirectoriesOptions.md

@@ -2,27 +2,27 @@
 
 ***
 
-[@wtasnorg/node-lib](../globals.md) / FindDirectoriesOptions
+[@wtasnorg/node-lib](../README.md) / FindDirectoriesOptions
 
 # Interface: FindDirectoriesOptions
 
-Defined in: [find.ts:8](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L8)
+Defined in: [find.ts:8](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L8)
 
 ## Properties
 
 ### allowlist?
 
-> `optional` **allowlist**: `string`[] \| (`absPath`, `name`) => `boolean`
+> `optional` **allowlist**: `string`[] \| (`_absPath`, `_name`) => `boolean`
 
-Defined in: [find.ts:11](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L11)
+Defined in: [find.ts:11](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L11)
 
 ***
 
 ### blocklist?
 
-> `optional` **blocklist**: `string`[] \| (`absPath`, `name`) => `boolean`
+> `optional` **blocklist**: `string`[] \| (`_absPath`, `_name`) => `boolean`
 
-Defined in: [find.ts:12](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L12)
+Defined in: [find.ts:12](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L12)
 
 ***
 
@@ -30,7 +30,7 @@ Defined in: [find.ts:12](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc34
 
 > `optional` **followSymlinks**: `boolean`
 
-Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L10)
+Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L10)
 
 ***
 
@@ -38,4 +38,4 @@ Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc34
 
 > `optional` **maxDepth**: `number`
 
-Defined in: [find.ts:9](https://github.com/wtasg/node-lib/blob/01d2e57d5a7dbc3451098355b40ab686f5320efe/src/find.ts#L9)
+Defined in: [find.ts:9](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/find.ts#L9)

package/docs/interfaces/UserAgentInfo.md

@@ -0,0 +1,61 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../README.md) / UserAgentInfo
+
+# Interface: UserAgentInfo
+
+Defined in: [user-agent.ts:4](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L4)
+
+Information extracted from a user-agent string.
+
+## Properties
+
+### browser
+
+> **browser**: `string`
+
+Defined in: [user-agent.ts:8](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L8)
+
+Browser name (e.g., Chrome, Firefox, Safari, Edge, Opera, Other).
+
+***
+
+### device
+
+> **device**: `string`
+
+Defined in: [user-agent.ts:20](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L20)
+
+Device type (e.g., Mobile, Tablet, Desktop, Other).
+
+***
+
+### engine
+
+> **engine**: `string`
+
+Defined in: [user-agent.ts:24](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L24)
+
+Rendering engine (e.g., Blink, WebKit, Gecko, Presto, Other).
+
+***
+
+### os
+
+> **os**: `string`
+
+Defined in: [user-agent.ts:16](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L16)
+
+Operating system (e.g., Windows, macOS, Linux, iOS, Android, Other).
+
+***
+
+### version
+
+> **version**: `string`
+
+Defined in: [user-agent.ts:12](https://github.com/wtasg/node-lib/blob/ac07f7b7be8233cfd945908394ac10daf671e6a9/src/user-agent.ts#L12)
+
+Browser version (e.g., 120.0.0.0).

package/eslint.config.js

@@ -0,0 +1,52 @@
+// @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
+        }
+    },
+
+    {
+        ignores: ["**/*.d.ts"]
+    },
+
+    {
+        rules: {
+            "@typescript-eslint/no-unused-vars": [
+                "error",
+                {
+                    argsIgnorePattern: "^_",
+                    varsIgnorePattern: "^_",
+                    caughtErrorsIgnorePattern: "^_"
+                }
+            ],
+
+            semi: ["error", "always"],
+            curly: ["error", "all"],
+            "prefer-const": "warn",
+            "@stylistic/quotes": ["error", "double"]
+        }
+    }
+]);

package/gen-docs/001_commands.txt

@@ -0,0 +1,44 @@
+# 001 Commands Executed
+Generated: 2026-01-19T20:40:49+05:30
+
+## Environment
+
+```bash
+node -v
+# v24.5.0
+
+npm -v
+# 11.7.0
+```
+
+## Verification Suite
+
+```bash
+npm run lint
+# PASS - 0 errors, 0 warnings
+
+npm run build
+# PASS - tsc compiled successfully
+
+npm run test
+# PASS - 17/17 tests passed
+```
+
+## Coverage
+
+```bash
+node --test --experimental-test-coverage src/**/*.test.js
+# Lines: 86.62%
+# Branches: 76.56%
+# Functions: 100%
+```
+
+## Documentation
+
+```bash
+npm run docs
+# Generated at ./docs
+
+npm run docs:json
+# Generated at ./docs/docs.json
+```

package/gen-docs/001_coverage.txt

@@ -0,0 +1,43 @@
+# 001 Coverage Report
+Generated: 2026-01-19T20:40:49+05:30
+
+## Summary
+
+| Metric    | Value  | Target |
+|-----------|--------|--------|
+| Lines     | 86.62% | >= 90% |
+| Branches  | 76.56% | >= 90% |
+| Functions | 100%   | >= 90% |
+
+## Per-File Breakdown
+
+```
+file             | line % | branch % | funcs % | uncovered lines
+-------------------------------------------------------------------
+src
+ find.js         |  64.71 |    70.59 |  100.00 | 14-22 27-35 40-45
+ hello.js        | 100.00 |   100.00 |  100.00 |
+ pojo.js         | 100.00 |   100.00 |  100.00 |
+ user-agent.js   |  92.55 |    76.19 |  100.00 | 80-83 119-122 175+
+-------------------------------------------------------------------
+all files        |  86.62 |    76.56 |  100.00 |
+```
+
+## Analysis
+
+### Meets Target
+- hello.js: 100% (all metrics)
+- pojo.js: 100% (all metrics)
+
+### Below Target
+- find.js: 64.71% lines, 70.59% branches
+  - `stat` dependency unused
+  - Allowlist/blocklist callback paths untested
+- user-agent.js: 92.55% lines, 76.19% branches
+  - Edge case UA strings not covered
+
+## Recommendations
+
+1. Add tests for `find.js` allowlist/blocklist callbacks
+2. Add edge case UA tests for user-agent.js
+3. Consider removing unused `stat` from FileSystemDependencies

package/gen-docs/001_env.txt

@@ -0,0 +1,33 @@
+# 001 Environment Verification
+Generated: 2026-01-19T20:40:49+05:30
+
+## Runtime Versions
+
+- Node.js: v24.5.0
+- npm: 11.7.0
+- TypeScript: 5.9.3
+
+## Dependencies Verified
+
+All devDependencies installed and functional:
+- @eslint/js: 9.39.1
+- @stylistic/eslint-plugin: 5.6.1
+- @types/node: 24.10.1
+- 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-eslint: 8.48.1
+
+## Tooling
+
+- Test runner: node:test (built-in)
+- Coverage: node --experimental-test-coverage
+- Linter: eslint with typescript-eslint
+- Docs: typedoc
+
+## Status
+
+Environment verified. No issues.

package/gen-docs/001_lint.txt

@@ -0,0 +1,40 @@
+# 001 Lint Report
+Generated: 2026-01-19T20:40:49+05:30
+
+## Command
+
+```bash
+npm run lint
+# => npx eslint src/*.ts --no-warn-ignored
+```
+
+## Results
+
+- Errors: 0
+- Warnings: 0
+- Status: PASS
+
+## Configuration
+
+ESLint config: eslint.config.js
+- eslint.configs.recommended
+- tseslint.configs.recommended
+- tseslint.configs.strict
+- tseslint.configs.stylistic
+- eslint-config-prettier
+
+### Key Rules
+
+| Rule                               | Setting |
+|------------------------------------|---------|
+| @typescript-eslint/no-unused-vars  | error   |
+| no-unused-vars                     | off     |
+| semi                               | error   |
+| curly                              | error   |
+| prefer-const                       | warn    |
+| @stylistic/quotes                  | double  |
+
+## Notes
+
+- Base `no-unused-vars` disabled in favor of TypeScript-aware version
+- Ignore patterns: ^_ for args, vars, caught errors

package/gen-docs/001_state.txt

@@ -0,0 +1,58 @@
+# 001 State Report
+Generated: 2026-01-19T20:40:49+05:30
+
+## Project Summary
+
+- Package: @wtasnorg/node-lib@0.0.8
+- Type: TypeScript/Node.js library
+- Modules: find, hello, pojo, user-agent
+
+## Baseline Results
+
+### Lint
+- Status: PASS
+- Errors: 0
+- Warnings: 0
+
+### Build
+- Status: PASS
+- Compiler: tsc (TypeScript 5.9.3)
+
+### Tests
+- Status: PASS
+- Total: 17
+- Passed: 17
+- Failed: 0
+- Skipped: 0
+
+### Coverage (Overall)
+- Lines: 86.62%
+- Branches: 76.56%
+- Functions: 100.00%
+
+### Coverage by Module
+
+| Module         | Lines  | Branches | Functions |
+|----------------|--------|----------|-----------|
+| find.js        | 64.71% | 70.59%   | 100.00%   |
+| hello.js       | 100%   | 100%     | 100%      |
+| pojo.js        | 100%   | 100%     | 100%      |
+| user-agent.js  | 92.55% | 76.19%   | 100%      |
+
+## Gap Analysis
+
+### Low Coverage: find.js (64.71%)
+
+Uncovered lines: 14-22, 27-35, 40-45
+- `stat` function defined but never used in tests
+- Allowlist/blocklist function callback paths untested
+
+### Medium Coverage: user-agent.js (92.55%)
+
+Uncovered lines: 80-83, 119-122, 175+
+- Some edge case UA strings not covered
+- Fallback paths for unusual browsers
+
+## Status
+
+All gates passed. No blocking issues.

package/gen-docs/002_api.txt

@@ -0,0 +1,34 @@
+# 002 API Surface Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Public Exports (index.ts)
+
+- hello
+- pojo
+- createFindDirectories
+- FindDirectoriesOptions (type)
+- FileSystemDependencies (type)
+
+## Issues Found
+
+### [ISSUE] user-agent.ts - parseUserAgent not exported from index.ts
+
+The main UA parsing function is exported from user-agent.ts but NOT re-exported from index.ts.
+
+```typescript
+// index.ts - missing:
+import { parseUserAgent, UserAgentInfo } from "./user-agent.js";
+export { parseUserAgent };
+export type { UserAgentInfo };
+```
+
+Recommendation: Add to public API.
+
+### [MINOR] user-agent.ts - Helper functions not exported
+
+detectBrowser, detectOS, detectDeviceType, detectEngine are private.
+This is correct - they are implementation details.
+
+## Status
+
+FAIL - parseUserAgent not in public API.

package/gen-docs/002_deps.txt

@@ -0,0 +1,46 @@
+# 002 Dependency Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Dependencies flow correctly. No circular dependencies. Clean architecture.
+
+## Per-Module Analysis
+
+### find.ts ✅
+- Imports: node:path (resolve, join)
+- Dependencies injected via factory pattern
+- No framework coupling
+
+### hello.ts ✅
+- No imports
+- Uses only global console (acceptable)
+
+### pojo.ts ✅
+- No imports
+- Pure utility function
+
+### user-agent.ts ✅
+- No imports
+- Pure parsing logic
+
+### index.ts ✅
+- Re-exports from modules
+- Clean public API surface
+
+## Issues Found
+
+### [MINOR] find.ts - Unused `stat` dependency
+
+```typescript
+interface FileSystemDependencies {
+    readdir: ...
+    stat: ... // Declared but never used
+}
+```
+
+Recommendation: Remove if not planned for use.
+
+## Status
+
+PASS - Minor cleanup opportunity.

package/gen-docs/002_errors.txt

@@ -0,0 +1,34 @@
+# 002 Error Handling Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Minimal error handling needed. Functions are defensive.
+
+## Per-Module Analysis
+
+### find.ts ⚠️
+- No explicit error handling for readdir failures
+- Errors will propagate as Promise rejection
+- Acceptable for utility library
+
+### hello.ts ✅
+- Guards console access: `if (console?.log)`
+- No errors expected
+
+### pojo.ts ✅
+- Pure function, no errors expected
+- Handles non-objects via Object.entries (returns [])
+
+### user-agent.ts ✅
+- Defensive null check: `if (!ua) { return defaults }`
+- Optional chaining on split: `?.split(" ")[0] || "0"`
+- All branches return valid defaults
+
+## Issues Found
+
+None requiring action.
+
+## Status
+
+PASS - Error handling appropriate for library scope.

package/gen-docs/002_naming.txt

@@ -0,0 +1,36 @@
+# 002 Naming Findings
+Generated: 2026-01-19T20:43:05+05:30
+
+## Summary
+
+Generally good naming. A few opportunities for improvement.
+
+## Issues Found
+
+### [MINOR] user-agent.ts:193-194 - Unreachable condition
+
+```typescript
+if (ua.includes("AppleWebKit")) {return "WebKit";}
+if (ua.includes("Blink") || (ua.includes("Chrome/") && ua.includes("AppleWebKit/"))) {return "Blink";}
+```
+
+The second condition can never be fully reached because "AppleWebKit" already returns "WebKit".
+Chrome uses AppleWebKit but should return "Blink".
+
+Recommendation: Reorder conditions - check for Chrome/AppleWebKit combo first.
+
+### [OK] find.ts - createFindDirectories
+
+Factory name is accurate. Returns findDirectories function.
+
+### [OK] pojo.ts - pojo
+
+Short but descriptive. Common abbreviation.
+
+### [OK] user-agent.ts - detectBrowser, detectOS, etc.
+
+Verb prefix indicates action. Clear intent.
+
+## Status
+
+PASS with one logic issue noted.