v3.0.0
release: v3.0.0 (#74)
Release: v3.0.0 — Complete Ground-Up Proxy Architecture Rewrite with Zero Runtime Dependencies
BREAKING CHANGE: complete v3 rewrite. See migration guide in README.md.
hook:config key replaceshooks:(singular)collision:config replacesallowMutation/allowConflictapi.slothlet.*is the new management namespace (no top-level helpers)- Minimum Node.js version is 16.20.2 (CallSite API regression in 16.4–16.19)
- All internal proxy properties are private; no direct access to wrapper internals
🚀 MAJOR VERSION RELEASE — FULL GROUND-UP REWRITE WITH UNIFIED WRAPPER ARCHITECTURE
• Implement UnifiedWrapper proxy-based architecture replacing all v2 wrapper types with a single, consistent implementation
• Introduce dual-context model: async mode (AsyncLocalStorage) and live mode (live bindings) for per-request isolation
• Implement lazy + eager loading strategies with full feature parity across both modes
• Implement complete hook system with before/primary/after subset execution phases and pattern matching
• Implement api.slothlet management namespace exposing hook, api, context, lifecycle, metadata, owner, sanitize, and diagnostics
• Achieve 100% branch and statement coverage across all source files
• Ship zero runtime dependencies — all functionality self-contained
✨ SMART FLATTENING ARCHITECTURE — ALL 13 RULES IMPLEMENTED
• Rule 1: filename-matches-container flattening extended to addApi runtime context
• Rule 6: folder/folder.mjs flattening with function-name preference (Rule 9)
• Rule 11: addapi.mjs special file pattern for plugin-style runtime API extensions — auto-flattens regardless of autoFlatten setting
• Rule 12: module ownership with selective API overwrite via forceOverwrite and allowApiOverwrite — validated across 17 configurations
• Rule 13: addApi path deduplication flattening and isDirectChild guard for mount folder root files
• Folder transparency: single-file subdirectories collapse into parent namespace
• Smart flattening decisions work identically during initial load and addApi runtime context
• Complete rule traceability system with automated test coverage mapping
🔧 PROXY ARCHITECTURE AND CORE ENGINE
• UnifiedWrapper: single proxy class handling lazy materialization, live bindings, collision resolution, ownership, hooks, and context
• Private class fields for all internal state; resolveWrapper() replaces direct ____slothletInternal access
• Lazy materialization: background option, deduplication, reference preservation across reload
• Collision modes: merge / replace / skip / warn / error — configurable per initial load and addApi
• CJS cache busting: require() cache cleared per-instance to ensure isolation across multiple instances
• api.add() supports file path, directory, or array inputs with full collision and ownership support
• api.remove() with deleteProperty trap, ownership cleanup, and cache invalidation
• Symbol.toStringTag, util.inspect.custom, toJSON, and toString proxy traps for correct console output
• Reflect.apply used in lazy mode to preserve this binding and prevent double hook execution
🔐 SECURITY HARDENING
• Lifecycle metadata token and wrapper exposure restricted; lifecycle public API limited to on/off
• Proxy C/D internals blocked; prototype chain walk gap closed
• All informational proxy properties enforced read-only
• ___getState removed from proxy surface and prototype
• api.add() internal options filtered before user-controllable parameter exposure
• Context isolation fixed: deep clone parent context in .run()/.scope() preventing cross-request mutation
• ReDoS vulnerability fixed in i18n placeholder cleanup regex (CodeQL high severity)
• Regex injection fixed in --file-pattern CLI argument parsing
• Backslash escaping fixed in Markdown table type-name helpers
🌍 I18N SYSTEM — 11 LANGUAGES, ALL MESSAGES KEYED
• Complete internationalization: every error, warning, and debug message keyed through translation system
• 173 hardcoded debug messages migrated to DEBUG_MODE_* translation keys
• 11 languages: en-us, en-gb, de-de, es-mx, fr-fr, hi-in, ja-jp, ko-kr, pt-br, ru-ru, zh-cn
• Auto-detect language from environment; runtime switch via api.slothlet.i18n
• Orphaned key scanner with balanced-paren extractor replacing fragile regex detection
• analyze-errors tool validates i18n completeness, placeholder parity, and debug conventions
📦 TYPESCRIPT SUPPORT — FAST AND STRICT MODES
• Fast mode: esbuild compilation, no type checking, zero-config .ts file loading alongside .mjs/.cjs
• Strict mode: tsc compilation with full type checking and automatic .d.ts generation
• Self declaration added to generated TypeScript types
• Both esbuild and typescript remain optional peer dependencies
• api_tests excluded from type generation reducing noise from test-only patterns
🔄 RELOAD AND LIFECYCLE SYSTEM
• Full hot reload: reuses load() and replays operations for minimal diff
• Selective module reload by moduleID with reference preservation across reload
• Hooks persist across reload; AsyncLocalStorage cleaned up on shutdown
• Shutdown is idempotent; lifecycle events: impl:added, impl:removed, impl:replaced
• api.slothlet.materialize tracking for lazy materialization progress
• backgroundMaterialize config option (default false)
• Metadata preserved across hot reload; setForPath / removeForPath reload-with-metadata option
📚 DOCUMENTATION — COMPLETE V3 REWRITE
• README.md: complete v3 rewrite with migration guide from v2
• AGENT-USAGE.md, BUGS.md, CONTRIBUTING.md, SECURITY.md: all rewritten for v3
• docs/API-RULES.md: all 13 rules with conditions, examples, and rule traceability
• docs/CONFIGURATION.md, HOOKS.md, I18N.md, LIFECYCLE.md, METADATA.md, CONTEXT-PROPAGATION.md, RELOAD.md, TYPESCRIPT.md, MODULE-STRUCTURE.md, SANITIZATION.md, PERFORMANCE.md: all new for v3
• Generated API.md via jsdoc2md with SlothletOptions/SlothletAPI typedefs, sorted properties, function sections, and filtered @internal modules
🛠️ BUILD, TOOLS, AND INFRASTRUCTURE
• tools/ reorganized into dev/, build/, ci/ subdirectories
• @cldmv/fix-headers package replaces inline fix-headers.mjs
• @cldmv/vitest-runner package delegates vitest execution with argument passthrough
• Quiet coverage mode with live progress and OS-agnostic run lock
• build:ci pipeline: cleanup → dist copy → types → exports → type-check → license → src cleanup
• import.meta.dirname replaced with dirname(fileURLToPath(import.meta.url)) for Node 16–20 compat
• All is-main guards standardized to process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
• build/ gitignore anchored to /build/ so tools/build/ is not ignored
• src/ stripped from NODE_OPTIONS post-build when dist/ is the target
Technical Implementation:
- UnifiedWrapper proxy class as the single wrapper type for all API nodes across eager and lazy modes
- ComponentBase extended by all internal components providing this.slothlet, this.debug(), and lifecycle access
- ApiCacheManager: separate cache storage system integrated with api.add/remove/reload
- AsyncLocalStorage context (async mode) and live reactive bindings (live mode) — both per-instance isolated
- Hook phases: before (sync only) → primary → after, with pattern matching, apiDepth, and subset ordering
- Ownership system: moduleID registration, collision mode propagation, stacked restore on unregister
- i18n: synchronous JSON loading replacing async .mjs; SlothletError / SlothletWarning / SlothletDebug classes
- Path resolution: resolve-from-caller.mjs handles closures, nested helpers, and ALS context stacks
- CJS isolation: require() cache keyed by instanceID preventing cross-instance contamination
Use Case Examples:
- Plugin systems: addapi.mjs pattern enables clean runtime namespace extension with auto-flattening
- Hot reload: full and selective reload with reference preservation and hook/context continuity
- Multi-runtime: per-request context isolation via async mode (ALS) or live mode (reactive proxy)
- TypeScript projects: zero-config .ts loading in fast mode; full type checking in strict mode
- Large APIs: lazy materialization with background option and progress tracking via api.slothlet.materialize
- Collision management: fine-grained control per initial load and addApi with merge/replace/skip/warn/error
Impact Assessment:
Complete architectural replacement — v3 is a ground-up rewrite addressing every known v2 limitation. Proxy-based unified wrapper eliminates inconsistencies between lazy and eager modes. Zero runtime dependencies reduces package surface. 100% coverage guarantees correctness of all branches. Full i18n removes all hardcoded messages. Security hardening closes proxy inspection and context mutation gaps. Smart flattening Rules 1–13 enable clean plugin and modular architectures.
Breaking Changes:
hook:replaceshooks:in config (singular key)collision:config replacesallowMutation/allowConflictapi.slothlet.*is the management namespace — no top-level helper exports- Minimum Node.js version is 16.20.2 (16.4–16.19 affected by CallSite regression)
- Internal wrapper properties are private and inaccessible through proxy
- No direct access to ____slothletInternal from outside the class
Testing Coverage:
100% branch and statement coverage across all source files. 29 Vitest suite directories. Matrix testing across all mode/runtime combinations (eager/lazy × async/live). Rule 12 ownership validated across 17 configurations. Path resolution tests for closures, nested calls, and ALS contexts. CJS isolation, TypeScript fast/strict, reload reference preservation, hook subset ordering, collision mode matrix, and context isolation deep-clone tests all covered.
Files Changed: 700+ files across complete architecture rewrite, documentation, test suites, and tooling
Commits: 400+ commits including architecture refactor, feature implementation, coverage work, security hardening, documentation, and CI fixes
Performance Impact: lazy materialization deferred until first access; background mode available; coverage-quiet mode and run lock prevent interference; path resolution cached; no runtime dependencies to load.
Production Ready: 100% coverage, comprehensive matrix testing, security-hardened proxy surface, zero runtime dependencies, cross-Node version compatibility (16.20.2–24.x).
This release establishes the v3 foundation: a clean, consistent, fully-tested proxy architecture that enables reliable plugin systems, hot reload, per-request context isolation, and TypeScript support while eliminating all v2 architectural limitations.
Full Changelog: v2.11.0...v3.0.0
