@cldmv/slothlet

@cldmv/slothlet is a sophisticated module loading framework that revolutionizes how you work with massive APIs in Node.js. Built for developers who demand smart, efficient module loading without compromising performance or developer experience.

Choose your loading strategy based on your needs: lazy mode loads modules on-demand for faster startup and lower memory usage, while eager mode loads everything upfront for maximum runtime performance and predictable behavior.

With our copy-left materialization in lazy mode, you get the best of both worlds: the memory efficiency of on-demand loading with near-eager performance on repeated calls. Once a module is materialized, it stays materialized-no re-processing overhead.

The name might suggest we're taking it easy, but don't be fooled. Slothlet delivers speed where it counts, with smart optimizations that make your APIs fly.

🎉 Welcome to the future of module loading with Slothlet v3!

Where sophisticated architecture meets blazing performance - slothlet is anything but slow.

[!NOTE] 🚀 Production Ready Modes:

• Eager Mode: Fully stable and production-ready for immediate module loading
• Lazy Mode: Production-ready with advanced copy-left materialization and 2.2x faster startup (function calls within 6% of eager - essentially equal)

🎉 Introducing Slothlet v3.0

[!IMPORTANT] Slothlet v3.0 is a major release - the biggest since v2.0.

v3 rebuilds Slothlet from the inside out with a Unified Wrapper architecture that delivers consistent, inspectable, hook-intercepted API proxies across every loading mode. On top of this foundation comes a redesigned hook system with three-phase subset ordering, per-request context isolation improvements, a full internationalization layer, background materialization with progress tracking, granular API mutation controls, collision modes for runtime API management, and lifecycle events for every stage of the module lifecycle.

Every feature has been hardened with a comprehensive test suite - over 5,300 tests across eager, lazy, CJS, ESM, TypeScript, and mixed module scenarios.

📋 See the full v3.0 changelog for the architecture rewrite, hook system redesign, i18n layer, background materialization, lifecycle events, collision modes, mutation controls, sanitization improvements, and context isolation upgrades.

✨ What's New

Latest: v3.7.0 (May 2026)

• Read-level permission gating — the permission system now checks property reads of data values, not just function calls. Until now a module exporting a Buffer, TypedArray, Date, or primitive left that value readable by any other module via self.something.value regardless of deny rules — the check fired at invocation, and a data value has no invocation step. Reading a terminal data value off a module API path is now enforced against the rule set exactly like a call, targeting its leaf path. This is on by default when permissions is configured (set readGating: false to opt out) — a defaultPolicy: "deny" config will now deny cross-module data reads unless an allow rule covers the path.
• Runtime-toggleable — read gating can be flipped after instance creation via api.slothlet.permissions.control.readGating(true|false). Namespace traversal stays ungated (no per-segment allow rules needed), callable functions remain call-gated, external user-code reads are exempt, and the self-call bypass still applies.
• View full v3.7.0 Changelog

Recent Releases

• v3.6.0 (May 2026) — self.slothlet.lockCaller() / bind() pin caller identity onto callbacks; hooks and run/scope callbacks keep caller identity (Changelog)
• v3.5.1 (May 2026) — Binary buffers (Buffer / TypedArray / DataView) cross self unwrapped; relative imports work from .ts / .mts modules (Changelog)
• v3.5.0 (May 2026) — TypeScript runtime imports (self / context / instanceID) work from .ts / .mts; slothlet typegen CLI + programmatic API; runtime self.X = … assignment now persists (Changelog)
• v3.4.1 (May 2026) — Permission gating for all api.slothlet.* routes; metadata hardening against prototype-pollution and circular payloads (Changelog)

📚 For complete version history and detailed release notes, see docs/changelog/ folder.

🚀 Key Features

🎯 Dual Loading Strategies

• Eager Loading: Immediate loading for maximum performance in production environments
• Lazy Loading: Copy-left materialization with look-ahead proxies (2.2x faster startup, function calls equal to eager after materialization)

[!IMPORTANT] Function Call Patterns:

• Lazy Mode: ALL function calls must be awaited (await api.math.add(2, 3)) due to materialization process
• Eager Mode: Functions behave as originally defined - sync functions are sync (api.math.add(2, 3)), async functions are async (await api.async.process())

⚡ Performance Excellence

• Startup Performance: 2.2x faster startup in lazy mode (15.41ms vs 34.28ms)
• Runtime Performance: Function calls essentially equal between modes (9.99μs lazy vs 9.46μs eager - within 6% measurement noise)
• Copy-left materialization: Once loaded, modules stay materialized - no re-processing overhead
• Zero dependencies: Pure Node.js implementation
• Memory efficiency: Lazy mode loads modules on-demand, eager mode optimizes for predictable behavior

📊 For comprehensive performance benchmarks and analysis, see docs/PERFORMANCE.md

🎣 Hook System (redesigned in v3)

Powerful function interceptor system with 4 hook types and three-phase subset ordering:

• before - Modify arguments or cancel execution (must be synchronous)
• after - Transform return values
• always - Observe final results (read-only; fires even on short-circuit)
• error - Monitor and handle errors with detailed source tracking

Each hook type supports three ordered execution subsets: "before" → "primary" (default) → "after". Pattern matching, priority control, runtime enable/disable, and short-circuit support included.

🎣 For complete hook system documentation, see docs/HOOKS.md

🔐 Permission System (new in v3.3, read-gated in v3.7)

Path-based access control for inter-module API calls and data-value reads (v3.7+):

• Glob pattern rules — same *, **, ?, {a,b} syntax as hooks
• Most-specific-wins — exact patterns override broad globs; tiebreak by registration order
• Self-call bypass — calls within the same source file always succeed
• Read-level gating (v3.7) — terminal data-value reads (Buffer, TypedArray, Date, Map, primitives, …) checked against the rule set; on by default, readGating: false to opt out
• Audit events — permission:denied, permission:allowed, permission:default, permission:self-bypass
• Runtime management — api.slothlet.permissions.addRule(), .removeRule(), .self.*, .global.*, .control.*
• Context conditions (v3.4) — optional condition field; accepts a plain object (deep leaf matching), function, or array (OR); evaluated against per-request ALS context

🔐 For complete permission system documentation, see docs/PERMISSIONS.md · 📐 For condition syntax, see docs/PERMISSIONS-CONDITIONS.md

🌍 Full Internationalization (new in v3)

All error messages and debug output are translated. Supported languages: English · Spanish · French · German · Portuguese · Italian · Japanese · Chinese (Simplified) · Korean

Configure via i18n: { language: "es" } in your slothlet config. See docs/I18N.md.

🔄 Context Propagation

Automatic context preservation across all asynchronous boundaries:

• Per-request isolation: api.slothlet.context.run(ctx, fn) and api.slothlet.context.scope(ctx)
• EventEmitter propagation: Context maintained across all event callbacks
• Class instance propagation: Context preserved in class method calls
• Zero configuration: Works automatically with TCP servers, HTTP servers, and custom EventEmitters

🔄 For context propagation details, see docs/CONTEXT-PROPAGATION.md

🔧 Smart API Management

• Intelligent Flattening: Clean APIs with automatic structure optimization (math/math.mjs → api.math)
• Smart Naming: Preserves original capitalization (auto-ip.mjs with autoIP → api.autoIP)
• Advanced Sanitization: Custom naming rules with glob and boundary patterns; api.slothlet.sanitize() at runtime
• Hybrid Exports: Support for callable APIs with methods, default + named exports

🏗️ Module structure · 📐 API flattening · 🔡 Sanitization

🔗 Runtime & Context System

• Context Isolation: Automatic per-request isolation using AsyncLocalStorage (default); switchable to live-bindings mode via runtime: "live" config option
• Cross-Module Access: self, context, and instanceID always available inside API modules via @cldmv/slothlet/runtime — works identically from .mjs, .cjs, .ts, and .mts
• Mixed Module Support: Seamlessly blend ESM and CommonJS modules
• Copy-Left Preservation: Materialized functions stay materialized

🛠 Developer Experience

• TypeScript-Friendly: Comprehensive JSDoc annotations with auto-generated declarations — see docs/TYPESCRIPT.md
• Configurable Debug: Detailed logging via CLI flags or environment variables
• Multiple Instances: Parameter-based isolation for complex applications
• Inspectable APIs: console.log(api.math) and logical versioned paths like console.log(api.auth) show real module contents instead of proxy internals (v3+)
• Development Checks: Built-in environment detection with silent production behavior

📦 Installation

Requirements

• Node.js v20.19.0 or higher

Install

npm install @cldmv/slothlet

🚀 Quick Start

import slothlet from "@cldmv/slothlet";

// Eager mode (default) — functions behave as originally defined
const api = await slothlet({
	dir: "./api",
	context: { user: "alice" }
});

const result = api.math.add(2, 3); // Sync stays sync
const asyncResult = await api.async.process(); // Async stays async

CommonJS works the same way: const slothlet = require("@cldmv/slothlet").

Lazy mode with copy-left materialization — all calls awaited, ~2.2× faster startup:

const api = await slothlet({ mode: "lazy", dir: "./api" });
const result = await api.math.add(2, 3); // ALL calls awaited in lazy mode

Hooks, dynamic API extension (api.slothlet.api.add/remove/reload), per-request context (api.slothlet.context.run/scope), and lifecycle events are all covered in the linked technical guides below.

📚 Configuration

The most-used options are summarized below. The complete reference — every option, every diagnostic, every deprecated alias — lives in docs/CONFIGURATION.md.

| Option | Type | Default | Description | | ------------- | -------- | ----------- | ---------------------------------------------------------------------------------- | | dir | string | "api" | Directory to load API modules from | | mode | string | "eager" | "eager" (load upfront) or "lazy" (on-demand with copy-left materialization) | | runtime | string | "async" | "async" (AsyncLocalStorage) or "live" (live-bindings) | | context | object | {} | Per-request context — read via import { context } from "@cldmv/slothlet/runtime" | | hook | mixed | false | Enable hooks; see HOOKS.md | | permissions | object | undefined | Path-based access control; see PERMISSIONS.md | | i18n | object | {} | Language for translated error/debug messages — see I18N.md |

Also configurable: apiDepth, debug, reference, sanitize, backgroundMaterialize, api.collision, api.mutations, versionDispatcher, typescript, plus diagnostics and lifecycle internals. All documented in CONFIGURATION.md.

🔀 Loading Modes

| Mode | Startup | Function calls | Best for | | -------------------------------------- | -------------- | --------------------------------------------- | --------------------------------------------------- | | Eager (default) | Loads upfront | Sync stays sync, async stays async | Production, predictable performance | | Lazy | 2.2× faster | All calls awaited; materialized on first use | Large APIs, startup-sensitive apps | | Lazy + backgroundMaterialize | 2.2× faster | Pre-warmed by background loader | Best of both — lazy startup, eager runtime |

// Lazy + background materialization
const api = await slothlet({ mode: "lazy", dir: "./api", backgroundMaterialize: true });
api.slothlet.lifecycle.on("materialized:complete", ({ total }) => console.log(`${total} modules ready`));
await api.slothlet.materialize.wait(); // optional: gate traffic on ready

📊 Benchmarks & analysis: docs/PERFORMANCE.md · 🔀 Visual pipeline diagram: docs/MODULE-STRUCTURE.md#loading-pipeline-overview · ⚡ Lifecycle events: docs/LIFECYCLE.md

🎣 Hooks

Four hook types (before, after, always, error) with three-phase subset ordering ("before" → "primary" → "after"), pattern matching, priority, and runtime enable/disable.

const api = await slothlet({ dir: "./api", hook: true });

api.slothlet.hook.on("before:math.add", ({ args }) => [args[0] * 2, args[1] * 2], { id: "double" });
api.slothlet.hook.on("after:math.*", ({ result }) => result * 10, { id: "scale" });
api.slothlet.hook.on("always:**", ({ path, hasError }) => console.log(path, hasError));
api.slothlet.hook.on("error:**", ({ path, error, source }) => console.error(path, source.type, error));

const out = await api.math.add(2, 3); // hooks fire automatically

🎣 Configuration, all four types, subsets, pattern syntax, management API: docs/HOOKS.md

🔄 Per-Request Context

// Scoped context for a single call
await api.slothlet.context.run({ userId: "alice", role: "admin" }, async () => {
	await api.database.query();
	await api.audit.log();
});

// Derived API with merged context
const scoped = api.slothlet.context.scope({ userId: "bob" });
await scoped.database.query();

Context propagates automatically through EventEmitter callbacks (TCP/HTTP servers, custom emitters), class methods, and every async boundary. Inside modules: import { context, instanceID } from "@cldmv/slothlet/runtime".

🔄 Full reference, isolation guarantees, merge strategies, TCP/HTTP examples: docs/CONTEXT-PROPAGATION.md

🔁 Hot Reload & Dynamic API

await api.slothlet.api.add("plugins", "./plugins-folder"); // add at runtime
await api.slothlet.api.add("plugins.trusted", "./trusted", { metadata: { trusted: true } });
await api.slothlet.api.remove("oldModule"); // remove
await api.slothlet.api.reload("database.*"); // hot-reload

Collision modes (merge / skip / overwrite / throw) — independently configurable for initial load vs runtime add(). Mutation controls let you disable add / remove / reload in production. Eager vs lazy reload semantics differ (eager merges into the live wrapper; lazy resets to an unmaterialized proxy).

🔁 Full reference: docs/RELOAD.md · 🏷️ Metadata system: docs/METADATA.md

⚡ Lifecycle Events

api.slothlet.lifecycle.on("materialized:complete", ({ total }) => console.log(`${total} modules ready`));
api.slothlet.lifecycle.on("impl:created", ({ apiPath }) => {
	/* … */
});
api.slothlet.lifecycle.on("impl:changed", ({ apiPath }) => {
	/* reload notify */
});
api.slothlet.lifecycle.on("impl:removed", ({ apiPath }) => {
	/* cleanup */
});

Events: materialized:complete, impl:created, impl:changed, impl:removed. Public surface is on / off only.

⚡ Full reference: docs/LIFECYCLE.md

📁 Module Structure

api/
├── config.mjs              → api.config.*
├── math/
│   └── math.mjs            → api.math.*       (flattened — filename matches folder)
├── util/
│   ├── util.mjs            → api.util.*       (flattened methods)
│   ├── extract.mjs         → api.util.extract.*
│   └── controller.mjs      → api.util.controller.*
└── nested/date/date.mjs    → api.nested.date.*

API modules must never import each other directly — use the live-binding runtime:

// ❌ WRONG — breaks lazy loading and context isolation
import { math } from "./math/math.mjs";

// ✅ CORRECT — always reflects current runtime state
import { self, context, instanceID } from "@cldmv/slothlet/runtime";

export const myModule = {
	async processData(input) {
		const r = self.math.add(2, 3);
		console.log(`[${instanceID}] caller=${context.userId}`);
		return `Processed: ${input}, Math: ${r}`;
	}
};

The same import works from .mjs, .cjs (via require), .ts, and .mts (TypeScript path fixed in v3.5.0).

🏗️ Module structure patterns · 📐 All 13 API transformation rules

🛡 Error Handling

Slothlet v3 uses a rich SlothletError class with translated messages and contextual hints:

try {
	await api.slothlet.api.add("plugins", "./dir");
} catch (error) {
	console.error(error.message); // Translated error message
	console.error(error.hint); // Contextual hint for resolution
	console.error(error.code); // Machine-readable error code
}

🏗️ Production & Development

• Eager Mode: Stable, battle-tested, maximum runtime performance
• Lazy Mode: Production-ready with copy-left optimization
• Background Materialization: Lazy startup + eager runtime performance
• Mixed Module Loading: ESM/CJS interoperability fully supported
• Debug Mode: i18n-translated logging via --slothletdebug flag or SLOTHLET_DEBUG=true
• Source Detection: Automatic src/ vs dist/ mode detection
• API Inspection: console.log(api.math) and versioned dispatcher paths show real module contents (v3+)

📚 Documentation

Reference

• Configuration Reference — every option with defaults, validation rules, and the api.slothlet.diag.* namespace
• Generated API Reference — auto-generated from JSDoc; the complete public surface
• Changelog — all release notes (v2 + v3)
• Migration Guide — upgrading from v2.x

Technical Guides

• Performance Analysis — startup vs runtime benchmarks, memory analysis, materialization cost breakdown
• Hook System — 4 types, three-phase subsets, pattern matching, management API
• Permission System — rules, glob patterns, self-call bypass, read gating, runtime management
• Permission Conditions — condition field syntax: deep object matching, functions, OR arrays
• Context Propagation — per-request isolation, EventEmitter / class propagation, merge strategies
• Lifecycle Events — materialized:complete, impl:* events, subscription API
• Hot Reload & Dynamic API — add, remove, reload, collision modes, mutation controls, eager vs lazy semantics
• Versioning — multi-version module dispatch, versionDispatcher, version metadata
• Metadata System — function metadata tagging for security, authorization, auditing
• Module Structure — organization patterns, examples, and the loading-pipeline diagram
• Sanitization — filename → property-name transformation rules
• TypeScript Support — fast mode (esbuild), strict mode (tsc), .d.ts generation
• Internationalization — supported languages and configuration

API Rules & Transformation

• API Rules — all 13 transformation rules with verified test examples
• API Rules Conditions — every conditional that controls API generation
• API Flattening — flattening rules with decision tree

Repo

• Agent Usage Guide — for AI agents building Slothlet API folders
• Contributing — contribution guidelines
• Security Policy — security guidelines and reporting
• Test Documentation — comprehensive test module examples

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

🔗 Links

• npm: @cldmv/slothlet
• GitHub: CLDMV/slothlet
• Issues: GitHub Issues
• Releases: GitHub Releases

📄 License

Apache-2.0 © Shinrai / CLDMV

🙏 Acknowledgments

To my wife and children - thank you for your patience, your encouragement, and the countless hours you gave me to build this. None of it would exist without your support.