@teqfw/di 1.2.0 → 1.3.0

package/README.md

@@ -3,30 +3,18 @@
 ![npms.io](https://img.shields.io/npm/dm/@teqfw/di)
 ![jsdelivr](https://img.shields.io/jsdelivr/npm/hm/@teqfw/di)
 
-> [!IMPORTANT] > **Breaking Changes in v1.0.0**
+> [!WARNING]
+> This branch contains the **legacy v1 line** of `@teqfw/di`.
+> The code here is **manually authored** and is kept for compatibility with existing integrations and previously delivered solutions.
 >
-> The library has been stable for a long time and is now promoted to its first major version. To improve security, the Object Container can no longer access itself, so all configuration must occur in the Composition Root. This restriction ensures that third-party plugins cannot override or modify the container's internal functionality. Legacy versions are maintained in the `forerunner` branch, and packages like `@teqfw/core` should depend on `@teqfw/di` versions below `1.0.0`.
-
-`@teqfw/di` is a lightweight dependency injection container for standard JavaScript, enabling late binding of code
-objects with minimal manual configuration. It integrates smoothly in both browser and Node.js environments, supporting
-flexibility, modularity, and easier testing for your applications.
-
-Unlike typical object containers, `@teqfw/di` requires no manual registration of objects, instead mapping dependency IDs
-directly to their source paths for greater simplicity. However, for advanced use cases—such as unit testing—it is
-possible to explicitly register singleton objects using the `register(depId, obj)` method (available only in test mode).
-This allows controlled substitution of dependencies without altering the main codebase.
-
-**This library is specifically optimized for ES6 modules, ensuring top performance and compatibility. It does not
-support CommonJS, AMD, UMD, or other module formats.**
-
-To increase robustness, all instances created by the container are automatically **frozen** using `Object.freeze()`.
-This guarantees immutability of the returned objects, helping prevent accidental modifications and ensuring predictable
-behavior at runtime.
+> Active development has moved to the main branch:
+> **https://github.com/teqfw/di/tree/main**
+>
+> The new container generation is built through an AI-agent workflow and follows a different architecture and dependency model.
+> **Backward compatibility with this v1 line is not guaranteed.**
 
-While this library is primarily designed for JavaScript, it is also fully compatible with TypeScript. Developers can use
-TypeScript to compose dependency identifiers in the same way as in JavaScript. It is important to ensure that TypeScript
-transpiles the source code to ES6 modules for proper functionality. With this setup, TypeScript users can effectively
-leverage the benefits of this library without any additional configuration.
+`@teqfw/di` v1 is a lightweight dependency injection container for standard JavaScript, enabling late binding of code
+objects with minimal manual configuration. It integrates in both browser and Node.js environments for modularity and testing.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Dependency Injection container for ES6 modules that works in both browser and Node.js apps.",
   "keywords": [
     "dependency injection",
@@ -23,9 +23,6 @@
   "files": [
     "dist/",
     "src/",
-    "CHANGELOG.md",
-    "LICENSE",
-    "README.md",
     "teqfw.json",
     "types.d.ts"
   ],
@@ -48,15 +45,16 @@
   },
   "scripts": {
     "rollup": "rollup -c",
-    "eslint": "eslint './src/**/*.js'",
-    "test": "node --test"
+    "eslint": "npx eslint './src/**/*.js'",
+    "test:unit": "node --test"
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "eslint": "^9.33.0",
-    "rollup": "^4.47.1"
+    "rollup": "^4.47.1",
+    "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">=20"

package/src/Api/Container/Config.js

@@ -0,0 +1,73 @@
+/**
+ * Public configuration API of the DI container.
+ *
+ * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
+ * @interface
+ */
+export default class TeqFw_Di_Api_Container_Config {
+
+    /**
+     * Returns the parser configurator.
+     *
+     * @returns {TeqFw_Di_Api_Container_Parser}
+     */
+    parser() {
+        throw new Error('TeqFw_Di_Api_Container_Config#parser is abstract.');
+    }
+
+    /**
+     * Returns the pre-processor configurator.
+     *
+     * @returns {TeqFw_Di_Api_Container_PreProcessor}
+     */
+    preProcessor() {
+        throw new Error('TeqFw_Di_Api_Container_Config#preProcessor is abstract.');
+    }
+
+    /**
+     * Returns the post-processor configurator.
+     *
+     * @returns {TeqFw_Di_Api_Container_PostProcessor}
+     */
+    postProcessor() {
+        throw new Error('TeqFw_Di_Api_Container_Config#postProcessor is abstract.');
+    }
+
+    /**
+     * Returns the resolver configurator.
+     *
+     * @returns {TeqFw_Di_Api_Container_Resolver}
+     */
+    resolver() {
+        throw new Error('TeqFw_Di_Api_Container_Config#resolver is abstract.');
+    }
+
+    /**
+     * Enables test mode.
+     *
+     * @returns {void}
+     */
+    enableTestMode() {
+        throw new Error('TeqFw_Di_Api_Container_Config#enableTestMode is abstract.');
+    }
+
+    /**
+     * Registers a singleton or a Node.js module replacement in test mode.
+     *
+     * @param {string} depId
+     * @param {object} obj
+     * @returns {void}
+     */
+    register(depId, obj) {
+        throw new Error('TeqFw_Di_Api_Container_Config#register is abstract.');
+    }
+
+    /**
+     * Finalizes configuration and returns a runtime container instance.
+     *
+     * @returns {TeqFw_Di_Api_Container}
+     */
+    finalize() {
+        throw new Error('TeqFw_Di_Api_Container_Config#finalize is abstract.');
+    }
+}

package/src/Api/Container/Parser/Chunk.js

@@ -12,12 +12,16 @@ export default class TeqFw_Di_Api_Container_Parser_Chunk {
      * @param {string} depId
      * @returns {boolean}
      */
-    canParse(depId) {};
+    canParse(depId) {
+        throw new Error('TeqFw_Di_Api_Container_Parser_Chunk#canParse is abstract.');
+    }
 
     /**
      * Parses a string ID for a runtime dependency and returns structured data (DTO).
      * @param {string} depId
      * @returns {TeqFw_Di_DepId}
      */
-    parse(depId) {}
-};
+    parse(depId) {
+        throw new Error('TeqFw_Di_Api_Container_Parser_Chunk#parse is abstract.');
+    }
+};

package/src/Api/Container/Parser.js

@@ -10,19 +10,25 @@ export default class TeqFw_Di_Api_Container_Parser {
      *
      * @param {TeqFw_Di_Api_Container_Parser_Chunk} chunk
      */
-    addChunk(chunk) {}
+    addChunk(chunk) {
+        throw new Error('TeqFw_Di_Api_Container_Parser#addChunk is abstract.');
+    }
 
     /**
      * Parse given dependency ID and return structured data as DTO.
      * @param {string} depId
      * @returns {TeqFw_Di_DepId}
      */
-    parse(depId) {}
+    parse(depId) {
+        throw new Error('TeqFw_Di_Api_Container_Parser#parse is abstract.');
+    }
 
     /**
      * Sets the default chunk of the parser.
      *
      * @param {TeqFw_Di_Api_Container_Parser_Chunk} chunk
      */
-    setDefaultChunk(chunk) {}
-}
+    setDefaultChunk(chunk) {
+        throw new Error('TeqFw_Di_Api_Container_Parser#setDefaultChunk is abstract.');
+    }
+}

package/src/Api/Container/PostProcessor.js

@@ -10,16 +10,20 @@ export default class TeqFw_Di_Api_Container_PostProcessor {
      *
      * @param {TeqFw_Di_Api_Container_PostProcessor_Chunk} chunk
      */
-    addChunk(chunk) {}
+    addChunk(chunk) {
+        throw new Error('TeqFw_Di_Api_Container_PostProcessor#addChunk is abstract.');
+    }
 
     /**
      * Modifies the result of the object composition.
      *
      * @param {*} obj - The result object to be modified.
      * @param {TeqFw_Di_DepId} depId - The original depID DTO.
-     * @param {string[]} - The stack of parent IDs.
+     * @param {string[]} stack - The stack of parent IDs.
      * @returns {Promise<*>}
      */
-    modify(obj, depId, stack) {}
+    modify(obj, depId, stack) {
+        throw new Error('TeqFw_Di_Api_Container_PostProcessor#modify is abstract.');
+    }
 
-}
+}

package/src/Api/Container/PreProcessor/Chunk.js

@@ -13,5 +13,7 @@ export default class TeqFw_Di_Api_Container_PreProcessor_Chunk {
      * @param {string[]} stack - stack of parents depIds
      * @returns {TeqFw_Di_DepId}
      */
-    modify(depId, originalId, stack) {}
-};
+    modify(depId, originalId, stack) {
+        throw new Error('TeqFw_Di_Api_Container_PreProcessor_Chunk#modify is abstract.');
+    }
+};

package/src/Api/Container/PreProcessor.js

@@ -10,7 +10,9 @@ export default class TeqFw_Di_Api_Container_PreProcessor {
      *
      * @param {TeqFw_Di_Api_Container_PreProcessor_Chunk} chunk
      */
-    addChunk(chunk) {}
+    addChunk(chunk) {
+        throw new Error('TeqFw_Di_Api_Container_PreProcessor#addChunk is abstract.');
+    }
 
     /**
      * Modify parsed depID and return it.
@@ -18,6 +20,8 @@ export default class TeqFw_Di_Api_Container_PreProcessor {
      * @param {string[]} stack - The stack of parent IDs.
      * @returns {TeqFw_Di_DepId} -
      */
-    modify(depId, stack) {}
+    modify(depId, stack) {
+        throw new Error('TeqFw_Di_Api_Container_PreProcessor#modify is abstract.');
+    }
 
-}
+}

package/src/Api/Container/Resolver.js

@@ -11,6 +11,8 @@ export default class TeqFw_Di_Api_Container_Resolver {
      * @param {string} moduleName 'Vendor_Package_Module'
      * @returns {string} '/home/user/app/node_modules/@vendor/package/src/Module.js'
      */
-    resolve(moduleName) {}
+    resolve(moduleName) {
+        throw new Error('TeqFw_Di_Api_Container_Resolver#resolve is abstract.');
+    }
 
-}
+}

package/src/Api/Container.js

@@ -0,0 +1,19 @@
+/**
+ * Public runtime API of the DI container.
+ *
+ * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
+ * @interface
+ */
+export default class TeqFw_Di_Api_Container {
+
+    /**
+     * Resolves a dependency by its identifier and returns the result.
+     *
+     * @param {string} depId
+     * @param {string[]} [stack]
+     * @returns {Promise<*>}
+     */
+    get(depId, stack) {
+        throw new Error('TeqFw_Di_Api_Container#get is abstract.');
+    }
+}

package/src/Container/Config.js

@@ -0,0 +1,93 @@
+import Container from '../Container.js';
+
+/**
+ * Runtime configuration facade for the DI container.
+ *
+ * @implements {TeqFw_Di_Api_Container_Config}
+ */
+export default class TeqFw_Di_Container_Config {
+    constructor() {
+        // VARS
+        const _container = new Container();
+        let _finalized = false;
+
+        // FUNCS
+        function assertNotFinalized() {
+            if (_finalized) throw new Error('Container configuration is finalized.');
+        }
+
+        // INSTANCE METHODS
+
+        /**
+         * Returns the parser configurator.
+         *
+         * @returns {TeqFw_Di_Api_Container_Parser}
+         */
+        this.parser = function () {
+            assertNotFinalized();
+            return _container.getParser();
+        };
+
+        /**
+         * Returns the pre-processor configurator.
+         *
+         * @returns {TeqFw_Di_Api_Container_PreProcessor}
+         */
+        this.preProcessor = function () {
+            assertNotFinalized();
+            return _container.getPreProcessor();
+        };
+
+        /**
+         * Returns the post-processor configurator.
+         *
+         * @returns {TeqFw_Di_Api_Container_PostProcessor}
+         */
+        this.postProcessor = function () {
+            assertNotFinalized();
+            return _container.getPostProcessor();
+        };
+
+        /**
+         * Returns the resolver configurator.
+         *
+         * @returns {TeqFw_Di_Api_Container_Resolver}
+         */
+        this.resolver = function () {
+            assertNotFinalized();
+            return _container.getResolver();
+        };
+
+        /**
+         * Enables test mode.
+         *
+         * @returns {void}
+         */
+        this.enableTestMode = function () {
+            assertNotFinalized();
+            _container.enableTestMode();
+        };
+
+        /**
+         * Registers a singleton or a Node.js module replacement in test mode.
+         *
+         * @param {string} depId
+         * @param {object} obj
+         * @returns {void}
+         */
+        this.register = function (depId, obj) {
+            assertNotFinalized();
+            _container.register(depId, obj);
+        };
+
+        /**
+         * Finalizes configuration and returns a runtime container instance.
+         *
+         * @returns {TeqFw_Di_Api_Container}
+         */
+        this.finalize = function () {
+            _finalized = true;
+            return _container;
+        };
+    }
+}

package/src/Container/Resolver.js

@@ -21,7 +21,7 @@ const NSS = '_';
 
 // MAIN
 /**
- * @implements TeqFw_Di_Api_Container_Resolver
+ * @implements {TeqFw_Di_Api_Container_Resolver}
  */
 export default class TeqFw_Di_Container_Resolver {
 

package/types.d.ts

@@ -1,24 +1,34 @@
-type TeqFw_Di_Container_A_Composer = InstanceType<typeof import("./src/Container/A/Composer.js").default>;
-type TeqFw_Di_Container_A_Composer_A_SpecParser = import("./src/Container/A/Composer/A/SpecParser.js").default;
-type TeqFw_Di_Container_A_Parser_Chunk_Def = InstanceType<typeof import("./src/Container/A/Parser/Chunk/Def.js").default>;
-type TeqFw_Di_Container_A_Parser_Chunk_V02X = InstanceType<typeof import("./src/Container/A/Parser/Chunk/V02X.js").default>;
-type TeqFw_Di_Container_Parser = InstanceType<typeof import("./src/Container/Parser.js").default>;
-type TeqFw_Di_Container_PostProcessor = InstanceType<typeof import("./src/Container/PostProcessor.js").default>;
-type TeqFw_Di_Container_PreProcessor = InstanceType<typeof import("./src/Container/PreProcessor.js").default>;
-type TeqFw_Di_Container_Resolver = InstanceType<typeof import("./src/Container/Resolver.js").default>;
+export {};
 
 declare global {
-  type TeqFw_Di_Api_Container_Parser = InstanceType<typeof import("./src/Api/Container/Parser.js").default>;
-  type TeqFw_Di_Api_Container_Parser_Chunk = InstanceType<typeof import("./src/Api/Container/Parser/Chunk.js").default>;
-  type TeqFw_Di_Api_Container_PostProcessor = InstanceType<typeof import("./src/Api/Container/PostProcessor.js").default>;
-  type TeqFw_Di_Api_Container_PostProcessor_Chunk = InstanceType<typeof import("./src/Api/Container/PostProcessor/Chunk.js").default>;
-  type TeqFw_Di_Api_Container_PreProcessor = InstanceType<typeof import("./src/Api/Container/PreProcessor.js").default>;
-  type TeqFw_Di_Api_Container_PreProcessor_Chunk = InstanceType<typeof import("./src/Api/Container/PreProcessor/Chunk.js").default>;
-  type TeqFw_Di_Api_Container_Resolver = InstanceType<typeof import("./src/Api/Container/Resolver.js").default>;
-  type TeqFw_Di_Container = InstanceType<typeof import("./src/Container.js").default>;
-  type TeqFw_Di_Defs = import("./src/Defs.js").default;
-  type TeqFw_Di_DepId = InstanceType<typeof import("./src/DepId.js").default>;
-  type TeqFw_Di_Pre_Replace = InstanceType<typeof import("./src/Pre/Replace.js").default>;
+  type TeqFw_Di_Api_Container = InstanceType<typeof import('./src/Api/Container.js').default>;
+  type TeqFw_Di_Api_Container_Config = InstanceType<typeof import('./src/Api/Container/Config.js').default>;
+  type TeqFw_Di_Api_Container_Parser = InstanceType<typeof import('./src/Api/Container/Parser.js').default>;
+  type TeqFw_Di_Api_Container_Parser_Chunk = InstanceType<typeof import('./src/Api/Container/Parser/Chunk.js').default>;
+  type TeqFw_Di_Api_Container_PostProcessor = InstanceType<typeof import('./src/Api/Container/PostProcessor.js').default>;
+  type TeqFw_Di_Api_Container_PostProcessor_Chunk = InstanceType<
+    typeof import('./src/Api/Container/PostProcessor/Chunk.js').default
+  >;
+  type TeqFw_Di_Api_Container_PreProcessor = InstanceType<typeof import('./src/Api/Container/PreProcessor.js').default>;
+  type TeqFw_Di_Api_Container_PreProcessor_Chunk = InstanceType<
+    typeof import('./src/Api/Container/PreProcessor/Chunk.js').default
+  >;
+  type TeqFw_Di_Api_Container_Resolver = InstanceType<typeof import('./src/Api/Container/Resolver.js').default>;
+  type TeqFw_Di_Container = InstanceType<typeof import('./src/Container.js').default>;
+  type TeqFw_Di_Container_A_Composer = InstanceType<typeof import('./src/Container/A/Composer.js').default>;
+  type TeqFw_Di_Container_A_Composer_A_SpecParser = typeof import('./src/Container/A/Composer/A/SpecParser.js').default;
+  type TeqFw_Di_Container_A_Parser_Chunk_Def = InstanceType<
+    typeof import('./src/Container/A/Parser/Chunk/Def.js').default
+  >;
+  type TeqFw_Di_Container_A_Parser_Chunk_V02X = InstanceType<
+    typeof import('./src/Container/A/Parser/Chunk/V02X.js').default
+  >;
+  type TeqFw_Di_Container_Config = InstanceType<typeof import('./src/Container/Config.js').default>;
+  type TeqFw_Di_Container_Parser = InstanceType<typeof import('./src/Container/Parser.js').default>;
+  type TeqFw_Di_Container_PostProcessor = InstanceType<typeof import('./src/Container/PostProcessor.js').default>;
+  type TeqFw_Di_Container_PreProcessor = InstanceType<typeof import('./src/Container/PreProcessor.js').default>;
+  type TeqFw_Di_Container_Resolver = InstanceType<typeof import('./src/Container/Resolver.js').default>;
+  type TeqFw_Di_Defs = typeof import('./src/Defs.js').default;
+  type TeqFw_Di_DepId = InstanceType<typeof import('./src/DepId.js').default>;
+  type TeqFw_Di_Pre_Replace = InstanceType<typeof import('./src/Pre/Replace.js').default>;
 }
-
-export {};

package/CHANGELOG.md

@@ -1,45 +0,0 @@
-# Changelog
-
-## 1.2.0
-
-- Documented the dependency declaration model in the README and product overview.
-- Refined the type map rules to clarify tsserver scope and public vs internal type visibility.
-- Updated `types.d.ts` mappings to use `InstanceType` for class defaults and split internal aliases from globals.
-
-## 1.1.3
-
-- Added global type declarations to `types.d.ts` to match the type map architecture rules.
-
-## 1.1.2
-
-- Moved architecture diagrams into `ctx/img/` and updated the context map accordingly.
-- Clarified type map rules to require global namespace declarations for IDE type resolution.
-
-## 1.1.1
-
-- Added missing published files (`CHANGELOG.md`, `teqfw.json`, `types.d.ts`) and declared `types.d.ts` in `package.json`.
-
-## 1.1.0
-
-- Added ADSM cognitive context documentation and reporting structure under `ctx/`.
-- Added type map documentation and a `types.d.ts` namespace-to-source mapping for IDE support.
-- Updated `.npmignore` to ignore `output.md` artifacts.
-
-## 1.0.2
-
-- Added ability to import the Replace preprocessor chunk via package subpath (`./pre/replace`).
-- Updated `.npmignore` to exclude development artifacts (`ctx/`, logs, test files) and ensure clean npm package contents.
-- Improved ignore patterns to prevent accidental publication of internal files.
-
-## 1.0.1
-
-- Prepare npm package for publication.
-- Add distribution build outputs to package files and specify entry points.
-
-## 1.0.0
-
-- Started changelog for version 1.0.0.
-- Added AGENTS.md with English-only guidelines and link to PHILOSOPHY.md.
-- Switched tests from Mocha to Node's built-in runner.
-- Updated package scripts and removed Mocha dependency.
-- Documented breaking changes for v1.0.0: the container can no longer access itself, configuration must occur in the Composition Root, and legacy versions live in the `forerunner` branch.