signalium 1.0.2 → 1.1.0

package/src/hooks.ts

@@ -11,9 +11,10 @@ import {
 import { useDerivedSignal } from './config.js';
 import { getCurrentScope, SignalScope } from './internals/contexts.js';
 import { createStateSignal } from './internals/state.js';
-import { createDerivedSignal } from './internals/derived.js';
+import { createDerivedSignal, DerivedSignalDefinition } from './internals/derived.js';
 import { ReactivePromise } from './internals/async.js';
 import { Tracer } from './trace.js';
+import { equalsFrom } from './internals/utils/equals.js';
 
 export const state = createStateSignal;
 
@@ -29,9 +30,16 @@ export function reactive<T, Args extends unknown[]>(
   fn: (...args: Args) => T,
   opts?: Partial<SignalOptionsWithInit<T, Args>>,
 ): (...args: Args) => ReactiveValue<T> {
+  const def: DerivedSignalDefinition<T, Args> = {
+    compute: fn,
+    equals: equalsFrom(opts?.equals),
+    shouldGC: opts?.shouldGC,
+    isSubscription: false,
+  };
+
   return (...args) => {
     const scope = getCurrentScope();
-    const signal = scope.get(fn as any, args, opts);
+    const signal = scope.get(def, args, opts);
 
     return useDerivedSignal(signal)!;
   };
@@ -64,5 +72,11 @@ export function watcher<T>(
   fn: () => T,
   opts?: SignalOptions<T, unknown[]> & { scope?: SignalScope; tracer?: Tracer },
 ): Signal<ReactiveValue<T>> {
-  return createDerivedSignal(fn, undefined, undefined, opts?.scope, opts);
+  const def: DerivedSignalDefinition<T, unknown[]> = {
+    compute: fn,
+    equals: equalsFrom(opts?.equals),
+    isSubscription: false,
+  };
+
+  return createDerivedSignal(def, undefined, undefined, opts?.scope, opts);
 }

package/src/index.ts

@@ -6,7 +6,14 @@ export { isReactivePromise, isReactiveTask, isReactiveSubscription } from './int
 
 export { callback } from './internals/get.js';
 
-export { createContext, useContext, withContexts, SignalScope, CONTEXT_KEY } from './internals/contexts.js';
+export {
+  createContext,
+  useContext,
+  withContexts,
+  setRootContexts,
+  SignalScope,
+  CONTEXT_KEY,
+} from './internals/contexts.js';
 
 export { setConfig } from './config.js';
 

package/src/internals/async.ts

@@ -8,7 +8,7 @@ import {
   SignalSubscribe,
   SignalSubscription,
 } from '../types.js';
-import { createDerivedSignal, DerivedSignal, SignalState } from './derived.js';
+import { createDerivedSignal, DerivedSignal, DerivedSignalDefinition, SignalState } from './derived.js';
 import { CURRENT_CONSUMER, generatorResultToPromise, getSignal } from './get.js';
 import { dirtySignal, dirtySignalConsumers } from './dirty.js';
 import { scheduleAsyncPull, schedulePull, setResolved } from './scheduling.js';
@@ -17,7 +17,7 @@ import { getCurrentScope, ROOT_SCOPE, SignalScope, withScope } from './contexts.
 import { createStateSignal } from './state.js';
 import { useStateSignal } from '../config.js';
 import { isGeneratorResult, isPromise } from './utils/type-utils.js';
-import { equalsFrom } from './utils/equals.js';
+import { DEFAULT_EQUALS, equalsFrom, FALSE_EQUALS } from './utils/equals.js';
 
 const enum AsyncFlags {
   // ======= Notifiers ========
@@ -72,10 +72,10 @@ export class ReactivePromise<T, Args extends unknown[] = unknown[]> implements B
   private _boundRun: ((...args: Args) => ReactivePromise<T, Args>) | undefined;
 
   static createPromise<T>(promise: Promise<T>, signal?: DerivedSignal<T, unknown[]>, initValue?: T | undefined) {
-    const p = new ReactivePromise();
+    const p = new ReactivePromise<T>();
 
     p._signal = signal;
-    p._equals = signal?.equals ?? ((a, b) => a === b);
+    p._equals = signal?.def.equals ?? DEFAULT_EQUALS;
 
     p._initFlags(AsyncFlags.Pending, initValue);
 
@@ -130,8 +130,8 @@ export class ReactivePromise<T, Args extends unknown[] = unknown[]> implements B
       },
     };
 
-    p._signal = createDerivedSignal(
-      () => {
+    const def: DerivedSignalDefinition<() => void, unknown[]> = {
+      compute: () => {
         if (active === false) {
           currentSub = subscribe(state);
           active = true;
@@ -144,11 +144,16 @@ export class ReactivePromise<T, Args extends unknown[] = unknown[]> implements B
 
         return unsubscribe;
       },
+      equals: DEFAULT_EQUALS,
+      isSubscription: true,
+    };
+
+    p._signal = createDerivedSignal<() => void, unknown[]>(
+      def,
       [],
       undefined,
       scope,
-      opts as Omit<SignalOptionsWithInit<T, unknown[]>, 'equals' | 'initValue' | 'paramKey'>,
-      true,
+      opts as Omit<SignalOptionsWithInit<T, unknown[]>, 'equals' | 'initValue' | 'paramKey' | 'shouldGC'>,
     );
 
     p._equals = equalsFrom(opts?.equals);

package/src/internals/connect.ts

@@ -10,6 +10,9 @@ export function watchSignal(signal: DerivedSignal<any, any>): void {
   // If > 0, already watching, return
   if (watchCount > 0) return;
 
+  // If signal is being watched again, remove from GC candidates
+  signal.scope?.removeFromGc(signal);
+
   for (const dep of signal.deps.keys()) {
     watchSignal(dep);
   }
@@ -38,4 +41,9 @@ export function unwatchSignal(signal: DerivedSignal<any, any>, count = 1) {
     // teardown the subscription
     signal.value?.();
   }
+
+  // If watchCount is now zero, mark the signal for GC
+  if (newWatchCount === 0 && signal.scope) {
+    signal.scope.markForGc(signal);
+  }
 }

package/src/internals/contexts.ts

@@ -1,8 +1,9 @@
 import { getFrameworkScope } from '../config.js';
 import { SignalOptionsWithInit } from '../types.js';
-import { DerivedSignal, createDerivedSignal } from './derived.js';
+import { DerivedSignal, DerivedSignalDefinition, createDerivedSignal } from './derived.js';
 import { CURRENT_CONSUMER } from './get.js';
 import { hashReactiveFn, hashValue } from './utils/hash.js';
+import { scheduleGcSweep } from './scheduling.js';
 
 export const CONTEXT_KEY = Symbol('signalium:context');
 
@@ -46,7 +47,8 @@ export class SignalScope {
   private parentScope?: SignalScope = undefined;
   private contexts: Record<symbol, unknown>;
   private children = new Map<number, SignalScope>();
-  private signals = new Map<number, DerivedSignal<any, any[]>>();
+  private signals = new Map<number, DerivedSignal<any, any>>();
+  private gcCandidates = new Set<DerivedSignal<any, any>>();
 
   getChild(contexts: [ContextImpl<unknown>, unknown][]) {
     const key = hashValue(contexts);
@@ -68,25 +70,58 @@ export class SignalScope {
   }
 
   get<T, Args extends unknown[]>(
-    fn: (...args: Args) => T,
+    def: DerivedSignalDefinition<T, Args>,
     args: Args,
     opts?: Partial<SignalOptionsWithInit<T, Args>>,
   ): DerivedSignal<T, Args> {
     const paramKey = opts?.paramKey?.(...args);
-    const key = hashReactiveFn(fn, paramKey ? [paramKey] : args);
+    const key = hashReactiveFn(def.compute, paramKey ? [paramKey] : args);
     let signal = this.signals.get(key) as DerivedSignal<T, Args> | undefined;
 
     if (signal === undefined) {
-      signal = createDerivedSignal(fn, args, key, this, opts);
+      signal = createDerivedSignal(def, args, key, this, opts);
       this.signals.set(key, signal);
     }
 
     return signal;
   }
+
+  markForGc(signal: DerivedSignal<any, any>) {
+    if (!this.gcCandidates.has(signal)) {
+      this.gcCandidates.add(signal);
+      scheduleGcSweep(this);
+    }
+  }
+
+  removeFromGc(signal: DerivedSignal<any, any>) {
+    this.gcCandidates.delete(signal);
+  }
+
+  forceGc(signal: DerivedSignal<any, any>) {
+    this.signals.delete(signal.key!);
+  }
+
+  sweepGc() {
+    for (const signal of this.gcCandidates) {
+      if (signal.watchCount === 0) {
+        const { shouldGC } = signal.def;
+
+        if (!shouldGC || shouldGC(signal, signal.value, signal.args)) {
+          this.signals.delete(signal.key!);
+        }
+      }
+    }
+
+    this.gcCandidates = new Set();
+  }
 }
 
 export let ROOT_SCOPE = new SignalScope([]);
 
+export function setRootContexts<C extends unknown[], U>(contexts: [...ContextPair<C>]): void {
+  ROOT_SCOPE = new SignalScope(contexts as [ContextImpl<unknown>, unknown][], ROOT_SCOPE);
+}
+
 export const clearRootScope = () => {
   ROOT_SCOPE = new SignalScope([]);
 };
@@ -131,3 +166,8 @@ export const useContext = <T>(context: Context<T>): T => {
 
   return scope.getContext(context) ?? (context as unknown as ContextImpl<T>).defaultValue;
 };
+
+export function forceGc(_signal: object) {
+  const signal = _signal as DerivedSignal<any, any>;
+  signal.scope?.forceGc(signal);
+}

package/src/internals/derived.ts

@@ -3,12 +3,11 @@ import { Tracer, TRACER, TracerMeta } from '../trace.js';
 import { ReactiveValue, Signal, SignalEquals, SignalListener, SignalOptionsWithInit } from '../types.js';
 import { getUnknownSignalFnName } from './utils/debug-name.js';
 import { SignalScope } from './contexts.js';
-import { checkAndRunListeners, getSignal } from './get.js';
-import { Edge, EdgeType, SignalEdge } from './edge.js';
+import { getSignal } from './get.js';
+import { Edge } from './edge.js';
 import { schedulePull, scheduleUnwatch } from './scheduling.js';
 import { hashValue } from './utils/hash.js';
 import { stringifyValue } from './utils/stringify.js';
-import { equalsFrom } from './utils/equals.js';
 
 /**
  * This file contains computed signal base types and struct definitions.
@@ -52,6 +51,17 @@ interface ListenerMeta {
   cachedBoundAdd: (listener: SignalListener) => () => void;
 }
 
+/**
+ * Shared definition for derived signals to reduce memory usage.
+ * Contains configuration that's common across all instances of a reactive function.
+ */
+export interface DerivedSignalDefinition<T, Args extends unknown[]> {
+  compute: (...args: Args) => T;
+  equals: SignalEquals<T>;
+  shouldGC?: (signal: object, value: T, args: Args) => boolean;
+  isSubscription: boolean;
+}
+
 export class DerivedSignal<T, Args extends unknown[]> implements Signal<ReactiveValue<T>> {
   // Bitmask containing state in the first 2 bits and boolean properties in the remaining bits
   private flags: number;
@@ -62,7 +72,6 @@ export class DerivedSignal<T, Args extends unknown[]> implements Signal<Reactive
 
   ref: WeakRef<DerivedSignal<T, Args>> = new WeakRef(this);
 
-  equals: SignalEquals<any>;
   dirtyHead: Edge | undefined = undefined;
 
   updatedCount: number = 0;
@@ -72,32 +81,33 @@ export class DerivedSignal<T, Args extends unknown[]> implements Signal<Reactive
 
   _listeners: ListenerMeta | null = null;
 
-  compute: (...args: Args) => T;
+  key: SignalId | undefined;
   args: Args;
   value: ReactiveValue<T> | undefined;
 
   tracerMeta?: TracerMeta;
 
+  // Reference to the shared definition
+  def: DerivedSignalDefinition<T, Args>;
+
   constructor(
-    isSubscription: boolean,
-    compute: (...args: Args) => T,
+    definition: DerivedSignalDefinition<T, Args>,
     args: Args,
     key?: SignalId,
     scope?: SignalScope,
     opts?: Partial<SignalOptionsWithInit<T, Args>> & { tracer?: Tracer },
   ) {
-    this.flags = (isSubscription ? SignalFlags.isSubscription : 0) | SignalState.Dirty;
+    this.flags = (definition.isSubscription ? SignalFlags.isSubscription : 0) | SignalState.Dirty;
     this.scope = scope;
-    this.compute = compute;
+    this.key = key;
     this.args = args;
-
-    this.equals = equalsFrom(opts?.equals);
+    this.def = definition;
     this.value = opts?.initValue as ReactiveValue<T>;
 
     if (TRACER) {
       this.tracerMeta = {
-        id: opts?.id ?? key ?? hashValue([compute, ID++]),
-        desc: opts?.desc ?? compute.name ?? getUnknownSignalFnName(compute),
+        id: opts?.id ?? key ?? hashValue([definition.compute, ID++]),
+        desc: opts?.desc ?? definition.compute.name ?? getUnknownSignalFnName(definition.compute),
         params: args.map(arg => stringifyValue(arg)).join(', '),
         tracer: opts?.tracer,
       };
@@ -197,12 +207,11 @@ export const isSubscription = (signal: unknown): boolean => {
 };
 
 export function createDerivedSignal<T, Args extends unknown[]>(
-  compute: (...args: Args) => T,
+  def: DerivedSignalDefinition<T, Args>,
   args: Args = [] as any,
   key?: SignalId,
   scope?: SignalScope,
   opts?: Partial<SignalOptionsWithInit<T, Args>> & { tracer?: Tracer },
-  isSubscription: boolean = false,
 ): DerivedSignal<T, Args> {
-  return new DerivedSignal(isSubscription, compute, args, key, scope, opts);
+  return new DerivedSignal(def, args, key, scope, opts);
 }

package/src/internals/get.ts

@@ -128,7 +128,7 @@ export function runSignal(signal: DerivedSignal<any, any[]>) {
 
     const initialized = updatedCount !== 0;
     const prevValue = signal.value;
-    let nextValue = signal.compute(...signal.args);
+    let nextValue = signal.def.compute(...signal.args);
     let valueIsPromise = false;
 
     if (nextValue !== null && typeof nextValue === 'object') {
@@ -177,7 +177,7 @@ export function runSignal(signal: DerivedSignal<any, any[]>) {
         signal.value = ReactivePromise.createPromise(nextValue, signal, initValue);
         signal.updatedCount = updatedCount + 1;
       }
-    } else if (!initialized || !signal.equals(prevValue!, nextValue)) {
+    } else if (!initialized || !signal.def.equals(prevValue!, nextValue)) {
       signal.value = nextValue;
       signal.updatedCount = updatedCount + 1;
     }

package/src/internals/scheduling.ts

@@ -6,6 +6,11 @@ import { runListeners as runStateListeners } from './state.js';
 import { Tracer } from '../trace.js';
 import { unwatchSignal } from './connect.js';
 import { StateSignal } from './state.js';
+import { ROOT_SCOPE, SignalScope } from './contexts.js';
+
+// Determine once at startup which scheduling function to use for GC
+const scheduleIdleCallback =
+  typeof requestIdleCallback === 'function' ? requestIdleCallback : (cb: () => void) => _scheduleFlush(cb);
 
 let PROMISE_WAS_RESOLVED = false;
 
@@ -14,6 +19,7 @@ let PENDING_ASYNC_PULLS: DerivedSignal<any, any>[] = [];
 let PENDING_UNWATCH = new Map<DerivedSignal<any, any>, number>();
 let PENDING_LISTENERS: (DerivedSignal<any, any> | StateSignal<any>)[] = [];
 let PENDING_TRACERS: Tracer[] = [];
+let PENDING_GC = new Set<SignalScope>();
 
 const microtask = () => Promise.resolve();
 
@@ -62,6 +68,20 @@ export const scheduleTracer = (tracer: Tracer) => {
   scheduleFlush(flushWatchers);
 };
 
+export const scheduleGcSweep = (scope: SignalScope) => {
+  PENDING_GC.add(scope);
+
+  if (PENDING_GC.size > 1) return;
+
+  scheduleIdleCallback(() => {
+    for (const scope of PENDING_GC) {
+      scope.sweepGc();
+    }
+
+    PENDING_GC.clear();
+  });
+};
+
 const flushWatchers = async () => {
   const flush = currentFlush!;
 

package/src/internals/state.ts

@@ -1,6 +1,6 @@
 import { TRACER as TRACER, TracerEventType } from '../trace.js';
-import { ReactiveValue, SignalEquals, SignalListener, SignalOptions, WriteableSignal } from '../types.js';
-import { DerivedSignal, SignalState } from './derived.js';
+import { SignalEquals, SignalListener, SignalOptions, StateSignal as IStateSignal } from '../types.js';
+import { DerivedSignal } from './derived.js';
 import { dirtySignal } from './dirty.js';
 import { CURRENT_CONSUMER } from './get.js';
 import { useStateSignal } from '../config.js';
@@ -8,7 +8,7 @@ import { scheduleListeners } from './scheduling.js';
 
 let STATE_ID = 0;
 
-export class StateSignal<T> implements WriteableSignal<T> {
+export class StateSignal<T> implements IStateSignal<T> {
   private _value: T;
   private _equals: SignalEquals<T>;
   private _subs = new Map<WeakRef<DerivedSignal<unknown, unknown[]>>, number>();

package/src/internals/utils/equals.ts

@@ -1,7 +1,7 @@
 import { SignalEquals } from '../../types.js';
 
-const DEFAULT_EQUALS: SignalEquals<unknown> = (a, b) => a === b;
-const FALSE_EQUALS: SignalEquals<unknown> = () => false;
+export const DEFAULT_EQUALS: SignalEquals<unknown> = (a, b) => a === b;
+export const FALSE_EQUALS: SignalEquals<unknown> = () => false;
 
 export const equalsFrom = <T>(equals: SignalEquals<T> | false | undefined): SignalEquals<T> => {
   if (equals === false) {

package/src/react/__tests__/contexts.test.tsx

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'vitest';
 import { render } from 'vitest-browser-react';
 import { state, reactive, createContext, useContext } from 'signalium';
-import { ContextProvider, setupReact } from '../index.js';
+import { ContextProvider, setupReact, useScope } from '../index.js';
 import React, { useState } from 'react';
 
 setupReact();
@@ -96,4 +96,23 @@ describe('React > contexts', () => {
 
     await expect.element(getByText('Hi, World')).toBeInTheDocument();
   });
+
+  test('useScope returns undefined outside of rendering context', async () => {
+    // Direct call outside of rendering should return undefined
+    expect(useScope()).toBeUndefined();
+
+    // Inside a component during rendering, it should return the scope
+    function TestComponent() {
+      const scope = useScope();
+      return <div data-testid="scope">{scope ? 'has-scope' : 'no-scope'}</div>;
+    }
+
+    const { getByTestId } = render(
+      <ContextProvider contexts={[]}>
+        <TestComponent />
+      </ContextProvider>,
+    );
+
+    await expect.element(getByTestId('scope')).toHaveTextContent('has-scope');
+  });
 });

package/src/react/context.ts

@@ -1,8 +1,14 @@
 import { createContext, useContext } from 'react';
 import { SignalScope } from '../internals/contexts.js';
+import { isRendering } from './rendering.js';
 
 export const ScopeContext = createContext<SignalScope | undefined>(undefined);
 
 export function useScope() {
+  if (!isRendering()) {
+    return undefined;
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   return useContext(ScopeContext);
 }

package/src/react/provider.tsx

@@ -13,12 +13,6 @@ export function ContextProvider<C extends unknown[]>({
   inherit?: boolean;
   root?: boolean;
 }) {
-  // if (root) {
-  //   useEffect(() => )
-
-  //   return <ScopeContext.Provider value={scope}>{children}</ScopeContext.Provider>;
-  // }
-
   const parentScope = useContext(ScopeContext);
   const scope = new SignalScope(contexts as [ContextImpl<unknown>, unknown][], inherit ? parentScope : undefined);
 

package/src/react/rendering.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+
+// This is a private React internal that we need to access to check if we are rendering.
+// There is no other consistent way to check if we are rendering in both development
+// and production, and it doesn't appear that the React team wants to add one. This
+// should be checked on every major React version upgrade.
+const REACT_INTERNALS =
+  (React as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED ||
+  (React as any).__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ||
+  (React as any).__SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+
+const IS_REACT_18 = !!REACT_INTERNALS.ReactCurrentDispatcher;
+const ReactCurrentDispatcher = REACT_INTERNALS.ReactCurrentDispatcher || REACT_INTERNALS;
+
+export function isRendering() {
+  const dispatcher = IS_REACT_18 ? ReactCurrentDispatcher.current : ReactCurrentDispatcher.H;
+
+  return (
+    !!dispatcher &&
+    // dispatcher can be in a state where it's defined, but all hooks are invalid to call.
+    // Only way we can tell is that if they are invalid, they will all be equal to each other
+    // (e.g. because it's the function that throws an error)
+    dispatcher.useState !== dispatcher.useEffect
+  );
+}

package/src/react/signal-value.ts

@@ -1,34 +1,11 @@
 /* eslint-disable react-hooks/rules-of-hooks */
-import React, { useCallback, useSyncExternalStore } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
 import type { DerivedSignal } from '../internals/derived.js';
 import type { StateSignal } from '../internals/state.js';
 import type { ReactiveValue } from '../types.js';
 import { isReactivePromise } from '../internals/utils/type-utils.js';
 import { isReactiveSubscription } from '../internals/async.js';
-
-// This is a private React internal that we need to access to check if we are rendering.
-// There is no other consistent way to check if we are rendering in both development
-// and production, and it doesn't appear that the React team wants to add one. This
-// should be checked on every major React version upgrade.
-const REACT_INTERNALS =
-  (React as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED ||
-  (React as any).__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ||
-  (React as any).__SERVER_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
-
-const IS_REACT_18 = !!REACT_INTERNALS.ReactCurrentDispatcher;
-const ReactCurrentDispatcher = REACT_INTERNALS.ReactCurrentDispatcher || REACT_INTERNALS;
-
-function isRendering() {
-  const dispatcher = IS_REACT_18 ? ReactCurrentDispatcher.current : ReactCurrentDispatcher.H;
-
-  return (
-    !!dispatcher &&
-    // dispatcher can be in a state where it's defined, but all hooks are invalid to call.
-    // Only way we can tell is that if they are invalid, they will all be equal to each other
-    // (e.g. because it's the function that throws an error)
-    dispatcher.useState !== dispatcher.useEffect
-  );
-}
+import { isRendering } from './rendering.js';
 
 export function useStateSignal<T>(signal: StateSignal<T>): T {
   if (!isRendering()) {
@@ -42,7 +19,7 @@ export function useStateSignal<T>(signal: StateSignal<T>): T {
   );
 }
 
-export function useDerivedSignal<T>(signal: DerivedSignal<T, unknown[]>): ReactiveValue<T> {
+export function useDerivedSignal<T, Args extends unknown[]>(signal: DerivedSignal<T, Args>): ReactiveValue<T> {
   if (!isRendering()) {
     return signal.get();
   }

package/src/react/state.ts

@@ -1,9 +1,9 @@
 import { useRef } from 'react';
 import { state } from '../hooks.js';
-import { SignalOptions, WriteableSignal } from '../types.js';
+import { SignalOptions, StateSignal } from '../types.js';
 
-export function useStateSignal<T>(value: T, opts?: SignalOptions<T, unknown[]>): WriteableSignal<T> {
-  const ref = useRef<WriteableSignal<T> | undefined>(undefined);
+export function useStateSignal<T>(value: T, opts?: SignalOptions<T, unknown[]>): StateSignal<T> {
+  const ref = useRef<StateSignal<T> | undefined>(undefined);
 
   if (!ref.current) {
     ref.current = state(value, opts);

package/src/types.ts

@@ -5,10 +5,17 @@ export interface Signal<T = unknown> {
   addListener(listener: SignalListener): () => void;
 }
 
-export interface WriteableSignal<T> extends Signal<T> {
+export interface StateSignal<T> extends Signal<T> {
   set(value: T): void;
+  peek(): T;
+  update(updater: (value: T) => T): void;
 }
 
+/**
+ * @deprecated Use `StateSignal` instead.
+ */
+export type WriteableSignal<T> = StateSignal<T>;
+
 export type SignalEquals<T> = (prev: T, next: T) => boolean;
 
 export type SignalListener = () => void;
@@ -34,6 +41,13 @@ export interface SignalOptions<T, Args extends unknown[]> {
   desc?: string;
   scope?: SignalScope;
   paramKey?: (...args: Args) => string;
+
+  /**
+   * Called when signal's watchCount reaches 0.
+   * Return `true` to allow GC, `false` to prevent it.
+   * If not provided, defaults to always allowing GC.
+   */
+  shouldGC?: (signal: object, value: T, args: Args) => boolean;
 }
 
 export interface SignalOptionsWithInit<T, Args extends unknown[]> extends SignalOptions<T, Args> {