Introduce ContextUpKey

An updatable context value key.

Author: surol

src/context-key.ts

@@ -102,7 +102,7 @@ export interface ContextValueOpts<Ctx extends ContextValues, Value, Src, Seed> {
   /**
    * Handles missing context value.
    *
-   * It can be called to prefer a fallback value over default one specified by the value key.
+   * It can be called to prefer a fallback value over the default one specified in the value key.
    *
    * @param defaultProvider  Default value provider. It is called unless a fallback value is specified.
    * If it returns a non-null/non-undefined value, then the returned value will be associated with the context key.

src/context-registry.spec.ts

@@ -63,7 +63,7 @@ describe('ContextRegistry', () => {
       expect(() => values.get(new SingleContextKey(key.name))).toThrowError(ContextKeyError);
       expect(() => values.get(new SingleContextKey(key.name), {})).toThrowError(ContextKeyError);
     });
-    it('provides fallback value is there is no provider', () => {
+    it('provides fallback value if there is no provider', () => {
       expect(values.get(new SingleContextKey<string>(key.name), { or: 'fallback' })).toBe('fallback');
     });
     it('provides default value if provider did not provide any value', () => {

src/context-up-key.spec.ts

@@ -0,0 +1,72 @@
+import { AfterEvent, afterEventOf } from 'fun-events';
+import { ContextKeyError } from './context-key-error';
+import { ContextRegistry } from './context-registry';
+import { SingleContextUpKey } from './context-up-key';
+import { ContextValues } from './context-values';
+
+describe('ContextUpKey', () => {
+
+  let registry: ContextRegistry<ContextValues>;
+  let values: ContextValues;
+
+  beforeEach(() => {
+    registry = new ContextRegistry();
+    values = registry.newValues();
+  });
+
+  describe('SingleContextUpKey', () => {
+
+    let key: SingleContextUpKey<string>;
+
+    beforeEach(() => {
+      key = new SingleContextUpKey('test-key');
+    });
+
+    it('provides a value specified verbatim', () => {
+
+      const value = 'test value';
+
+      registry.provide({ a: key, is: value });
+      expect(readValue(values.get(key))).toBe(value);
+    });
+    it('provides a value specified by event keeper', () => {
+
+      const value = 'test value';
+
+      registry.provide({ a: key, is: afterEventOf(value) });
+      expect(readValue(values.get(key))).toBe(value);
+    });
+    it('throws if there is neither default nor fallback value', () => {
+      expect(() => readValue(values.get(key))).toThrowError(ContextKeyError);
+      expect(() => readValue(values.get(key, {})!)).toThrowError(ContextKeyError);
+    });
+    it('throws if fallback value is `null`', () => {
+      expect(() => readValue(values.get(key, { or: null })!)).toThrowError(ContextKeyError);
+    });
+    it('throws if fallback value is `undefined`', () => {
+      expect(() => readValue(values.get(key, { or: undefined })!)).toThrowError(ContextKeyError);
+    });
+    it('provides fallback value if there is no provider', () => {
+      expect(readValue(values.get(key, { or: afterEventOf('fallback') }))).toBe('fallback');
+    });
+    it('provides default value if provider did not provide any value', () => {
+
+      const defaultValue = 'default';
+      const keyWithDefaults = new SingleContextUpKey<string>(key.name, { byDefault: () => defaultValue });
+
+      registry.provide({ a: keyWithDefaults, is: null });
+
+      expect(readValue(values.get(keyWithDefaults))).toBe(defaultValue);
+    });
+  });
+
+});
+
+function readValue<Value>(from: AfterEvent<[Value]>): Value {
+
+  let received: Value = undefined!;
+
+  from.once(value => received = value);
+
+  return received;
+}

src/context-up-key.ts

@@ -0,0 +1,182 @@
+import { flatMapIt, mapIt, overArray } from 'a-iterable';
+import { asis, NextArgs, nextArgs, noop } from 'call-thru';
+import {
+  AfterEvent,
+  afterEventBy,
+  afterEventFrom,
+  afterEventFromEach,
+  afterEventOf,
+  EventKeeper,
+  isEventKeeper,
+  trackValue,
+  ValueTracker,
+} from 'fun-events';
+import { ContextKey, ContextSeedKey, ContextValueOpts } from './context-key';
+import { ContextSeeder } from './context-seeder';
+import { ContextValueProvider } from './context-value-spec';
+import { ContextValues } from './context-values';
+import { ContextKeyError } from './context-key-error';
+
+class ContextUpSeeder<Ctx extends ContextValues, Src>
+    implements ContextSeeder<Ctx, Src | EventKeeper<Src[]>, AfterEvent<Src[]>> {
+
+  private readonly _providers: ValueTracker<ContextValueProvider<Ctx, Src | EventKeeper<Src[]>>[]> = trackValue([]);
+
+  provide(provider: ContextValueProvider<Ctx, Src | EventKeeper<Src[]>>): void {
+    this._providers.it = [...this._providers.it, provider];
+  }
+
+  seed(context: Ctx, initial: AfterEvent<Src[]> = afterEventOf<Src[]>()): AfterEvent<Src[]> {
+    return this.combine(initial, upSrcKeepers(context, this._providers));
+  }
+
+  isEmpty(): boolean {
+    return false;
+  }
+
+  combine(first: AfterEvent<Src[]>, second: AfterEvent<Src[]>): AfterEvent<Src[]> {
+    return afterEventFromEach(
+        first,
+        second,
+    ).keep.thru(
+        (...sources) => flatUpSources(sources),
+    );
+  }
+
+}
+
+function upSrcKeepers<Ctx extends ContextValues, Src>(
+    context: Ctx,
+    providersTracker: ValueTracker<ContextValueProvider<Ctx, Src | EventKeeper<Src[]>>[]>,
+): AfterEvent<Src[]> {
+  return providersTracker.read.keep.dig(
+      providers => !providers.length ? afterEventOf() : afterEventFromEach(
+          ...mapIt(
+              mapIt(
+                  overArray(providers),
+                  prov => prov(context),
+              ),
+              toUpSrcKeeper,
+          ),
+      ).keep.thru(
+          (...sources) => flatUpSources(sources),
+      ));
+}
+
+function toUpSrcKeeper<Src>(src: null | undefined | Src | EventKeeper<Src[]>): AfterEvent<Src[]> {
+  return src == null ? afterEventOf() : isUpSrcKeeper(src) ? afterEventFrom(src) : afterEventOf(src);
+}
+
+function isUpSrcKeeper<Src>(src: Src | EventKeeper<Src[]>): src is EventKeeper<Src[]> {
+  return (typeof src === 'object' || typeof src === 'function') && isEventKeeper(src as (object | Function));
+}
+
+function flatUpSources<Src, NextReturn>(sources: Src[][]): NextArgs<Src[], NextReturn> {
+  return nextArgs<Src[], NextReturn>(
+      ...flatMapIt(overArray(sources), asis)
+  );
+}
+
+class ContextSeedUpKey<Src> extends ContextSeedKey<Src | EventKeeper<Src[]>, AfterEvent<Src[]>> {
+
+  seeder<Ctx extends ContextValues>(): ContextSeeder<Ctx, Src | EventKeeper<Src[]>, AfterEvent<Src[]>> {
+    return new ContextUpSeeder();
+  }
+
+}
+
+/**
+ * Abstract implementation of updatable context value key.
+ *
+ * Accepts single value sources and `EventKeeper`s of value source arrays.
+ *
+ * Collects value sources into `AfterEvent` registrar of source values array receivers.
+ *
+ * @typeparam Value  Context value type.
+ * @typeparam Src  Source value type.
+ */
+export abstract class ContextUpKey<Value, Src> extends ContextKey<Value, Src | EventKeeper<Src[]>, AfterEvent<Src[]>> {
+
+  readonly seedKey: ContextSeedKey<Src | EventKeeper<Src[]>, AfterEvent<Src[]>>;
+
+  /**
+   * Constructs simple context value key.
+   *
+   * @param name  Human-readable key name.
+   * @param seedKey  Value seed key. A new one will be constructed when omitted.
+   */
+  protected constructor(name: string, seedKey?: ContextSeedKey<Src | EventKeeper<Src[]>, AfterEvent<Src[]>>) {
+    super(name);
+    this.seedKey = seedKey || new ContextSeedUpKey(this);
+  }
+
+}
+
+/**
+ * Single updatable context value key.
+ *
+ * The associated value is an `AfterEvent` registrar of receivers of the last source value. It is always present,
+ * but signals an [[ContextKeyError]] error on attempt to receive an absent value.
+ *
+ * It is an error to provide a `null` or `undefined` {@link ContextRequest.Opts.or fallback value} when requesting
+ * an associated value. Use an `afterEventOf()` result as a fallback instead.
+ *
+ * @typeparam Value  Context value type.
+ */
+export class SingleContextUpKey<Value> extends ContextUpKey<AfterEvent<[Value]>, Value> {
+
+  /**
+   * A provider of context value used when there is no value associated with this key.
+   */
+  readonly byDefault: ContextValueProvider<ContextValues, Value>;
+
+  /**
+   * Constructs single updatable context value key.
+   *
+   * @param name  Human-readable key name.
+   * @param seedKey  Value seed key. A new one will be constructed when omitted.
+   * @param byDefault  Optional default value provider. If unspecified or `undefined` the key has no default
+   * value.
+   */
+  constructor(
+      name: string,
+      {
+        seedKey,
+        byDefault = noop,
+      }: {
+        seedKey?: ContextSeedKey<Value | EventKeeper<Value[]>, AfterEvent<Value[]>>,
+        byDefault?: ContextValueProvider<ContextValues, Value>,
+      } = {}) {
+    super(name, seedKey);
+    this.byDefault = byDefault;
+  }
+
+  grow<Ctx extends ContextValues>(
+      opts: ContextValueOpts<Ctx, AfterEvent<[Value]>, EventKeeper<Value[]> | Value, AfterEvent<Value[]>>,
+  ): AfterEvent<[Value]> {
+    return opts.seed.keep.dig((...sources) => {
+      if (sources.length) {
+        // Sources present. Take the last one.
+        return afterEventOf(sources[sources.length - 1]);
+      }
+
+      // Sources absent. Attempt to detect the backup value.
+      const backup = opts.byDefault(() => {
+
+        const defaultValue = this.byDefault(opts.context);
+
+        return defaultValue && afterEventOf(defaultValue);
+      });
+
+      if (backup != null) {
+        return backup; // Backup value found.
+      }
+
+      // Backup value is absent. Construct a error response.
+      return afterEventBy<[Value]>(() => {
+        throw new ContextKeyError(this);
+      });
+    });
+  }
+
+}

src/index.ts

@@ -3,6 +3,7 @@ export * from './context-key-error';
 export * from './context-ref';
 export * from './context-registry';
 export * from './context-seeder';
+export * from './context-up-key';
 export * from './context-value-spec';
 export * from './context-values';
 export * from './simple-context-key';