docs: 📝 tracking example, additions to readme

README.md

@@ -60,6 +60,12 @@ const nextSession = container.get(sessionRef)
 console.log(currentSession, nextSession)
 ```
 
+## Extensions
+
+ - The TrackingContainer in comparison to a normal Container has the method `run` which wraps around AsyncLocalStorage. Inside the callback of `run` the methods of TrackingContainer are using a separate scope.
+
+ - The decorators `Inject` and `InjectOrFail` can be created for a container and then used above class variables. When an object of such a class is created, the decorated class variables are filled by the container.
+
 ## Integrations
 
 Some libraries include direct support or are easily extended with a  context object. Typically AsynLocalStorage is used in the background to track it. The TrackingContainer also uses asynchronous context tracking and creates a new scope inside every `run` callback.
@@ -79,7 +85,7 @@ export const container = new TrackingContainer()
 export const ormRef = Container.ref<EntityManager>()
 ~~~
 
-Add a scoped factory to create a fork of EntityManager. It is necessry to use the option `disableContextResolution` to prevent a recursion. Now init MikroORM with the `context` option getting the orm object from the container.
+Add a scoped factory to create a fork of EntityManager. It is necessary to use the option `disableContextResolution` to prevent a recursion. Now init MikroORM with the `context` option getting the orm object from the container.
 
 ~~~ts
 let orm: EntityManager | null  = null
@@ -106,9 +112,14 @@ The documentation is build with TypeDoc and hosted on GitHub Pages at [https://m
 ### Examples
 
 - [Basic](https://github.com/ml1nk/symboldi/tree/main/packages/example/src/basic)
+
+- [Tracking](https://github.com/ml1nk/symboldi/tree/main/packages/example/src/tracking)
+
 - [Decorators](https://github.com/ml1nk/symboldi/tree/main/packages/example/src/decorators)
 
 ## Similiar projects
+
 - [Inversify](https://github.com/inversify/InversifyJS)
+
 - [TypeDi](https://github.com/typestack/typedi)
 

packages/example/package.json

@@ -8,6 +8,7 @@
   },
   "scripts": {
     "basic": "node ./dist/src/basic/use.js",
-    "decorators": "node ./dist/src/basic/use.js"
+    "tracking": "node ./dist/src/tracking/use.js",
+    "decorators": "node ./dist/src/decorators/use.js"
   }
 }

packages/example/src/tracking/register.ts

@@ -0,0 +1,4 @@
+import { sessionRef, container } from './service.js'
+import crypto from 'crypto'
+
+container.addScoped(() => crypto.randomUUID(), sessionRef)

packages/example/src/tracking/service.ts

@@ -0,0 +1,7 @@
+import { TrackingContainer } from 'symboldi/tracking'
+
+// empty container
+export const container = new TrackingContainer()
+
+// define ref for session
+export const sessionRef = TrackingContainer.ref<string>()

packages/example/src/tracking/use.ts

@@ -0,0 +1,20 @@
+import { container, sessionRef } from './service.js'
+import './register.js'
+
+// get first session
+const firstSession = container.get(sessionRef)
+let secondSession = ""
+
+container.run(()=>{
+    // get a second session, inside the run callback
+    secondSession = container.getOrFail(sessionRef)
+})
+
+// get a third session, outside the run callback
+const thirdSession = container.getOrFail(sessionRef)
+
+/**
+ * firstSession and thirdSession matches, secondSession is different
+ * ceff046e-ceb0-456e-875b-3010792e1294 dbe8fd2e-99c4-4f03-b57e-b930a90249f2 ceff046e-ceb0-456e-875b-3010792e1294
+ */
+console.log(firstSession, secondSession, thirdSession)

packages/symboldi/src/classes/TrackingContainer.ts

@@ -16,9 +16,7 @@ export class TrackingContainer extends Container {
   }
 
   /**
-   * Runs the callback in a new context.
-   * If there was already a context a new scope is created,
-   * otherwise the base container is cloned.
+   * Inside the callback a new scope is used.
    *
    * @param callback fn to execute inside context
    * @param args args of callback
@@ -28,10 +26,8 @@ export class TrackingContainer extends Container {
     callback: (...args: TArgs) => R,
     ...args: TArgs
   ): R {
-    const store = this.#storage.getStore()
-    const container = store !== undefined ? store.scopeCreate() : super.scopeCreate()
     return this.#storage.run(
-      container,
+      super.scopeCreate(),
       callback,
       ...args
     )