@tstdl/base 0.84.4 → 0.84.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.84.4",
+  "version": "0.84.5",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -20,6 +20,7 @@
     "tsc-alias:watch": "tsc-alias --watch"
   },
   "dependencies": {
+    "@angular/core": "^16.0.0",
     "luxon": "^3.3",
     "reflect-metadata": "^0.1",
     "rxjs": "^7.8",

package/signals/api.d.ts

@@ -0,0 +1,14 @@
+import type * as Types from './implementation/index.js';
+export type { CreateComputedOptions, CreateEffectOptions, CreateSignalOptions, EffectRef, Signal, WritableSignal } from './implementation/index.js';
+export type SignalsConfiguration = {
+    signal: typeof Types.signal;
+    computed: typeof Types.computed;
+    effect: typeof Types.effect;
+    untracked: typeof Types.untracked;
+    isSignal: typeof Types.isSignal;
+};
+export declare let signal: typeof Types.signal;
+export declare let computed: typeof Types.computed;
+export declare let effect: typeof Types.effect;
+export declare let untracked: typeof Types.untracked;
+export declare let isSignal: typeof Types.isSignal;

package/signals/api.js

@@ -0,0 +1,57 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var api_exports = {};
+__export(api_exports, {
+  computed: () => computed,
+  effect: () => effect,
+  isSignal: () => isSignal,
+  signal: () => signal,
+  untracked: () => untracked
+});
+module.exports = __toCommonJS(api_exports);
+var AngularCore = __toESM(require("@angular/core"), 1);
+let signal;
+let computed;
+let effect;
+let untracked;
+let isSignal;
+function configureSignals(configuration) {
+  signal = configuration.signal;
+  computed = configuration.computed;
+  effect = configuration.effect;
+  untracked = configuration.untracked;
+  isSignal = configuration.isSignal;
+}
+configureSignals({
+  signal: AngularCore.signal,
+  computed: AngularCore.computed,
+  effect: AngularCore.effect,
+  untracked: AngularCore.untracked,
+  isSignal: AngularCore.isSignal
+});

package/signals/implementation/api.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import type { ReactiveNode } from './graph.js';
+/**
+ * Symbol used to tell `Signal`s apart from other functions.
+ *
+ * This can be used to auto-unwrap signals in various cases, or to auto-wrap non-signal values.
+ */
+declare const SIGNAL: unique symbol;
+/**
+ * A reactive value which notifies consumers of any changes.
+ *
+ * Signals are functions which returns their current value. To access the current value of a signal,
+ * call it.
+ *
+ * Ordinary values can be turned into `Signal`s with the `signal` function.
+ */
+export interface Signal<T> {
+    (): T;
+    [SIGNAL]?: unknown;
+}
+/**
+ * Checks if the given `value` function is a reactive `Signal`.
+ */
+export declare function isSignal(value: Function): value is Signal<unknown>;
+/**
+ * Converts `fn` into a marked signal function (where `isSignal(fn)` will be `true`).
+ *
+ * @param fn A zero-argument function which will be converted into a `Signal`.
+ */
+export declare function createSignalFromFunction<T>(node: ReactiveNode, fn: () => T): Signal<T>;
+/**
+ * Converts `fn` into a marked signal function (where `isSignal(fn)` will be `true`), and
+ * potentially add some set of extra properties (passed as an object record `extraApi`).
+ *
+ * @param fn A zero-argument function which will be converted into a `Signal`.
+ * @param extraApi An object whose properties will be copied onto `fn` in order to create a specific
+ *     desired interface for the `Signal`.
+ */
+export declare function createSignalFromFunction<T, U extends Record<string, unknown>>(node: ReactiveNode, fn: () => T, extraApi: U): Signal<T> & U;
+/**
+ * A comparison function which can determine if two values are equal.
+ *
+ * @developerPreview
+ */
+export type ValueEqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * The default equality function used for `signal` and `computed`, which treats objects and arrays
+ * as never equal, and all other primitive values using identity semantics.
+ *
+ * This allows signals to hold non-primitive values (arrays, objects, other collections) and still
+ * propagate change notification upon explicit mutation without identity change.
+ *
+ * @developerPreview
+ */
+export declare function defaultEquals<T>(a: T, b: T): boolean;
+export {};

package/signals/implementation/api.js

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var api_exports = {};
+__export(api_exports, {
+  createSignalFromFunction: () => createSignalFromFunction,
+  defaultEquals: () => defaultEquals,
+  isSignal: () => isSignal
+});
+module.exports = __toCommonJS(api_exports);
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+const SIGNAL = Symbol("SIGNAL");
+function isSignal(value) {
+  return value[SIGNAL] !== void 0;
+}
+function createSignalFromFunction(node, fn, extraApi = {}) {
+  fn[SIGNAL] = node;
+  return Object.assign(fn, extraApi);
+}
+function defaultEquals(a, b) {
+  return (a === null || typeof a !== "object") && Object.is(a, b);
+}

package/signals/implementation/computed.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import type { Signal, ValueEqualityFn } from './api.js';
+/**
+ * Options passed to the `computed` creation function.
+ *
+ * @developerPreview
+ */
+export interface CreateComputedOptions<T> {
+    /**
+     * A comparison function which defines equality for computed values.
+     */
+    equal?: ValueEqualityFn<T>;
+    additionalDependencies?: Signal<any>[];
+}
+/**
+ * Create a computed `Signal` which derives a reactive value from an expression.
+ *
+ * @developerPreview
+ */
+export declare function computed<T>(computation: () => T, options?: CreateComputedOptions<T>): Signal<T>;

package/signals/implementation/computed.js

@@ -0,0 +1,125 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var computed_exports = {};
+__export(computed_exports, {
+  computed: () => computed
+});
+module.exports = __toCommonJS(computed_exports);
+var import_type_guards = require("../../utils/type-guards.js");
+var import_api = require("./api.js");
+var import_graph = require("./graph.js");
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+function computed(computation, options = {}) {
+  const actualComputation = (0, import_type_guards.isUndefined)(options.additionalDependencies) || options.additionalDependencies.length == 0 ? computation : () => {
+    for (const dependency of options.additionalDependencies) {
+      dependency();
+    }
+    return computation();
+  };
+  const node = new ComputedImpl(actualComputation, options.equal ?? import_api.defaultEquals);
+  return (0, import_api.createSignalFromFunction)(node, node.signal.bind(node));
+}
+const UNSET = Symbol("UNSET");
+const COMPUTING = Symbol("COMPUTING");
+const ERRORED = Symbol("ERRORED");
+class ComputedImpl extends import_graph.ReactiveNode {
+  computation;
+  equal;
+  constructor(computation, equal) {
+    super();
+    this.computation = computation;
+    this.equal = equal;
+  }
+  /**
+   * Current value of the computation.
+   *
+   * This can also be one of the special values `UNSET`, `COMPUTING`, or `ERRORED`.
+   */
+  value = UNSET;
+  /**
+   * If `value` is `ERRORED`, the error caught from the last computation attempt which will
+   * be re-thrown.
+   */
+  error = null;
+  /**
+   * Flag indicating that the computation is currently stale, meaning that one of the
+   * dependencies has notified of a potential change.
+   *
+   * It's possible that no dependency has _actually_ changed, in which case the `stale`
+   * state can be resolved without recomputing the value.
+   */
+  stale = true;
+  consumerAllowSignalWrites = false;
+  onConsumerDependencyMayHaveChanged() {
+    if (this.stale) {
+      return;
+    }
+    this.stale = true;
+    this.producerMayHaveChanged();
+  }
+  onProducerUpdateValueVersion() {
+    if (!this.stale) {
+      return;
+    }
+    if (this.value !== UNSET && this.value !== COMPUTING && !this.consumerPollProducersForChange()) {
+      this.stale = false;
+      return;
+    }
+    this.recomputeValue();
+  }
+  recomputeValue() {
+    if (this.value === COMPUTING) {
+      throw new Error("Detected cycle in computations.");
+    }
+    const oldValue = this.value;
+    this.value = COMPUTING;
+    this.trackingVersion++;
+    const prevConsumer = (0, import_graph.setActiveConsumer)(this);
+    let newValue;
+    try {
+      newValue = this.computation();
+    } catch (err) {
+      newValue = ERRORED;
+      this.error = err;
+    } finally {
+      (0, import_graph.setActiveConsumer)(prevConsumer);
+    }
+    this.stale = false;
+    if (oldValue !== UNSET && oldValue !== ERRORED && newValue !== ERRORED && this.equal(oldValue, newValue)) {
+      this.value = oldValue;
+      return;
+    }
+    this.value = newValue;
+    this.valueVersion++;
+  }
+  signal() {
+    this.onProducerUpdateValueVersion();
+    this.producerAccessed();
+    if (this.value === ERRORED) {
+      throw this.error;
+    }
+    return this.value;
+  }
+}

package/signals/implementation/effect.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+/**
+ * A global reactive effect, which can be manually destroyed.
+ */
+export interface EffectRef {
+    /**
+     * Shut down the effect, removing it from any upcoming scheduled executions.
+     */
+    destroy(): void;
+}
+/**
+ * An effect can, optionally, register a cleanup function. If registered, the cleanup is executed
+ * before the next effect run. The cleanup function makes it possible to "cancel" any work that the
+ * previous effect run might have started.
+ */
+export type EffectCleanupFn = () => void;
+/**
+ * A callback passed to the effect function that makes it possible to register cleanup logic.
+ */
+export type EffectCleanupRegisterFn = (cleanupFn: EffectCleanupFn) => void;
+export type CreateEffectOptions = {
+    /**
+     * Whether the `effect` should allow writing to signals.
+     *
+     * Using effects to synchronize data by writing to signals can lead to confusing and potentially
+     * incorrect behavior, and should be enabled only when necessary.
+     */
+    allowSignalWrites?: boolean;
+    /**
+     * Immediately run effect after creation without scheduling - for advanced use cases.
+     */
+    runImmediately?: boolean;
+};
+/**
+ * Tracks all effects registered within a given application and runs them via `flush`.
+ */
+export declare class EffectManager {
+    private readonly all;
+    private readonly queue;
+    private pendingFlush;
+    create(effectFn: (onCleanup: (cleanupFn: EffectCleanupFn) => void) => void, { allowSignalWrites, runImmediately }?: CreateEffectOptions): EffectRef;
+    flush(): void;
+    get isQueueEmpty(): boolean;
+}
+/**
+ * Create a global `Effect` for the given reactive function.
+ */
+export declare function effect(effectFn: (onCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions): EffectRef;

package/signals/implementation/effect.js

@@ -0,0 +1,82 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var effect_exports = {};
+__export(effect_exports, {
+  EffectManager: () => EffectManager,
+  effect: () => effect
+});
+module.exports = __toCommonJS(effect_exports);
+var import_watch = require("./watch.js");
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+class EffectManager {
+  all = /* @__PURE__ */ new Set();
+  queue = /* @__PURE__ */ new Set();
+  pendingFlush;
+  create(effectFn, { allowSignalWrites = false, runImmediately = false } = {}) {
+    const watch = new import_watch.Watch(effectFn, (watch2) => {
+      if (!this.all.has(watch2)) {
+        return;
+      }
+      this.queue.add(watch2);
+      if (!this.pendingFlush) {
+        this.pendingFlush = true;
+        queueMicrotask(() => {
+          this.pendingFlush = false;
+          this.flush();
+        });
+      }
+    }, allowSignalWrites);
+    this.all.add(watch);
+    if (runImmediately) {
+      watch.run();
+    } else {
+      watch.notify();
+    }
+    const destroy = () => {
+      watch.cleanup();
+      this.all.delete(watch);
+      this.queue.delete(watch);
+    };
+    return {
+      destroy
+    };
+  }
+  flush() {
+    if (this.queue.size === 0) {
+      return;
+    }
+    for (const watch of this.queue) {
+      this.queue.delete(watch);
+      watch.run();
+    }
+  }
+  get isQueueEmpty() {
+    return this.queue.size === 0;
+  }
+}
+const effectManager = new EffectManager();
+function effect(effectFn, options) {
+  return effectManager.create(effectFn, options);
+}

package/signals/implementation/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+export declare function throwInvalidWriteToSignalError(): void;
+export declare function setThrowInvalidWriteToSignalError(fn: () => never): void;

package/signals/implementation/errors.js

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var errors_exports = {};
+__export(errors_exports, {
+  setThrowInvalidWriteToSignalError: () => setThrowInvalidWriteToSignalError,
+  throwInvalidWriteToSignalError: () => throwInvalidWriteToSignalError
+});
+module.exports = __toCommonJS(errors_exports);
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+function defaultThrowError() {
+  throw new Error();
+}
+let throwInvalidWriteToSignalErrorFn = defaultThrowError;
+function throwInvalidWriteToSignalError() {
+  throwInvalidWriteToSignalErrorFn();
+}
+function setThrowInvalidWriteToSignalError(fn) {
+  throwInvalidWriteToSignalErrorFn = fn;
+}

package/signals/implementation/graph.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+export declare function setActiveConsumer(consumer: ReactiveNode | null): ReactiveNode | null;
+/**
+ * A node in the reactive graph.
+ *
+ * Nodes can be producers of reactive values, consumers of other reactive values, or both.
+ *
+ * Producers are nodes that produce values, and can be depended upon by consumer nodes.
+ *
+ * Producers expose a monotonic `valueVersion` counter, and are responsible for incrementing this
+ * version when their value semantically changes. Some producers may produce their values lazily and
+ * thus at times need to be polled for potential updates to their value (and by extension their
+ * `valueVersion`). This is accomplished via the `onProducerUpdateValueVersion` method for
+ * implemented by producers, which should perform whatever calculations are necessary to ensure
+ * `valueVersion` is up to date.
+ *
+ * Consumers are nodes that depend on the values of producers and are notified when those values
+ * might have changed.
+ *
+ * Consumers do not wrap the reads they consume themselves, but rather can be set as the active
+ * reader via `setActiveConsumer`. Reads of producers that happen while a consumer is active will
+ * result in those producers being added as dependencies of that consumer node.
+ *
+ * The set of dependencies of a consumer is dynamic. Implementers expose a monotonically increasing
+ * `trackingVersion` counter, which increments whenever the consumer is about to re-run any reactive
+ * reads it needs and establish a new set of dependencies as a result.
+ *
+ * Producers store the last `trackingVersion` they've seen from `Consumer`s which have read them.
+ * This allows a producer to identify whether its record of the dependency is current or stale, by
+ * comparing the consumer's `trackingVersion` to the version at which the dependency was
+ * last observed.
+ */
+export declare abstract class ReactiveNode {
+    private readonly id;
+    /**
+     * A cached weak reference to this node, which will be used in `ReactiveEdge`s.
+     */
+    private readonly ref;
+    /**
+     * Edges to producers on which this node depends (in its consumer capacity).
+     */
+    private readonly producers;
+    /**
+     * Edges to consumers on which this node depends (in its producer capacity).
+     */
+    private readonly consumers;
+    /**
+     * Monotonically increasing counter representing a version of this `Consumer`'s
+     * dependencies.
+     */
+    protected trackingVersion: number;
+    /**
+     * Monotonically increasing counter which increases when the value of this `Producer`
+     * semantically changes.
+     */
+    protected valueVersion: number;
+    /**
+     * Whether signal writes should be allowed while this `ReactiveNode` is the current consumer.
+     */
+    protected abstract readonly consumerAllowSignalWrites: boolean;
+    /**
+     * Called for consumers whenever one of their dependencies notifies that it might have a new
+     * value.
+     */
+    protected abstract onConsumerDependencyMayHaveChanged(): void;
+    /**
+     * Called for producers when a dependent consumer is checking if the producer's value has actually
+     * changed.
+     */
+    protected abstract onProducerUpdateValueVersion(): void;
+    /**
+     * Polls dependencies of a consumer to determine if they have actually changed.
+     *
+     * If this returns `false`, then even though the consumer may have previously been notified of a
+     * change, the values of its dependencies have not actually changed and the consumer should not
+     * rerun any reactions.
+     */
+    protected consumerPollProducersForChange(): boolean;
+    /**
+     * Notify all consumers of this producer that its value may have changed.
+     */
+    protected producerMayHaveChanged(): void;
+    /**
+     * Mark that this producer node has been accessed in the current reactive context.
+     */
+    protected producerAccessed(): void;
+    /**
+     * Whether this consumer currently has any producers registered.
+     */
+    protected get hasProducers(): boolean;
+    /**
+     * Whether this `ReactiveNode` in its producer capacity is currently allowed to initiate updates,
+     * based on the current consumer context.
+     */
+    protected get producerUpdatesAllowed(): boolean;
+    /**
+     * Checks if a `Producer` has a current value which is different than the value
+     * last seen at a specific version by a `Consumer` which recorded a dependency on
+     * this `Producer`.
+     */
+    private producerPollStatus;
+}