@tstdl/base 0.93.181 → 0.93.183

package/signals/implementation/resource/resource.js

@@ -0,0 +1,402 @@
+/**
+ * @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
+ */
+/* eslint-disable */
+/** biome-ignore-all lint: <explanation> */
+import { isDevMode } from '../../../core.js';
+import { registerFinalization } from '../../../memory/finalization.js';
+import { computed } from '../computed.js';
+import { effect } from '../effect.js';
+import { linkedSignal } from '../linked_signal.js';
+import { signal, signalAsReadonlyFn } from '../signal.js';
+import { untracked } from '../untracked.js';
+import { ResourceDependencyError, ResourceParamsStatus } from './api.js';
+export function resource(options) {
+    const oldNameForParams = options.request;
+    const params = options.params ?? oldNameForParams ?? (() => null);
+    return new ResourceImpl(params, getLoader(options), options.defaultValue, options.equal ? wrapEqualityFn(options.equal) : undefined, options.debugName, options.injector);
+}
+/**
+ * Base class which implements `.value` as a `WritableSignal` by delegating `.set` and `.update`.
+ */
+class BaseWritableResource {
+    value;
+    isLoading;
+    constructor(value, debugName) {
+        this.value = value;
+        this.value.set = this.set.bind(this);
+        this.value.update = this.update.bind(this);
+        this.value.asReadonly = signalAsReadonlyFn;
+        this.isLoading = computed(() => this.status() === 'loading' || this.status() === 'reloading', isDevMode() ? createDebugNameObject(debugName, 'isLoading') : undefined);
+    }
+    isError = computed(() => this.status() === 'error');
+    update(updateFn) {
+        this.set(updateFn(untracked(this.value)));
+    }
+    // Use a computed here to avoid triggering reactive consumers if the value changes while staying
+    // either defined or undefined.
+    isValueDefined = computed(() => {
+        // Check if it's in an error state first to prevent the error from bubbling up.
+        if (this.isError()) {
+            return false;
+        }
+        return this.value() !== undefined;
+    });
+    _snapshot;
+    get snapshot() {
+        return (this._snapshot ??= computed(() => {
+            const status = this.status();
+            if (status === 'error') {
+                return { status: 'error', error: this.error() };
+            }
+            else {
+                return { status, value: this.value() };
+            }
+        }));
+    }
+    hasValue() {
+        return this.isValueDefined();
+    }
+    asReadonly() {
+        return this;
+    }
+}
+/**
+ * Implementation for `resource()` which uses a `linkedSignal` to manage the resource's state.
+ */
+export class ResourceImpl extends BaseWritableResource {
+    /**
+     * The current state of the resource. Status, value, and error are derived from this.
+     */
+    state;
+    /**
+     * Combines the current request with a reload counter which allows the resource to be reloaded on
+     * imperative command.
+     */
+    extRequest;
+    effectRef;
+    loaderFn;
+    defaultValue;
+    equal;
+    debugName;
+    pendingController;
+    resolvePendingTask = undefined;
+    destroyed = false;
+    unregisterOnDestroy;
+    status;
+    error;
+    constructor(request, loaderFn, defaultValue, equal, debugName, injector, getInitialStream) {
+        if (isInParamsFunction()) {
+            throw invalidResourceCreationInParams();
+        }
+        super(
+        // Feed a computed signal for the value to `BaseWritableResource`, which will upgrade it to a
+        // `WritableSignal` that delegates to `ResourceImpl.set`.
+        computed(() => {
+            const streamValue = this.state().stream?.();
+            if (!streamValue) {
+                return defaultValue;
+            }
+            // Prevents `hasValue()` from throwing an error when a reload happened in the error state
+            if (this.state().status === 'loading' && this.error()) {
+                return defaultValue;
+            }
+            if (!isResolved(streamValue)) {
+                throw new ResourceValueError(this.error());
+            }
+            return streamValue.value;
+        }, { equal, ...(isDevMode() ? createDebugNameObject(debugName, 'value') : undefined) }), debugName);
+        this.loaderFn = loaderFn;
+        this.defaultValue = defaultValue;
+        this.equal = equal;
+        this.debugName = debugName;
+        this.extRequest = linkedSignal(() => {
+            try {
+                setInParamsFunction(true);
+                return { request: request(paramsContext), reload: 0 };
+            }
+            catch (error) {
+                rethrowFatalErrors(error);
+                if (error === ResourceParamsStatus.IDLE) {
+                    return { status: 'idle', reload: 0 };
+                }
+                else if (error === ResourceParamsStatus.LOADING) {
+                    return { status: 'loading', reload: 0 };
+                }
+                return { error: error, reload: 0 };
+            }
+            finally {
+                setInParamsFunction(false);
+            }
+        }, isDevMode() ? createDebugNameObject(debugName, 'extRequest') : undefined);
+        // The main resource state is managed in a `linkedSignal`, which allows the resource to change
+        // state instantaneously when the request signal changes.
+        this.state = linkedSignal({
+            // Whenever the request changes,
+            source: this.extRequest,
+            // Compute the state of the resource given a change in status.
+            computation: (extRequest, previous) => {
+                let { request, status, error } = extRequest;
+                let stream;
+                if (error) {
+                    status = 'resolved';
+                    stream = signal({ error: encapsulateResourceError(error) }, isDevMode() ? createDebugNameObject(this.debugName, 'stream') : undefined);
+                }
+                else if (!status) {
+                    if (!previous) {
+                        stream = getInitialStream?.(extRequest.request);
+                        // Clear getInitialStream so it doesn't hold onto memory
+                        getInitialStream = undefined;
+                        status = request === undefined ? 'idle' : stream ? 'resolved' : 'loading';
+                    }
+                    else {
+                        status = request === undefined ? 'idle' : 'loading';
+                        if (previous.value.extRequest.request === request) {
+                            stream = previous.value.stream;
+                        }
+                    }
+                }
+                return {
+                    extRequest,
+                    status,
+                    previousStatus: previous ? projectStatusOfState(previous.value) : 'idle',
+                    stream,
+                };
+            },
+            ...(isDevMode() ? createDebugNameObject(debugName, 'state') : undefined),
+        });
+        this.effectRef = effect(this.loadEffect.bind(this), {
+            injector,
+            manualCleanup: true,
+            ...(isDevMode() ? createDebugNameObject(debugName, 'loadEffect') : undefined),
+        });
+        this.status = computed(() => projectStatusOfState(this.state()), isDevMode() ? createDebugNameObject(debugName, 'status') : undefined);
+        this.error = computed(() => {
+            const stream = this.state().stream?.();
+            return stream && !isResolved(stream) ? stream.error : undefined;
+        }, isDevMode() ? createDebugNameObject(debugName, 'error') : undefined);
+        registerFinalization(this, () => this.destroy());
+    }
+    /**
+     * Called either directly via `WritableResource.set` or via `.value.set()`.
+     */
+    set(value) {
+        if (this.destroyed) {
+            return;
+        }
+        const error = untracked(this.error);
+        const state = untracked(this.state);
+        if (!error) {
+            const current = untracked(this.value);
+            if (state.status === 'local' &&
+                (this.equal ? this.equal(current, value) : current === value)) {
+                return;
+            }
+        }
+        // Enter Local state with the user-defined value.
+        this.state.set({
+            extRequest: state.extRequest,
+            status: 'local',
+            previousStatus: 'local',
+            stream: signal({ value }, isDevMode() ? createDebugNameObject(this.debugName, 'stream') : undefined),
+        });
+        // We're departing from whatever state the resource was in previously, so cancel any in-progress
+        // loading operations.
+        this.abortInProgressLoad();
+    }
+    reload() {
+        // We don't want to restart in-progress loads.
+        const { status } = untracked(this.state);
+        if (status === 'idle' || status === 'loading') {
+            return false;
+        }
+        // Increment the request reload to trigger the `state` linked signal to switch us to `Reload`
+        this.extRequest.update(({ request, reload }) => ({ request, reload: reload + 1 }));
+        return true;
+    }
+    destroy() {
+        this.destroyed = true;
+        this.unregisterOnDestroy();
+        this.effectRef.destroy();
+        this.abortInProgressLoad();
+        // Destroyed resources enter Idle state.
+        this.state.set({
+            extRequest: { request: undefined, reload: 0 },
+            status: 'idle',
+            previousStatus: 'idle',
+            stream: undefined,
+        });
+    }
+    async loadEffect() {
+        const extRequest = this.extRequest();
+        // Capture the previous status before any state transitions. Note that this is `untracked` since
+        // we do not want the effect to depend on the state of the resource, only on the request.
+        const { status: currentStatus, previousStatus } = untracked(this.state);
+        if (extRequest.request === undefined) {
+            // Nothing to load (and we should already be in a non-loading state).
+            return;
+        }
+        else if (currentStatus !== 'loading') {
+            // We're not in a loading or reloading state, so this loading request is stale.
+            return;
+        }
+        // Cancel any previous loading attempts.
+        this.abortInProgressLoad();
+        const { signal: abortSignal } = (this.pendingController = new AbortController());
+        try {
+            // The actual loading is run through `untracked` - only the request side of `resource` is
+            // reactive. This avoids any confusion with signals tracking or not tracking depending on
+            // which side of the `await` they are.
+            const stream = await untracked(() => {
+                return this.loaderFn({
+                    params: extRequest.request,
+                    abortSignal,
+                    previous: {
+                        status: previousStatus,
+                    },
+                });
+            });
+            // If this request has been aborted, or the current request no longer
+            // matches this load, then we should ignore this resolution.
+            if (abortSignal.aborted || untracked(this.extRequest) !== extRequest) {
+                return;
+            }
+            this.state.set({
+                extRequest,
+                status: 'resolved',
+                previousStatus: 'resolved',
+                stream,
+            });
+        }
+        catch (err) {
+            rethrowFatalErrors(err);
+            if (abortSignal.aborted || untracked(this.extRequest) !== extRequest) {
+                return;
+            }
+            this.state.set({
+                extRequest,
+                status: 'resolved',
+                previousStatus: 'error',
+                stream: signal({ error: encapsulateResourceError(err) }, isDevMode() ? createDebugNameObject(this.debugName, 'stream') : undefined),
+            });
+        }
+    }
+    abortInProgressLoad() {
+        untracked(() => this.pendingController?.abort());
+        this.pendingController = undefined;
+        // Once the load is aborted, we no longer want to block stability on its resolution.
+        this.resolvePendingTask?.();
+        this.resolvePendingTask = undefined;
+    }
+}
+/**
+ * Wraps an equality function to handle either value being `undefined`.
+ */
+function wrapEqualityFn(equal) {
+    return (a, b) => (a === undefined || b === undefined ? a === b : equal(a, b));
+}
+function getLoader(options) {
+    if (isStreamingResourceOptions(options)) {
+        return options.stream;
+    }
+    return async (params) => {
+        try {
+            return signal({ value: await options.loader(params) }, isDevMode() ? createDebugNameObject(options.debugName, 'stream') : undefined);
+        }
+        catch (err) {
+            return signal({ error: encapsulateResourceError(err) }, isDevMode() ? createDebugNameObject(options.debugName, 'stream') : undefined);
+        }
+    };
+}
+function isStreamingResourceOptions(options) {
+    return !!options.stream;
+}
+/**
+ * Project from a state with `ResourceInternalStatus` to the user-facing `ResourceStatus`
+ */
+function projectStatusOfState(state) {
+    switch (state.status) {
+        case 'loading':
+            return state.extRequest.reload === 0 ? 'loading' : 'reloading';
+        case 'resolved':
+            return isResolved(state.stream()) ? 'resolved' : 'error';
+        default:
+            return state.status;
+    }
+}
+function isResolved(state) {
+    return state.error === undefined;
+}
+/**
+ * Creates a debug name object for an internal signal.
+ */
+function createDebugNameObject(resourceDebugName, internalSignalDebugName) {
+    return {
+        debugName: `Resource${resourceDebugName ? '#' + resourceDebugName : ''}.${internalSignalDebugName}`,
+    };
+}
+export function encapsulateResourceError(error) {
+    if (isErrorLike(error)) {
+        return error;
+    }
+    return new ResourceWrappedError(error);
+}
+export function isErrorLike(error) {
+    return (error instanceof Error ||
+        (typeof error === 'object' &&
+            typeof error.name === 'string' &&
+            typeof error.message === 'string'));
+}
+export class ResourceValueError extends Error {
+    constructor(error) {
+        super(isDevMode()
+            ? `Resource is currently in an error state (see Error.cause for details): ${error.message}`
+            : error.message, { cause: error });
+    }
+}
+class ResourceWrappedError extends Error {
+    constructor(error) {
+        super(isDevMode()
+            ? `Resource returned an error that's not an Error instance: ${String(error)}. Check this error's .cause for the actual error.`
+            : String(error), { cause: error });
+    }
+}
+/**
+ * Chains the value of another resource into the params of the current resource, returning the value
+ * of the other resource if it is available, or propagating the status to the current resource if it
+ * is not.
+ */
+export const paramsContext = {
+    chain(resource) {
+        switch (resource.status()) {
+            case 'idle':
+                throw ResourceParamsStatus.IDLE;
+            case 'error':
+                throw new ResourceDependencyError(resource);
+            case 'loading':
+            case 'reloading':
+                throw ResourceParamsStatus.LOADING;
+        }
+        return resource.value();
+    },
+};
+let inParamsFunction = false;
+export function isInParamsFunction() {
+    return inParamsFunction;
+}
+export function setInParamsFunction(value) {
+    inParamsFunction = value;
+}
+export function invalidResourceCreationInParams() {
+    return new Error(`Cannot create a resource inside the \`params\` of another resource`);
+}
+export function rethrowFatalErrors(error) {
+    if (error instanceof Error &&
+        error.message === `Cannot create a resource inside the \`params\` of another resource`) {
+        throw error;
+    }
+}

package/signals/implementation/root_effect_scheduler.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @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
+ */
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
+/**
+ * Abstraction that encompasses any kind of effect that can be scheduled.
+ */
+export interface SchedulableEffect {
+    run(): void;
+    dirty: boolean;
+}
+/**
+ * A scheduler which manages the execution of effects.
+ */
+export declare abstract class EffectScheduler {
+    abstract add(e: SchedulableEffect): void;
+    /**
+     * Schedule the given effect to be executed at a later time.
+     *
+     * It is an error to attempt to execute any effects synchronously during a scheduling operation.
+     */
+    abstract schedule(e: SchedulableEffect): void;
+    /**
+     * Run any scheduled effects.
+     */
+    abstract flush(): void;
+    /** Remove a scheduled effect */
+    abstract remove(e: SchedulableEffect): void;
+}
+export declare class MicrotaskEffectScheduler implements EffectScheduler {
+    private readonly queue;
+    private dirtyEffectCount;
+    private hasPendingFlush;
+    add(handle: SchedulableEffect): void;
+    schedule(handle: SchedulableEffect): void;
+    remove(handle: SchedulableEffect): void;
+    private enqueue;
+    /**
+     * Run all scheduled effects.
+     *
+     * Execution order of effects within the same zone is guaranteed to be FIFO, but there is no
+     * ordering guarantee between effects scheduled in different zones.
+     */
+    flush(): void;
+}
+export declare const microtaskEffectScheduler: MicrotaskEffectScheduler;

package/signals/implementation/root_effect_scheduler.js

@@ -0,0 +1,66 @@
+/**
+ * @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
+ */
+/**
+ * A scheduler which manages the execution of effects.
+ */
+export class EffectScheduler {
+}
+export class MicrotaskEffectScheduler {
+    queue = new Set();
+    dirtyEffectCount = 0;
+    hasPendingFlush = false;
+    add(handle) {
+        this.enqueue(handle);
+        this.schedule(handle);
+    }
+    schedule(handle) {
+        if (!handle.dirty) {
+            return;
+        }
+        this.dirtyEffectCount++;
+        if (!this.hasPendingFlush) {
+            this.hasPendingFlush = true;
+            queueMicrotask(() => {
+                this.hasPendingFlush = false;
+                this.flush();
+            });
+        }
+    }
+    remove(handle) {
+        this.queue.delete(handle);
+        if (handle.dirty) {
+            this.dirtyEffectCount--;
+        }
+    }
+    enqueue(handle) {
+        if (this.queue.has(handle)) {
+            return;
+        }
+        this.queue.add(handle);
+    }
+    /**
+     * Run all scheduled effects.
+     *
+     * Execution order of effects within the same zone is guaranteed to be FIFO, but there is no
+     * ordering guarantee between effects scheduled in different zones.
+     */
+    flush() {
+        while (this.dirtyEffectCount > 0) {
+            for (const handle of this.queue) {
+                if (!handle.dirty) {
+                    continue;
+                }
+                this.dirtyEffectCount--;
+                // TODO: what happens if this throws an error?
+                handle.run();
+            }
+        }
+        this.dirtyEffectCount = 0;
+    }
+}
+export const microtaskEffectScheduler = new MicrotaskEffectScheduler();

package/signals/implementation/signal.d.ts

@@ -3,27 +3,51 @@
  * 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
  */
-import type { ValueEqualityFn } from './equality.js';
-import type { ReactiveNode } from './graph.js';
-import { SIGNAL } from './graph.js';
-export interface SignalNode<T> extends ReactiveNode {
-    value: T;
-    equal: ValueEqualityFn<T>;
+import type { Signal, ValueEqualityFn } from './api.js';
+import { type SignalGetter } from './primitive/signal.js';
+/** Symbol used distinguish `WritableSignal` from other non-writable signals and functions. */
+export declare const ɵWRITABLE_SIGNAL: unique symbol;
+/**
+ * A `Signal` with a value that can be mutated via a setter interface.
+ *
+ * @publicApi 17.0
+ */
+export interface WritableSignal<T> extends Signal<T> {
+    [ɵWRITABLE_SIGNAL]: T;
+    /**
+     * Directly set the signal to a new value, and notify any dependents.
+     */
+    set(value: T): void;
+    /**
+     * Update the value of the signal based on its current value, and
+     * notify any dependents.
+     */
+    update(updateFn: (value: T) => T): void;
+    /**
+     * Returns a readonly version of this signal. Readonly signals can be accessed to read their value
+     * but can't be changed using set or update methods. The readonly signals do _not_ have
+     * any built-in mechanism that would prevent deep-mutation of their value.
+     */
+    asReadonly(): Signal<T>;
 }
-export type SignalBaseGetter<T> = (() => T) & {
-    readonly [SIGNAL]: unknown;
-};
-export interface SignalGetter<T> extends SignalBaseGetter<T> {
-    readonly [SIGNAL]: SignalNode<T>;
+/**
+ * Options passed to the `signal` creation function.
+ */
+export interface CreateSignalOptions<T> {
+    /**
+     * A comparison function which defines equality for signal values.
+     */
+    equal?: ValueEqualityFn<T>;
+    /**
+     * A debug name for the signal. Used in Angular DevTools to identify the signal.
+     */
+    debugName?: string;
 }
 /**
  * Create a `Signal` that can be set or updated directly.
+ * @see [Angular Signals](guide/signals)
  */
-export declare function createSignal<T>(initialValue: T): SignalGetter<T>;
-export declare function setPostSignalSetFn(fn: (() => void) | null): (() => void) | null;
-export declare function signalGetFn<T>(this: SignalNode<T>): T;
-export declare function signalSetFn<T>(node: SignalNode<T>, newValue: T): void;
-export declare function signalUpdateFn<T>(node: SignalNode<T>, updater: (value: T) => T): void;
-export declare const SIGNAL_NODE: SignalNode<unknown>;
+export declare function signal<T>(initialValue: T, options?: CreateSignalOptions<T>): WritableSignal<T>;
+export declare function signalAsReadonlyFn<T>(this: SignalGetter<T>): Signal<T>;

package/signals/implementation/signal.js

@@ -1,59 +1,39 @@
-/* eslint-disable */
-import { defaultEquals } from './equality.js';
-import { throwInvalidWriteToSignalError } from './errors.js';
-import { producerAccessed, producerIncrementEpoch, producerNotifyConsumers, producerUpdatesAllowed, REACTIVE_NODE, SIGNAL } from './graph.js';
 /**
- * If set, called after `WritableSignal`s are updated.
+ * @license
+ * Copyright Google LLC All Rights Reserved.
  *
- * This hook can be used to achieve various effects, such as running effects synchronously as part
- * of setting a signal.
+ * 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
  */
-let postSignalSetFn = null;
+import { isDevMode } from '../../core.js';
+import { SIGNAL } from '../symbol.js';
+import { createSignal } from './primitive/signal.js';
+/** Symbol used distinguish `WritableSignal` from other non-writable signals and functions. */
+export const ɵWRITABLE_SIGNAL = /* @__PURE__ */ Symbol('WRITABLE_SIGNAL');
 /**
  * Create a `Signal` that can be set or updated directly.
+ * @see [Angular Signals](guide/signals)
  */
-export function createSignal(initialValue) {
-    const node = Object.create(SIGNAL_NODE);
-    node.value = initialValue;
-    const getter = (() => {
-        producerAccessed(node);
-        return node.value;
-    });
-    getter[SIGNAL] = node;
-    return getter;
-}
-export function setPostSignalSetFn(fn) {
-    const prev = postSignalSetFn;
-    postSignalSetFn = fn;
-    return prev;
-}
-export function signalGetFn() {
-    producerAccessed(this);
-    return this.value;
-}
-export function signalSetFn(node, newValue) {
-    if (!producerUpdatesAllowed()) {
-        throwInvalidWriteToSignalError();
-    }
-    if (!node.equal(node.value, newValue)) {
-        node.value = newValue;
-        signalValueChanged(node);
+export function signal(initialValue, options) {
+    const [get, set, update] = createSignal(initialValue, options?.equal);
+    const signalFn = get;
+    const node = signalFn[SIGNAL];
+    signalFn.set = set;
+    signalFn.update = update;
+    signalFn.asReadonly = signalAsReadonlyFn.bind(signalFn);
+    if (isDevMode()) {
+        const debugName = options?.debugName;
+        node.debugName = debugName;
+        signalFn.toString = () => `[Signal${debugName ? ' (' + debugName + ')' : ''}: ${signalFn()}]`;
     }
+    return signalFn;
 }
-export function signalUpdateFn(node, updater) {
-    if (!producerUpdatesAllowed()) {
-        throwInvalidWriteToSignalError();
+export function signalAsReadonlyFn() {
+    const node = this[SIGNAL];
+    if (node.readonlyFn === undefined) {
+        const readonlyFn = () => this();
+        readonlyFn[SIGNAL] = node;
+        node.readonlyFn = readonlyFn;
     }
-    signalSetFn(node, updater(node.value));
-}
-export const SIGNAL_NODE = {
-    ...REACTIVE_NODE,
-    equal: defaultEquals,
-    value: undefined,
-};
-function signalValueChanged(node) {
-    node.version++;
-    producerIncrementEpoch();
-    producerNotifyConsumers(node);
-    postSignalSetFn?.();
+    return node.readonlyFn;
 }