Add Reset feature, update get to return undefined instead of null

Author: etienne-dldc

mod.ts

@@ -1,5 +1,13 @@
+export { RESET } from "./src/constants.ts";
+export {
+  InvalidStackSubClassErreur,
+  MissingContextErreur,
+} from "./src/erreur.ts";
+export type {
+  InvalidStackSubClassErreurData,
+  MissingContextErreurData,
+} from "./src/erreur.ts";
 export * from "./src/Key.ts";
 export { Stack } from "./src/Stack.ts";
 export { StackCore } from "./src/StackCore.ts";
 export type { TStackCoreTuple, TStackCoreValue } from "./src/StackCore.ts";
-export { MissingContextErreur } from "./src/erreur.ts";

src/Key.ts

@@ -1,11 +1,18 @@
-import { INTERNAL } from "./constants.ts";
+import { INTERNAL, RESET } from "./constants.ts";
 
 /**
  * A function that stringify a value.
  * This should return a single line that represent the value.
  */
 export type TStringify<T> = (value: T) => string;
 
+/**
+ * The object used to read a value from the stack.
+ *
+ * ```ts
+ * stack.get(MyKey.Consumer)
+ * ```
+ */
 export interface TKeyConsumer<T, HasDefault extends boolean = boolean> {
   readonly [INTERNAL]: true;
   readonly stringify: TStringify<T>;
@@ -14,6 +21,14 @@ export interface TKeyConsumer<T, HasDefault extends boolean = boolean> {
   readonly defaultValue: T | undefined;
 }
 
+/**
+ * An object that can be used to set a value in the stack.
+ * Use `MyKey.Provider(value)` to create it.
+ *
+ * ```ts
+ * stack.with(MyKey.Provider(value))
+ * ```
+ */
 export interface TKeyProvider<T, HasDefault extends boolean = boolean> {
   readonly [INTERNAL]: true;
   readonly name: string;
@@ -23,78 +38,120 @@ export interface TKeyProvider<T, HasDefault extends boolean = boolean> {
 
 export type TArgsBase = readonly unknown[];
 
+/**
+ * A function that create a TKeyProvider.
+ */
 export type TKeyProviderFn<
   T,
   HasDefault extends boolean,
-  Args extends TArgsBase,
-> = (
-  ...args: Args
-) => TKeyProvider<T, HasDefault>;
+  Args extends TArgsBase
+> = (...args: Args) => TKeyProvider<T, HasDefault>;
 
-// Expose both Provider & Consumer because this way you can expose only one of them
+/**
+ * Result of `createKey`, `createKeyWithDefault` and `createEmptyKey`.
+ *
+ * ```ts
+ * const MyKey = createKey<number>('num');
+ * ```
+ */
 export interface TKeyBase<
   T,
   HasDefault extends boolean,
-  Args extends TArgsBase = [T],
+  Args extends TArgsBase = [T]
 > {
   Consumer: TKeyConsumer<T, HasDefault>;
   Provider: TKeyProviderFn<T, HasDefault, Args>;
+  Reset: TKeyProvider<T, HasDefault>;
 }
 
+/**
+ * Type of a key created with `createKey`.
+ */
 export type TKey<T, HasDefault extends boolean = false> = TKeyBase<
   T,
   HasDefault,
   [value: T]
 >;
+
+/**
+ * Type of a key created with `createEmptyKey`.
+ */
 export type TVoidKey<HasDefault extends boolean = false> = TKeyBase<
   undefined,
   HasDefault,
   []
 >;
 
+/**
+ * Create a key for a Stack
+ *
+ * ```ts
+ * const MyKey = createKey<number>('num');
+ * const MyKeyStringified = createKey<number>('str', (value) => value.toFixed(2));
+ * ```
+ *
+ * @param name The name of the key, used when inspecting the stack.
+ * @param stringify An optional function that convert the value to a string when inspecting the stack.
+ * @returns {TKey} A key object.
+ */
 export function createKey<T>(
   name: string,
-  stringify: TStringify<T> = strigifyUnknow,
+  stringify: TStringify<T> = strigifyUnknow
 ): TKey<T, false> {
   return createInternal<T, false, [value: T]>(
     name,
     stringify,
     false,
-    undefined,
+    undefined
   );
 }
 
+/**
+ * Create a key for a Stack with a default value.
+ *
+ * ```ts
+ * const MyKey = createKeyWithDefault<number>('num', 42);
+ * ```
+ *
+ * @param name The name of the key, used when inspecting the stack.
+ * @param defaultValue The default value of the key, this value will be used if the key is not set in the stack when calling `get`.
+ * @param stringify An optional function that convert the value to a string when inspecting the stack.
+ * @returns A key object with a default value.
+ */
 export function createKeyWithDefault<T>(
   name: string,
   defaultValue: T,
-  stringify: TStringify<T> = strigifyUnknow,
+  stringify: TStringify<T> = strigifyUnknow
 ): TKey<T, true> {
   return createInternal<T, true, [value: T]>(
     name,
     stringify,
     true,
-    defaultValue,
+    defaultValue
   );
 }
 
+/**
+ * Create a key for a Stack with no value.
+ * With suck key, `get` will always return `undefined`. You should use `has` to check if the key is set.
+ *
+ * @param name The name of the key, used when inspecting the stack.
+ * @returns A key object with no value.
+ */
 export function createEmptyKey(name: string): TVoidKey<false> {
   return createInternal<undefined, false, []>(
     name,
     strigifyEmpty,
     false,
-    undefined,
+    undefined
   );
 }
 
-function createInternal<
-  T,
-  HasDefault extends boolean,
-  Args extends TArgsBase,
->(
+function createInternal<T, HasDefault extends boolean, Args extends TArgsBase>(
   name: string,
   stringify: TStringify<T>,
   hasDefault: HasDefault,
-  defaultValue: T | undefined,
+  defaultValue: T | undefined
 ): TKeyBase<T, HasDefault, Args> {
   const Consumer: TKeyConsumer<T, HasDefault> = {
     [INTERNAL]: true,
@@ -109,6 +166,7 @@ function createInternal<
   return {
     Consumer,
     Provider: Provider as unknown as TKeyProviderFn<T, HasDefault, Args>,
+    Reset: Provider(RESET as T) as TKeyProvider<T, HasDefault>,
   };
 }
 

src/Stack.ts

@@ -4,6 +4,7 @@ import type { TKeyConsumer, TKeyProvider } from "./Key.ts";
 import type { TStackCoreValue } from "./StackCore.ts";
 import { StackCore } from "./StackCore.ts";
 import { INTERNAL, NODE_INSPECT } from "./constants.ts";
+import { createInvalidStackSubClassErreur } from "./erreur.ts";
 import { indent } from "./indent.ts";
 
 /**
@@ -28,8 +29,8 @@ export class Stack {
   }
 
   public get<T, HasDefault extends boolean>(
-    consumer: TKeyConsumer<T, HasDefault>,
-  ): HasDefault extends true ? T : T | null {
+    consumer: TKeyConsumer<T, HasDefault>
+  ): HasDefault extends true ? T : T | undefined {
     return StackCore.get(this[INTERNAL], consumer);
   }
 
@@ -61,9 +62,7 @@ export class Stack {
   protected instantiate(stackCore: TStackCoreValue): this {
     // make sure we are instantiating the same class
     if (this.constructor !== Stack) {
-      throw new Error(
-        "Cannot instantiate a Stack subclass, you need to override instantiate()",
-      );
+      throw createInvalidStackSubClassErreur(this.constructor);
     }
     return new Stack(stackCore) as this;
   }

src/StackCore.ts

@@ -1,8 +1,8 @@
 // deno-lint-ignore-file no-explicit-any
 
 import type { TKeyConsumer, TKeyProvider } from "./Key.ts";
-import { DEBUG, NODE_INSPECT, PARENT, PROVIDER } from "./constants.ts";
-import { throwMissingContextErreur } from "./erreur.ts";
+import { DEBUG, NODE_INSPECT, PARENT, PROVIDER, RESET } from "./constants.ts";
+import { createMissingContextErreur } from "./erreur.ts";
 import { indent } from "./indent.ts";
 
 export type TStackCoreTuple = [parent: StackCore, provider: TKeyProvider<any>];
@@ -15,7 +15,7 @@ export class StackCore {
 
   protected constructor(
     provider: TKeyProvider<any>,
-    parent: TStackCoreValue = null,
+    parent: TStackCoreValue = null
   ) {
     Object.defineProperty(this, PARENT, {
       enumerable: false,
@@ -53,38 +53,51 @@ export class StackCore {
 
   static findFirstMatch(
     stack: TStackCoreValue,
-    consumer: TKeyConsumer<any, any>,
+    consumer: TKeyConsumer<any, any>
   ): { found: boolean; value: any } {
     if (stack === null) {
       return { found: false, value: null };
     }
     const provider = stack[PROVIDER];
     if (provider.consumer === consumer) {
-      return {
-        found: true,
-        value: provider.value,
-      };
+      if (provider.value === RESET) {
+        return { found: false, value: null };
+      }
+      return { found: true, value: provider.value };
     }
     return StackCore.findFirstMatch(stack[PARENT], consumer);
   }
 
+  /**
+   * Return true if the stack has a value for the given consumer.
+   * If the last value is RESET, it will return false.
+   * @param stack
+   * @param consumer
+   * @returns
+   */
   static has(
     stack: TStackCoreValue,
-    consumer: TKeyConsumer<any, any>,
+    consumer: TKeyConsumer<any, any>
   ): boolean {
     return StackCore.findFirstMatch(stack, consumer).found;
   }
 
+  /**
+   * Get the value for a given consumer.
+   * @param stack
+   * @param consumer
+   * @returns
+   */
   static get<T, HasDefault extends boolean>(
     stack: TStackCoreValue,
-    consumer: TKeyConsumer<T, HasDefault>,
-  ): HasDefault extends true ? T : T | null {
+    consumer: TKeyConsumer<T, HasDefault>
+  ): HasDefault extends true ? T : T | undefined {
     const res = StackCore.findFirstMatch(stack, consumer);
     if (res.found === false) {
       if (consumer.hasDefault) {
         return consumer.defaultValue as any;
       }
-      return null as any;
+      return undefined as any;
     }
     return res.value;
   }
@@ -100,8 +113,10 @@ export class StackCore {
     for (const [, provider] of StackCore.extract(stack)) {
       details.unshift(
         `${provider.consumer.name}: ${
-          provider.consumer.stringify(provider.value)
-        }`,
+          provider.value === RESET
+            ? "RESET"
+            : provider.consumer.stringify(provider.value)
+        }`
       );
     }
     if (details.length === 0) {
@@ -114,9 +129,14 @@ export class StackCore {
     return details.join("\n");
   }
 
+  /**
+   * Get all the values for a given consumer as an iterator.
+   * The values are returned in the reverse order they were set (First In Last Out).
+   * The iterator will stop when it reaches the end of the stack or when it finds a RESET value.
+   */
   static getAll<T>(
     stack: TStackCoreValue,
-    consumer: TKeyConsumer<T>,
+    consumer: TKeyConsumer<T>
   ): IterableIterator<T> {
     let current: TStackCoreValue = stack;
     return {
@@ -125,6 +145,10 @@ export class StackCore {
           const provider = current[PROVIDER];
           current = current[PARENT];
           if (provider.consumer === consumer) {
+            if (provider.value === RESET) {
+              current = null;
+              return { value: undefined, done: true };
+            }
             return { value: provider.value, done: false };
           }
         }
@@ -142,7 +166,7 @@ export class StackCore {
       if (consumer.hasDefault) {
         return consumer.defaultValue as any;
       }
-      return throwMissingContextErreur(consumer);
+      throw createMissingContextErreur(stack, consumer);
     }
     return res.value;
   }
@@ -193,7 +217,7 @@ export class StackCore {
     }
     const rightExtracted = Array.from(
       StackCore.extract(right),
-      ([, provider]) => provider,
+      ([, provider]) => provider
     ).reverse();
     return StackCore.with(left, ...rightExtracted);
   }
@@ -218,7 +242,10 @@ export class StackCore {
         continue;
       }
       seenKeys.add(provider.consumer);
-      baseQueue.push(provider);
+      // If the value is RESET, no need to add it to the queue
+      if (provider.value !== RESET) {
+        baseQueue.push(provider);
+      }
     }
     if (base === stack) {
       // no duplicates
@@ -231,7 +258,8 @@ export class StackCore {
 
   static debug(stack: TStackCoreValue): Array<{ value: any; ctxId: string }> {
     const world: any = globalThis;
-    const idMap = (world[DEBUG] as WeakMap<any, string>) ||
+    const idMap =
+      (world[DEBUG] as WeakMap<any, string>) ||
       (world[DEBUG] = new WeakMap<any, string>());
     const result: Array<{ value: any; ctxName: string; ctxId: string }> = [];
     traverse(stack);

src/constants.ts

@@ -3,4 +3,10 @@ export const PROVIDER = Symbol.for("dldc.stack.provider");
 export const PARENT = Symbol.for("dldc.stack.parent");
 export const DEBUG = Symbol.for("dldc.stack.debug");
 
+/**
+ * Special symbol to reset a Key.
+ * If the latest value is RESET, has() will return false.
+ */
+export const RESET = Symbol.for("dldc.stack.reset");
+
 export const NODE_INSPECT = Symbol.for("nodejs.util.inspect.custom");