static-injector 5.0.2 → 6.0.1

package/import/resource/api.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @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 { Injector } from '../di/injector';
+import { Signal, ValueEqualityFn } from '../render3/reactivity/api';
+import { WritableSignal } from '../render3/reactivity/signal';
+/**
+ * Status of a `Resource`.
+ *
+ * @experimental
+ */
+export declare enum ResourceStatus {
+    /**
+     * The resource has no valid request and will not perform any loading.
+     *
+     * `value()` will be `undefined`.
+     */
+    Idle = 0,
+    /**
+     * Loading failed with an error.
+     *
+     * `value()` will be `undefined`.
+     */
+    Error = 1,
+    /**
+     * The resource is currently loading a new value as a result of a change in its `request`.
+     *
+     * `value()` will be `undefined`.
+     */
+    Loading = 2,
+    /**
+     * The resource is currently reloading a fresh value for the same request.
+     *
+     * `value()` will continue to return the previously fetched value during the reloading operation.
+     */
+    Reloading = 3,
+    /**
+     * Loading has completed and the resource has the value returned from the loader.
+     */
+    Resolved = 4,
+    /**
+     * The resource's value was set locally via `.set()` or `.update()`.
+     */
+    Local = 5
+}
+/**
+ * A Resource is an asynchronous dependency (for example, the results of an API call) that is
+ * managed and delivered through signals.
+ *
+ * The usual way of creating a `Resource` is through the `resource` function, but various other APIs
+ * may present `Resource` instances to describe their own concepts.
+ *
+ * @experimental
+ */
+export interface Resource<T> {
+    /**
+     * The current value of the `Resource`, or `undefined` if there is no current value.
+     */
+    readonly value: Signal<T>;
+    /**
+     * The current status of the `Resource`, which describes what the resource is currently doing and
+     * what can be expected of its `value`.
+     */
+    readonly status: Signal<ResourceStatus>;
+    /**
+     * When in the `error` state, this returns the last known error from the `Resource`.
+     */
+    readonly error: Signal<unknown>;
+    /**
+     * Whether this resource is loading a new value (or reloading the existing one).
+     */
+    readonly isLoading: Signal<boolean>;
+    /**
+     * Whether this resource has a valid current value.
+     *
+     * This function is reactive.
+     */
+    hasValue(): this is Resource<Exclude<T, undefined>>;
+    /**
+     * Instructs the resource to re-load any asynchronous dependency it may have.
+     *
+     * Note that the resource will not enter its reloading state until the actual backend request is
+     * made.
+     *
+     * @returns true if a reload was initiated, false if a reload was unnecessary or unsupported
+     */
+    reload(): boolean;
+}
+/**
+ * A `Resource` with a mutable value.
+ *
+ * Overwriting the value of a resource sets it to the 'local' state.
+ *
+ * @experimental
+ */
+export interface WritableResource<T> extends Resource<T> {
+    readonly value: WritableSignal<T>;
+    hasValue(): this is WritableResource<Exclude<T, undefined>>;
+    /**
+     * Convenience wrapper for `value.set`.
+     */
+    set(value: T): void;
+    /**
+     * Convenience wrapper for `value.update`.
+     */
+    update(updater: (value: T) => T): void;
+    asReadonly(): Resource<T>;
+}
+/**
+ * A `WritableResource` created through the `resource` function.
+ *
+ * @experimental
+ */
+export interface ResourceRef<T> extends WritableResource<T> {
+    hasValue(): this is ResourceRef<Exclude<T, undefined>>;
+    /**
+     * Manually destroy the resource, which cancels pending requests and returns it to `idle` state.
+     */
+    destroy(): void;
+}
+/**
+ * Parameter to a `ResourceLoader` which gives the request and other options for the current loading
+ * operation.
+ *
+ * @experimental
+ */
+export interface ResourceLoaderParams<R> {
+    request: Exclude<NoInfer<R>, undefined>;
+    abortSignal: AbortSignal;
+    previous: {
+        status: ResourceStatus;
+    };
+}
+/**
+ * Loading function for a `Resource`.
+ *
+ * @experimental
+ */
+export type ResourceLoader<T, R> = (param: ResourceLoaderParams<R>) => PromiseLike<T>;
+/**
+ * Streaming loader for a `Resource`.
+ *
+ * @experimental
+ */
+export type ResourceStreamingLoader<T, R> = (param: ResourceLoaderParams<R>) => PromiseLike<Signal<ResourceStreamItem<T>>>;
+/**
+ * Options to the `resource` function, for creating a resource.
+ *
+ * @experimental
+ */
+export interface BaseResourceOptions<T, R> {
+    /**
+     * A reactive function which determines the request to be made. Whenever the request changes, the
+     * loader will be triggered to fetch a new value for the resource.
+     *
+     * If a request function isn't provided, the loader won't rerun unless the resource is reloaded.
+     */
+    request?: () => R;
+    /**
+     * The value which will be returned from the resource when a server value is unavailable, such as
+     * when the resource is still loading, or in an error state.
+     */
+    defaultValue?: NoInfer<T>;
+    /**
+     * Equality function used to compare the return value of the loader.
+     */
+    equal?: ValueEqualityFn<T>;
+    /**
+     * Overrides the `Injector` used by `resource`.
+     */
+    injector?: Injector;
+}
+/**
+ * Options to the `resource` function, for creating a resource.
+ *
+ * @experimental
+ */
+export interface PromiseResourceOptions<T, R> extends BaseResourceOptions<T, R> {
+    /**
+     * Loading function which returns a `Promise` of the resource's value for a given request.
+     */
+    loader: ResourceLoader<T, R>;
+    /**
+     * Cannot specify `stream` and `loader` at the same time.
+     */
+    stream?: never;
+}
+/**
+ * Options to the `resource` function, for creating a resource.
+ *
+ * @experimental
+ */
+export interface StreamingResourceOptions<T, R> extends BaseResourceOptions<T, R> {
+    /**
+     * Loading function which returns a `Promise` of a signal of the resource's value for a given
+     * request, which can change over time as new values are received from a stream.
+     */
+    stream: ResourceStreamingLoader<T, R>;
+    /**
+     * Cannot specify `stream` and `loader` at the same time.
+     */
+    loader?: never;
+}
+/**
+ * @experimental
+ */
+export type ResourceOptions<T, R> = PromiseResourceOptions<T, R> | StreamingResourceOptions<T, R>;
+/**
+ * @experimental
+ */
+export type ResourceStreamItem<T> = {
+    value: T;
+} | {
+    error: unknown;
+};

package/{es2022/di/injectable.js → import/resource/index.d.ts}

@@ -3,6 +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
  */
-export {};
+export * from './api';
+export { resource } from './resource';

package/import/resource/resource.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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 { WritableSignal } from '../render3/reactivity/signal';
+import { Signal } from '../render3/reactivity/api';
+import { ResourceOptions, ResourceStatus, WritableResource, Resource, ResourceRef, ResourceStreamingLoader } from './api';
+import { ValueEqualityFn } from '@angular/core/primitives/signals';
+import { Injector } from '../di/injector';
+/**
+ * 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
+ */
+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
+ */
+export declare function resource<T, R>(options: ResourceOptions<T, R>): ResourceRef<T | undefined>;
+type WrappedRequest = {
+    request: unknown;
+    reload: number;
+};
+/**
+ * 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<unknown>;
+    abstract reload(): boolean;
+    constructor(value: Signal<T>);
+    abstract set(value: T): void;
+    update(updateFn: (value: T) => T): void;
+    readonly isLoading: Signal<boolean>;
+    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> {
+    private readonly loaderFn;
+    private readonly defaultValue;
+    private readonly equal;
+    private readonly pendingTasks;
+    /**
+     * 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 pendingController;
+    private resolvePendingTask;
+    private destroyed;
+    constructor(request: () => R, loaderFn: ResourceStreamingLoader<T, R>, defaultValue: T, equal: ValueEqualityFn<T> | undefined, injector: Injector);
+    readonly status: Signal<ResourceStatus>;
+    readonly error: Signal<unknown>;
+    /**
+     * Called either directly via `WritableResource.set` or via `.value.set()`.
+     */
+    set(value: T): void;
+    reload(): boolean;
+    destroy(): void;
+    private loadEffect;
+    private abortInProgressLoad;
+}
+export {};

package/import/util/callback_scheduler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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
+ */
+/**
+ * Gets a scheduling function that runs the callback after the first of setTimeout and
+ * requestAnimationFrame resolves.
+ *
+ * - `requestAnimationFrame` ensures that change detection runs ahead of a browser repaint.
+ * This ensures that the create and update passes of a change detection always happen
+ * in the same frame.
+ * - When the browser is resource-starved, `rAF` can execute _before_ a `setTimeout` because
+ * rendering is a very high priority process. This means that `setTimeout` cannot guarantee
+ * same-frame create and update pass, when `setTimeout` is used to schedule the update phase.
+ * - While `rAF` gives us the desirable same-frame updates, it has two limitations that
+ * prevent it from being used alone. First, it does not run in background tabs, which would
+ * prevent Angular from initializing an application when opened in a new tab (for example).
+ * Second, repeated calls to requestAnimationFrame will execute at the refresh rate of the
+ * hardware (~16ms for a 60Hz display). This would cause significant slowdown of tests that
+ * are written with several updates and asserts in the form of "update; await stable; assert;".
+ * - Both `setTimeout` and `rAF` are able to "coalesce" several events from a single user
+ * interaction into a single change detection. Importantly, this reduces view tree traversals when
+ * compared to an alternative timing mechanism like `queueMicrotask`, where change detection would
+ * then be interleaves between each event.
+ *
+ * By running change detection after the first of `setTimeout` and `rAF` to execute, we get the
+ * best of both worlds.
+ *
+ * @returns a function to cancel the scheduled callback
+ */
+export declare function scheduleCallbackWithRafRace(callback: Function): () => void;
+export declare function scheduleCallbackWithMicrotask(callback: Function): () => void;

package/{typings → import}/util/closure.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
  */
 /**
  * Convince closure compiler that the wrapped function has no side-effects.

package/{typings → import}/util/decorators.d.ts

@@ -3,14 +3,14 @@
  * 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 } from '../interface/type';
 /**
  * An interface implemented by all Angular type decorators, which allows them to be used as
  * decorators as well as Angular syntax.
  *
- * ```
+ * ```ts
  * @ng.Component({...})
  * class MyClass {...}
  * ```
@@ -22,7 +22,7 @@ export interface TypeDecorator {
      * Invoke as decorator.
      */
     <T extends Type<any>>(type: T): T;
-    (target: Object, propertyKey?: string | symbol, parameterIndex?: number): void;
+    (target: object, propertyKey?: string | symbol, parameterIndex?: number): void;
     (target: unknown, context: unknown): void;
 }
 export declare const PARAMETERS = "__parameters__";

package/{typings → import}/util/empty.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
  */
 /**
  * This file contains reuseable "empty" symbols that can be used as default return values

package/{es2022/di/provider_token.js → import/util/noop.d.ts}

@@ -3,6 +3,6 @@
  * 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
  */
-export {};
+export declare function noop(...args: any[]): any;

package/{typings → import}/util/property.d.ts

@@ -3,6 +3,6 @@
  * 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
  */
 export declare function getClosureSafeProperty<T>(objWithPropertyToExtract: T): string;

package/{typings → import}/util/stringify.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
  */
 export declare function stringify(token: any): string;
 /**