@teqfw/di 2.0.2 → 2.0.4

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.