@teqfw/di 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.0.3 - 2026-03-07 - Package agent interface
+
+- Added `ai/` to the published package file list.
+- Updated package version metadata to `2.0.3`.
+
 ## 2.0.2 - 2026-03-05
 
 - Replaced `tsconfig.json` with `jsconfig.json` for JavaScript type-checking configuration.

package/ai/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+Version: 20260307
+
+## Package Purpose
+
+This directory provides the **Agent Interface** of the package. It contains a compact usage-oriented description intended for LLM agents that use the package as a dependency. The documents describe how the package is applied by external code and exclude development methodology, repository organization, testing infrastructure, and other internal aspects of the project.
+
+The package implements a **dependency container for ES modules** based on runtime late binding. Dependencies between modules are resolved by the container using structured dependency identifiers and deterministic namespace resolution rules rather than static imports. The container dynamically loads ES modules, instantiates exported factories, and returns linked objects according to dependency identifier semantics.
+
+## When to Use This Package
+
+This package should be used when a system requires the following capabilities:
+
+- runtime dependency injection
+- late binding between ES modules
+- deterministic dependency resolution
+- controlled instantiation of components
+- modules that remain environment-agnostic across Node.js and browser runtimes
+
+The container serves as the **composition root** of the application. Application modules declare dependencies and receive instantiated objects from the container rather than resolving dependencies directly.
+
+## Architectural Model
+
+The system is based on four mechanisms:
+
+- **Late binding of dependencies at runtime**, allowing modules to remain independent of specific implementations.
+- **A container responsible for dependency resolution and instantiation**, which loads modules and produces linked objects.
+- **Structured dependency identifiers**, interpreted by the container to determine how a dependency must be resolved.
+- **Namespace mapping rules**, which deterministically translate identifiers into module locations.
+
+Together these mechanisms form a deterministic runtime linking system for ES modules.
+
+## Runtime Linking Model
+
+The container acts as a runtime linker for ES modules.
+
+Instead of relying on static `import` statements, modules declare dependency contracts through `__deps__` descriptors and CDC identifiers. When a dependency is requested, the container resolves the identifier, loads the required module, constructs the object graph, and returns the linked result.
+
+In this model:
+
+- ES modules provide implementations.
+- CDC identifiers define dependency contracts.
+- the container performs deterministic runtime linking.
+
+This mechanism separates module implementation from dependency binding and allows systems to assemble component graphs dynamically while preserving deterministic behavior.
+
+## Reading Order
+
+Agents should read the documents in this directory in the following order:
+
+1. **AGENTS.md** — overview of the package and navigation of the Agent Interface.
+2. **concepts.md** — architectural concepts and design principles.
+3. **container.md** — container responsibilities and dependency resolution pipeline.
+4. **dependency-id.md** — syntax and semantics of dependency identifiers.
+5. **extensions.md** — extension mechanisms such as preprocessors and wrappers.
+6. **usage.md** — minimal usage scenarios and examples.
+
+This sequence reflects the conceptual flow required to understand the package: architectural model → operational mechanism → dependency addressing → extension points → practical usage.
+
+## Interface Scope
+
+The documents in this directory define the supported usage semantics of the package. Behaviors not described here should be treated as undefined and should not be inferred. The interface intentionally contains only the information required to correctly apply the package in external code.
+
+## Relation to TeqFW
+
+The package follows architectural principles used in the **Tequila Framework (TeqFW)** platform, including:
+
+- late binding between components
+- separation of data structures and logic handlers
+- namespace-based module organization
+- development in modern JavaScript without compilation
+
+Understanding the broader TeqFW ecosystem is not required to use the package, but the container follows the same architectural philosophy.

package/ai/concepts.md

@@ -0,0 +1,66 @@
+# concepts.md
+
+Version: 20260307
+
+## Purpose of the Container
+
+The container provides a deterministic mechanism for linking ES modules at runtime. Instead of static imports between modules, dependencies are resolved through a central container that loads modules, instantiates exported factories, and returns linked objects. This approach separates module implementation from dependency resolution and allows systems to assemble components dynamically.
+
+## Late Binding
+
+Dependencies between modules are resolved at runtime rather than during module loading. Modules do not import their collaborators directly and therefore remain independent of concrete implementations. The container performs dependency resolution when an object is requested, which allows components to be replaced, extended, or mocked without modifying module code.
+
+Late binding enables the following properties:
+
+- reduced coupling between modules
+- runtime replacement of implementations
+- simplified testing through dependency substitution
+- compatibility with different runtime environments
+
+## Dependency Container
+
+The container acts as the composition root of the application. It receives dependency requests expressed as identifiers, resolves them into module locations, loads the corresponding ES modules, and produces linked objects.
+
+The container is responsible for:
+
+- translating dependency identifiers into module references
+- loading ES modules dynamically
+- instantiating exported factories
+- applying preprocessing and postprocessing steps
+- returning fully linked objects to the caller
+
+Application modules do not construct their dependencies directly and do not perform dependency resolution.
+
+## Dependency Identifiers
+
+Dependencies are addressed using structured identifiers interpreted by the container. An identifier describes how the dependency should be resolved and how the resulting object should be instantiated.
+
+Dependency identifiers define:
+
+- which module provides the dependency
+- which export must be used
+- whether the dependency represents a singleton or a new instance
+
+The identifier syntax and resolution rules are described in **dependency-id.md**.
+
+## Namespaces
+
+Namespaces provide deterministic mapping between logical identifiers and module locations. Each package defines a namespace root that corresponds to a directory containing source modules.
+
+The container resolves identifiers by applying namespace rules that translate identifier prefixes into filesystem paths. This mechanism allows modules to be referenced through stable logical names instead of file paths.
+
+Namespace resolution ensures:
+
+- predictable module addressing
+- isolation between packages
+- consistent mapping between identifiers and modules
+
+## Immutable Linked Objects
+
+Objects returned by the container represent linked components of the application and are treated as immutable values. After an object is created and linked, it is frozen to prevent runtime modification.
+
+Immutability ensures that:
+
+- components behave consistently after linking
+- shared instances cannot be altered by consumers
+- the container remains the single authority responsible for object construction

package/ai/container.md

@@ -0,0 +1,72 @@
+# container.md
+
+Version: 20260307
+
+## Role of the Container
+
+The container provides the operational mechanism that links ES modules at runtime. It resolves dependency identifiers, loads modules, instantiates exported factories, and returns fully linked objects. The container serves as the composition root of the system and centralizes all dependency resolution.
+
+Application modules do not resolve dependencies themselves and do not construct collaborators directly. Instead, they request dependencies from the container using dependency identifiers.
+
+## Container Responsibilities
+
+The container performs the following responsibilities:
+
+- interpret dependency identifiers
+- resolve identifiers into module locations
+- load ES modules dynamically
+- instantiate exported factories
+- apply preprocess and postprocess handlers
+- manage object lifecycle semantics
+- freeze linked objects before returning them
+
+These responsibilities ensure deterministic runtime linking between modules.
+
+## Dependency Resolution Pipeline
+
+When a dependency is requested, the container processes the request through a deterministic pipeline consisting of the following stages:
+
+1. **Parse** — interpret the dependency identifier.
+2. **Preprocess** — allow registered preprocess handlers to transform the identifier.
+3. **Resolve** — translate the identifier into a module reference.
+4. **Instantiate** — load the module and create the object using the selected export.
+5. **Postprocess** — apply wrapper handlers to the created object.
+6. **Lifecycle** — apply lifecycle semantics such as singleton caching or instance creation.
+7. **Freeze** — freeze the resulting object before returning it.
+
+This pipeline ensures that all dependencies are created and linked through a consistent process.
+
+## Container API
+
+The container exposes a minimal public interface used by application code and configuration code.
+
+The core operations are:
+
+- **register(identifier, value)** — register a predefined dependency or instance in the container.
+- **get(identifier)** — resolve a dependency identifier and return the linked object.
+- **addPreprocess(handler)** — register a handler that can transform dependency identifiers before resolution.
+- **addPostprocess(handler)** — register a handler that can modify created objects after instantiation.
+
+The exact semantics of dependency identifiers are defined in **dependency-id.md**.
+
+## Container State Model
+
+The container operates in three states:
+
+- **initial** — the container is being configured and dependencies may be registered.
+- **active** — the container resolves dependencies and produces linked objects.
+- **failed** — the container has encountered an unrecoverable error.
+
+If an error occurs during dependency resolution or any pipeline stage, the container transitions to the **failed** state. Once the container enters this state, all subsequent dependency requests are rejected.
+
+This fail-fast behavior prevents partially linked systems from continuing execution.
+
+## Object Linking and Freezing
+
+Objects returned by the container represent linked components of the application. After an object is created and all pipeline stages are completed, the container freezes the object before returning it.
+
+Freezing ensures that:
+
+- linked objects cannot be modified by consumers
+- shared instances remain stable
+- the container remains the only authority responsible for object construction and linking

package/ai/dependency-id.md

@@ -0,0 +1,116 @@
+# dependency-id.md
+
+Version: 20260307
+
+## Purpose
+
+Dependencies in the container are addressed using **Canonical Dependency Codes (CDC)**. A CDC is a structured identifier interpreted by the container to determine which module must be loaded, which export must be used, and how the resulting object must be instantiated.
+
+CDC provides a stable logical addressing mechanism that is independent of file paths and runtime environments.
+
+## Canonical Form
+
+A CDC follows the canonical structure:
+
+```txt
+[PlatformPrefix]ModuleName[__ExportName][Lifecycle][WrapperSuffixes]
+```
+
+The components have the following roles:
+
+- **PlatformPrefix** — optional prefix identifying a platform module source.
+- **ModuleName** — logical module identifier within a namespace.
+- **ExportName** — optional named export selector.
+- **Lifecycle** — marker defining instantiation semantics.
+- **WrapperSuffixes** — optional sequence of wrapper identifiers.
+
+Each CDC is interpreted deterministically by the container.
+
+## Platform Prefix
+
+A CDC may reference modules provided by the runtime platform or external packages.
+
+The following prefixes are supported:
+
+- **`node_`** — reference a built-in Node.js module.
+- **`npm_`** — reference a module from the npm ecosystem.
+
+Examples:
+
+```txt
+node_fs$
+npm_lodash$
+```
+
+If no platform prefix is present, the identifier refers to an application module resolved through namespace mapping.
+
+## Module Identification
+
+The **ModuleName** identifies the module that provides the dependency. Module identifiers use namespace-based naming and are translated into filesystem paths according to namespace resolution rules described in **container.md**.
+
+Identifier segments separated by underscores correspond to directory boundaries in the module path.
+
+Example:
+
+```txt
+App_Service_User
+```
+
+maps to a module located at:
+
+```txt
+AppRoot/Service/User.js
+```
+
+## Export Selection
+
+A CDC may reference either the default export of a module or a named export.
+
+Named exports are selected using a double underscore separator.
+
+Examples:
+
+```txt
+App_Service_User$
+App_Service_User__Factory$
+```
+
+The first identifier resolves the module default export. The second resolves the named export `Factory`.
+
+## Lifecycle Markers
+
+Lifecycle markers define how the container instantiates and returns objects.
+
+The following markers are supported:
+
+- **`$`** — singleton lifecycle; the container creates the object once and returns the same instance for subsequent requests.
+- **`$$`** — factory lifecycle; a new instance is created for each request.
+- **`$$$`** — transient lifecycle; the container delegates lifecycle management entirely to the caller.
+
+Lifecycle markers are appended at the end of the identifier.
+
+## Wrapper Suffixes
+
+Wrappers allow postprocessing of created objects. Wrapper identifiers are appended after the lifecycle marker and separated by underscores.
+
+Example:
+
+```txt
+App_Service_User$$_wrapLog_wrapTrace
+```
+
+In this example the container creates a new instance and applies the wrappers `wrapLog` and `wrapTrace` during the postprocess stage.
+
+Wrapper behavior is described in **extensions.md**.
+
+## Resolution Semantics
+
+When the container receives a CDC it performs the following interpretation steps:
+
+1. determine the platform prefix and module namespace
+2. resolve the module identifier into a module location
+3. select the requested export
+4. apply lifecycle semantics
+5. apply wrapper suffixes if present
+
+These interpretation steps integrate with the dependency resolution pipeline described in **container.md**.

package/ai/extensions.md

@@ -0,0 +1,71 @@
+# extensions.md
+
+Version: 20260307
+
+## Purpose
+
+The container supports controlled extension of the dependency resolution process through **preprocess handlers** and **postprocess wrappers**. These mechanisms allow the behavior of dependency resolution and object creation to be adjusted without modifying container internals.
+
+Extensions are registered during container configuration and become part of the deterministic resolution pipeline.
+
+## Extension Points
+
+Two extension points are available:
+
+- **Preprocess handlers** — transform dependency identifiers before resolution.
+- **Postprocess wrappers** — modify or decorate created objects after instantiation.
+
+These extension points correspond to the preprocess and postprocess stages of the container pipeline described in **container.md**.
+
+## Preprocess Handlers
+
+Preprocess handlers receive a dependency identifier before it is interpreted by the container. A handler may transform the identifier and return a modified value that continues through the resolution pipeline.
+
+Typical uses of preprocess handlers include:
+
+- rewriting dependency identifiers
+- applying identifier aliases
+- enforcing project-specific identifier conventions
+
+Preprocess handlers operate only on identifiers and do not interact with instantiated objects.
+
+## Postprocess Wrappers
+
+Postprocess wrappers operate on objects created by the container. A wrapper receives the instantiated object and may return a modified or decorated version.
+
+Wrappers are typically used for:
+
+- logging or tracing
+- instrumentation
+- capability injection
+- runtime adaptation of object behavior
+
+Wrappers do not modify the dependency resolution logic itself and operate only after object instantiation.
+
+## Wrapper Selection
+
+Wrappers are applied when their identifiers appear in a CDC. Wrapper identifiers are appended after the lifecycle marker and separated by underscores.
+
+Example:
+
+```txt
+App_Service_User$$_wrapLog_wrapTrace
+```
+
+In this example the container creates a new instance of the dependency and applies the wrappers `wrapLog` and `wrapTrace` during the postprocess stage.
+
+## Execution Order
+
+Multiple wrappers may be applied to a single dependency. Wrappers are executed in the order in which they appear in the CDC.
+
+Each wrapper receives the object returned by the previous wrapper and may return a new object that becomes the input to the next wrapper.
+
+## Extension Constraints
+
+Extensions must satisfy the following constraints:
+
+- they must be registered before the container becomes active
+- they must be deterministic and free of side effects that alter container state
+- they must not bypass lifecycle semantics enforced by the container
+
+These constraints ensure that extensions do not compromise deterministic dependency resolution.

package/ai/usage.md

@@ -0,0 +1,244 @@
+# usage.md
+
+Version: 20260307
+
+## Purpose
+
+This document describes typical usage patterns of the container. The examples illustrate how modules declare dependencies, how the container is configured in the composition root, and how Canonical Dependency Codes (CDC) control dependency resolution, instantiation, and behavioral modification.
+
+The container performs deterministic runtime linking of ES modules and returns frozen object graphs constructed from explicitly declared dependency contracts.
+
+## Module Structure
+
+Modules intended for container linking export a default class and may export a static dependency descriptor named `__deps__`.
+
+Dependencies are injected into the constructor as a single structured object. In TeqFW-style modules the public API is defined inside the constructor through assignments to `this`, while internal state may be held in constructor-local variables captured by closures.
+
+Example module:
+
+```js
+// @ts-check
+
+export const __deps__ = {
+  default: {
+    child: "App_Child$",
+  },
+};
+
+/**
+ * @typedef {Object} App_Root$Deps
+ * @property {App_Child} child
+ */
+
+export default class App_Root {
+  /**
+   * @param {App_Root$Deps} deps
+   */
+  constructor({ child }) {
+    this.getName = function () {
+      return "root";
+    };
+
+    this.getChild = function () {
+      return child;
+    };
+  }
+}
+```
+
+Dependency module:
+
+```js
+// @ts-check
+
+export default class App_Child {
+  constructor() {
+    this.getName = function () {
+      return "child";
+    };
+  }
+}
+```
+
+Rules:
+
+- if `__deps__` is absent the module has no dependencies
+- `__deps__.default` describes dependencies of the default export
+- keys correspond to constructor dependency names
+- values are CDC identifiers
+- dependencies are resolved recursively before instantiation
+
+## Container Configuration
+
+The container is configured in the composition root of the application. Namespace roots define how CDC prefixes map to module locations.
+
+```js
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Container from "@teqfw/di";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const container = new Container();
+
+container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
+```
+
+Configuration must be completed before the first dependency resolution.
+
+## Resolving Dependencies
+
+Dependencies are obtained using CDC identifiers.
+
+```js
+const root = await container.get("App_Root$");
+```
+
+The container:
+
+- parses the CDC
+- loads the module
+- resolves dependencies declared in `__deps__`
+- instantiates modules
+- links the dependency graph
+- freezes the produced value
+
+Example usage:
+
+```js
+console.log(root.getName());
+console.log(root.getChild().getName());
+console.log(Object.isFrozen(root));
+```
+
+## Typical CDC Usage Patterns
+
+CDC identifiers define how the container interprets a dependency. The following patterns represent common usage scenarios.
+
+### Module As-Is
+
+A CDC without lifecycle marker returns the module export as-is.
+
+```text
+App_Service
+```
+
+Typical usage:
+
+- utility modules
+- stateless helpers
+- constant providers
+
+Example:
+
+```js
+const math = await container.get("App_Math");
+```
+
+### Singleton from Default Export
+
+A lifecycle marker `$` creates a singleton instance.
+
+```text
+App_Service$
+```
+
+Typical usage:
+
+- application services
+- repositories
+- infrastructure adapters
+
+### Transient Instance
+
+Marker `$$` creates a new instance for every request.
+
+```text
+App_Service$$
+```
+
+Typical usage:
+
+- request objects
+- short-lived workers
+- task processors
+
+### Named Export Resolution
+
+CDC may reference a named export using the `__ExportName` segment.
+
+```text
+App_Module__build$
+```
+
+Typical usage:
+
+- builders
+- factory entry points
+- specialized constructors
+
+### Wrapper Application
+
+Wrappers modify the produced value through postprocess plugins.
+
+```text
+App_Service$$_log_trace
+```
+
+The container creates the dependency and applies wrappers in declared order.
+
+Typical usage:
+
+- logging
+- tracing
+- metrics collection
+- behavioral instrumentation
+
+### Platform Dependencies
+
+CDC may reference runtime platform modules.
+
+```text
+node_fs
+npm_lodash
+```
+
+These identifiers provide access to Node.js built-ins and npm packages.
+
+### Root Graph Resolution
+
+Applications typically resolve a single root dependency.
+
+```js
+const root = await container.get("App_Root$");
+```
+
+The container recursively resolves all dependencies declared through `__deps__` and constructs the object graph.
+
+## Wrapper-Based Behavioral Composition
+
+Wrappers enable declarative behavioral composition at the dependency level. By attaching wrapper identifiers to CDC strings the caller can modify the runtime behavior of a dependency without modifying its module implementation.
+
+Example:
+
+```text
+App_Service$$_log
+```
+
+The service module remains unaware of logging. The wrapper introduces cross-cutting behavior during the container postprocess stage.
+
+This mechanism enables patterns similar to aspect-oriented programming while preserving deterministic dependency resolution.
+
+## Minimal Smoke Pattern
+
+A minimal integration scenario demonstrating container operation:
+
+```js
+const container = new Container();
+container.addNamespaceRoot("Fx_", FIXTURE_DIR, ".mjs");
+
+const value = await container.get("Fx_Root$");
+```
+
+The container loads modules, resolves dependencies, instantiates objects, and returns a frozen result.

package/jsconfig.json

@@ -3,11 +3,11 @@
     "baseUrl": ".",
     "checkJs": true,
     "forceConsistentCasingInFileNames": true,
-    "module": "ESNext",
-    "moduleResolution": "node",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
     "noEmit": true,
     "skipLibCheck": true,
-    "target": "ES2022"
+    "target": "ESNext"
   },
-  "include": ["src", "types.d.ts"]
+  "include": ["src", "test", "types.d.ts"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Dependency Injection container for ES6 modules that works in both browser and Node.js apps.",
   "keywords": [
     "dependency injection",
@@ -21,6 +21,7 @@
     "url": "https://github.com/flancer64"
   },
   "files": [
+    "ai/",
     "dist/",
     "src/",
     "CHANGELOG.md",