@tstdl/base 0.93.182 → 0.93.183

package/signals/implementation/to-observable.d.ts

@@ -1,10 +1,14 @@
+/**
+ * @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 type { SignalsInjector } from '../api.js';
-import type { Signal } from './api.js';
+import type { Signal, SignalsInjector } from '../api.js';
 /**
  * Options for `toObservable`.
- *
- * @developerPreview
  */
 export interface ToObservableOptions {
     /**
@@ -16,8 +20,11 @@ export interface ToObservableOptions {
     injector?: SignalsInjector;
 }
 /**
- * Exposes the value of an `Signal` as an RxJS `Observable`.
+ * Exposes the value of an Angular `Signal` as an RxJS `Observable`.
+ * As it reflects a state, the observable will always emit the latest value upon subscription.
  *
  * The signal's value will be propagated into the `Observable`'s subscribers using an `effect`.
+ *
+ * `toObservable` must be called in an injection context unless an injector is provided via options.
  */
 export declare function toObservable<T>(source: Signal<T>, options?: ToObservableOptions): Observable<T>;

package/signals/implementation/to-observable.js

@@ -1,10 +1,20 @@
+/**
+ * @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 { effect } from './effect.js';
 import { untracked } from './untracked.js';
 /**
- * Exposes the value of an `Signal` as an RxJS `Observable`.
+ * Exposes the value of an Angular `Signal` as an RxJS `Observable`.
+ * As it reflects a state, the observable will always emit the latest value upon subscription.
  *
  * The signal's value will be propagated into the `Observable`'s subscribers using an `effect`.
+ *
+ * `toObservable` must be called in an injection context unless an injector is provided via options.
  */
 export function toObservable(source, options) {
     return new Observable((subscriber) => {
@@ -16,7 +26,7 @@ export function toObservable(source, options) {
             catch (error) {
                 untracked(() => subscriber.error(error));
             }
-        }, { allowSignalWrites: true, injector: options?.injector, manualCleanup: true });
+        }, { injector: options?.injector, manualCleanup: true });
         return () => effectRef.destroy();
     });
 }

package/signals/implementation/to-signal.d.ts

@@ -1,14 +1,10 @@
+/** biome-ignore-all lint: <explanation> */
+import type { Observable, Subscribable } from 'rxjs';
+import { type SignalsInjector } from '../api.js';
+import type { Signal, ValueEqualityFn } from './api.js';
 /**
- * @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.io/license
+ * Options for `toSignal`.
  */
-import type { Observable, Subscribable } from 'rxjs';
-import type { SignalsInjector } from '../api.js';
-import type { Signal } from './api.js';
-import type { ValueEqualityFn } from './equality.js';
 export interface ToSignalOptions<T> {
     /**
      * Initial value for the signal produced by `toSignal`.
@@ -40,21 +36,16 @@ export interface ToSignalOptions<T> {
      * until the `Observable` itself completes.
      */
     manualCleanup?: boolean;
-    /**
-     * Whether `toSignal` should throw errors from the Observable error channel back to RxJS, where
-     * they'll be processed as uncaught exceptions.
-     *
-     * In practice, this means that the signal returned by `toSignal` will keep returning the last
-     * good value forever, as Observables which error produce no further values. This option emulates
-     * the behavior of the `async` pipe.
-     */
-    rejectErrors?: boolean;
     /**
      * A comparison function which defines equality for values emitted by the observable.
      *
      * Equality comparisons are executed against the initial value if one is provided.
      */
     equal?: ValueEqualityFn<T>;
+    /**
+     * A debug name for the signal. Used in Angular DevTools to identify the signal.
+     */
+    debugName?: string;
 }
 export declare function toSignal<T>(source: Observable<T> | Subscribable<T>): Signal<T | undefined>;
 export declare function toSignal<T>(source: Observable<T> | Subscribable<T>, options: NoInfer<ToSignalOptions<T | undefined>> & {

package/signals/implementation/to-signal.js

@@ -1,9 +1,18 @@
 /* eslint-disable */
-import { registerFinalization } from '../../memory/finalization.js';
+/** 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 { isDevMode } from '../../core.js';
+import { defineEnum } from '../../enumeration/index.js';
+import { registerFinalization } from '../../memory/index.js';
+import { signal } from '../api.js';
 import { assertNotInReactiveContext } from './asserts.js';
 import { computed } from './computed.js';
-import { signal } from './writable-signal.js';
-import { defineEnum } from '../../enumeration/enumeration.js';
 /**
  * Get the current value of an `Observable` as a reactive `Signal`.
  *
@@ -15,22 +24,36 @@ import { defineEnum } from '../../enumeration/enumeration.js';
  * With `requireSync` set to `true`, `toSignal` will assert that the `Observable` produces a value
  * immediately upon subscription. No `initialValue` is needed in this case, and the returned signal
  * does not include an `undefined` type.
+ *
+ * By default, the subscription will be automatically cleaned up when the current [injection
+ * context](guide/di/dependency-injection-context) is destroyed. For example, when `toSignal` is
+ * called during the construction of a component, the subscription will be cleaned up when the
+ * component is destroyed. If an injection context is not available, an explicit `Injector` can be
+ * passed instead.
+ *
+ * If the subscription should persist until the `Observable` itself completes, the `manualCleanup`
+ * option can be specified instead, which disables the automatic subscription teardown. No injection
+ * context is needed in this configuration as well.
+ *
+ * @see [RxJS interop with Angular signals](ecosystem/rxjs-interop)
  */
 export function toSignal(source, options) {
-    assertNotInReactiveContext(toSignal, 'Invoking `toSignal` causes new subscriptions every time. ' +
-        'Consider moving `toSignal` outside of the reactive context and read the signal value where needed.');
+    isDevMode() &&
+        assertNotInReactiveContext(toSignal, 'Invoking `toSignal` causes new subscriptions every time. ' +
+            'Consider moving `toSignal` outside of the reactive context and read the signal value where needed.');
     const equal = makeToSignalEqual(options?.equal);
     // Note: T is the Observable value type, and U is the initial value type. They don't have to be
     // the same - the returned signal gives values of type `T`.
     let state;
     if (options?.requireSync) {
         // Initially the signal is in a `NoValue` state.
-        state = signal({ kind: StateKind.NoValue }, { equal });
+        state = signal({ kind: StateKind.NoValue }, { equal, ...(isDevMode() ? createDebugNameObject(options?.debugName, 'state') : undefined) });
     }
     else {
         // If an initial value was passed, use it. Otherwise, use `undefined` as the initial value.
-        state = signal({ kind: StateKind.Value, value: options?.initialValue }, { equal });
+        state = signal({ kind: StateKind.Value, value: options?.initialValue }, { equal, ...(isDevMode() ? createDebugNameObject(options?.debugName, 'state') : undefined) });
     }
+    let destroyUnregisterFn;
     // Note: This code cannot run inside a reactive context (see assertion above). If we'd support
     // this, we would subscribe to the observable outside of the current reactive context, avoiding
     // that side-effect signal reads/writes are attribute to the current consumer. The current
@@ -40,12 +63,11 @@ export function toSignal(source, options) {
     const sub = source.subscribe({
         next: (value) => state.set({ kind: StateKind.Value, value }),
         error: (error) => {
-            if (options?.rejectErrors) {
-                // Kick the error back to RxJS. It will be caught and rethrown in a macrotask, which causes
-                // the error to end up as an uncaught exception.
-                throw error;
-            }
             state.set({ kind: StateKind.Error, error });
+            destroyUnregisterFn?.();
+        },
+        complete: () => {
+            destroyUnregisterFn?.();
         },
         // Completion of the Observable is meaningless to the signal. Signals don't have a concept of
         // "complete".
@@ -66,13 +88,24 @@ export function toSignal(source, options) {
                 // This shouldn't really happen because the error is thrown on creation.
                 throw new Error('`toSignal()` called with `requireSync` but `Observable` did not emit synchronously.');
         }
-    }, { equal: options?.equal });
+    }, {
+        equal: options?.equal,
+        ...(isDevMode() ? createDebugNameObject(options?.debugName, 'source') : undefined),
+    });
     registerFinalization(result, () => sub.unsubscribe());
     return result;
 }
 function makeToSignalEqual(userEquality = Object.is) {
     return (a, b) => a.kind === StateKind.Value && b.kind === StateKind.Value && userEquality(a.value, b.value);
 }
+/**
+ * Creates a debug name object for an internal toSignal signal.
+ */
+function createDebugNameObject(toSignalDebugName, internalSignalDebugName) {
+    return {
+        debugName: `toSignal${toSignalDebugName ? '#' + toSignalDebugName : ''}.${internalSignalDebugName}`,
+    };
+}
 const StateKind = defineEnum('StateKind', {
     NoValue: 0,
     Value: 1,

package/signals/implementation/untracked.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
  */
 /**
  * Execute an arbitrary function in a non-reactive (non-tracking) context. The executed function

package/signals/implementation/untracked.js

@@ -3,21 +3,13 @@
  * 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 { setActiveConsumer } from './graph.js';
+import { untracked as untrackedPrimitive } from './primitive/untracked.js';
 /**
  * Execute an arbitrary function in a non-reactive (non-tracking) context. The executed function
  * can, optionally, return a value.
  */
 export function untracked(nonReactiveReadsFn) {
-    const prevConsumer = setActiveConsumer(null);
-    // We are not trying to catch any particular errors here, just making sure that the consumers
-    // stack is restored in case of errors.
-    try {
-        return nonReactiveReadsFn();
-    }
-    finally {
-        setActiveConsumer(prevConsumer);
-    }
+    return untrackedPrimitive(nonReactiveReadsFn);
 }

package/signals/operators/debounce.d.ts

@@ -0,0 +1,8 @@
+import { type Signal } from '../api.js';
+/**
+ * Creates a signal that debounces the value of the source signal.
+ * @param source The source signal.
+ * @param ms The debounce time in milliseconds.
+ * @returns A signal that debounces the source signal.
+ */
+export declare function debounce<T>(source: Signal<T>, ms: number): Signal<T>;

package/signals/operators/debounce.js

@@ -0,0 +1,19 @@
+import { registerFinalization } from '../../memory/finalization.js';
+import { effect, signal, untracked } from '../api.js';
+/**
+ * Creates a signal that debounces the value of the source signal.
+ * @param source The source signal.
+ * @param ms The debounce time in milliseconds.
+ * @returns A signal that debounces the source signal.
+ */
+export function debounce(source, ms) {
+    const debouncedSignal = signal(untracked(source));
+    const effectRef = effect((onCleanup) => {
+        const value = source();
+        const timeout = setTimeout(() => debouncedSignal.set(value), ms);
+        onCleanup(() => clearTimeout(timeout));
+    });
+    const result = debouncedSignal.asReadonly();
+    registerFinalization(result, () => effectRef.destroy());
+    return result;
+}

package/signals/operators/derive-async.js

@@ -1,4 +1,4 @@
-import { Subject, concatAll, exhaustAll, from, isObservable, mergeAll, of, switchAll, takeUntil } from 'rxjs';
+import { BehaviorSubject, Subject, concatAll, exhaustAll, filter, from, isObservable, map, materialize, mergeAll, of, switchAll, takeUntil } from 'rxjs';
 import { registerFinalization } from '../../memory/finalization.js';
 import { isPromise } from '../../utils/type-guards.js';
 import { computed, effect, toSignal, untracked } from '../api.js';
@@ -8,28 +8,56 @@ const operatorMap = {
     exhaust: exhaustAll,
     switch: switchAll,
 };
+/**
+ * Derives a signal from an asynchronous source (Promise or Observable).
+ *
+ * @param source A function that returns a value, a Promise, or an Observable.
+ * @param options Options for the signal and the async behavior.
+ *
+ * @warning If `requireSync: true` is used, the source MUST emit synchronously.
+ * Since Promises are always resolved asynchronously (on the microtask queue),
+ * they will ALWAYS throw an error if used with `requireSync: true`.
+ *
+ * @returns A Signal that represents the latest value from the async source.
+ */
 export function deriveAsync(source, options) {
-    const outerSource = computed(() => {
-        const rawSource = source();
-        if (isPromise(rawSource)) {
-            return from(rawSource);
-        }
-        if (isObservable(rawSource)) {
-            return rawSource;
-        }
-        return of(rawSource);
-    });
-    const source$ = new Subject();
+    const initialRaw = untracked(source);
+    const initialSource = isPromise(initialRaw) ? from(initialRaw) : isObservable(initialRaw) ? initialRaw : of(initialRaw);
+    const source$ = new BehaviorSubject(initialSource);
     const destroy$ = new Subject();
     const operator = operatorMap[options?.behavior ?? 'switch'];
-    const valueSource$ = source$.pipe(operator(), takeUntil(destroy$));
-    const result = toSignal(valueSource$, options);
+    const valueSource$ = source$.pipe(map((inner$) => inner$.pipe(materialize(), filter((n) => n.kind != 'C'))), operator(), takeUntil(destroy$));
+    const notificationSignal = toSignal(valueSource$, {
+        requireSync: options?.requireSync,
+        injector: options?.injector,
+        manualCleanup: options?.manualCleanup,
+        debugName: options?.debugName ? `${options.debugName}-notifications` : undefined,
+        initialValue: undefined,
+    });
+    const result = computed(() => {
+        const notification = notificationSignal();
+        if (notification === undefined) {
+            return options?.initialValue;
+        }
+        if (notification.kind === 'E') {
+            throw notification.error;
+        }
+        return notification.value;
+    }, { equal: options?.equal });
+    let firstRun = true;
     const effectRef = effect(() => {
-        const observableInput = outerSource();
+        const rawSource = source();
+        if (firstRun) {
+            firstRun = false;
+            return;
+        }
+        const observableInput = isPromise(rawSource) ? from(rawSource) : isObservable(rawSource) ? rawSource : of(rawSource);
         untracked(() => source$.next(observableInput));
     });
     registerFinalization(result, () => {
         destroy$.next();
+        destroy$.complete();
+        source$.complete();
         effectRef.destroy();
     });
     return result;

package/signals/operators/index.d.ts

@@ -1,5 +1,7 @@
 export * from './combine.js';
+export * from './debounce.js';
 export * from './defer.js';
 export * from './derive-async.js';
 export * from './map.js';
 export * from './switchAll.js';
+export * from './throttle.js';

package/signals/operators/index.js

@@ -1,5 +1,7 @@
 export * from './combine.js';
+export * from './debounce.js';
 export * from './defer.js';
 export * from './derive-async.js';
 export * from './map.js';
 export * from './switchAll.js';
+export * from './throttle.js';

package/signals/operators/throttle.d.ts

@@ -0,0 +1,8 @@
+import { type Signal } from '../api.js';
+/**
+ * Creates a signal that throttles the value of the source signal.
+ * @param source The source signal.
+ * @param ms The throttle time in milliseconds.
+ * @returns A signal that throttles the source signal.
+ */
+export declare function throttle<T>(source: Signal<T>, ms: number): Signal<T>;

package/signals/operators/throttle.js

@@ -0,0 +1,31 @@
+import { registerFinalization } from '../../memory/finalization.js';
+import { effect, signal, untracked } from '../api.js';
+/**
+ * Creates a signal that throttles the value of the source signal.
+ * @param source The source signal.
+ * @param ms The throttle time in milliseconds.
+ * @returns A signal that throttles the source signal.
+ */
+export function throttle(source, ms) {
+    const throttledSignal = signal(untracked(source));
+    let lastUpdate = 0;
+    const effectRef = effect((onCleanup) => {
+        const value = source();
+        const now = Date.now();
+        const remaining = ms - (now - lastUpdate);
+        if (remaining <= 0) {
+            lastUpdate = now;
+            throttledSignal.set(value);
+        }
+        else {
+            const timeout = setTimeout(() => {
+                lastUpdate = Date.now();
+                throttledSignal.set(value);
+            }, remaining);
+            onCleanup(() => clearTimeout(timeout));
+        }
+    });
+    const result = throttledSignal.asReadonly();
+    registerFinalization(result, () => effectRef.destroy());
+    return result;
+}

package/ai/genkit/tests/multi-region.test.d.ts

@@ -1,2 +0,0 @@
-/** biome-ignore-all lint/suspicious/useAwait: defineModel requires async */
-export {};

package/ai/genkit/tests/multi-region.test.js

@@ -1,179 +0,0 @@
-/** biome-ignore-all lint/suspicious/useAwait: defineModel requires async */
-import { genkit, GenkitError, z } from 'genkit';
-import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
-import { CircuitBreakerState } from '../../../circuit-breaker/index.js';
-import { CircuitBreakerProvider } from '../../../circuit-breaker/provider.js';
-import { Logger } from '../../../logger/logger.js';
-import { setupIntegrationTest } from '../../../testing/index.js';
-import { vertexAiMultiLocation } from '../multi-region.plugin.js';
-vi.mock('../../../utils/array/index.js', async (importOriginal) => {
-    const actual = await importOriginal();
-    return {
-        ...actual,
-        shuffle: vi.fn((items) => [...items]),
-    };
-});
-vi.mock('@genkit-ai/google-genai', () => ({
-    // biome-ignore lint/style/useNamingConvention: given
-    vertexAI: {
-        model: vi.fn((name) => ({
-            name: `vertexai/${name}`,
-            info: { label: 'mock' },
-            configSchema: z.object({}),
-        })),
-    },
-    // biome-ignore lint/style/useNamingConvention: given
-    googleAI: vi.fn(),
-}));
-describe('Genkit vertexai-multi-location Plugin Tests', () => {
-    let ai;
-    let cbProvider;
-    let logger;
-    beforeAll(async () => {
-        const { injector } = await setupIntegrationTest({ modules: { circuitBreaker: true } });
-        cbProvider = injector.resolve(CircuitBreakerProvider);
-        logger = injector.resolve(Logger, 'Test');
-    });
-    beforeEach(async () => {
-        vi.clearAllMocks();
-        ai = genkit({
-            plugins: [
-                vertexAiMultiLocation({
-                    locations: ['region-1', 'region-2'],
-                    circuitBreakerProvider: cbProvider,
-                    logger,
-                    circuitBreakerConfig: { resetTimeout: 1_000_000, threshold: 1 },
-                }),
-            ],
-        });
-        const config = { threshold: 1, resetTimeout: 1_000_000 };
-        await cbProvider.provide('genkit:vertex-ai:location:region-1', config).recordSuccess();
-        await cbProvider.provide('genkit:vertex-ai:location:region-2', config).recordSuccess();
-        await cbProvider.provide('genkit:vertex-ai:location:cb-fail', config).recordSuccess();
-        await cbProvider.provide('genkit:vertex-ai:location:cb-success', config).recordSuccess();
-    });
-    it('should route to a location successfully', async () => {
-        // Register a mock for the regional model in the registry
-        ai.defineModel({
-            name: 'vertexai/gemini-2.5-flash',
-        }, async (request) => {
-            return {
-                message: {
-                    role: 'model',
-                    content: [{ text: `hello from ${request.config?.location}` }],
-                },
-            };
-        });
-        const response = await ai.generate({
-            model: 'vertexai-multi-location/gemini-2.5-flash',
-            prompt: 'test',
-        });
-        expect(response.text).toContain('hello from');
-    });
-    it('should failover on 429 error', async () => {
-        let callCount = 0;
-        // Overwrite the mock model to fail once
-        ai.defineModel({
-            name: 'vertexai/gemini-2.5-flash',
-        }, async (request) => {
-            callCount++;
-            if (callCount === 1) {
-                throw new GenkitError({ status: 'RESOURCE_EXHAUSTED', message: 'Rate limit exceeded' });
-            }
-            return {
-                message: {
-                    role: 'model',
-                    content: [{ text: `success from ${request.config?.location}` }],
-                },
-            };
-        });
-        const response = await ai.generate({
-            model: 'vertexai-multi-location/gemini-2.5-flash',
-            prompt: 'test',
-        });
-        expect(response.text).toContain('success from');
-        expect(callCount).toBe(2);
-    });
-    it('should trip circuit breaker on 429 and skip location', async () => {
-        const locationToFail = 'cb-fail';
-        const locationToSuccess = 'cb-success';
-        const locations = [locationToFail, locationToSuccess];
-        ai = genkit({
-            plugins: [
-                vertexAiMultiLocation({
-                    locations,
-                    circuitBreakerProvider: cbProvider,
-                    logger,
-                    circuitBreakerConfig: { resetTimeout: 1000000, threshold: 1 },
-                }),
-            ],
-        });
-        ai.defineModel({
-            name: 'vertexai/gemini-2.5-flash',
-        }, async (request) => {
-            if (request.config?.location === locationToFail) {
-                throw new GenkitError({ status: 'RESOURCE_EXHAUSTED', message: 'Rate limit' });
-            }
-            return {
-                message: {
-                    role: 'model',
-                    content: [{ text: `success from ${request.config?.location}` }],
-                },
-            };
-        });
-        // First call to trip the breaker for 'locationToFail'
-        const response1 = await ai.generate({
-            model: 'vertexai-multi-location/gemini-2.5-flash',
-            prompt: 'test',
-        });
-        expect(response1.text).toBe('success from cb-success');
-        const cb = cbProvider.provide(`genkit:vertex-ai:location:${locationToFail}`, { threshold: 1, resetTimeout: 1000000 });
-        const status = await cb.check();
-        expect(status.state).toBe(CircuitBreakerState.Open);
-        expect(status.allowed).toBe(false);
-        // Second call should skip 'locationToFail' automatically
-        const response2 = await ai.generate({
-            model: 'vertexai-multi-location/gemini-2.5-flash',
-            prompt: 'test',
-        });
-        expect(response2.text).toBe('success from cb-success');
-    });
-    it('should throw if no locations are provided', async () => {
-        expect(() => {
-            vertexAiMultiLocation({
-                locations: [],
-                circuitBreakerProvider: cbProvider,
-                logger,
-            });
-        }).toThrow('At least one location must be provided');
-    });
-    it('should throw if all locations are unhealthy', async () => {
-        const ai2 = genkit({
-            plugins: [
-                vertexAiMultiLocation({
-                    locations: ['unhealthy-1'],
-                    circuitBreakerProvider: cbProvider,
-                    logger,
-                    circuitBreakerConfig: { resetTimeout: 1000000, threshold: 1 },
-                }),
-            ],
-        });
-        // Manually trip the circuit breaker
-        const cb = cbProvider.provide('genkit:vertex-ai:location:unhealthy-1', { threshold: 1, resetTimeout: 1000000 });
-        await cb.recordFailure();
-        ai2.defineModel({
-            name: 'vertexai/gemini-2.5-flash',
-        }, async () => {
-            return {
-                message: {
-                    role: 'model',
-                    content: [{ text: 'success' }],
-                },
-            };
-        });
-        await expect(ai2.generate({
-            model: 'vertexai-multi-location/gemini-2.5-flash',
-            prompt: 'test',
-        })).rejects.toThrow('All locations were skipped because they are unhealthy');
-    });
-});

package/ai/genkit/tests/token-limit-fallback.test.d.ts

@@ -1,2 +0,0 @@
-/** biome-ignore-all lint/suspicious/useAwait: defineModel requires async */
-export {};