static-injector 6.3.1 → 7.0.0

package/import/pending_tasks_internal.d.ts

@@ -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 { Observable } from 'rxjs';
+import { OnDestroy } from './change_detection/lifecycle_hooks';
+/**
+ * Internal implementation of the pending tasks service.
+ */
+export declare class PendingTasksInternal implements OnDestroy {
+    private taskId;
+    private pendingTasks;
+    private destroyed;
+    private pendingTask;
+    private debugTaskTracker;
+    get hasPendingTasks(): boolean;
+    /**
+     * In case the service is about to be destroyed, return a self-completing observable.
+     * Otherwise, return the observable that emits the current state of pending tasks.
+     */
+    get hasPendingTasksObservable(): Observable<boolean>;
+    add(): number;
+    has(taskId: number): boolean;
+    remove(taskId: number): void;
+    ngOnDestroy(): void;
+    /** @nocollapse */
+    static ɵprov: import("./di/interface/defs").ɵɵInjectableDeclaration<PendingTasksInternal>;
+}

package/import/render3/debug/injector_profiler.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @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 { ProviderToken } from '../../di';
+import type { Injector } from '../../di/injector';
+import { InternalInjectFlags } from '../../di/interface/injector';
+import type { SingleProvider } from '../../di/provider_collection';
+import { Type } from '../../interface/type';
+import type { EffectRefImpl } from '../reactivity/effect';
+/**
+ * An enum describing the types of events that can be emitted from the injector profiler
+ */
+export declare const enum InjectorProfilerEventType {
+    /**
+     * Emits when a service is injected.
+     */
+    Inject = 0,
+    /**
+     * Emits when an Angular class instance is created by an injector.
+     */
+    InstanceCreatedByInjector = 1,
+    /**
+     * Emits when an injector configures a provider.
+     */
+    ProviderConfigured = 2,
+    /**
+     * Emits when an effect is created.
+     */
+    EffectCreated = 3,
+    /**
+     * Emits when an after render effect phase is created.
+     */
+    AfterRenderEffectPhaseCreated = 4,
+    /**
+     * Emits when an Angular DI system is about to create an instance corresponding to a given token.
+     */
+    InjectorToCreateInstanceEvent = 5
+}
+/**
+ * An object that defines an injection context for the injector profiler.
+ */
+export interface InjectorProfilerContext {
+}
+export interface InjectedServiceEvent {
+}
+export interface InjectorToCreateInstanceEvent {
+}
+export interface InjectorCreatedInstanceEvent {
+}
+export interface ProviderConfiguredEvent {
+}
+export interface EffectCreatedEvent {
+}
+export interface AfterRenderEffectPhaseCreatedEvent {
+}
+/**
+ * An object representing an event that is emitted through the injector profiler
+ */
+export type InjectorProfilerEvent = InjectedServiceEvent | InjectorToCreateInstanceEvent | InjectorCreatedInstanceEvent | ProviderConfiguredEvent | EffectCreatedEvent | AfterRenderEffectPhaseCreatedEvent;
+/**
+ * An object that contains information about a provider that has been configured
+ *
+ * TODO: rename to indicate that it is a debug structure eg. ProviderDebugInfo.
+ */
+export interface ProviderRecord {
+}
+/**
+ * An object that contains information about a value that has been constructed within an injector
+ */
+export interface InjectorCreatedInstance {
+}
+/**
+ * An object that contains information a service that has been injected within an
+ * InjectorProfilerContext
+ */
+export interface InjectedService {
+    /**
+     * In NodeInjectors, the LView and TNode that serviced this injection.
+     */
+    injectedIn?: {};
+}
+export interface InjectorProfiler {
+    (event: InjectorProfilerEvent): void;
+}
+export declare function getInjectorProfilerContext(): InjectorProfilerContext;
+export declare function setInjectorProfilerContext(context: InjectorProfilerContext): InjectorProfilerContext;
+/**
+ * Adds a callback function which will be invoked during certain DI events within the
+ * runtime (for example: injecting services, creating injectable instances, configuring providers).
+ * Multiple profiler callbacks can be set: in this case profiling events are
+ * reported to every registered callback.
+ *
+ * Warning: this function is *INTERNAL* and should not be relied upon in application's code.
+ * The contract of the function might be changed in any release and/or the function can be removed
+ * completely.
+ *
+ * @param profiler function provided by the caller or null value to disable profiling.
+ * @returns a cleanup function that, when invoked, removes a given profiler callback.
+ */
+export declare function setInjectorProfiler(injectorProfiler: InjectorProfiler | null): () => void;
+/**
+ * Injector profiler function which emits on DI events executed by the runtime.
+ *
+ * @param event InjectorProfilerEvent corresponding to the DI event being emitted
+ */
+export declare function injectorProfiler(event: InjectorProfilerEvent): void;
+/**
+ * Emits an InjectorProfilerEventType.ProviderConfigured to the injector profiler. The data in the
+ * emitted event includes the raw provider, as well as the token that provider is providing.
+ *
+ * @param eventProvider A provider object
+ */
+export declare function emitProviderConfiguredEvent(eventProvider: SingleProvider, isViewProvider?: boolean): void;
+/**
+ * Emits an event to the injector profiler when an instance corresponding to a given token is about to be created be an injector. Note that
+ * the injector associated with this emission can be accessed by using getDebugInjectContext()
+ *
+ * @param instance an object created by an injector
+ */
+export declare function emitInjectorToCreateInstanceEvent(token: ProviderToken<unknown>): void;
+/**
+ * Emits an event to the injector profiler with the instance that was created. Note that
+ * the injector associated with this emission can be accessed by using getDebugInjectContext()
+ *
+ * @param instance an object created by an injector
+ */
+export declare function emitInstanceCreatedByInjectorEvent(instance: unknown): void;
+/**
+ * @param token DI token associated with injected service
+ * @param value the instance of the injected service (i.e the result of `inject(token)`)
+ * @param flags the flags that the token was injected with
+ */
+export declare function emitInjectEvent(token: Type<unknown>, value: unknown, flags: InternalInjectFlags): void;
+export declare function emitEffectCreatedEvent(effect: EffectRefImpl): void;
+export declare function runInInjectorProfilerContext(injector: Injector, token: Type<unknown>, callback: () => void): void;

package/import/render3/debug/special_providers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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
+ */
+/**
+ * Registers a class as a special provider for debug tooling.
+ *
+ * @param clazz The class to register
+ */
+export declare function registerSpecialProvider(clazz: any): void;
+/**
+ * Gets all special providers that have been registered.
+ */
+export declare function getAllSpecialProviders(): ReadonlySet<any>;

package/import/render3/errors_di.d.ts

@@ -6,10 +6,35 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 import type { ProviderToken } from '../di';
+import { Type } from '../interface/type';
 /** Creates a circular dependency runtime error. */
 export declare function cyclicDependencyError(token: string, path?: string[]): Error;
+/** Creates a circular dependency runtime error including a dependency path in the error message. */
+export declare function cyclicDependencyErrorWithDetails(token: string, path: string[]): Error;
+export declare function throwMixedMultiProviderError(): void;
+export declare function throwInvalidProviderError(ngModuleType?: Type<unknown>, providers?: any[], provider?: any): never;
 /** Throws an error when a token is not found in DI. */
 export declare function throwProviderNotFoundError(token: ProviderToken<unknown>, injectorName?: string): never;
+/**
+ * Given an Error instance and the current token - update the monkey-patched
+ * dependency path info to include that token.
+ *
+ * @param error Current instance of the Error class.
+ * @param token Extra token that should be appended.
+ */
+export declare function prependTokenToDependencyPath(error: any, token: ProviderToken<unknown> | {
+    multi: true;
+    provide: ProviderToken<unknown>;
+}): void;
+/**
+ * Modifies an Error instance with an updated error message
+ * based on the accumulated dependency path.
+ *
+ * @param error Current instance of the Error class.
+ * @param source Extra info about the injector which started
+ *    the resolution process, which eventually failed.
+ */
+export declare function augmentRuntimeError(error: any, source: string | null): Error;
 /**
  * Creates an initial RuntimeError instance when a problem is detected.
  * Monkey-patches extra info in the RuntimeError instance, so that it can

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

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 import { SIGNAL } from '../../../primitives/signals';
+import type { WritableSignal } from './signal';
 /**
  * A reactive value which notifies consumers of any changes.
  *
@@ -14,6 +15,8 @@ import { SIGNAL } from '../../../primitives/signals';
  *
  * Ordinary values can be turned into `Signal`s with the `signal` function.
  *
+ * @see [What are signals?](guide/signals#what-are-signals)
+ *
  * @publicApi 17.0
  */
 export type Signal<T> = (() => T) & {
@@ -22,12 +25,24 @@ export type Signal<T> = (() => T) & {
 /**
  * Checks if the given `value` is a reactive `Signal`.
  *
+ * @see [Type checking signals](guide/signals#type-checking-signals)
+ *
  * @publicApi 17.0
  */
 export declare function isSignal(value: unknown): value is Signal<unknown>;
 /**
  * A comparison function which can determine if two values are equal.
  *
+ * @see [Signal equality functions](guide/signals#signal-equality-functions)
+ *
  * @publicApi 17.0
  */
 export type ValueEqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Checks if the given `value` is a writeable signal.
+ *
+ * @see [Type checking signals](guide/signals#type-checking-signals)
+ *
+ * @publicApi 21.1
+ */
+export declare function isWritableSignal(value: unknown): value is WritableSignal<unknown>;

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

@@ -10,6 +10,7 @@
  * to disallow certain code from running inside a reactive context (see {@link /api/core/rxjs-interop/toSignal toSignal})
  *
  * @param debugFn a reference to the function making the assertion (used for the error message).
+ * @see [Asserts the reactive context](guide/signals#asserts-the-reactive-context)
  *
  * @publicApi
  */

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

@@ -13,6 +13,8 @@ import { EffectScheduler, SchedulableEffect } from './root_effect_scheduler';
  * A global reactive effect, which can be manually destroyed.
  *
  * @publicApi 20.0
+ *
+ * @see [Destroying effects](guide/signals/effect#destroying-effects)
  */
 export interface EffectRef {
     /**
@@ -100,7 +102,7 @@ export interface EffectNode extends BaseEffectNode, SchedulableEffect {
     cleanupFns: EffectCleanupFn[] | undefined;
     injector: Injector;
     notifier: ChangeDetectionScheduler;
-    onDestroyFn: () => void;
+    onDestroyFns: (() => void)[] | null;
 }
 export interface RootEffectNode extends EffectNode {
     scheduler: EffectScheduler;

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

@@ -33,7 +33,7 @@ export declare abstract class EffectScheduler {
     /** Remove a scheduled effect */
     abstract remove(e: SchedulableEffect): void;
     /** @nocollapse */
-    static ɵprov: unknown;
+    static ɵprov: import("../../di/interface/defs").ɵɵInjectableDeclaration<ZoneAwareEffectScheduler>;
 }
 /**
  * A wrapper around `ZoneAwareQueueingScheduler` that schedules flushing via the microtask queue

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

@@ -58,7 +58,3 @@ export interface CreateSignalOptions<T> {
  */
 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/util/stringify_utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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
+ */
+/**
+ * Used for stringify render output in Ivy.
+ * Important! This function is very performance-sensitive and we should
+ * be extra careful not to introduce megamorphic reads in it.
+ * Check `core/test/render3/perf/render_stringify` for benchmarks and alternate implementations.
+ */
+export declare function renderStringify(value: unknown): string;
+/**
+ * Used to stringify a value so that it can be displayed in an error message.
+ *
+ * Important! This function contains a megamorphic read and should only be
+ * used for error messages.
+ */
+export declare function stringifyForError(value: any): string;

package/import/resource/api.d.ts

@@ -8,6 +8,37 @@
 import { Injector } from '../di/injector';
 import { Signal, ValueEqualityFn } from '../render3/reactivity/api';
 import { WritableSignal } from '../render3/reactivity/signal';
+/** Error thrown when a `Resource` dependency of another resource errors. */
+export declare class ResourceDependencyError extends Error {
+    /** The dependency that errored. */
+    readonly dependency: Resource<unknown>;
+    constructor(dependency: Resource<unknown>);
+}
+/**
+ * Special status codes that can be thrown from a resource's `params` or `request` function to
+ * indicate that the resource should transition to that status.
+ */
+export declare class ResourceParamsStatus extends Error {
+    private readonly _brand;
+    private constructor();
+    /** Status code that transitions the resource to `idle` status. */
+    static readonly IDLE: ResourceParamsStatus;
+    /** Status code that transitions the resource to `loading` status. */
+    static readonly LOADING: ResourceParamsStatus;
+}
+/**
+ * Context received by a resource's `params` or `request` function.
+ *
+ * @see [Chaining resources](guide/signals/resource#chaining-resources)
+ */
+export interface ResourceParamsContext {
+    /**
+     * Chains the current params off of the value of another resource, returning the value
+     * of the other resource if it is available, or propagating the status to the current resource by
+     * throwing the appropriate status code if the value is not available.
+     */
+    readonly chain: <T>(resource: Resource<T>) => T;
+}
 /**
  * String value capturing the status of a `Resource`.
  *
@@ -29,7 +60,7 @@ import { WritableSignal } from '../render3/reactivity/signal';
  *
  * `local` - The resource's value was set locally via `.set()` or `.update()`.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export type ResourceStatus = 'idle' | 'error' | 'loading' | 'reloading' | 'resolved' | 'local';
 /**
@@ -39,7 +70,7 @@ export type ResourceStatus = 'idle' | 'error' | 'loading' | 'reloading' | 'resol
  * 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
+ * @publicApi 22.0
  */
 export interface Resource<T> {
     /**
@@ -59,6 +90,10 @@ export interface Resource<T> {
      * Whether this resource is loading a new value (or reloading the existing one).
      */
     readonly isLoading: Signal<boolean>;
+    /**
+     * The current state of this resource, represented as a `ResourceSnapshot`.
+     */
+    readonly snapshot: Signal<ResourceSnapshot<T>>;
     /**
      * Whether this resource has a valid current value.
      *
@@ -72,7 +107,7 @@ export interface Resource<T> {
  *
  * Overwriting the value of a resource sets it to the 'local' state.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export interface WritableResource<T> extends Resource<T> {
     readonly value: WritableSignal<T>;
@@ -100,7 +135,7 @@ export interface WritableResource<T> extends Resource<T> {
 /**
  * A `WritableResource` created through the `resource` function.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export interface ResourceRef<T> extends WritableResource<T> {
     hasValue(this: T extends undefined ? this : never): this is ResourceRef<Exclude<T, undefined>>;
@@ -114,7 +149,7 @@ export interface ResourceRef<T> extends WritableResource<T> {
  * Parameter to a `ResourceLoader` which gives the request and other options for the current loading
  * operation.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export interface ResourceLoaderParams<R> {
     params: NoInfer<Exclude<R, undefined>>;
@@ -126,19 +161,19 @@ export interface ResourceLoaderParams<R> {
 /**
  * Loading function for a `Resource`.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export type ResourceLoader<T, R> = (param: ResourceLoaderParams<R>) => PromiseLike<T>;
 /**
  * Streaming loader for a `Resource`.
  *
- * @experimental
+ * @publicApi 22.0
  */
-export type ResourceStreamingLoader<T, R> = (param: ResourceLoaderParams<R>) => PromiseLike<Signal<ResourceStreamItem<T>>>;
+export type ResourceStreamingLoader<T, R> = (param: ResourceLoaderParams<R>) => Signal<ResourceStreamItem<T>> | PromiseLike<Signal<ResourceStreamItem<T>>> | undefined;
 /**
  * Options to the `resource` function, for creating a resource.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export interface BaseResourceOptions<T, R> {
     /**
@@ -147,7 +182,7 @@ export interface BaseResourceOptions<T, R> {
      *
      * If a params function isn't provided, the loader won't rerun unless the resource is reloaded.
      */
-    params?: () => R;
+    params?: (ctx: ResourceParamsContext) => R;
     /**
      * The value which will be returned from the resource when a server value is unavailable, such as
      * when the resource is still loading.
@@ -161,11 +196,16 @@ export interface BaseResourceOptions<T, R> {
      * Overrides the `Injector` used by `resource`.
      */
     injector?: Injector;
+    /**
+     * Identifier used to cache the resource data in the `TransferState` during server-side rendering and to retrieve it on the client side.
+     * This value value needs to be identical for both the client and server.
+     */
+    id?: string;
 }
 /**
  * Options to the `resource` function, for creating a resource.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export interface PromiseResourceOptions<T, R> extends BaseResourceOptions<T, R> {
     /**
@@ -180,7 +220,7 @@ export interface PromiseResourceOptions<T, R> extends BaseResourceOptions<T, R>
 /**
  * Options to the `resource` function, for creating a resource.
  *
- * @experimental
+ * @publicApi 22.0
  */
 export interface StreamingResourceOptions<T, R> extends BaseResourceOptions<T, R> {
     /**
@@ -194,14 +234,60 @@ export interface StreamingResourceOptions<T, R> extends BaseResourceOptions<T, R
     loader?: never;
 }
 /**
- * @experimental
+ * @publicApi 22.0
  */
-export type ResourceOptions<T, R> = PromiseResourceOptions<T, R> | StreamingResourceOptions<T, R>;
+export type ResourceOptions<T, R> = (PromiseResourceOptions<T, R> | StreamingResourceOptions<T, R>) & {
+    /**
+     * A debug name for the reactive node. Used in Angular DevTools to identify the node.
+     */
+    debugName?: string;
+};
 /**
- * @experimental
+ * @publicApi 22.0
  */
 export type ResourceStreamItem<T> = {
     value: T;
 } | {
     error: Error;
 };
+/**
+ * An explicit representation of a resource's state.
+ *
+ * @publicApi 22.0
+ * @see [Resource composition with snapshots](guide/signals/resource#resource-composition-with-snapshots)
+ */
+export type ResourceSnapshot<T> = {
+    readonly status: 'idle';
+    readonly value: T;
+} | {
+    readonly status: 'loading' | 'reloading';
+    readonly value: T;
+} | {
+    readonly status: 'resolved' | 'local';
+    readonly value: T;
+} | {
+    readonly status: 'error';
+    readonly error: Error;
+};
+/**
+ * Options for `debounced`.
+ *
+ * @see [Debouncing signals with `debounced`](guide/signals/debounced)
+ *
+ * @experimental 22.0
+ */
+export interface DebouncedOptions<T> {
+    /** The `Injector` to use for the debounced resource. */
+    injector?: Injector;
+    /** The equality function to use for comparing values. */
+    equal?: ValueEqualityFn<T>;
+}
+/**
+ * Represents the wait condition for item debouncing.
+ * Can be a number of milliseconds or a function that returns a Promise.
+ *
+ * @see [Debouncing signals with `debounced`](guide/signals/debounced)
+ *
+ * @experimental 22.0
+ */
+export type DebounceTimer<T> = number | ((value: T, lastValue: ResourceSnapshot<T>) => Promise<void> | void);

package/import/resource/debounce.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @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 { Resource, type DebounceTimer, type DebouncedOptions } from './api';
+/**
+ * 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
+ *
+ * @see [Debouncing signals with `debounced`](guide/signals/debounced)
+ */
+export declare function debounced<T>(source: () => T, wait: NoInfer<DebounceTimer<T>>, options?: NoInfer<DebouncedOptions<T>>): Resource<T>;

package/import/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 { Resource, ResourceSnapshot } from './api';
+/**
+ * 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/import/resource/index.d.ts

@@ -6,4 +6,6 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 export * from './api';
+export { debounced } from './debounce';
+export { resourceFromSnapshots } from './from_snapshots';
 export { resource } from './resource';