@tstdl/base 0.93.182 → 0.93.184

package/signals/implementation/effect.js

@@ -1,78 +1,113 @@
 /* eslint-disable */
-import { assertNotInReactiveContext } from './asserts.js';
-import { createWatch } from './watch.js';
+/** biome-ignore-all lint: <explanation> */
 /**
- * A scheduler which manages the execution of effects.
+ * @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.dev/license
  */
-export class EffectScheduler {
-}
-export class TstdlEffectScheduler {
-    queue = new Set();
-    hasPendingFlush = false;
-    scheduleEffect(effect) {
-        if (this.queue.has(effect)) {
-            return;
-        }
-        this.queue.add(effect);
-        if (!this.hasPendingFlush) {
-            this.hasPendingFlush = true;
-            queueMicrotask(() => {
-                this.hasPendingFlush = false;
-                this.flush();
-            });
-        }
+import { isDevMode } from '../../core.js';
+import { SIGNAL } from '../symbol.js';
+import { assertNotInReactiveContext } from './asserts.js';
+import { BASE_EFFECT_NODE, runEffect } from './primitive/effect.js';
+import { consumerDestroy, isInNotificationPhase, setActiveConsumer } from './primitive/graph.js';
+import { microtaskEffectScheduler } from './root_effect_scheduler.js';
+export class EffectRefImpl {
+    [SIGNAL];
+    constructor(node) {
+        this[SIGNAL] = node;
     }
-    flush() {
-        for (const effect of this.queue) {
-            this.queue.delete(effect);
-            effect.run();
-        }
+    destroy() {
+        this[SIGNAL].destroy();
     }
 }
 /**
- * Core reactive node for an effect.
+ * Registers an "effect" that will be scheduled & executed whenever the signals that it reads
+ * changes.
+ *
+ * Angular has two different kinds of effect: component effects and root effects. Component effects
+ * are created when `effect()` is called from a component, directive, or within a service of a
+ * component/directive. Root effects are created when `effect()` is called from outside the
+ * component tree, such as in a root service.
+ *
+ * The two effect types differ in their timing. Component effects run as a component lifecycle
+ * event during Angular's synchronization (change detection) process, and can safely read input
+ * signals or create/destroy views that depend on component state. Root effects run as microtasks
+ * and have no connection to the component tree or change detection.
  *
- * `EffectHandle` combines the reactive graph's `Watch` base node for effects with the framework's
- * scheduling abstraction (`EffectScheduler`) as well as automatic cleanup via `DestroyRef` if
- * available/requested.
+ * `effect()` must be run in injection context, unless the `injector` option is manually specified.
+ *
+ * @see [Effects](guide/signals#effects)
+ *
+ * @publicApi 20.0
  */
-class EffectHandle {
-    scheduler;
-    effectFn;
-    watcher;
-    constructor(scheduler, effectFn, allowSignalWrites) {
-        this.scheduler = scheduler;
-        this.effectFn = effectFn;
-        this.watcher = createWatch((onCleanup) => this.runEffect(onCleanup), () => this.schedule(), allowSignalWrites);
+export function effect(effectFn, options) {
+    isDevMode() &&
+        assertNotInReactiveContext(effect, 'Call `effect` outside of a reactive context. For example, schedule the ' +
+            'effect inside the component constructor.');
+    if (isDevMode() && options?.allowSignalWrites !== undefined) {
+        console.warn(`The 'allowSignalWrites' flag is deprecated and no longer impacts effect() (writes are always allowed)`);
     }
-    runEffect(onCleanup) {
+    const node = createRootEffect(effectFn, microtaskEffectScheduler);
+    return new EffectRefImpl(node);
+}
+export const EFFECT_NODE = 
+/* @__PURE__ */ (() => ({
+    ...BASE_EFFECT_NODE,
+    cleanupFns: undefined,
+    onDestroyFns: null,
+    run() {
+        if (isDevMode() && isInNotificationPhase()) {
+            throw new Error(`Schedulers cannot synchronously execute watches while scheduling.`);
+        }
+        runEffect(this);
+    },
+    cleanup() {
+        if (!this.cleanupFns?.length) {
+            return;
+        }
+        const prevConsumer = setActiveConsumer(null);
         try {
-            this.effectFn(onCleanup);
+            // Attempt to run the cleanup functions. Regardless of failure or success, we consider
+            // cleanup "completed" and clear the list for the next run of the effect. Note that an error
+            // from the cleanup function will still crash the current run of the effect.
+            while (this.cleanupFns.length) {
+                this.cleanupFns.pop()();
+            }
         }
-        catch (err) {
-            queueMicrotask(() => { throw err; });
+        finally {
+            this.cleanupFns = [];
+            setActiveConsumer(prevConsumer);
         }
-    }
-    run() {
-        this.watcher.run();
-    }
-    schedule() {
-        this.scheduler.scheduleEffect(this);
-    }
+    },
+}))();
+export const ROOT_EFFECT_NODE = 
+/* @__PURE__ */ (() => ({
+    ...EFFECT_NODE,
+    consumerMarkedDirty() {
+        this.scheduler.schedule(this);
+    },
     destroy() {
-        this.watcher.destroy();
-        // Note: if the effect is currently scheduled, it's not un-scheduled, and so the scheduler will
-        // retain a reference to it. Attempting to execute it will be a no-op.
-    }
+        consumerDestroy(this);
+        if (this.onDestroyFns !== null) {
+            for (const fn of this.onDestroyFns) {
+                fn();
+            }
+        }
+        this.cleanup();
+        this.scheduler.remove(this);
+    },
+}))();
+export function createRootEffect(fn, scheduler) {
+    const node = Object.create(ROOT_EFFECT_NODE);
+    node.fn = createEffectFn(node, fn);
+    node.scheduler = scheduler;
+    node.scheduler.add(node);
+    return node;
 }
-const effectScheduler = new TstdlEffectScheduler();
-/**
- * Create a global `Effect` for the given reactive function.
- */
-export function effect(effectFn, options) {
-    assertNotInReactiveContext(effect, 'Call `effect` outside of a reactive context. For example, schedule the ' +
-        'effect inside the component constructor.');
-    const handle = new EffectHandle(effectScheduler, effectFn, options?.allowSignalWrites ?? false);
-    handle.watcher.notify();
-    return handle;
+function createEffectFn(node, fn) {
+    return () => {
+        fn((cleanupFn) => (node.cleanupFns ??= []).push(cleanupFn));
+    };
 }

package/signals/implementation/index.d.ts

@@ -3,11 +3,9 @@ export * from './asserts.js';
 export * from './computed.js';
 export * from './configure.js';
 export * from './effect.js';
-export * from './equality.js';
-export * from './graph.js';
+export * from './linked_signal.js';
+export * from './resource/index.js';
 export * from './signal.js';
 export * from './to-observable.js';
 export * from './to-signal.js';
 export * from './untracked.js';
-export * from './watch.js';
-export * from './writable-signal.js';

package/signals/implementation/index.js

@@ -3,11 +3,9 @@ export * from './asserts.js';
 export * from './computed.js';
 export * from './configure.js';
 export * from './effect.js';
-export * from './equality.js';
-export * from './graph.js';
+export * from './linked_signal.js';
+export * from './resource/index.js';
 export * from './signal.js';
 export * from './to-observable.js';
 export * from './to-signal.js';
 export * from './untracked.js';
-export * from './watch.js';
-export * from './writable-signal.js';

package/signals/implementation/linked_signal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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.dev/license
+ */
+import type { ValueEqualityFn } from './primitive/equality.js';
+import { type WritableSignal } from './signal.js';
+/**
+ * Creates a writable signal whose value is initialized and reset by the linked, reactive computation.
+ *
+ * @publicApi 20.0
+ */
+export declare function linkedSignal<D>(computation: () => D, options?: {
+    equal?: ValueEqualityFn<NoInfer<D>>;
+    debugName?: string;
+}): WritableSignal<D>;
+/**
+ * Creates a writable signal whose value is initialized and reset by the linked, reactive computation.
+ * This is an advanced API form where the computation has access to the previous value of the signal and the computation result.
+ *
+ * Note: The computation is reactive, meaning the linked signal will automatically update whenever any of the signals used within the computation change.
+ *
+ * @publicApi 20.0
+ * @see [Dependent state with linkedSignal](guide/signals/linked-signal)
+ */
+export declare function linkedSignal<S, D>(options: {
+    source: () => S;
+    computation: (source: NoInfer<S>, previous?: {
+        source: NoInfer<S>;
+        value: NoInfer<D>;
+    }) => D;
+    equal?: ValueEqualityFn<NoInfer<D>>;
+    debugName?: string;
+}): WritableSignal<D>;

package/signals/implementation/linked_signal.js

@@ -0,0 +1,34 @@
+/**
+ * @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.dev/license
+ */
+import { isDevMode } from '../../core.js';
+import { SIGNAL } from '../symbol.js';
+import { createLinkedSignal, linkedSignalSetFn, linkedSignalUpdateFn } from './primitive/linked_signal.js';
+import { signalAsReadonlyFn } from './signal.js';
+const identityFn = (v) => v;
+export function linkedSignal(optionsOrComputation, options) {
+    if (typeof optionsOrComputation === 'function') {
+        const getter = createLinkedSignal(optionsOrComputation, (identityFn), options?.equal);
+        return upgradeLinkedSignalGetter(getter, options?.debugName);
+    }
+    else {
+        const getter = createLinkedSignal(optionsOrComputation.source, optionsOrComputation.computation, optionsOrComputation.equal);
+        return upgradeLinkedSignalGetter(getter, optionsOrComputation.debugName);
+    }
+}
+function upgradeLinkedSignalGetter(getter, debugName) {
+    if (isDevMode()) {
+        getter[SIGNAL].debugName = debugName;
+        getter.toString = () => `[LinkedSignal${debugName ? ' (' + debugName + ')' : ''}: ${getter()}]`;
+    }
+    const node = getter[SIGNAL];
+    const upgradedGetter = getter;
+    upgradedGetter.set = (newValue) => linkedSignalSetFn(node, newValue);
+    upgradedGetter.update = (updateFn) => linkedSignalUpdateFn(node, updateFn);
+    upgradedGetter.asReadonly = signalAsReadonlyFn.bind(getter);
+    return upgradedGetter;
+}

package/signals/implementation/primitive/computed.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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.dev/license
+ */
+import { type ValueEqualityFn } from './equality.js';
+import { type ReactiveNode, SIGNAL } from './graph.js';
+/**
+ * A computation, which derives a value from a declarative reactive expression.
+ *
+ * `Computed`s are both producers and consumers of reactivity.
+ */
+export interface ComputedNode<T> extends ReactiveNode {
+    /**
+     * Current value of the computation, or one of the sentinel values above (`UNSET`, `COMPUTING`,
+     * `ERROR`).
+     */
+    value: T;
+    /**
+     * If `value` is `ERRORED`, the error caught from the last computation attempt which will
+     * be re-thrown.
+     */
+    error: unknown;
+    /**
+     * The computation function which will produce a new value.
+     */
+    computation: () => T;
+    equal: ValueEqualityFn<T>;
+}
+export type ComputedGetter<T> = (() => T) & {
+    [SIGNAL]: ComputedNode<T>;
+};
+/**
+ * Create a computed signal which derives a reactive value from an expression.
+ */
+export declare function createComputed<T>(computation: () => T, equal?: ValueEqualityFn<T>): ComputedGetter<T>;
+/**
+ * A dedicated symbol used before a computed value has been calculated for the first time.
+ * Explicitly typed as `any` so we can use it as signal's value.
+ */
+export declare const UNSET: any;
+/**
+ * A dedicated symbol used in place of a computed signal value to indicate that a given computation
+ * is in progress. Used to detect cycles in computation chains.
+ * Explicitly typed as `any` so we can use it as signal's value.
+ */
+export declare const COMPUTING: any;
+/**
+ * A dedicated symbol used in place of a computed signal value to indicate that a given computation
+ * failed. The thrown error is cached until the computation gets dirty again.
+ * Explicitly typed as `any` so we can use it as signal's value.
+ */
+export declare const ERRORED: any;

package/signals/implementation/primitive/computed.js

@@ -0,0 +1,107 @@
+/**
+ * @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.dev/license
+ */
+import { isDevMode } from '../../../core.js';
+import { defaultEquals } from './equality.js';
+import { consumerAfterComputation, consumerBeforeComputation, producerAccessed, producerUpdateValueVersion, REACTIVE_NODE, runPostProducerCreatedFn, setActiveConsumer, SIGNAL, } from './graph.js';
+/**
+ * Create a computed signal which derives a reactive value from an expression.
+ */
+export function createComputed(computation, equal) {
+    const node = Object.create(COMPUTED_NODE);
+    node.computation = computation;
+    if (equal !== undefined) {
+        node.equal = equal;
+    }
+    const computed = () => {
+        // Check if the value needs updating before returning it.
+        producerUpdateValueVersion(node);
+        // Record that someone looked at this signal.
+        producerAccessed(node);
+        if (node.value === ERRORED) {
+            throw node.error;
+        }
+        return node.value;
+    };
+    computed[SIGNAL] = node;
+    if (isDevMode()) {
+        computed.toString = () => `[Computed${node.debugName ? ' (' + node.debugName + ')' : ''}: ${String(node.value)}]`;
+    }
+    runPostProducerCreatedFn(node);
+    return computed;
+}
+/**
+ * A dedicated symbol used before a computed value has been calculated for the first time.
+ * Explicitly typed as `any` so we can use it as signal's value.
+ */
+export const UNSET = /* @__PURE__ */ Symbol('UNSET');
+/**
+ * A dedicated symbol used in place of a computed signal value to indicate that a given computation
+ * is in progress. Used to detect cycles in computation chains.
+ * Explicitly typed as `any` so we can use it as signal's value.
+ */
+export const COMPUTING = /* @__PURE__ */ Symbol('COMPUTING');
+/**
+ * A dedicated symbol used in place of a computed signal value to indicate that a given computation
+ * failed. The thrown error is cached until the computation gets dirty again.
+ * Explicitly typed as `any` so we can use it as signal's value.
+ */
+export const ERRORED = /* @__PURE__ */ Symbol('ERRORED');
+// Note: Using an IIFE here to ensure that the spread assignment is not considered
+// a side-effect, ending up preserving `COMPUTED_NODE` and `REACTIVE_NODE`.
+const COMPUTED_NODE = /* @__PURE__ */ (() => {
+    return {
+        ...REACTIVE_NODE,
+        value: UNSET,
+        dirty: true,
+        error: null,
+        equal: defaultEquals,
+        kind: 'computed',
+        producerMustRecompute(node) {
+            // Force a recomputation if there's no current value, or if the current value is in the
+            // process of being calculated (which should throw an error).
+            return node.value === UNSET || node.value === COMPUTING;
+        },
+        producerRecomputeValue(node) {
+            if (node.value === COMPUTING) {
+                // Our computation somehow led to a cyclic read of itself.
+                throw new Error(isDevMode() ? 'Detected cycle in computations.' : '');
+            }
+            const oldValue = node.value;
+            node.value = COMPUTING;
+            const prevConsumer = consumerBeforeComputation(node);
+            let newValue;
+            let wasEqual = false;
+            try {
+                newValue = node.computation();
+                // We want to mark this node as errored if calling `equal` throws; however, we don't want
+                // to track any reactive reads inside `equal`.
+                setActiveConsumer(null);
+                wasEqual =
+                    oldValue !== UNSET &&
+                        oldValue !== ERRORED &&
+                        newValue !== ERRORED &&
+                        node.equal(oldValue, newValue);
+            }
+            catch (err) {
+                newValue = ERRORED;
+                node.error = err;
+            }
+            finally {
+                consumerAfterComputation(node, prevConsumer);
+            }
+            if (wasEqual) {
+                // No change to `valueVersion` - old and new values are
+                // semantically equivalent.
+                node.value = oldValue;
+                return;
+            }
+            node.value = newValue;
+            node.version++;
+        },
+    };
+})();

package/signals/implementation/primitive/effect.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.dev/license
+ */
+import { type ReactiveNode } from './graph.js';
+/**
+ * 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 interface BaseEffectNode extends ReactiveNode {
+    fn: () => void;
+    destroy(): void;
+    cleanup(): void;
+    run(): void;
+}
+export declare const BASE_EFFECT_NODE: Omit<BaseEffectNode, 'fn' | 'destroy' | 'cleanup' | 'run'>;
+export declare function runEffect(node: BaseEffectNode): void;

package/signals/implementation/primitive/effect.js

@@ -0,0 +1,31 @@
+/**
+ * @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.dev/license
+ */
+import { consumerAfterComputation, consumerBeforeComputation, consumerPollProducersForChange, REACTIVE_NODE, } from './graph.js';
+export const BASE_EFFECT_NODE = 
+/* @__PURE__ */ (() => ({
+    ...REACTIVE_NODE,
+    consumerIsAlwaysLive: true,
+    consumerAllowSignalWrites: true,
+    dirty: true,
+    kind: 'effect',
+}))();
+export function runEffect(node) {
+    node.dirty = false;
+    if (node.version > 0 && !consumerPollProducersForChange(node)) {
+        return;
+    }
+    node.version++;
+    const prevNode = consumerBeforeComputation(node);
+    try {
+        node.cleanup();
+        node.fn();
+    }
+    finally {
+        consumerAfterComputation(node, prevNode);
+    }
+}

package/signals/implementation/{equality.d.ts → primitive/equality.d.ts}

@@ -3,7 +3,7 @@
  * 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
+ * found in the LICENSE file at https://angular.dev/license
  */
 /**
  * A comparison function which can determine if two values are equal.

package/signals/implementation/{equality.js → primitive/equality.js}

@@ -3,7 +3,7 @@
  * 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
+ * found in the LICENSE file at https://angular.dev/license
  */
 /**
  * The default equality function used for `signal` and `computed`, which uses referential equality.

package/signals/implementation/primitive/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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.dev/license
+ */
+import type { SignalNode } from './signal.js';
+export declare function throwInvalidWriteToSignalError<T>(node: SignalNode<T>): void;
+export declare function setThrowInvalidWriteToSignalError(fn: <T>(node: SignalNode<T>) => never): void;

package/signals/implementation/{errors.js → primitive/errors.js}

@@ -1,17 +1,16 @@
-/* eslint-disable */
 /**
  * @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
+ * found in the LICENSE file at https://angular.dev/license
  */
 function defaultThrowError() {
     throw new Error();
 }
 let throwInvalidWriteToSignalErrorFn = defaultThrowError;
-export function throwInvalidWriteToSignalError() {
-    throwInvalidWriteToSignalErrorFn();
+export function throwInvalidWriteToSignalError(node) {
+    throwInvalidWriteToSignalErrorFn(node);
 }
 export function setThrowInvalidWriteToSignalError(fn) {
     throwInvalidWriteToSignalErrorFn = fn;

package/signals/implementation/primitive/formatter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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.dev/license
+ */
+declare global {
+    var devtoolsFormatters: any[];
+}
+/**
+ * Installs the custom formatter into custom formatting on Signals in the devtools.
+ *
+ * Supported by both Chrome and Firefox.
+ *
+ * @see https://firefox-source-docs.mozilla.org/devtools-user/custom_formatters/index.html
+ */
+export declare function installDevToolsSignalFormatter(): void;
+export {};