@travetto/context 5.0.16 → 6.0.0-rc.0

package/README.md

@@ -17,52 +17,88 @@ This module provides a wrapper around node's [async_hooks](https://nodejs.org/ap
 
 The most common way of utilizing the context, is via the [WithAsyncContext](https://github.com/travetto/travetto/tree/main/module/context/src/decorator.ts#L7) decorator.  The decorator requires the class it's being used in, to have a [AsyncContext](https://github.com/travetto/travetto/tree/main/module/context/src/service.ts#L12) member, as it is the source of the contextual information. 
 
-The decorator will load the context on invocation, and will keep the context active during the entire asynchronous call chain.
+The decorator will load the context on invocation, and will keep the context active during the entire asynchronous call chain. 
+
+**NOTE:** while access context properties directly is supported, it is recommended to use [AsyncContextValue](https://github.com/travetto/travetto/tree/main/module/context/src/value.ts#L16) instead.
 
 **Code: Usage of context within a service**
 ```typescript
 import { AsyncContext, WithAsyncContext } from '@travetto/context';
+import { Inject } from '@travetto/di';
+
+const NAME = Symbol.for('My Custom name symbol');
 
 export class ContextAwareService {
 
-  constructor(public context: AsyncContext) { }
+  @Inject()
+  context: AsyncContext;
 
   @WithAsyncContext()
   async complexOperator(name: string) {
-    this.context.set({ name });
+    this.context.set(NAME, name);
     await this.additionalOp('extra');
     await this.finalOp();
   }
 
   async additionalOp(additional: string) {
-    const { name } = this.context.get();
-    this.context.set({ name: `${name} ${additional}` });
+    const name = this.context.get(NAME);
+    this.context.set(NAME, `${name} ${additional}`);
   }
 
   async finalOp() {
-    const { name } = this.context.get();
+    const name = this.context.get(NAME);
     // Use name
     return name;
   }
 }
 ```
 
-The decorator also allows for a priming of the contextual information.  This is generally useful for system generated operations that are not initiated by a user.
+## AsyncContextValue
+Within the framework that is a need to access context values, in a type safe fashion.  Additionally, we have the requirement to keep the data accesses isolated from other operations.  To this end, [AsyncContextValue](https://github.com/travetto/travetto/tree/main/module/context/src/value.ts#L16) was created to support this use case.  This class represents the ability to define a simple read/write contract for a given context field.  It also provides some supplemental functionality, e.g., the ability to suppress errors if a context is not initialized.
 
-**Code: Usage of context within a service**
+**Code: Source for AsyncContextValue**
 ```typescript
-import { AsyncContext, WithAsyncContext } from '@travetto/context';
+export class AsyncContextValue<T = unknown> {
+  constructor(source: StorageSource, config?: ContextConfig);
+  /**
+   * Get value
+   */
+  get(): T | undefined;
+  /**
+   * Set value
+   */
+  set(value: T | undefined): void;
+}
+```
 
-export class SystemInitiatedContext {
+**Code: Usage of context value within a service**
+```typescript
+import { AsyncContext, AsyncContextValue, WithAsyncContext } from '@travetto/context';
+import { Inject } from '@travetto/di';
+
+export class ContextValueService {
+
+  @Inject()
+  context: AsyncContext;
 
-  constructor(public context: AsyncContext) { }
+  #name = new AsyncContextValue<string>(this);
 
-  @WithAsyncContext({
-    user: 'system',
-    uid: 20
-  })
-  async runJob(name: string) {
-    console.log('Running', { user: this.context.get().user, jobName: name });
+  @WithAsyncContext()
+  async complexOperator(name: string) {
+    this.#name.set(name);
+    await this.additionalOp('extra');
+    await this.finalOp();
+  }
+
+  async additionalOp(additional: string) {
+    const name = this.#name.get();
+    this.#name.set(`${name} ${additional}`);
+  }
+
+  async finalOp() {
+    const name = this.#name.get();
+    // Use name
+    return name;
   }
 }
 ```

package/__index__.ts

@@ -1,2 +1,3 @@
 export * from './src/service';
+export * from './src/value';
 export * from './src/decorator';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/context",
-  "version": "5.0.16",
+  "version": "6.0.0-rc.0",
   "description": "Async-aware state management, maintaining context across asynchronous calls.",
   "keywords": [
     "async-hooks",
@@ -26,10 +26,10 @@
     "directory": "module/context"
   },
   "dependencies": {
-    "@travetto/di": "^5.0.16"
+    "@travetto/di": "^6.0.0-rc.0"
   },
   "peerDependencies": {
-    "@travetto/test": "^5.0.18"
+    "@travetto/test": "^6.0.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@travetto/test": {

package/src/decorator.ts

@@ -4,7 +4,7 @@ import { AsyncContext } from './service';
 /**
  * Allows running a function while providing an async context
  */
-export function WithAsyncContext(data?: Record<string, unknown>) {
+export function WithAsyncContext() {
   return function <T extends { context: AsyncContext }>(
     target: T,
     prop: string,
@@ -12,7 +12,7 @@ export function WithAsyncContext(data?: Record<string, unknown>) {
   ): typeof descriptor {
     const og = descriptor.value!;
     descriptor.value = function (...args: unknown[]): ReturnType<typeof og> {
-      return this.context.run(og.bind(this, ...args), structuredClone(data ?? {}));
+      return this.context.run(og.bind(this, ...args));
     };
 
     Object.defineProperty(descriptor.value, 'name', { value: og.name });

package/src/service.ts

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 import { Injectable } from '@travetto/di';
-import { AppError, castTo } from '@travetto/runtime';
+import { AppError, AsyncQueue, castTo } from '@travetto/runtime';
 
 type Ctx<T = unknown> = Record<string | symbol, T>;
 
@@ -11,89 +11,72 @@ type Ctx<T = unknown> = Record<string | symbol, T>;
 @Injectable()
 export class AsyncContext {
 
-  alStorage = new AsyncLocalStorage<{ value?: Ctx }>();
-  active = 0;
+  storage = new AsyncLocalStorage<Ctx>();
 
   constructor() {
     this.run = this.run.bind(this);
     this.iterate = this.iterate.bind(this);
   }
 
-  #store<T = unknown>(setAs?: Ctx<T> | null): Ctx<T> {
-    const val = this.alStorage.getStore();
-    if (!val) {
+  #get<T = unknown>(): Ctx<T> {
+    const store = this.storage.getStore();
+    if (!store) {
       throw new AppError('Context is not initialized');
     }
-    if (setAs) {
-      val.value = setAs;
-    } else if (!val.value) {
-      val.value = {};
-    }
-    return castTo(val.value);
+    return castTo(store);
   }
 
   /**
-   * Get entire context or a portion by key
+   * Are we in an active context
    */
-  get<T = unknown>(key: string | symbol): T;
-  get(): Ctx;
-  get<T>(key?: string | symbol): Ctx | T {
-    const root = this.#store<T>();
-    if (key) {
-      return root[key];
-    } else {
-      return root;
-    }
+  get active(): boolean {
+    return this.storage.getStore() !== undefined;
   }
 
   /**
-   * Set entire context or a portion by key
+   * Get context field by key
    */
-  set(key: string | symbol, val: unknown): void;
-  set(val: Ctx): void;
-  set(keyOrVal: string | symbol | Ctx, valWithKey?: unknown): void {
-    if (typeof keyOrVal === 'string' || typeof keyOrVal === 'symbol') {
-      this.get()[keyOrVal] = valWithKey;
-    } else {
-      this.#store(keyOrVal);
-    }
+  get<T = unknown>(key: string | symbol): T | undefined {
+    return this.#get<T>()[key];
+  }
+
+  /**
+   * Set context field by key
+   */
+  set<T = unknown>(key: string | symbol, val: T | undefined): void {
+    this.#get()[key] = val;
+  }
+
+  /**
+   * Get entire context
+   * @private
+   */
+  copy<T = unknown>(): Ctx<T> {
+    return structuredClone(this.#get<T>());
   }
 
   /**
    * Run an async function and ensure the context is available during execution
    */
   async run<T = unknown>(fn: () => Promise<T> | T, init: Ctx = {}): Promise<T> {
-    if (this.alStorage.getStore()) {
-      init = { ...this.#store(), ...init };
-    }
-    this.active += 1;
-    this.alStorage.enterWith({ value: init });
-    try {
-      return await fn();
-    } finally {
-      delete this.alStorage.getStore()?.value;
-      if ((this.active -= 1) === 0) {
-        this.alStorage.disable();
-      }
-    }
+    return this.storage.run({ ...this.storage.getStore(), ...init }, fn);
   }
 
   /**
    * Run an async function and ensure the context is available during execution
    */
-  async * iterate<T>(fn: () => AsyncGenerator<T>, init: Ctx = {}): AsyncGenerator<T> {
-    if (this.alStorage.getStore()) {
-      init = { ...this.#store(), ...init };
-    }
-    this.active += 1;
-    this.alStorage.enterWith({ value: init });
-    try {
-      return yield* fn();
-    } finally {
-      delete this.alStorage.getStore()?.value;
-      if ((this.active -= 1) === 0) {
-        this.alStorage.disable();
+  iterate<T>(fn: () => AsyncIterable<T>, init: Ctx = {}): AsyncIterable<T> {
+    const out = new AsyncQueue<T>();
+    this.storage.run({ ...this.storage.getStore(), ...init }, async () => {
+      try {
+        for await (const item of fn()) {
+          out.add(item);
+        }
+        out.close();
+      } catch (err) {
+        out.throw(castTo(err));
       }
-    }
+    });
+    return out;
   }
 }

package/src/value.ts

@@ -0,0 +1,60 @@
+import { AppError, castTo } from '@travetto/runtime';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+type Payload<T> = Record<string | symbol, T | undefined>;
+type Storage<T = unknown> = AsyncLocalStorage<Payload<T>>;
+type Key = string | symbol;
+type StorageSource = Storage | (() => Storage) | { storage: Storage } | { context: { storage: Storage } };
+
+type ContextConfig = {
+  failIfUnbound?: boolean;
+};
+
+/**
+ * Async Context Value
+ */
+export class AsyncContextValue<T = unknown> {
+
+  #source: () => Storage<T>;
+  #storage?: Storage<T>;
+  #key: Key = Symbol();
+  #failIfUnbound: boolean;
+
+  constructor(source: StorageSource, config?: ContextConfig) {
+    this.#source = castTo(typeof source === 'function' ?
+      source :
+      ((): Storage => 'getStore' in source ?
+        source :
+        ('storage' in source ?
+          source.storage :
+          source.context.storage
+        ))
+    );
+    this.#failIfUnbound = config?.failIfUnbound ?? true;
+  }
+
+  get #store(): Payload<T> | undefined {
+    const store = (this.#storage ??= this.#source()).getStore();
+    if (!store && this.#failIfUnbound) {
+      throw new AppError('Context not initialized');
+    }
+    return store;
+  }
+
+  /**
+   * Get value
+   */
+  get(): T | undefined {
+    return this.#store?.[this.#key];
+  }
+
+  /**
+   * Set value
+   */
+  set(value: T | undefined): void {
+    const store = this.#store;
+    if (store) {
+      store[this.#key] = value;
+    }
+  }
+}

package/support/test/context.ts

@@ -11,11 +11,11 @@ const Init = Symbol();
  * Allows for defining a common suite context
  * @param data
  */
-export function WithSuiteContext(data: Record<string, unknown> = {}) {
+export function WithSuiteContext() {
   return (target: Class): void => {
     function wrapped(ctx: AsyncContext, og: Function) {
       return function (this: unknown) {
-        return ctx.run(og.bind(this), structuredClone(data));
+        return ctx.run(og.bind(this));
       };
     }
 

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2020 ArcSine Technologies
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.