pathlra-aliaser 4.6.9 → 4.7.0

package/5ety

@@ -0,0 +1,343 @@
+
+  
+
+# Ultra-Fast, Zero-Dependency Path Alias Resolver for Node.js
+`Developed by hub-mgv ❤️`
+
+  
+
+# pathlra-aliaser
+
+  
+
+Ultra-Fast, Zero-Dependency Path Alias Resolver for Node.js
+
+  
+
+Engineered for sub-millisecond resolution, extreme performance, and seamless integration with zero runtime overhead in production
+
+  
+
+---
+
+  
+
+## Why pathlra-aliaser?
+
+  
+
+Most alias tools are slow, bloated, or force you to manage paths in JavaScript files.
+
+  
+
+`pathlra-aliaser` is a high-performance module loader enhancer built for speed, stability, and minimal memory footprint It safely patches Node.js’s module resolution system, enabling clean, readable imports like:
+
+  
+
+```js
+
+const  db  =  require("@services/database");
+
+```
+
+  
+
+without any build step, transpilation, or runtime penalty
+
+  
+
+---
+
+  
+
+## Key Features
+
+  
+
+-  _Sub-millisecond_ resolution: Resolves aliases in <0.1ms even under heavy load.
+- Adaptive strategy engine:
+- Linear scan for ≤100 aliases
+- Radix tree for ≥100 aliases
+- Optimized LRU cache: Batch eviction (10% at a time) to avoid GC spikes.
+- Package.json-first design: Aliases live only in package.json.
+- Dynamic alias support: Programmatic runtime path generation.
+- Custom module directories: Extend require() to search in non-standard folders.
+- Zero dependencies: Pure Node.js, fully compatible with `"use strict"`.
+- Minimal memory footprint: Optimized data structures and memory-aware algorithms.
+- Hot-reload support (optional) for development.
+- Verbose/debug mode for tracing resolution steps.
+- TypeScript paths auto-generation.
+- Friendly error messages & config validation.
+- Default presets: `@root`, `@src` for plug-and-play.
+
+  
+
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## How It Works
+
+  
+
+- Initialization: Scans `package.json` for keys starting with `path_aliaser`.
+- Alias Registration: Loads all alias → target mappings.
+- Strategy Selection:
+-  `<100 aliases → linear scan`
+-  `≥100 aliases → radix tree for O(k) prefix lookups`
+- Module Patching: Overrides Node.js’s resolver functions.
+- Caching: Uses high-efficiency LRU cache with batch eviction.
+- Path Propagation: Custom module directories injected into all active module paths.
+
+  
+
+All happens once at startup with near-zero runtime cost.
+
+  
+
+---
+## Feature & Performance Comparison: `pathlra-aliaser` vs Top Alternatives
+
+| Feature / Capability | **`pathlra-aliaser`** ✅ | **`module-alias`** | **`tsconfig-paths`** | **`babel-plugin-module-resolver`** |
+|----------------------|--------------------------|--------------------|------------------------|------------------------------------|
+| **Pure Node.js (no build step)** | ✅ Yes | ✅ Yes | ⚠️ Only with `ts-node` | ❌ Requires Babel transpilation |
+| **Zero Dependencies** | ✅ Yes | ✅ Yes | ❌ Needs TypeScript | ❌ Needs Babel + plugins |
+| **Sub-millisecond Resolution** | ✅ **<0.1ms** (adaptive) | ❌ ~0.3–1ms (linear only) | ⚠️ Slower (TS overhead) | N/A (build-time only) |
+| **Smart Resolution Strategy** | ✅ **Radix Tree (≥100 aliases)** + Linear (<100) | ❌ Linear scan only (`O(n)`) | ❌ Regex-based matching | N/A |
+| **LRU Caching with Batch Eviction** | ✅ Yes (10k entries, 10% batch) | ❌ No cache | ⚠️ Limited caching | N/A |
+| **Dynamic Aliases (Handler Functions)** | ✅ Yes + **type validation** | ✅ Yes (no validation) | ❌ No | ❌ No |
+| **Hot-Reload Support** | ✅ Optional (dev-only) | ❌ No | ⚠️ Via `ts-node-dev` | ❌ No |
+| **TypeScript Paths Auto-Gen** | ✅ Built-in `_internal.generateTSConfig()` | ❌ No | N/A (it *is* TS) | ❌ Manual sync needed |
+| **Security: Path Traversal Protection** | ✅ Blocks `..`, `~`, `\0` | ❌ **Vulnerable** | ⚠️ Depends on config | N/A |
+| **Memory Optimization** | ✅ **Minimal Mode** (<10 aliases → 1k cache) | ❌ Fixed overhead | ❌ High TS memory use | N/A |
+| **Config via `package.json`** | ✅ Any key starting with `path_aliaser` | ✅ `_moduleAliases` only | ❌ `tsconfig.json` only | ❌ `.babelrc` / `babel.config.js` |
+| **Custom Module Directories** | ✅ `_moduleDirectories` + `ap()` | ✅ `_moduleDirectories` | ❌ No | ❌ No |
+| **Debug/Verbose Mode** | ✅ Full resolution tracing | ❌ No | ⚠️ Limited logs | ❌ No |
+| **ESM Support** | ✅ Via patched resolver | ✅ Partial (Node ≥14.6+) | ✅ With `ts-node` | ✅ If Babel configured |
+| **Works in Jest** | ⚠️ Same as `module-alias` (needs `moduleNameMapper`) | ⚠️ Requires Jest config | ✅ With `ts-jest` | ✅ If Babel used in Jest |
+| **Production-Ready Performance** | ✅ **8.7x faster @ 1k aliases**, 60% less RAM | ❌ Degrades with scale | ❌ Not for pure JS projects | ❌ Build-only |
+| **Default Presets** | ✅ `@root`, `@src` auto-applied | ❌ None | ❌ None | ❌ None |
+| **Friendly Error Messages** | ✅ Clear, actionable errors | ⚠️ Generic errors | ⚠️ TS cryptic errors | ⚠️ Babel errors |
+
+
+  
+
+## Installation
+
+  
+
+```bash
+
+npm  install  pathlra-aliaser
+
+```
+
+  
+
+---
+
+  
+
+## Configuration via `package.json`
+
+  
+
+```json
+
+{
+
+	"name": "name",
+	"version": "4",
+	"main": "index.js",
+	"dependencies": {
+	"pathlra-aliaser": "^3.6.7"
+
+	},
+	"path_aliaser": {
+	"@products": "./routes/products.js",
+	"@users": "./routes/users.js",
+	"@logger": "./utils/logger.js"
+	},
+	"_moduleDirectories": ["node_modules", "custom_libs"],
+	"scripts": {
+	"test": "echo "Error:  no  test  specified" && exit 1"
+
+	},
+	"license": "ISC",
+	"description": "High-performance path alias resolver for Node.js with LRU caching and radix-tree optimization"
+
+}
+
+```
+
+  
+
+_Paths are relative to the project root._
+
+`_moduleDirectories` extends Node.js’s search paths safely.
+
+  
+
+---
+
+  
+
+## Example Usage
+
+  
+
+```js
+
+"use strict";
+require("pathlra-aliaser")(); // Must be called BEFORE any aliased requires
+const  logger  =  require("@utils/logger");
+const  User  =  require("@models/User");
+
+```
+
+  
+
+---
+
+  
+
+## Advanced Features
+
+  
+
+**Dynamic Aliases:**
+
+  
+
+```js
+
+const  aliaser  =  require("pathlra-aliaser");
+aliaser.aa("@dynamic", () =>  "./runtime/path");
+
+```
+
+  
+
+**Add Custom Module Directory:**
+
+  
+
+```js
+
+aliaser.ap("./internal_modules");
+
+```
+
+  
+
+**Bulk Alias Registration:**
+
+  
+
+```js
+
+aliaser.addAliases({ "@core": "./src/core" });
+
+```
+
+  
+
+---
+
+  
+
+## Performance & Benchmarks
+
+  
+
+- Cache: 10,000 entries by default
+- Eviction: 10% of least-used entries per batch
+- Memory usage: <2 MB with 1,000+ aliases
+
+  
+
+**Benchmarks vs module-alias:**
+
+  
+
+- 3.2x faster (10 aliases)
+- 8.7x faster (1,000 aliases)
+- 60% lower memory usage under load
+
+  
+
+---
+
+  
+
+## Ideal For
+
+  
+
+- Large-scale Node.js applications
+- Microservices
+- Performance-critical systems
+- Long-running processes
+- Teams enforcing standardized path conventions
+
+  
+
+**Not for:** Frontend bundling, TypeScript-only projects (unless with ts-node), or projects preferring config files over package.json.
+
+  
+
+---
+
+  
+
+## Common Misconceptions
+
+  
+
+- “I need to call `aa()` for every alias.” → No, `package.json` is enough.
+- “It modifies global behavior unsafely” → Only patches Node.js resolver safely.
+- “It slows down my app.” → Benchmarks show faster resolution than manual paths after warm-up.
+
+  
+
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## License
+MIT © hub-mgv
+Engineered for speed. Built for scale. Designed to disappear.
+`pathlra-aliaser`: where path resolution becomes invisible.
+
+
+
+ طيب وظبط لي دوت وكلل الماركت الماركت شويه يعني ما تظهرش دايما ان احنا افضل من الكل والكل مجرد ضعفه كده لا قلل شويه الماركه عشان مثلا ما يكونش تكبر او حاجه  ارفعوا ملف README.md    ارفعه لي في ملف zip  مش موقع  

package/README.md

@@ -1,289 +1,208 @@
-
-  
-
-# Developed by hub-mgv ❤️❤️❤️
-
-  
-
 # pathlra-aliaser
 
-  
-
-Ultra-Fast, Zero-Dependency Path Alias Resolver for Node.js
+High-performance path alias resolver for Node.js, with a focus on speed, safety, and predictable behavior.
 
-  
+Designed to provide fast alias resolution in large codebases, using built-in caching and zero external dependencies.
 
-Engineered for sub-millisecond resolution, extreme performance, and seamless integration with zero runtime overhead in production
-
-  
+Works with CommonJS out of the box and requires no code changes beyond a simple initialization call.
 
 ---
 
-  
-
 ## Why pathlra-aliaser?
 
-  
-
-Most alias tools are slow, bloated, or force you to manage paths in JavaScript files.
-
-  
+`pathlra-aliaser` is a path alias resolver and module loader enhancement for Node.js.
 
-`pathlra-aliaser` is a high-performance module loader enhancer built for speed, stability, and minimal memory footprint It safely patches Node.js’s module resolution system, enabling clean, readable imports like:
+It is designed to balance performance, correctness, and simplicity. Instead of introducing additional configuration files,
+build steps, or runtime layers, it integrates directly with Node.js’s module resolution mechanism while preserving its
+expected behavior.
 
-  
+Internally, the resolver applies adaptive lookup strategies and caching to keep alias resolution efficient as projects
+grow. This makes it suitable for larger codebases that want cleaner and more readable import paths, without relying on
+deep relative paths or additional runtime dependencies.
 
 ```js
-
-const  db  =  require("@services/database");
-
+const db = require("@services/database");
 ```
 
-  
-
-without any build step, transpilation, or runtime penalty
-
-  
+No build step or transpilation is required.
 
 ---
 
-  
-
 ## Key Features
 
-  
-
--  _Sub-millisecond_ resolution: Resolves aliases in <0.1ms even under heavy load.
-- Adaptive strategy engine:
-- Linear scan for ≤100 aliases
-- Radix tree for ≥100 aliases
-- Optimized LRU cache: Batch eviction (10% at a time) to avoid GC spikes.
-- Package.json-first design: Aliases live only in package.json.
-- Dynamic alias support: Programmatic runtime path generation.
-- Custom module directories: Extend require() to search in non-standard folders.
-- Zero dependencies: Pure Node.js, fully compatible with `"use strict"`.
-- Minimal memory footprint: Optimized data structures and memory-aware algorithms.
-- Hot-reload support (optional) for development.
-- Verbose/debug mode for tracing resolution steps.
-- TypeScript paths auto-generation.
-- Friendly error messages & config validation.
-- Default presets: `@root`, `@src` for plug-and-play.
-
-  
-
----
-
-  
+- Sub-millisecond alias resolution in typical usage scenarios
+- Adaptive resolution strategy:
+  - Linear scan for smaller alias sets (≤100)
+  - Radix tree lookup for larger configurations (>100)
+- LRU cache with batch-based eviction to reduce GC pressure
+- Aliases configured directly in `package.json`
+- Support for dynamic, runtime-generated aliases
+- Optional custom module directories
+- Zero external dependencies (pure Node.js)
+- Small and predictable memory footprint
+- Optional hot-reload support for development environments
+- Debug and verbose modes for tracing resolution behavior
+- Helper for generating TypeScript path mappings
+- Configuration validation with clear error messages
+- Built-in presets such as `@root` and `@src`
 
 ## How It Works
 
-  
+- Initialization: Reads alias definitions from `package.json` keys starting with `path_aliaser`
+- Registration: Builds internal alias-to-path mappings
+- Strategy selection:
+  - Fewer aliases use a simple linear scan
+  - Larger sets switch to a radix-tree-based lookup
+- Module patching: Hooks into Node.js module resolution
+- Caching: Stores resolved paths using an LRU cache
+- Path propagation: Injects custom module directories when configured
 
-- Initialization: Scans `package.json` for keys starting with `path_aliaser`.
-- Alias Registration: Loads all alias → target mappings.
-- Strategy Selection:
--  `<100 aliases → linear scan`
--  `≥100 aliases → radix tree for O(k) prefix lookups`
-- Module Patching: Overrides Node.js’s resolver functions.
-- Caching: Uses high-efficiency LRU cache with batch eviction.
-- Path Propagation: Custom module directories injected into all active module paths.
-
-  
-
-All happens once at startup with near-zero runtime cost.
-
-  
+All setup is performed once at startup.
 
 ---
 
-  
-
 ## Installation
 
-  
-
 ```bash
-
-npm  install  pathlra-aliaser
-
+npm install pathlra-aliaser
 ```
 
-  
-
 ---
 
-  
-
 ## Configuration via `package.json`
 
-  
-
 ```json
-
 {
-
-	"name": "name",
-	"version": "4",
-	"main": "index.js",
-	"dependencies": {
-	"pathlra-aliaser": "^3.6.7"
-
-	},
-	"path_aliaser": {
-	"@products": "./routes/products.js",
-	"@users": "./routes/users.js",
-	"@logger": "./utils/logger.js"
-	},
-	"_moduleDirectories": ["node_modules", "custom_libs"],
-	"scripts": {
-	"test": "echo "Error:  no  test  specified" && exit 1"
-
-	},
-	"license": "ISC",
-	"description": "High-performance path alias resolver for Node.js with LRU caching and radix-tree optimization"
-
+  "dependencies": {
+    "pathlra-aliaser": "^3.6.7"
+  },
+  "path_aliaser": {
+    "@products": "./routes/products.js",
+    "@users": "./routes/users.js",
+    "@logger": "./utils/logger.js"
+  },
+  "_moduleDirectories": ["node_modules", "custom_libs"]
 }
-
 ```
 
-  
-
-_Paths are relative to the project root._
-
-`_moduleDirectories` extends Node.js’s search paths safely.
+Paths are resolved relative to the project root.
 
-  
+`_moduleDirectories` extends Node.js’s module search paths in a controlled manner.
 
 ---
 
-  
-
 ## Example Usage
 
-  
-
 ```js
-
 "use strict";
-require("pathlra-aliaser")(); // Must be called BEFORE any aliased requires
-const  logger  =  require("@utils/logger");
-const  User  =  require("@models/User");
 
-```
+require("pathlra-aliaser")(); // Must be called before aliased requires
 
-  
+const logger = require("@utils/logger");
+const User = require("@models/User");
+```
 
 ---
 
-  
-
 ## Advanced Features
 
-  
-
-**Dynamic Aliases:**
-
-  
+### Dynamic Aliases
 
 ```js
+const aliaser = require("pathlra-aliaser");
 
-const  aliaser  =  require("pathlra-aliaser");
-aliaser.aa("@dynamic", () =>  "./runtime/path");
-
+aliaser.aa("@dynamic", () => "./runtime/path");
 ```
 
-  
-
-**Add Custom Module Directory:**
-
-  
+### Add a Custom Module Directory
 
 ```js
-
 aliaser.ap("./internal_modules");
-
 ```
 
-  
-
-**Bulk Alias Registration:**
-
-  
+### Bulk Alias Registration
 
 ```js
+aliaser.addAliases({
+  "@core": "./src/core"
+});
+```
 
-aliaser.addAliases({ "@core": "./src/core" });
+---
 
-```
+## Performance & Benchmarks
 
-  
+- Default cache size: 10,000 entries
+- Eviction strategy: Batch removal of least-used entries
+- Typical memory usage: <2 MB with large alias sets
+
+Benchmark results depend on workload and project structure.
 
 ---
 
-  
+## Ideal For
 
-## Performance & Benchmarks
+- Medium to large Node.js applications
+- Microservices and modular architectures
+- Long-running backend processes
+- Teams that want consistent import conventions
 
-  
+**Not intended for:** frontend bundling workflows, build-time-only aliasing, or projects that avoid `package.json` configuration.
 
-- Cache: 10,000 entries by default
-- Eviction: 10% of least-used entries per batch
-- Memory usage: <2 MB with 1,000+ aliases
+---
 
-  
+## Common Misconceptions
 
-**Benchmarks vs module-alias:**
+- “I need to register every alias manually.” → Aliases can be defined entirely in `package.json`.
+- “It replaces Node.js behavior unsafely.” → It integrates with the resolver while preserving expected semantics.
+- “It adds noticeable runtime overhead.” → Resolution is cached and designed to remain efficient after warm-up.
 
-  
+---
 
-- 3.2x faster (10 aliases)
-- 8.7x faster (1,000 aliases)
-- 60% lower memory usage under load
 
-  
 
----
 
-  
 
-## Ideal For
 
-  
 
-- Large-scale Node.js applications
-- Microservices
-- Performance-critical systems
-- Long-running processes
-- Teams enforcing standardized path conventions
+## Feature & Performance Comparison: `pathlra-aliaser` vs Top Alternatives
 
-  
+| Feature / Capability | **`pathlra-aliaser`** ✅ | **`module-alias`** | **`tsconfig-paths`** | **`babel-plugin-module-resolver`** |
+|----------------------|--------------------------|--------------------|------------------------|------------------------------------|
+| **Pure Node.js (no build step)** | ✅ Yes | ✅ Yes | ⚠️ Only with `ts-node` | ❌ Requires Babel transpilation |
+| **Zero Dependencies** | ✅ Yes | ✅ Yes | ❌ Needs TypeScript | ❌ Needs Babel + plugins |
+| **Sub-millisecond Resolution** | ✅ **<0.1ms** (adaptive) | ❌ ~0.3–1ms (linear only) | ⚠️ Slower (TS overhead) | N/A (build-time only) |
+| **Smart Resolution Strategy** | ✅ **Radix Tree (≥100 aliases)** + Linear (<100) | ❌ Linear scan only (`O(n)`) | ❌ Regex-based matching | N/A |
+| **LRU Caching with Batch Eviction** | ✅ Yes (10k entries, 10% batch) | ❌ No cache | ⚠️ Limited caching | N/A |
+| **Dynamic Aliases (Handler Functions)** | ✅ Yes + **type validation** | ✅ Yes (no validation) | ❌ No | ❌ No |
+| **Hot-Reload Support** | ✅ Optional (dev-only) | ❌ No | ⚠️ Via `ts-node-dev` | ❌ No |
+| **TypeScript Paths Auto-Gen** | ✅ Built-in `_internal.generateTSConfig()` | ❌ No | N/A (it *is* TS) | ❌ Manual sync needed |
+| **Security: Path Traversal Protection** | ✅ Blocks `..`, `~`, `\0` | ❌ **Vulnerable** | ⚠️ Depends on config | N/A |
+| **Memory Optimization** | ✅ **Minimal Mode** (<10 aliases → 1k cache) | ❌ Fixed overhead | ❌ High TS memory use | N/A |
+| **Config via `package.json`** | ✅ Any key starting with `path_aliaser` | ✅ `_moduleAliases` only | ❌ `tsconfig.json` only | ❌ `.babelrc` / `babel.config.js` |
+| **Custom Module Directories** | ✅ `_moduleDirectories` + `ap()` | ✅ `_moduleDirectories` | ❌ No | ❌ No |
+| **Debug/Verbose Mode** | ✅ Full resolution tracing | ❌ No | ⚠️ Limited logs | ❌ No |
+| **ESM Support** | ✅ Via patched resolver | ✅ Partial (Node ≥14.6+) | ✅ With `ts-node` | ✅ If Babel configured |
+| **Works in Jest** | ⚠️ Same as `module-alias` (needs `moduleNameMapper`) | ⚠️ Requires Jest config | ✅ With `ts-jest` | ✅ If Babel used in Jest |
+| **Production-Ready Performance** | ✅ **8.7x faster @ 1k aliases**, 60% less RAM | ❌ Degrades with scale | ❌ Not for pure JS projects | ❌ Build-only |
+| **Default Presets** | ✅ `@root`, `@src` auto-applied | ❌ None | ❌ None | ❌ None |
+| **Friendly Error Messages** | ✅ Clear, actionable errors | ⚠️ Generic errors | ⚠️ TS cryptic errors | ⚠️ Babel errors |
 
-**Not for:** Frontend bundling, TypeScript-only projects (unless with ts-node), or projects preferring config files over package.json.
 
-  
 
----
 
-  
 
-## Common Misconceptions
 
-  
 
-- “I need to call `aa()` for every alias.” → No, `package.json` is enough.
-- “It modifies global behavior unsafely” → Only patches Node.js resolver safely.
-- “It slows down my app.” → Benchmarks show faster resolution than manual paths after warm-up.
 
-  
 
----
 
-  
 
+---
 ## License
-MIT © hub-mgv
-Engineered for speed. Built for scale. Designed to disappear.
-`pathlra-aliaser`: where path resolution becomes invisible.
 
+MIT © hub-mgv
 
+Built to be reliable, efficient, and unobtrusive.
 
+`pathlra-aliaser`: keeping path resolution simple.

package/index.html

@@ -0,0 +1,409 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>pathlra-aliaser - README.md</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+            line-height: 1.6;
+            color: #24292e;
+            max-width: 900px;
+            margin: 0 auto;
+            padding: 2rem 1rem;
+            background-color: #ffffff;
+        }
+        h1, h2, h3 {
+            margin-top: 1.5em;
+            margin-bottom: 0.8em;
+            font-weight: 600;
+        }
+        h1 {
+            font-size: 2.25em;
+            border-bottom: 1px solid #eaecef;
+            padding-bottom: 0.3em;
+        }
+        h2 {
+            font-size: 1.75em;
+            border-bottom: 1px solid #eaecef;
+            padding-bottom: 0.3em;
+        }
+        h3 {
+            font-size: 1.375em;
+        }
+        p {
+            margin: 0.8em 0;
+        }
+        code {
+            background-color: rgba(27,31,35,0.05);
+            padding: 0.2em 0.4em;
+            border-radius: 6px;
+            font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
+            font-size: 0.9em;
+        }
+        pre {
+            background-color: #f6f8fa;
+            border-radius: 6px;
+            padding: 16px;
+            overflow: auto;
+            margin: 1rem 0;
+        }
+        pre code {
+            background: none;
+            padding: 0;
+            font-size: 0.95em;
+        }
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            margin: 1rem 0;
+        }
+        th, td {
+            padding: 6px 13px;
+            border: 1px solid #dfe2e5;
+            text-align: left;
+        }
+        th {
+            background-color: #f6f8fa;
+            font-weight: 600;
+        }
+        tr:nth-child(even) {
+            background-color: #f6f8fa;
+        }
+        ul, ol {
+            padding-left: 2em;
+            margin: 0.8em 0;
+        }
+        li {
+            margin: 0.3em 0;
+        }
+        .highlight {
+            background-color: #fff8c5;
+            padding: 0.2em 0.4em;
+            border-radius: 4px;
+        }
+        .note {
+            background-color: #f0f8ff;
+            border-left: 4px solid #0366d6;
+            padding: 1em 1.2em;
+            margin: 1.5em 0;
+        }
+        .footer {
+            margin-top: 2rem;
+            padding-top: 1rem;
+            border-top: 1px solid #eaecef;
+            color: #6a737d;
+            font-size: 0.9em;
+        }
+        .badge {
+            display: inline-block;
+            padding: 0.25em 0.5em;
+            font-size: 0.8em;
+            font-weight: bold;
+            border-radius: 4px;
+            margin-right: 0.3em;
+        }
+        .success { background-color: #dafbe1; color: #22863a; }
+        .warning { background-color: #fff5b1; color: #9a6700; }
+        .danger { background-color: #ffe3e6; color: #d73a49; }
+        .info { background-color: #dbedff; color: #0366d6; }
+    </style>
+</head>
+<body>
+    <h1>Ultra-Fast, Zero-Dependency Path Alias Resolver for Node.js</h1>
+    <p><em>Developed by hub-mgv ❤️</em></p>
+
+    <h2>pathlra-aliaser</h2>
+    <p>Ultra-Fast, Zero-Dependency Path Alias Resolver for Node.js</p>
+    <p>Engineered for sub-millisecond resolution, extreme performance, and seamless integration with zero runtime overhead in production.</p>
+
+    <hr>
+
+    <h2>Why pathlra-aliaser?</h2>
+    <p>Most alias tools are slow, bloated, or force you to manage paths in JavaScript files.</p>
+    <p><code>pathlra-aliaser</code> is a high-performance module loader enhancer built for speed, stability, and minimal memory footprint. It safely patches Node.js’s module resolution system, enabling clean, readable imports like:</p>
+    <pre><code class="language-js">const db = require("@services/database");</code></pre>
+    <p>without any build step, transpilation, or runtime penalty.</p>
+
+    <hr>
+
+    <h2>Key Features</h2>
+    <ul>
+        <li><span class="highlight">Sub-millisecond resolution</span>: Resolves aliases in &lt;0.1ms even under heavy load.</li>
+        <li><strong>Adaptive strategy engine</strong>:
+            <ul>
+                <li>Linear scan for ≤100 aliases</li>
+                <li>Radix tree for ≥100 aliases</li>
+            </ul>
+        </li>
+        <li><strong>Optimized LRU cache</strong>: Batch eviction (10% at a time) to avoid GC spikes.</li>
+        <li><strong>Package.json-first design</strong>: Aliases live only in package.json.</li>
+        <li><strong>Dynamic alias support</strong>: Programmatic runtime path generation.</li>
+        <li><strong>Custom module directories</strong>: Extend require() to search in non-standard folders.</li>
+        <li><strong>Zero dependencies</strong>: Pure Node.js, fully compatible with <code>"use strict"</code>.</li>
+        <li><strong>Minimal memory footprint</strong>: Optimized data structures and memory-aware algorithms.</li>
+        <li><strong>Hot-reload support</strong> (optional) for development.</li>
+        <li><strong>Verbose/debug mode</strong> for tracing resolution steps.</li>
+        <li><strong>TypeScript paths auto-generation</strong>.</li>
+        <li><strong>Friendly error messages &amp; config validation</strong>.</li>
+        <li><strong>Default presets</strong>: <code>@root</code>, <code>@src</code> for plug-and-play.</li>
+    </ul>
+
+    <hr>
+
+    <h2>How It Works</h2>
+    <ul>
+        <li><strong>Initialization</strong>: Scans <code>package.json</code> for keys starting with <code>path_aliaser</code>.</li>
+        <li><strong>Alias Registration</strong>: Loads all alias → target mappings.</li>
+        <li><strong>Strategy Selection</strong>:
+            <ul>
+                <li>&lt;100 aliases → linear scan</li>
+                <li>≥100 aliases → radix tree for O(k) prefix lookups</li>
+            </ul>
+        </li>
+        <li><strong>Module Patching</strong>: Overrides Node.js’s resolver functions.</li>
+        <li><strong>Caching</strong>: Uses high-efficiency LRU cache with batch eviction.</li>
+        <li><strong>Path Propagation</strong>: Custom module directories injected into all active module paths.</li>
+    </ul>
+    <p>All happens once at startup with near-zero runtime cost.</p>
+
+    <hr>
+
+    <h2>Feature & Performance Comparison</h2>
+    <table>
+        <thead>
+            <tr>
+                <th>Feature / Capability</th>
+                <th>pathlra-aliaser</th>
+                <th>module-alias</th>
+                <th>tsconfig-paths</th>
+                <th>babel-plugin-module-resolver</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>Pure Node.js (no build step)</td>
+                <td><span class="badge success">Yes</span></td>
+                <td><span class="badge success">Yes</span></td>
+                <td><span class="badge warning">Only with ts-node</span></td>
+                <td><span class="badge danger">Requires Babel</span></td>
+            </tr>
+            <tr>
+                <td>Zero Dependencies</td>
+                <td><span class="badge success">Yes</span></td>
+                <td><span class="badge success">Yes</span></td>
+                <td><span class="badge danger">Needs TypeScript</span></td>
+                <td><span class="badge danger">Needs Babel + plugins</span></td>
+            </tr>
+            <tr>
+                <td>Sub-millisecond Resolution</td>
+                <td><span class="badge success">&lt;0.1ms (adaptive)</span></td>
+                <td><span class="badge danger">~0.3–1ms (linear only)</span></td>
+                <td><span class="badge warning">Slower (TS overhead)</span></td>
+                <td>N/A (build-time only)</td>
+            </tr>
+            <tr>
+                <td>Smart Resolution Strategy</td>
+                <td><span class="badge success">Radix Tree (≥100) + Linear (&lt;100)</span></td>
+                <td><span class="badge danger">Linear scan only (O(n))</span></td>
+                <td><span class="badge danger">Regex-based matching</span></td>
+                <td>N/A</td>
+            </tr>
+            <tr>
+                <td>LRU Caching with Batch Eviction</td>
+                <td><span class="badge success">Yes (10k entries, 10% batch)</span></td>
+                <td><span class="badge danger">No cache</span></td>
+                <td><span class="badge warning">Limited caching</span></td>
+                <td>N/A</td>
+            </tr>
+            <tr>
+                <td>Dynamic Aliases (Handler Functions)</td>
+                <td><span class="badge success">Yes + type validation</span></td>
+                <td><span class="badge info">Yes (no validation)</span></td>
+                <td><span class="badge danger">No</span></td>
+                <td><span class="badge danger">No</span></td>
+            </tr>
+            <tr>
+                <td>Hot-Reload Support</td>
+                <td><span class="badge success">Optional (dev-only)</span></td>
+                <td><span class="badge danger">No</span></td>
+                <td><span class="badge warning">Via ts-node-dev</span></td>
+                <td><span class="badge danger">No</span></td>
+            </tr>
+            <tr>
+                <td>TypeScript Paths Auto-Gen</td>
+                <td><span class="badge success">Built-in</span></td>
+                <td><span class="badge danger">No</span></td>
+                <td>N/A (it <em>is</em> TS)</td>
+                <td><span class="badge danger">Manual sync needed</span></td>
+            </tr>
+            <tr>
+                <td>Security: Path Traversal Protection</td>
+                <td><span class="badge success">Blocks .., ~, \0</span></td>
+                <td><span class="badge danger">Vulnerable</span></td>
+                <td><span class="badge warning">Depends on config</span></td>
+                <td>N/A</td>
+            </tr>
+            <tr>
+                <td>Memory Optimization</td>
+                <td><span class="badge success">Minimal Mode (&lt;10 aliases → 1k cache)</span></td>
+                <td><span class="badge danger">Fixed overhead</span></td>
+                <td><span class="badge danger">High TS memory use</span></td>
+                <td>N/A</td>
+            </tr>
+            <tr>
+                <td>Config via package.json</td>
+                <td><span class="badge success">Any key starting with path_aliaser</span></td>
+                <td><span class="badge success">_moduleAliases only</span></td>
+                <td><span class="badge danger">tsconfig.json only</span></td>
+                <td><span class="badge danger">.babelrc / babel.config.js</span></td>
+            </tr>
+            <tr>
+                <td>Custom Module Directories</td>
+                <td><span class="badge success">_moduleDirectories + ap()</span></td>
+                <td><span class="badge success">_moduleDirectories</span></td>
+                <td><span class="badge danger">No</span></td>
+                <td><span class="badge danger">No</span></td>
+            </tr>
+            <tr>
+                <td>Debug/Verbose Mode</td>
+                <td><span class="badge success">Full resolution tracing</span></td>
+                <td><span class="badge danger">No</span></td>
+                <td><span class="badge warning">Limited logs</span></td>
+                <td><span class="badge danger">No</span></td>
+            </tr>
+            <tr>
+                <td>ESM Support</td>
+                <td><span class="badge success">Via patched resolver</span></td>
+                <td><span class="badge info">Partial (Node ≥14.6+)</span></td>
+                <td><span class="badge success">With ts-node</span></td>
+                <td><span class="badge success">If Babel configured</span></td>
+            </tr>
+            <tr>
+                <td>Works in Jest</td>
+                <td><span class="badge warning">Same as module-alias (needs moduleNameMapper)</span></td>
+                <td><span class="badge warning">Requires Jest config</span></td>
+                <td><span class="badge success">With ts-jest</span></td>
+                <td><span class="badge success">If Babel used in Jest</span></td>
+            </tr>
+            <tr>
+                <td>Production-Ready Performance</td>
+                <td><span class="badge success">8.7x faster @ 1k aliases, 60% less RAM</span></td>
+                <td><span class="badge danger">Degrades with scale</span></td>
+                <td><span class="badge danger">Not for pure JS projects</span></td>
+                <td><span class="badge danger">Build-only</span></td>
+            </tr>
+            <tr>
+                <td>Default Presets</td>
+                <td><span class="badge success">@root, @src auto-applied</span></td>
+                <td><span class="badge danger">None</span></td>
+                <td><span class="badge danger">None</span></td>
+                <td><span class="badge danger">None</span></td>
+            </tr>
+            <tr>
+                <td>Friendly Error Messages</td>
+                <td><span class="badge success">Clear, actionable errors</span></td>
+                <td><span class="badge warning">Generic errors</span></td>
+                <td><span class="badge warning">TS cryptic errors</span></td>
+                <td><span class="badge warning">Babel errors</span></td>
+            </tr>
+        </tbody>
+    </table>
+
+    <hr>
+
+    <h2>Installation</h2>
+    <pre><code class="language-bash">npm install pathlra-aliaser</code></pre>
+
+    <hr>
+
+    <h2>Configuration via package.json</h2>
+    <pre><code class="language-json">{
+  "name": "name",
+  "version": "4",
+  "main": "index.js",
+  "dependencies": {
+    "pathlra-aliaser": "^3.6.7"
+  },
+  "path_aliaser": {
+    "@products": "./routes/products.js",
+    "@users": "./routes/users.js",
+    "@logger": "./utils/logger.js"
+  },
+  "_moduleDirectories": ["node_modules", "custom_libs"],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "license": "ISC",
+  "description": "High-performance path alias resolver for Node.js with LRU caching and radix-tree optimization"
+}</code></pre>
+    <p><em>Paths are relative to the project root.</em></p>
+    <p><code>_moduleDirectories</code> extends Node.js’s search paths safely.</p>
+
+    <hr>
+
+    <h2>Example Usage</h2>
+    <pre><code class="language-js">"use strict";
+require("pathlra-aliaser")(); // Must be called BEFORE any aliased requires
+const logger = require("@utils/logger");
+const User = require("@models/User");</code></pre>
+
+    <hr>
+
+    <h2>Advanced Features</h2>
+    <p><strong>Dynamic Aliases:</strong></p>
+    <pre><code class="language-js">const aliaser = require("pathlra-aliaser");
+aliaser.aa("@dynamic", () => "./runtime/path");</code></pre>
+
+    <p><strong>Add Custom Module Directory:</strong></p>
+    <pre><code class="language-js">aliaser.ap("./internal_modules");</code></pre>
+
+    <p><strong>Bulk Alias Registration:</strong></p>
+    <pre><code class="language-js">aliaser.addAliases({ "@core": "./src/core" });</code></pre>
+
+    <hr>
+
+    <h2>Performance & Benchmarks</h2>
+    <ul>
+        <li>Cache: 10,000 entries by default</li>
+        <li>Eviction: 10% of least-used entries per batch</li>
+        <li>Memory usage: &lt;2 MB with 1,000+ aliases</li>
+    </ul>
+    <p><strong>Benchmarks vs module-alias:</strong></p>
+    <ul>
+        <li>3.2x faster (10 aliases)</li>
+        <li>8.7x faster (1,000 aliases)</li>
+        <li>60% lower memory usage under load</li>
+    </ul>
+
+    <hr>
+
+    <h2>Ideal For</h2>
+    <ul>
+        <li>Large-scale Node.js applications</li>
+        <li>Microservices</li>
+        <li>Performance-critical systems</li>
+        <li>Long-running processes</li>
+        <li>Teams enforcing standardized path conventions</li>
+    </ul>
+    <p><strong>Not for:</strong> Frontend bundling, TypeScript-only projects (unless with ts-node), or projects preferring config files over package.json.</p>
+
+    <hr>
+
+    <h2>Common Misconceptions</h2>
+    <ul>
+        <li>“I need to call <code>aa()</code> for every alias.” → No, <code>package.json</code> is enough.</li>
+        <li>“It modifies global behavior unsafely” → Only patches Node.js resolver safely.</li>
+        <li>“It slows down my app.” → Benchmarks show faster resolution than manual paths after warm-up.</li>
+    </ul>
+
+    <div class="footer">
+        <h2>License</h2>
+        <p>MIT © hub-mgv<br>
+        Engineered for speed. Built for scale. Designed to disappear.<br>
+        <code>pathlra-aliaser</code>: where path resolution becomes invisible.</p>
+    </div>
+</body>
+</html>
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pathlra-aliaser",
-  "version": "4.6.9",
+  "version": "4.7.0",
   "description": "High-performance path alias resolver for Node.js with LRU caching and radix-tree optimization",
   "main": "test.js",
   "scripts": {