@tstdl/base 0.93.182 → 0.93.183

package/signals/implementation/resource/debounce.d.ts

@@ -0,0 +1,13 @@
+/** biome-ignore-all lint: <explanation> */
+import type { DebouncedOptions, DebounceTimer, Resource } from './api.js';
+/**
+ * Creates a resource representing a debounced version of the source signal.
+ *
+ * @param source The source signal to debounce.
+ * @param wait The amount of time to wait before calling the source signal, or a function that
+ *   returns a promise that resolves when the debounced value should be updated.
+ * @param options The options to use for the debounced signal.
+ * @returns A resource representing the debounced signal.
+ * @experimental 22.0
+ */
+export declare function debounced<T>(source: () => T, wait: NoInfer<DebounceTimer<T>>, options?: NoInfer<DebouncedOptions<T>>): Resource<T>;

package/signals/implementation/resource/debounce.js

@@ -0,0 +1,113 @@
+/* eslint-disable */
+/** biome-ignore-all lint: <explanation> */
+/**
+ * @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 { effect } from '../effect.js';
+import { linkedSignal } from '../linked_signal.js';
+import { untracked } from '../untracked.js';
+import { resourceFromSnapshots } from './from_snapshots.js';
+import { invalidResourceCreationInParams, isInParamsFunction, rethrowFatalErrors, setInParamsFunction } from './resource.js';
+/**
+ * Creates a resource representing a debounced version of the source signal.
+ *
+ * @param source The source signal to debounce.
+ * @param wait The amount of time to wait before calling the source signal, or a function that
+ *   returns a promise that resolves when the debounced value should be updated.
+ * @param options The options to use for the debounced signal.
+ * @returns A resource representing the debounced signal.
+ * @experimental 22.0
+ */
+export function debounced(source, wait, options) {
+    if (isInParamsFunction()) {
+        throw invalidResourceCreationInParams();
+    }
+    let active;
+    let pendingValue;
+    const state = linkedSignal({
+        source: () => {
+            try {
+                setInParamsFunction(true);
+                return { value: source(), thrown: false };
+            }
+            catch (err) {
+                rethrowFatalErrors(err);
+                return { error: err, thrown: true };
+            }
+            finally {
+                setInParamsFunction(false);
+            }
+        },
+        computation: (res, previous) => {
+            // If we already have a state from the effect or a previous read, keep it!
+            // The effect is responsible for timing and state transitions.
+            if (previous !== undefined) {
+                return previous.value;
+            }
+            // On the very first evaluation, determine the initial state synchronously.
+            if (res.thrown) {
+                return { status: 'error', error: res.error };
+            }
+            return { status: 'resolved', value: res.value };
+        },
+    });
+    effect(() => {
+        // Enter error state if the source throws.
+        let value;
+        try {
+            setInParamsFunction(true);
+            value = source();
+        }
+        catch (err) {
+            rethrowFatalErrors(err);
+            state.set({ status: 'error', error: err });
+            active = pendingValue = undefined;
+            return;
+        }
+        finally {
+            setInParamsFunction(false);
+        }
+        const currentState = untracked(state);
+        // Check if the value is the same as the previous one.
+        const equal = options?.equal ?? Object.is;
+        if (currentState.status === 'reloading' || currentState.status === 'loading') {
+            if (equal(value, pendingValue))
+                return;
+        }
+        else if (currentState.status === 'resolved') {
+            if (equal(value, currentState.value))
+                return;
+        }
+        const waitFn = typeof wait === 'number'
+            ? () => new Promise((resolve) => setTimeout(resolve, wait))
+            : wait;
+        const result = waitFn(value, currentState);
+        if (result === undefined) {
+            // Synchronous case, go straight to resolved.
+            state.set({ status: 'resolved', value });
+            active = pendingValue = undefined;
+        }
+        else {
+            // Asynchronous case:
+            // If we're in error state or loading state, remain in that state.
+            // Otherwise, change to loading state but keep the current value until the new one loads.
+            if (currentState.status !== 'loading' && currentState.status !== 'error') {
+                state.set({ status: 'loading', value: currentState.value });
+            }
+            active = result;
+            pendingValue = value;
+            // Once the promise resolves, update the state to resolved.
+            result.then(() => {
+                if (active === result) {
+                    state.set({ status: 'resolved', value });
+                    active = pendingValue = undefined;
+                }
+            });
+        }
+    }, { injector: options?.injector });
+    return resourceFromSnapshots(state);
+}

package/signals/implementation/resource/from_snapshots.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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 { Resource, ResourceSnapshot } from './api.js';
+/**
+ * Creates a `Resource` driven by a source of `ResourceSnapshot`s.
+ *
+ * @see [Resource composition with snapshots](guide/signals/resource#resource-composition-with-snapshots)
+ *
+ * @experimental
+ */
+export declare function resourceFromSnapshots<T>(source: () => ResourceSnapshot<T>): Resource<T>;

package/signals/implementation/resource/from_snapshots.js

@@ -0,0 +1,44 @@
+/**
+ * @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 { isSignal } from '../api.js';
+import { computed } from '../computed.js';
+import { ResourceValueError } from './resource.js';
+/**
+ * Creates a `Resource` driven by a source of `ResourceSnapshot`s.
+ *
+ * @see [Resource composition with snapshots](guide/signals/resource#resource-composition-with-snapshots)
+ *
+ * @experimental
+ */
+export function resourceFromSnapshots(source) {
+    return new SnapshotResource(isSignal(source) ? source : computed(source));
+}
+class SnapshotResource {
+    snapshot;
+    constructor(snapshot) {
+        this.snapshot = snapshot;
+    }
+    get state() {
+        return this.snapshot();
+    }
+    value = computed(() => {
+        if (this.state.status === 'error') {
+            throw new ResourceValueError(this.state.error);
+        }
+        return this.state.value;
+    });
+    status = computed(() => this.state.status);
+    error = computed(() => (this.state.status === 'error' ? this.state.error : undefined));
+    isLoading = computed(() => this.state.status === 'loading' || this.state.status === 'reloading');
+    isValueDefined = computed(() => this.state.status !== 'error' && this.state.value !== undefined);
+    hasValue() {
+        return this.isValueDefined();
+    }
+}

package/signals/implementation/resource/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 * from './api.js';
+export { debounced } from './debounce.js';
+export { resourceFromSnapshots } from './from_snapshots.js';
+export { resource } from './resource.js';

package/signals/implementation/resource/index.js

@@ -0,0 +1,11 @@
+/**
+ * @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 * from './api.js';
+export { debounced } from './debounce.js';
+export { resourceFromSnapshots } from './from_snapshots.js';
+export { resource } from './resource.js';

package/signals/implementation/resource/resource.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @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 { SignalsInjector } from '../../../signals/api.js';
+import type { Signal, ValueEqualityFn } from '../api.js';
+import { type WritableSignal } from '../signal.js';
+import { type Resource, type ResourceOptions, type ResourceParamsContext, type ResourceRef, type ResourceSnapshot, type ResourceStatus, type ResourceStreamingLoader, type ResourceStreamItem, type WritableResource } from './api.js';
+/**
+ * Constructs a `Resource` that projects a reactive request to an asynchronous operation defined by
+ * a loader function, which exposes the result of the loading operation via signals.
+ *
+ * Note that `resource` is intended for _read_ operations, not operations which perform mutations.
+ * `resource` will cancel in-progress loads via the `AbortSignal` when destroyed or when a new
+ * request object becomes available, which could prematurely abort mutations.
+ */
+export declare function resource<T, R>(options: ResourceOptions<T, R> & {
+    defaultValue: NoInfer<T>;
+}): ResourceRef<T>;
+/**
+ * Constructs a `Resource` that projects a reactive request to an asynchronous operation defined by
+ * a loader function, which exposes the result of the loading operation via signals.
+ *
+ * Note that `resource` is intended for _read_ operations, not operations which perform mutations.
+ * `resource` will cancel in-progress loads via the `AbortSignal` when destroyed or when a new
+ * request object becomes available, which could prematurely abort mutations.
+ *
+ * @experimental 19.0
+ * @see [Async reactivity with resources](guide/signals/resource)
+ */
+export declare function resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T | undefined>;
+type ResourceInternalStatus = 'idle' | 'loading' | 'resolved' | 'local';
+type WrappedRequest = {
+    request?: unknown;
+    reload: number;
+    status?: ResourceInternalStatus;
+    error?: Error;
+};
+/**
+ * Base class which implements `.value` as a `WritableSignal` by delegating `.set` and `.update`.
+ */
+declare abstract class BaseWritableResource<T> implements WritableResource<T> {
+    readonly value: WritableSignal<T>;
+    abstract readonly status: Signal<ResourceStatus>;
+    abstract readonly error: Signal<Error | undefined>;
+    abstract reload(): boolean;
+    readonly isLoading: Signal<boolean>;
+    constructor(value: Signal<T>, debugName: string | undefined);
+    abstract set(value: T): void;
+    private readonly isError;
+    update(updateFn: (value: T) => T): void;
+    private readonly isValueDefined;
+    private _snapshot;
+    get snapshot(): Signal<ResourceSnapshot<T>>;
+    hasValue(): this is ResourceRef<Exclude<T, undefined>>;
+    asReadonly(): Resource<T>;
+}
+/**
+ * Implementation for `resource()` which uses a `linkedSignal` to manage the resource's state.
+ */
+export declare class ResourceImpl<T, R> extends BaseWritableResource<T> implements ResourceRef<T> {
+    /**
+     * The current state of the resource. Status, value, and error are derived from this.
+     */
+    private readonly state;
+    /**
+     * Combines the current request with a reload counter which allows the resource to be reloaded on
+     * imperative command.
+     */
+    protected readonly extRequest: WritableSignal<WrappedRequest>;
+    private readonly effectRef;
+    private readonly loaderFn;
+    defaultValue: T;
+    private readonly equal;
+    private readonly debugName;
+    private pendingController;
+    private resolvePendingTask;
+    private destroyed;
+    private unregisterOnDestroy;
+    readonly status: Signal<ResourceStatus>;
+    readonly error: Signal<Error | undefined>;
+    constructor(request: (ctx: ResourceParamsContext) => R, loaderFn: ResourceStreamingLoader<T, R>, defaultValue: T, equal: ValueEqualityFn<T> | undefined, debugName: string | undefined, injector?: SignalsInjector, getInitialStream?: (request: R) => Signal<ResourceStreamItem<T>> | undefined);
+    /**
+     * Called either directly via `WritableResource.set` or via `.value.set()`.
+     */
+    set(value: T): void;
+    reload(): boolean;
+    destroy(): void;
+    private loadEffect;
+    private abortInProgressLoad;
+}
+export declare function encapsulateResourceError(error: unknown): Error;
+export declare function isErrorLike(error: unknown): error is Error;
+export declare class ResourceValueError extends Error {
+    constructor(error: 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 declare const paramsContext: ResourceParamsContext;
+export declare function isInParamsFunction(): boolean;
+export declare function setInParamsFunction(value: boolean): void;
+export declare function invalidResourceCreationInParams(): Error;
+export declare function rethrowFatalErrors(error: unknown): void;
+export {};