@wtasnorg/node-lib 0.0.7 → 0.0.9

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/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L19)
+Defined in: [find.ts:19](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/src/find.ts#L19)
 
 Factory that produces an async findDirectories function with
 injected filesystem dependencies for full testability.

package/docs/functions/decode.md

@@ -0,0 +1,49 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../README.md) / decode
+
+# Function: decode()
+
+> **decode**(`input`, `charset`): `string`
+
+Defined in: base64.ts:119
+
+Decode a Base64 string.
+
+## Parameters
+
+### input
+
+`string`
+
+The Base64 encoded string.
+
+### charset
+
+The charset variant to use (default: "standard").
+
+`"standard"` | `"urlsafe"` | `"imap"` | `"radix64"`
+
+## Returns
+
+`string`
+
+The decoded string.
+
+## Example
+
+```typescript
+import { decode } from "./base64.js";
+
+decode("SGVsbG8sIFdvcmxkIQ==");
+// => "Hello, World!"
+
+decode("SGVsbG8sIFdvcmxkIQ==", "standard");
+// => "Hello, World!"
+```
+
+## Throws
+
+Error if the input contains invalid characters.

package/docs/functions/encode.md

@@ -0,0 +1,45 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../README.md) / encode
+
+# Function: encode()
+
+> **encode**(`input`, `charset`): `string`
+
+Defined in: base64.ts:79
+
+Encode a string to Base64.
+
+## Parameters
+
+### input
+
+`string`
+
+The string to encode.
+
+### charset
+
+The charset variant to use (default: "standard").
+
+`"standard"` | `"urlsafe"` | `"imap"` | `"radix64"`
+
+## Returns
+
+`string`
+
+The Base64 encoded string.
+
+## Example
+
+```typescript
+import { encode } from "./base64.js";
+
+encode("Hello, World!");
+// => "SGVsbG8sIFdvcmxkIQ=="
+
+encode("Hello, World!", "urlsafe");
+// => "SGVsbG8sIFdvcmxkIQ=="
+```

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/5ccb6028429af225c9ab29e1b6007075025c601f/src/hello.ts#L6)
+Defined in: [hello.ts:6](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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`, `unknown`\>
 
-Defined in: [pojo.ts:10](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/pojo.ts#L10)
+Defined in: [pojo.ts:10](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/src/pojo.ts#L10)
 
 Convert a class instance into a plain JavaScript object.
 Copies only the instance's own enumerable data properties

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/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L3)
+Defined in: [find.ts:3](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L4)
+Defined in: [find.ts:4](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/5ccb6028429af225c
 
 ### stat()
 
-> **stat**: (`path`) => `Promise`\<\{ `isDirectory`: `boolean`; \}\>
+> **stat**: (`_path`) => `Promise`\<\{ `isDirectory`: `boolean`; \}\>
 
-Defined in: [find.ts:5](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L5)
+Defined in: [find.ts:5](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L8)
+Defined in: [find.ts:8](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L11)
+Defined in: [find.ts:11](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L12)
+Defined in: [find.ts:12](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/src/find.ts#L12)
 
 ***
 
@@ -30,7 +30,7 @@ Defined in: [find.ts:12](https://github.com/wtasg/node-lib/blob/5ccb6028429af225
 
 > `optional` **followSymlinks**: `boolean`
 
-Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L10)
+Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/src/find.ts#L10)
 
 ***
 
@@ -38,4 +38,4 @@ Defined in: [find.ts:10](https://github.com/wtasg/node-lib/blob/5ccb6028429af225
 
 > `optional` **maxDepth**: `number`
 
-Defined in: [find.ts:9](https://github.com/wtasg/node-lib/blob/5ccb6028429af225c9ab29e1b6007075025c601f/src/find.ts#L9)
+Defined in: [find.ts:9](https://github.com/wtasg/node-lib/blob/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/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/b5efd5c345e8fa1bdc2a6d3ea4dd4b2eb5b9cc62/src/user-agent.ts#L12)
+
+Browser version (e.g., 120.0.0.0).

package/docs/type-aliases/Base64CharsetType.md

@@ -0,0 +1,13 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../README.md) / Base64CharsetType
+
+# Type Alias: Base64CharsetType
+
+> **Base64CharsetType** = *typeof* [`Base64Charset`](../variables/Base64Charset.md)\[`number`\]
+
+Defined in: base64.ts:18
+
+Base64 charset type.

package/docs/variables/Base64Charset.md

@@ -0,0 +1,17 @@
+[**@wtasnorg/node-lib**](../README.md)
+
+***
+
+[@wtasnorg/node-lib](../README.md) / Base64Charset
+
+# Variable: Base64Charset
+
+> `const` **Base64Charset**: readonly \[`"standard"`, `"urlsafe"`, `"imap"`, `"radix64"`\]
+
+Defined in: base64.ts:13
+
+Available Base64 charset variants.
+- `standard`: RFC 4648 standard alphabet (A-Z, a-z, 0-9, +, /)
+- `urlsafe`: URL and filename safe (A-Z, a-z, 0-9, -, _)
+- `imap`: Modified Base64 for IMAP mailbox names (A-Z, a-z, 0-9, +, ,)
+- `radix64`: Base64 variant used in OpenPGP (A-Z, a-z, 0-9, +, /)

package/eslint.config.js

@@ -28,10 +28,14 @@ export default defineConfig([
         }
     },
 
+    {
+        ignores: ["**/*.d.ts"]
+    },
+
     {
         rules: {
             "@typescript-eslint/no-unused-vars": [
-                "warn",
+                "error",
                 {
                     argsIgnorePattern: "^_",
                     varsIgnorePattern: "^_",
@@ -40,7 +44,8 @@ export default defineConfig([
             ],
 
             semi: ["error", "always"],
-            // "no-unused-vars": ["error", { varsIgnorePattern: "^[A-Z_]" }],
+            curly: ["error", "all"],
+            "prefer-const": "warn",
             "@stylistic/quotes": ["error", "double"]
         }
     }

package/gen-docs/001_base64_refine.txt

@@ -0,0 +1,50 @@
+# Base64 Module Refinement Pass
+# Date: 2026-01-19
+# Scope: src/base64.ts
+
+## SRP Analysis
+- encode(): Single responsibility - string to Base64
+- decode(): Single responsibility - Base64 to string
+- buildDecodeTable(): Single responsibility - lookup table creation
+- No business logic mixing, no I/O coupling
+
+## Dependency Direction
+- No external dependencies beyond Node.js built-ins (TextEncoder/TextDecoder)
+- No circular dependencies
+- Pure computation, no framework coupling
+
+## Purity & Side-Effects
+- All functions are pure (no I/O, no global state mutation)
+- Deterministic: same input always produces same output
+- No hidden state mutation
+
+## Naming Review
+- encode/decode: Clear, idiomatic names
+- Base64Charset: Descriptive, matches domain
+- CHARSETS/DECODE_TABLES: Clear internal constants
+- buildDecodeTable: Accurate verb+noun pattern
+
+## Error Handling
+- decode() throws Error with specific character on invalid input
+- Error message includes the offending character
+- No swallowed exceptions
+
+## API Surface
+- Exports: encode, decode, Base64Charset, Base64CharsetType
+- Minimal and focused public API
+- Internal helpers (buildDecodeTable, CHARSETS, PAD) are not exported
+
+## Invariants
+- Charset type is constrained via TypeScript const assertion
+- Invalid charset impossible at compile time
+- Padding handled correctly per Base64 spec
+
+## Test Coverage
+- 74 tests total, base64 tests cover:
+  - Encode: empty, single char, padding, all charsets, UTF-8
+  - Decode: empty, padding, error handling
+  - Round-trip: all charsets with 10 test cases each
+- Tests verify behavior, not implementation
+
+## Summary
+No actionable refinement items. Code is clean, focused, and well-tested.

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.