signalium 1.0.2 → 1.1.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 { state, reactive, createContext, useContext, setRootContexts } from '../../index.js';
+import { ContextProvider, setupReact, useScope } from '../index.js';
 import React, { useState } from 'react';
 
 setupReact();
@@ -49,6 +49,69 @@ describe('React > contexts', () => {
     await expect.element(getByText('Hey, World')).toBeInTheDocument();
   });
 
+  test('provider inherits from root scope', async () => {
+    const defaultValue1 = state('default1');
+    const defaultValue2 = state('default2');
+    const ctx1 = createContext(defaultValue1);
+    const ctx2 = createContext(defaultValue2);
+    const rootOverride1 = state('root1');
+    const rootOverride2 = state('root2');
+
+    // Set root contexts
+    setRootContexts([
+      [ctx1, rootOverride1],
+      [ctx2, rootOverride2],
+    ]);
+
+    // Component that uses both contexts
+    function Component({ testId }: { testId: string }): React.ReactNode {
+      const value1 = useContext(ctx1);
+      const value2 = useContext(ctx2);
+      const derived = reactive(() => `${value1.get()}-${value2.get()}`);
+      return <div data-testid={testId}>{derived()}</div>;
+    }
+    const localOverride1 = state('local1');
+    const localOverride2 = state('local2');
+
+    // Should inherit from root scope when no local overrides
+    const { getByTestId } = render(
+      <>
+        <ContextProvider contexts={[]}>
+          <Component testId="result" />
+        </ContextProvider>
+        <ContextProvider contexts={[[ctx1, localOverride1]]}>
+          <Component testId="result2" />
+        </ContextProvider>
+        <ContextProvider
+          contexts={[
+            [ctx1, localOverride1],
+            [ctx2, localOverride2],
+          ]}
+        >
+          <Component testId="result3" />
+        </ContextProvider>
+      </>,
+    );
+
+    await expect.element(getByTestId('result')).toHaveTextContent('root1-root2');
+
+    // Should inherit from root scope for unoverridden contexts
+    await expect.element(getByTestId('result2')).toHaveTextContent('local1-root2');
+
+    // Should use local overrides when provided
+    await expect.element(getByTestId('result3')).toHaveTextContent('local1-local2');
+
+    // Changes to root contexts should be reflected in inherited contexts
+    rootOverride1.set('updated-root1');
+    rootOverride2.set('updated-root2');
+
+    await expect.element(getByTestId('result')).toHaveTextContent('updated-root1-updated-root2');
+
+    // Local overrides should remain unaffected by root context changes
+    await expect.element(getByTestId('result2')).toHaveTextContent('local1-updated-root2');
+    await expect.element(getByTestId('result3')).toHaveTextContent('local1-local2');
+  });
+
   test('useContext works inside computed value passed via context provider', async () => {
     const value = state('Hello');
     const override = state('Hey');
@@ -96,4 +159,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

@@ -1,25 +1,17 @@
 import { useContext } from 'react';
 import { ScopeContext } from './context.js';
-import { ContextImpl, ContextPair, SignalScope } from '../internals/contexts.js';
+import { ContextImpl, ContextPair, ROOT_SCOPE, SignalScope } from '../internals/contexts.js';
 
 export function ContextProvider<C extends unknown[]>({
   children,
-  contexts,
+  contexts = [],
   inherit = true,
-  root = false,
 }: {
   children: React.ReactNode;
-  contexts: [...ContextPair<C>];
+  contexts?: [...ContextPair<C>] | [];
   inherit?: boolean;
-  root?: boolean;
 }) {
-  // if (root) {
-  //   useEffect(() => )
-
-  //   return <ScopeContext.Provider value={scope}>{children}</ScopeContext.Provider>;
-  // }
-
-  const parentScope = useContext(ScopeContext);
+  const parentScope = useContext(ScopeContext) ?? ROOT_SCOPE;
   const scope = new SignalScope(contexts as [ContextImpl<unknown>, unknown][], inherit ? parentScope : undefined);
 
   return <ScopeContext.Provider value={scope}>{children}</ScopeContext.Provider>;

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> {