@teqfw/di 0.31.0 → 0.32.0

package/RELEASE.md

@@ -1,5 +1,13 @@
 # @teqfw/di releases
 
+## 0.32.0 - added support for the `node:` prefix
+
+- **Added ability** to manually register objects in the container (`register`).
+- **Optimized dependency parsing**, added support for the `node:` prefix.
+- **Updated singleton handling**, fixed issues with `Defs.LS`.
+- **Added protection against object modification**, freezing objects when possible (`Object.freeze`).
+- **Updated dependencies** (Mocha, Rollup, Rollup plugins).
+
 ## 0.31.0
 
 * Added optional `stack` parameter to the `get` method for improved dependency tracking and debugging.
@@ -70,6 +78,6 @@
 ## 0.8.0
 
 * docs for plugin's teq-descriptor (see in `main` branch);
-* use object notation instead of array notation in namespace replacement statements of
-  teq-descriptor (`@teqfw/di.replace` node format is changed in `./teqfw.json`);
+* use object notation instead of array notation in namespace replacement statements of teq-descriptor (
+  `@teqfw/di.replace` node format is changed in `./teqfw.json`);
 * array is used as a container for upline dependencies in the 'SpecProxy' (object was);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Dependency Injection container for ES6 modules that works in both browser and Node.js apps.",
   "keywords": [
     "dependency injection",
@@ -31,10 +31,10 @@
     "test": "mocha --recursive './test/**/*.test.mjs'"
   },
   "devDependencies": {
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "mocha": "^10.7.0",
-    "rollup": "^2.79.1",
-    "rollup-plugin-terser": "^7.0.2"
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "mocha": "^11.1.0",
+    "rollup": "^4.36.0",
+    "@rollup/plugin-terser": "^0.4.4"
   },
   "mocha": {
     "spec": "./test/**/*.test.mjs",

package/rollup.config.js

@@ -1,5 +1,5 @@
 import resolve from '@rollup/plugin-node-resolve';
-import {terser} from 'rollup-plugin-terser';
+import terser from '@rollup/plugin-terser';
 
 export default {
     input: 'src/Container.js',

package/src/Api/Container.js

@@ -34,6 +34,13 @@ export default class TeqFw_Di_Api_Container {
      */
     getResolver() {};
 
+    /**
+     * Registers an object (module, singleton, factory, or prototype) by dependency ID.
+     * @param {string} depId
+     * @param {Object} obj
+     */
+    register(depId, obj) {};
+
     /**
      * Enable disable debug output for the object composition process.
      * @param {boolean} data

package/src/Container/A/Composer.js

@@ -29,17 +29,17 @@ export default class TeqFw_Di_Container_A_Composer {
          * @returns {Promise<*>}
          */
         this.create = async function (depId, module, stack, container) {
-            if (stack.includes(depId.value))
-                throw new Error(`Circular dependency for '${depId.value}'. Parents are: ${JSON.stringify(stack)}`);
+            if (stack.includes(depId.origin))
+                throw new Error(`Circular dependency for '${depId.origin}'. Parents are: ${JSON.stringify(stack)}`);
             if (depId.exportName) {
                 // use export from the es6-module
-                const stackNew = [...stack, depId.value];
+                const stackNew = [...stack, depId.origin];
                 const {[depId.exportName]: exp} = module;
-                if (depId.composition === Defs.COMP_F) {
+                if (depId.composition === Defs.CF) {
                     if (typeof exp === 'function') {
                         // create deps for factory function
                         const deps = specParser(exp);
-                        if (deps.length) log(`Deps for object '${depId.value}' are: ${JSON.stringify(deps)}`);
+                        if (deps.length) log(`Deps for object '${depId.origin}' are: ${JSON.stringify(deps)}`);
                         const spec = {};
                         for (const dep of deps)
                             spec[dep] = await container.compose(dep, stackNew);

package/src/Container/A/Parser/Chunk/Def.js

@@ -1,6 +1,8 @@
 /**
  * Default parser for object keys in format:
  *   - Ns_Module.export$$(post)
+ *   - node:package.export$$(post)
+ *   - node:@scope/package.export$$(post)
  *
  * @namespace TeqFw_Di_Container_A_Parser_Chunk_Def
  */
@@ -8,8 +10,8 @@ import Dto from '../../../../DepId.js';
 import Defs from '../../../../Defs.js';
 
 // VARS
-/** @type {RegExp} expression for default object key (Ns_Module.export$$(post)) */
-const REGEXP = /^((([A-Z])[A-Za-z0-9_]*)((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?)$/;
+/** @type {RegExp} expression for default object key */
+const REGEXP = /^(node:)?((@?[A-Za-z0-9_\-]+\/?[A-Za-z0-9_\-]*))((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?$/;
 
 /**
  * @implements TeqFw_Di_Api_Container_Parser_Chunk
@@ -17,49 +19,51 @@ const REGEXP = /^((([A-Z])[A-Za-z0-9_]*)((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\((
 export default class TeqFw_Di_Container_A_Parser_Chunk_Def {
 
     canParse(depId) {
-        // default parser always trys to parse the depId
+        // default parser always tries to parse the depId
         return true;
     }
 
     parse(objectKey) {
         const res = new Dto();
-        res.value = objectKey;
+        res.origin = objectKey;
         const parts = REGEXP.exec(objectKey);
         if (parts) {
-            res.moduleName = parts[2];
+            res.isNodeModule = Boolean(parts[1]); // Detect 'node:' prefix
+            res.moduleName = parts[2].replace(/^node:/, ''); // Remove 'node:' prefix
+
             if (parts[5] === '.') {
-                // Ns_Module.export...
+                // Ns_Module.export or node:package.export
                 if ((parts[7] === '$') || (parts[7] === '$$')) {
-                    // Ns_Module.export$...
-                    res.composition = Defs.COMP_F;
+                    res.composition = Defs.CF;
                     res.exportName = parts[6];
-                    res.life = (parts[7] === '$') ? Defs.LIFE_S : Defs.LIFE_I;
+                    res.life = (parts[7] === '$') ? Defs.LS : Defs.LI;
                 } else {
-                    res.composition = Defs.COMP_A;
-                    res.life = Defs.LIFE_S;
-                    // res.exportName = (parts[6]) ? parts[6] : 'default';
+                    res.composition = Defs.CA;
+                    res.life = Defs.LS;
                     res.exportName = (parts[6] !== '') ? parts[6] : 'default';
                 }
             } else if ((parts[7] === '$') || parts[7] === '$$') {
-                // Ns_Module$$
-                res.composition = Defs.COMP_F;
+                // Ns_Module$$ or node:package$$
+                res.composition = Defs.CF;
                 res.exportName = 'default';
-                res.life = (parts[7] === '$') ? Defs.LIFE_S : Defs.LIFE_I;
+                res.life = (parts[7] === '$') ? Defs.LS : Defs.LI;
             } else {
-                // Ns_Module (es6 module)
+                // Ns_Module or node:package (ES6 module)
                 res.composition = undefined;
                 res.exportName = undefined;
                 res.life = undefined;
             }
-            // wrappers
+
+            // Wrappers handling
             if (parts[11]) {
                 res.wrappers = parts[11].split(',');
             }
         }
 
-        // we should always use singletons for as-is exports
-        if ((res.composition === Defs.COMP_A) && (res.life === Defs.LIFE_I))
-            throw new Error(`Export is not a function and should be used as a singleton only: '${res.value}'.`);
+        // Ensure singletons for non-factory exports
+        if ((res.composition === Defs.CA) && (res.life === Defs.LI))
+            throw new Error(`Export is not a function and should be used as a singleton only: '${res.origin}'.`);
+
         return res;
     }
-}
+}

package/src/Container/A/Parser/Chunk/V02X.js

@@ -1,6 +1,7 @@
 /**
  * Default parser for object keys in format:
  *   - Ns_Module[.|#]export$[F|A][S|I]
+ *   - node:package[.|#]export$[F|A][S|I]
  *
  * @namespace TeqFw_Di_Container_A_Parser_Chunk_V02X
  */
@@ -8,8 +9,8 @@ import Dto from '../../../../DepId.js';
 import Defs from '../../../../Defs.js';
 
 // VARS
-/** @type {RegExp} expression for default object key (Ns_Module[.|#]export$[F|A][S|I]) */
-const REGEXP = /^((([A-Z])[A-Za-z0-9_]*)((#|\.)?([A-Za-z0-9_]*)((\$)([F|A])?([S|I])?)?)?)$/;
+/** @type {RegExp} expression for default object key */
+const REGEXP = /^(node:)?((([A-Z])[A-Za-z0-9_]*|[a-z][a-z0-9\-]*))((#|\.)?([A-Za-z0-9_]*)((\$)([F|A])?([S|I])?)?)?$/;
 
 /**
  * @implements TeqFw_Di_Api_Container_Parser_Chunk
@@ -17,54 +18,48 @@ const REGEXP = /^((([A-Z])[A-Za-z0-9_]*)((#|\.)?([A-Za-z0-9_]*)((\$)([F|A])?([S|
 export default class TeqFw_Di_Container_A_Parser_Chunk_V02X {
 
     canParse(depId) {
-        // default parser always trys to parse the depId
+        // default parser always tries to parse the depId
         return true;
     }
 
     parse(objectKey) {
         const res = new Dto();
-        res.value = objectKey;
+        res.origin = objectKey;
         const parts = REGEXP.exec(objectKey);
         if (parts) {
-            res.moduleName = parts[2];
-            if (parts[5] === '.') {
-                // App_Service.export...
-                if (parts[8] === '$') {
-                    // App_Service.export$...
-                    res.composition = Defs.COMP_F;
-                    res.exportName = parts[6];
-                    res.life = (parts[10] === Defs.LIFE_I)
-                        ? Defs.LIFE_I : Defs.LIFE_S;
-                } else {
-                    res.composition = ((parts[8] === undefined) || (parts[8] === Defs.COMP_A))
-                        ? Defs.COMP_A : Defs.COMP_F;
-                    res.exportName = parts[6];
-                    res.life = ((parts[8] === undefined) || (parts[10] === Defs.LIFE_S))
-                        ? Defs.LIFE_S : Defs.LIFE_I;
-                }
+            res.isNodeModule = Boolean(parts[1]); // Check if it starts with 'node:'
+            res.moduleName = parts[2].replace(/^node:/, ''); // Remove 'node:' if present
 
-
-            } else if (parts[8] === '$') {
-                // App_Logger$FS
-                res.composition = ((parts[9] === undefined) || (parts[9] === Defs.COMP_F))
-                    ? Defs.COMP_F : Defs.COMP_A;
-                res.exportName = 'default';
-                if (parts[10]) {
-                    res.life = (parts[10] === Defs.LIFE_S) ? Defs.LIFE_S : Defs.LIFE_I;
+            if (parts[6] === '.') {
+                // App_Service.export or node:package.export
+                if (parts[9] === '$') {
+                    // App_Service.export$ or node:package.export$
+                    res.composition = Defs.CF;
+                    res.exportName = parts[7];
+                    res.life = (parts[11] === Defs.LI) ? Defs.LI : Defs.LS;
                 } else {
-                    res.life = (res.composition === Defs.COMP_F) ? Defs.LIFE_S : Defs.LIFE_I;
+                    res.composition = (!parts[9] || parts[9] === Defs.CA) ? Defs.CA : Defs.CF;
+                    res.exportName = parts[7];
+                    res.life = (!parts[9] || parts[11] === Defs.LS) ? Defs.LS : Defs.LI;
                 }
+            } else if (parts[9] === '$') {
+                // App_Logger$FS or node:package$
+                res.composition = (!parts[10] || parts[10] === Defs.CF) ? Defs.CF : Defs.CA;
+                res.exportName = 'default';
+                res.life = parts[11] ? (parts[11] === Defs.LS ? Defs.LS : Defs.LI) : (res.composition === Defs.CF ? Defs.LS : Defs.LI);
             } else {
-                // App_Service (es6 module)
+                // App_Service or node:package (ES6 module)
                 res.composition = undefined;
                 res.exportName = undefined;
                 res.life = undefined;
             }
         }
 
-        // we should always use singletons for as-is exports
-        if ((res.composition === Defs.COMP_A) && (res.life === Defs.LIFE_I))
-            throw new Error(`Export is not a function and should be used as a singleton only: '${res.value}'.`);
+        // Enforce singleton for non-factory exports
+        if (res.composition === Defs.CA && res.life === Defs.LI) {
+            throw new Error(`Export is not a function and should be used as a singleton only: '${res.origin}'.`);
+        }
+
         return res;
     }
-}
+}

package/src/Container.js

@@ -19,6 +19,21 @@ function getSingletonId(key) {
     return `${key.moduleName}#${key.exportName}`;
 }
 
+/**
+ * Determines if an object, function, or primitive can be safely frozen.
+ * @param {*} value - The value to check.
+ * @returns {boolean} - Returns true if the value can be safely frozen.
+ */
+function canBeFrozen(value) {
+    // Primitives (except objects and functions) cannot be frozen
+    if (value === null || typeof value !== 'object' && typeof value !== 'function') return false;
+    // // ES modules cannot be frozen
+    if (Object.prototype.toString.call(value) === '[object Module]') return false;
+    // check is Object is already frozen
+    return !Object.isFrozen(value);
+}
+
+
 // MAIN
 /**
  * @implements TeqFw_Di_Api_Container
@@ -80,7 +95,7 @@ export default class TeqFw_Di_Container {
             // modify original key according to some rules (replacements, etc.)
             const key = _preProcessor.modify(parsed, stack);
             // return existing singleton
-            if (key.life === Defs.LIFE_S) {
+            if (key.life === Defs.LS) {
                 const singleId = getSingletonId(key);
                 if (_regSingles[singleId]) {
                     log(`Existing singleton '${singleId}' is returned.`);
@@ -111,11 +126,13 @@ export default class TeqFw_Di_Container {
             }
             // create object using the composer then modify it in post-processor
             let res = await _composer.create(key, module, stack, this);
+            // freeze the result to prevent modifications (TODO: should we have configuration for the feature?)
+            if (canBeFrozen(res)) Object.freeze(res);
             res = await _postProcessor.modify(res, key, stack);
             log(`Object '${depId}' is created.`);
 
             // save singletons
-            if (key.life === Defs.LIFE_S) {
+            if (key.life === Defs.LS) {
                 const singleId = getSingletonId(key);
                 _regSingles[singleId] = res;
                 log(`Object '${depId}' is saved as singleton.`);
@@ -128,8 +145,27 @@ export default class TeqFw_Di_Container {
         this.getPreProcessor = () => _preProcessor;
 
         this.getPostProcessor = () => _postProcessor;
+
         this.getResolver = () => _resolver;
 
+        /**
+         * Register new object in the Container.
+         * @param {string} depId
+         * @param {Object} obj
+         */
+        this.register = function (depId, obj) {
+            if (!depId || !obj) throw new Error('depId and object are required');
+            const key = _parser.parse(depId);
+            if (key.life === Defs.LS) {
+                const singleId = getSingletonId(key);
+                _regSingles[singleId] = obj;
+                log(`Object '${depId}' is registered manually as singleton.`);
+            } else {
+                // TODO: factory function also should be added manually
+                throw new Error(`Only singletons can be registered manually. Given: ${depId}`);
+            }
+        };
+
         this.setDebug = function (data) {
             _debug = data;
             _composer.setDebug(data);

package/src/Defs.js

@@ -3,12 +3,13 @@
  * @namespace TeqFw_Di_Defs
  */
 export default {
-    COMP_A: 'A', // composition: as-is
-    COMP_F: 'F', // composition: factory
+    CA: 'A', // composition: as-is
+    CF: 'F', // composition: factory
+    // TODO: we don't need an access to the container itself.
     ID: 'container', // default ID for container itself
     ID_FQN: 'TeqFw_Di_Container$', // default Full Qualified Name for container itself
-    LIFE_I: 'I', // lifestyle: instance
-    LIFE_S: 'S', // lifestyle: singleton
+    LI: 'I', // lifestyle: instance
+    LS: 'S', // lifestyle: singleton
 
     /**
      * Return 'true' if function is a class definition.

package/src/DepId.js

@@ -1,33 +1,44 @@
 /**
- * This is a DTO that represents the structure of an ID for a runtime dependency.
+ *  DTO representing a dependency identifier in the container.
  * @namespace TeqFw_Di_DepId
  */
 export default class TeqFw_Di_DepId {
     /**
-     * The name of an export of the module.
+     * The name of an export from the module.
+     * Example: 'default', 'logger', 'DbClient'.
      * @type {string}
      */
     exportName;
     /**
-     * Composition type (see Defs.COMPOSE_): use the export as Factory (F) or return as-is (A).
+     * Defines how the export should be used:
+     * - 'F' (Factory): The export is a factory function, call it to get an instance.
+     * - 'A' (As-Is): The export is returned as-is, without calling.
+     * Example: 'F', 'A'.
      * @type {string}
      */
     composition;
     /**
-     * Lifestyle type (see Defs.LIFE_): singleton (S) or instance (I).
+     * Defines the lifecycle of the resolved dependency:
+     * - 'S' (Singleton): A single instance is created and reused.
+     * - 'I' (Instance): A new instance is created on each request.
+     * Example: 'S', 'I'.
      * @type {string}
      */
     life;
     /**
-     * The code for ES6 module that can be converted to the path to this es6 module.
+     * ES6 module identifier, which can be transformed into a file path.
+     * This value is processed by the Resolver to determine the module's location.
+     * Example: 'TeqFw_Core_Shared_Api_Logger'.
      * @type {string}
      */
     moduleName;
     /**
-     * Object key value.
+     * The original identifier string provided to the container.
+     * This is the unprocessed dependency key.
+     * Example: 'TeqFw_Core_Shared_Api_Logger$$'.
      * @type {string}
      */
-    value;
+    origin;
     /**
      * List of wrappers to decorate the result.
      * @type {string[]}