static-injector 5.0.1 → 6.0.0

package/import/render3/reactivity/root_effect_scheduler.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.dev/license
+ */
+/**
+ * Abstraction that encompasses any kind of effect that can be scheduled.
+ */
+export interface SchedulableEffect {
+    run(): void;
+    zone: {
+        run<T>(fn: () => T): T;
+    } | null;
+}
+/**
+ * A scheduler which manages the execution of effects.
+ */
+export declare abstract class EffectScheduler {
+    /**
+     * 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;
+    /** @nocollapse */
+    static ɵprov: unknown;
+}
+/**
+ * A wrapper around `ZoneAwareQueueingScheduler` that schedules flushing via the microtask queue
+ * when.
+ */
+export declare class ZoneAwareEffectScheduler implements EffectScheduler {
+    private queuedEffectCount;
+    private queues;
+    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;
+    private flushQueue;
+}

package/import/render3/reactivity/signal.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @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 { SignalGetter } from '@angular/core/primitives/signals';
+import { Signal, ValueEqualityFn } from './api';
+/** 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.
+ */
+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>;
+}
+/**
+ * Utility function used during template type checking to extract the value from a `WritableSignal`.
+ * @codeGenApi
+ */
+export declare function ɵunwrapWritableSignal<T>(value: T | {
+    [ɵWRITABLE_SIGNAL]: T;
+}): 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.
+ */
+export declare function signal<T>(initialValue: T, options?: CreateSignalOptions<T>): WritableSignal<T>;
+export declare function signalAsReadonlyFn<T>(this: SignalGetter<T>): Signal<T>;
+/**
+ * Checks if the given `value` is a writeable signal.
+ */
+export declare function isWritableSignal(value: unknown): value is WritableSignal<unknown>;

package/import/render3/reactivity/untracked.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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
+ */
+/**
+ * Execute an arbitrary function in a non-reactive (non-tracking) context. The executed function
+ * can, optionally, return a value.
+ */
+export declare function untracked<T>(nonReactiveReadsFn: () => T): T;

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;
 /**