@teqfw/di 0.21.0 → 0.21.1

package/RELEASE.md

@@ -1,5 +1,9 @@
 # @teqfw/di releases
 
+## 0.21.1
+
+* Fix the dependency key signature in `TeqFw_Di_Container_A_Parser_Chunk_Def`.
+
 ## 0.21.0
 
 * Restructured modules in the package.

package/docs/README.md

@@ -0,0 +1,6 @@
+# Documentation for @teqfw/di
+
+Publish updates to https://teqfw.github.io/di/:
+```shell
+$ npm run deploy
+```

package/docs/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <NuxtLayout>
+    <NuxtPage/>
+  </NuxtLayout>
+</template>

package/docs/assets/css/layout.css

@@ -0,0 +1,51 @@
+@import "vars.css";
+
+HTML {
+    font-family: 'Inter', sans-serif;
+    offset-anchor: 1cm 2cm;
+}
+
+BODY {
+    font-size: 1rem;
+    margin: 0;
+    padding: 0;
+}
+
+H1 {
+    font-size: 2.25rem;
+}
+
+H2 {
+    font-size: 1.5rem;
+}
+
+H3 {
+    font-size: 1.25rem;
+}
+
+H4 {
+    font-size: 1rem;
+}
+
+A {
+    /*color: var(--color-set-green);*/
+    /*color: #0E6758;*/
+    color: #0A9466;
+    font-weight: bold;
+    text-decoration: none;
+}
+
+A:visited {
+    text-decoration: none;
+}
+
+P {
+    text-align: justify;
+}
+
+PRE {
+    background-color: var(--color-set-black);
+    color: var(--color-set-green);
+    font-size: 0.75rem;
+    padding: 5px;
+}

package/docs/assets/css/vars.css

@@ -0,0 +1,6 @@
+:root {
+    --color-set-black: #16181F;
+    /*--color-set-green: #00FF57;*/
+    /*--color-set-green: #114A47;*/
+    --color-set-green: #07B469;
+}

package/docs/components/AppFooter.vue

@@ -0,0 +1,47 @@
+<script setup>
+
+</script>
+
+<template>
+  <footer>
+    <div>&copy; 2023 Wiredgeese</div>
+    <div class="v-line">|</div>
+    <div><a href="mailto:info@wiredgeese.com">info@wiredgeese.com</a></div>
+    <div class="v-line">|</div>
+    <div><a href="https://t.me/wiredgeese">@wiredgeese</a></div>
+  </footer>
+</template>
+
+<style>
+FOOTER {
+  background-color: var(--color-set-black);
+  color: var(--color-set-green);
+  display: flex;
+  justify-content: center; /* Distribute space between elements */
+  align-items: center; /* Center items vertically */
+  margin-top: 50px;
+  padding: 5px;
+  text-align: center;
+  z-index: 1000;
+}
+
+FOOTER A {
+  font-weight: normal;
+  color: var(--color-set-green);
+}
+
+FOOTER .v-line {
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+@media only screen and (max-width: 800px) {
+  FOOTER {
+    flex-direction: column;
+  }
+
+  FOOTER .v-line {
+    display: none;
+  }
+}
+</style>

package/docs/components/AppHeader.vue

@@ -0,0 +1,79 @@
+<script setup>
+
+</script>
+
+<template>
+  <header>
+    <div class="h-left">
+      <div class="img-container">
+        <img src="/favicon.ico" alt="logo">
+      </div>
+      <h4>TeqFW</h4>
+    </div>
+    <div class="h-center">
+      <h3>Dependency Injection</h3>
+    </div>
+    <div class="h-right">
+      <div class="img-container">
+        <a href="https://www.npmjs.com/package/@teqfw/di">
+          <img src="/img/npm.png" alt="npm"/>
+        </a>
+      </div>
+      <div class="img-container">
+        <a href="https://github.com/teqfw/di">
+          <img src="/img/github.svg" alt="GitHub"/>
+        </a>
+      </div>
+    </div>
+  </header>
+</template>
+
+<style>
+HEADER {
+  background-color: var(--color-set-black);
+  color: var(--color-set-green);
+  position: sticky;
+  top: 0;
+  z-index: 1000;;
+}
+
+HEADER, .h-left, .h-center, .h-right {
+  align-items: center;
+  display: flex;
+  justify-content: space-between;
+}
+
+HEADER H3, HEADER H4 {
+  margin-block: 10px 10px;
+}
+
+.h-left {
+  margin-left: 20px;
+}
+
+.h-right {
+  margin-right: 20px;
+}
+
+.img-container {
+  /* border: 2px solid var(--color-set-green); */
+  margin: 5px;
+  border-radius: 50%;
+  height: 40px;
+  overflow: hidden;
+  width: 40px;
+}
+
+.img-container IMG {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* === Styles for mobiles === */
+@media only screen and (max-width: 800px) {
+  .h-center H3 {
+    display: none;
+  }
+}
+</style>

package/docs/content/index.md

@@ -0,0 +1,272 @@
+# @teqfw/di
+
+A Dependency Injection container for regular JavaScript is provided, which can be used in both _browser_ and _Node.js_
+applications. This library exclusively supports ES6 modules. The primary objective of this library is late binding with
+_minimal manual configuration_ for the container. All linking instructions are encapsulated within the dependency
+identifiers and source path resolver. Additionally, the container offers the capability to modify object identifiers
+(_preprocessing_) and the created objects (_postprocessing_). These features enable you to more comprehensively
+distribute the necessary functionality across npm packages and reuse npm packages in different projects, following a
+'_modular monolith_' architecture (see the [sample](https://github.com/flancer64/demo-di-app)).
+
+## Inversion of Control
+
+The primary motivation for creating this library was the concept that JavaScript is a language in which the entire
+application can be written, both on the front end and the back end. The idea was to enable the use of the same
+JavaScript code seamlessly on both the front end and the back end without requiring any changes, including additional
+transpilation.
+
+The main challenge encountered along this path was static importing. When the entire application can fit into a single
+npm package, all sources can be linked to each other through relative paths. However, if the sources are distributed
+across different npm packages, addressing them becomes problematic:
+
+```javascript
+// backend style
+import something from '@vendor/package/src/Module.js';
+
+// frontend style
+import something from 'https://domain.com/@vendor/package/src/Module.js'; 
+```
+
+The inversion of control (IoC) design pattern came to the rescue. In this pattern, any software object with external
+dependencies provides a mechanism for obtaining these dependencies. The external environment, whether it's a test unit
+or an object container, is responsible for creating these dependencies and providing them to the software object.
+
+```javascript
+// constructor-based injection
+class Service {
+  constructor(config, logger) {}
+}
+```
+
+If all dependencies are added to software objects through a similar mechanism, there is no need to use static imports in
+the source code itself. Now, they can be used without any changes, both on the front end and on the back end.
+
+## Object Container
+
+Many programming languages implement the Dependency Injection pattern. In this pattern, an application typically
+utilizes an object container, responsible for creating all the application's objects and their dependencies. The
+`@teqfw/di` package provides precisely such an object container (`src/Container.js`). This object container is
+initialized and configured at the outset of application execution, after which it assumes responsibility for creating
+the remaining application objects:
+
+```javascript
+import Container from '@teqfw/di';
+
+const container = new Container();
+const resolver = container.getResolver();
+resolver.addNamespaceRoot('App_', pathApp);
+resolver.addNamespaceRoot('Sample_Lib_', pathLib);
+const app = await container.get('App_Main$');
+```
+
+Since JavaScript does not have its own namespaces, similar to packages in Java and namespaces in PHP, the experience of
+[Zend 1](https://framework.zend.com/manual/2.4/en/migration/namespacing-old-classes.html) is used as the basis for
+identifiers.
+
+## Namespaces
+
+The primary purpose of namespaces is to address code elements within an application. In JavaScript (JS) applications,
+code is organized into npm packages, within which the sources reside in files and directories. Each npm package and its
+root directory can be linked to a namespace:
+
+```
+Vendor_Package_ => /home/user/app/node_modules/@vendor/package/src/....
+```
+
+This way, you can reference any ES6 module in any npm package:
+
+```
+Venodr_Package_Shared_Dto_Service_Save 
+    => /home/user/app/node_modules/@vendor/package/src/Shared/Dto/Service/Save.js 
+```
+
+Depending on the execution environment, the mapping may be different:
+
+```
+Vendor_Package_ => /home/user/app/node_modules/@vendor/package/src    // Linux style
+Vendor_Package_ => C:\projects\app\node_modules\@vendor\package\src   // Windows style
+Vendor_Package_ => https://unpkg.com/@vendor/package/src              // Web style
+```
+
+The source code employs namespaces to reference dependencies, while the object container utilizes a resolver to
+translate the namespace into the corresponding path to the source code file, contingent upon the runtime environment:
+
+```
+Venodr_Package_Shared_Dto_Service_Save 
+    => /home/user/app/node_modules/@vendor/package/src/Shared/Dto/Service/Save.js
+Venodr_Package_Shared_Dto_Service_Save 
+    => C:\projects\app\node_modules\@vendor\package\src\Shared\Dto\Service\Save.js
+Venodr_Package_Shared_Dto_Service_Save 
+    => https://unpkg.com/@vendor/package/src/Shared/Dto/Service/Save.js
+```
+
+## Dependency Specification
+
+JavaScript lacks reflection capabilities similar to Java or PHP. Consequently, to enable the object container to
+comprehend the necessary dependencies for creating a specific object, a distinct convention is employed - a dependency
+specification. A dependency specification is an object where each key represents the identifier of the required
+dependency:
+
+```javascript
+class Service {
+  constructor(
+          {
+            App_Config: config,
+            App_Logger: logger
+          }
+  ) {}
+}
+```
+
+In the object container, the required object is created as follows:
+
+```javascript
+const App_Config = await container.get('App_Config');
+const App_Logger = await container.get('App_Logger');
+const spec = {App_Config, App_Logger};
+const obj = new Service(spec);
+```
+
+If dependencies are injected into a factory function, it appears as follows:
+
+```javascript
+function Factory({App_Config: config, App_Logger: logger}) {
+  // perform operations with dependencies and compose the result
+  return res;
+}
+```
+
+## Es6 export
+
+In ES6+, a distinct building block in application development is the act
+of [exporting](https://flancer32.com/es6-export-as-code-brick-b33a8efb3510):
+
+```javascript
+export {
+  obj1 as default, obj2, obj3
+};
+```
+
+Static linking through imports is performed at the level of these building blocks:
+
+````javascript
+import obj1 from './mod.js';
+import {obj2} from './mod.js';
+````
+
+This implies that the dependency identifier must have the capability to reference not only the ES6 module itself but
+also a specific export within it, as illustrated in this example:
+
+```javascript
+const exp = 'Vendor_Package_Module.export';
+const def = 'Vendor_Package_Module.default';
+const obj2 = 'Vendor_Package_Module.obj2';
+```
+
+In this case, the dependency declaration in a constructor or factory function could look like this:
+
+```javascript
+class Service {
+  constructor(
+          {
+            'App_Config.default': config,
+            'App_Util.logger': logger
+          }
+  ) {}
+}
+```
+
+## Late binding
+
+The object container links objects not at the source code level but in runtime mode. In my applications, I have
+encountered two particularly useful runtime object lifecycles:
+
+* **Singleton**: It exists in a single instance within the application.
+* **Instance**: A new object is created each time.
+
+Since any string can be used as an object key in a dependency specification, various formats can be devised to specify
+the lifecycle of the required dependency. I have personally chosen the following format:
+
+```javascript
+const asIs = 'Vendor_Package_Module.default';
+const asSingleton = 'Vendor_Package_Module.default$';
+const asInstance = 'Vendor_Package_Module.default$$';
+```
+
+In principle, each package can have its own format for describing the dependencies it uses internally. The
+`TeqFw_Di_Container_Parser` object is responsible for applying the appropriate format within the required namespace.
+
+## Transforming the Result
+
+Here are the steps for the object container:
+
+![processing steps](./img/teqfw_di_container_steps.png)
+
+There are two stages involved here:
+
+* **Preprocessing**: the modification of the dependency identifier
+* **Postprocessing**: the modification of the created object
+
+### Preprocessing
+
+At times, situations may arise, especially when utilizing various extensions of the core functionality, where it becomes
+necessary to redefine certain objects within the application. For such scenarios, `@teqfw/di` includes a preprocessor:
+
+```javascript
+/** @type {TeqFw_Di_Api_Container_PreProcessor} */
+const pre = container.getPreProcessor();
+```
+
+You can add handlers (chunks) to the preprocessor that are capable of modifying the initial `depId`:
+
+```javascript
+/** @type {TeqFw_Di_Api_Container_PreProcessor_Chunk} */
+const replace = new ReplaceChunk(); // some implementation of the interface
+pre.addChunk(replace);
+```
+
+The preprocessor calls the handlers sequentially and can, for example, replace a dependency from the base npm package
+(`App_Base_Mod_Api_Service_Auth`) with another dependency from one of the npm packages (`Auth_Password_Mod_Service` or
+`OAuth2_Mod_Service`), depending on the npm packages included in the application compilation.
+
+By using such replacements, you can implement the core functionality in one npm package, while in other npm packages,
+you can implement the additional functionality required by the core package.
+
+### Postprocessing
+
+Since the container creates all objects in the application, it can also perform additional actions on newly created
+objects, such as adding extra functionality to them in the form of a wrapper.
+
+`@teqfw/di` enables you to add individual handlers to the post-processing stage and modify the result. For example, you
+can wrap a finished object or perform various operations on it:
+
+```javascript
+// ./PostChunk.js
+/**
+ * @implements TeqFw_Di_Api_Container_PostProcessor_Chunk
+ */
+export default {
+    modify: function (obj, originalId, stack) {
+        if (originalId.wrappers.indexOf('proxy') !== -1)
+            return new Proxy(obj, {
+                get: async function (base, name) { /* do something */ }
+            });
+        else return obj;
+    }
+};
+```
+
+```javascript
+// ./main.js
+import postChunk from './PostChunk.mjs';
+
+container.getPostProcessor().addChunk(postChunk);
+```
+
+## Resume
+
+`@teqfw/di` offers Dependency Injection for regular JavaScript with minimal manual configuration, supporting both
+browser and Node.js environments. Its use of late binding and an object container in JavaScript applications, along with
+the ability to modify the behavior of created objects (via pseudo-interfaces and wrappers), allows you to apply
+architectural solutions from other languages (such as Java, PHP, C#) and fully harness the capabilities of npm packages
+and ES6 modules in JavaScript applications, particularly in the Node.js environment.

package/docs/content/test.md

@@ -0,0 +1,20 @@
+---
+title: 'Title of the page'
+description: 'meta description of the page'
+---
+
+# TEST
+
+Any text is going here...
+
+## H2
+
+Any text is going here...
+
+### H3
+
+Any text is going here...
+
+#### H4
+
+Any text is going here...

package/docs/layouts/default.vue

@@ -0,0 +1,83 @@
+<script setup>
+onMounted(() => {
+  // FUNCS
+  /**
+   * Scroll down the page on hashtag to display text under header block.
+   */
+  function scrollToChapter() {
+    const hash = window.location.hash;
+    if (hash) {
+      const target = document.querySelector(hash);
+      if (target) {
+        window.scrollTo({
+          top: target.offsetTop - 50,
+          // behavior: 'smooth' // Для плавной прокрутки
+        });
+      }
+    }
+  }
+
+  // MAIN
+  window.addEventListener('hashchange', scrollToChapter);
+  scrollToChapter();
+});
+
+useHead(() => ({
+  link: [
+    {rel: 'icon', type: 'image/x-icon', href: '/favicon.ico'},
+  ]
+}));
+
+</script>
+
+<template>
+  <div class="app-frame">
+    <AppHeader/>
+    <div class="app-main">
+      <div class="app-left"></div>
+      <main class="app-center">
+        <slot/>
+      </main>
+      <div class="app-right"></div>
+    </div>
+    <AppFooter/>
+  </div>
+</template>
+
+<style>
+.app-frame {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+.app-main {
+  display: flex;
+}
+
+.app-left, .app-center, .app-right {
+  flex: 1;
+}
+
+.app-center {
+  margin: 0;
+  max-width: 800px;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+.app-center IMG {
+  width: 100%;
+}
+
+/* === Styles for mobiles === */
+@media only screen and (max-width: 800px) {
+  .app-center {
+    max-width: calc(100vw - 10px);
+  }
+
+  PRE {
+    max-width: calc(100vw - 10px);
+  }
+}
+</style>

package/docs/nuxt.config.mjs

@@ -0,0 +1,11 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+export default defineNuxtConfig({
+  app: {baseURL: '/'},
+  content: {},
+  css: ['~/assets/css/layout.css'],
+  devtools: {enabled: false},
+  experimental: {payloadExtraction: false},
+  googleFonts: {families: {Inter: true},},
+  gtag: {id: 'AW-11336737732'},
+  modules: ['@nuxt/content', '@nuxtjs/google-fonts', 'nuxt-gtag'],
+});