signalium 0.3.8 → 1.0.0

package/src/internals/contexts.ts

@@ -0,0 +1,133 @@
+import { getFrameworkScope } from '../config.js';
+import { SignalOptionsWithInit } from '../types.js';
+import { DerivedSignal, createDerivedSignal } from './derived.js';
+import { CURRENT_CONSUMER } from './get.js';
+import { hashReactiveFn, hashValue } from './utils/hash.js';
+
+export const CONTEXT_KEY = Symbol('signalium:context');
+
+export type Context<T> = {
+  defaultValue: T;
+};
+
+export type ContextPair<T extends unknown[]> = {
+  [K in keyof T]: [Context<T[K]>, NoInfer<T[K]>];
+};
+
+let CONTEXT_ID = 0;
+
+export class ContextImpl<T> {
+  _key: symbol;
+  _description: string;
+
+  constructor(
+    public readonly defaultValue: T,
+    desc?: string,
+  ) {
+    this._description = desc ?? `context:${CONTEXT_ID++}`;
+    this._key = Symbol(this._description);
+  }
+}
+
+export const createContext = <T>(initialValue: T, description?: string): Context<T> => {
+  return new ContextImpl(initialValue, description);
+};
+
+export class SignalScope {
+  constructor(contexts: [ContextImpl<unknown>, unknown][], parent?: SignalScope) {
+    this.parentScope = parent;
+    this.contexts = Object.create(parent?.contexts || null);
+
+    for (const [context, value] of contexts) {
+      this.contexts[context._key] = value;
+    }
+  }
+
+  private parentScope?: SignalScope = undefined;
+  private contexts: Record<symbol, unknown>;
+  private children = new Map<number, SignalScope>();
+  private signals = new Map<number, DerivedSignal<any, any[]>>();
+
+  getChild(contexts: [ContextImpl<unknown>, unknown][]) {
+    const key = hashValue(contexts);
+
+    let child = this.children.get(key);
+
+    if (child === undefined) {
+      child = new SignalScope(contexts, this);
+      this.children.set(key, child);
+    }
+
+    return child;
+  }
+
+  getContext<T>(_context: Context<T>): T | undefined {
+    const context = _context as unknown as ContextImpl<T>;
+
+    return this.contexts[context._key] as T | undefined;
+  }
+
+  get<T, Args extends unknown[]>(
+    fn: (...args: Args) => T,
+    args: Args,
+    opts?: Partial<SignalOptionsWithInit<T, Args>>,
+  ): DerivedSignal<T, Args> {
+    const paramKey = opts?.paramKey?.(...args);
+    const key = hashReactiveFn(fn, paramKey ? [paramKey] : args);
+    let signal = this.signals.get(key) as DerivedSignal<T, Args> | undefined;
+
+    if (signal === undefined) {
+      signal = createDerivedSignal(fn, args, key, this, opts);
+      this.signals.set(key, signal);
+    }
+
+    return signal;
+  }
+}
+
+export let ROOT_SCOPE = new SignalScope([]);
+
+export const clearRootScope = () => {
+  ROOT_SCOPE = new SignalScope([]);
+};
+
+let OVERRIDE_SCOPE: SignalScope | undefined;
+
+export const getCurrentScope = (): SignalScope => {
+  return OVERRIDE_SCOPE ?? CURRENT_CONSUMER?.scope ?? getFrameworkScope() ?? ROOT_SCOPE;
+};
+
+export function withContexts<C extends unknown[], U>(contexts: [...ContextPair<C>], fn: () => U): U {
+  const prevScope = OVERRIDE_SCOPE;
+  const currentScope = getCurrentScope();
+
+  try {
+    OVERRIDE_SCOPE = currentScope.getChild(contexts as [ContextImpl<unknown>, unknown][]);
+    return fn();
+  } finally {
+    OVERRIDE_SCOPE = prevScope;
+  }
+}
+
+export const withScope = <T>(scope: SignalScope, fn: () => T) => {
+  const prevScope = OVERRIDE_SCOPE;
+
+  try {
+    OVERRIDE_SCOPE = scope;
+    return fn();
+  } finally {
+    OVERRIDE_SCOPE = prevScope;
+  }
+};
+
+export const useContext = <T>(context: Context<T>): T => {
+  const scope = OVERRIDE_SCOPE ?? CURRENT_CONSUMER?.scope ?? getFrameworkScope();
+
+  if (scope === undefined) {
+    throw new Error(
+      'useContext must be used within a signal hook, a withContext, or within a framework-specific context provider.',
+    );
+  }
+
+  return scope.getContext(context) ?? (context as unknown as ContextImpl<T>).defaultValue;
+};

package/src/internals/derived.ts

@@ -0,0 +1,208 @@
+import WeakRef from '../weakref.js';
+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 { 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.
+ *
+ * Computed signals are monomorphic to make them more efficient, but this also
+ * means that multiple fields differ based on the type of the signal. Defining
+ * them using this pattern rather than a class allows us to switch on the `type`
+ * field to get strong typing in branches everywhere else.
+ *
+ * "Methods" for this struct are defined in other files for better organization.
+ */
+
+export type SignalId = number;
+
+export const enum SignalState {
+  Clean = 0,
+  Pending = 1,
+  Dirty = 2,
+  MaybeDirty = 3,
+}
+
+export const enum SignalFlags {
+  // State
+  State = 0b11,
+
+  // Properties
+  isSubscription = 0b100,
+  isListener = 0b1000,
+}
+
+let ID = 0;
+
+interface ListenerMeta {
+  updatedAt: number;
+  current: Set<SignalListener>;
+
+  // Cached bound add method to avoid creating a new one on each call, this is
+  // specifically for React hooks where useSyncExternalStore will resubscribe each
+  // time if the method is not cached. This prevents us from having to add a
+  // useCallback for the listener.
+  cachedBoundAdd: (listener: SignalListener) => () => void;
+}
+
+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;
+  scope: SignalScope | undefined = undefined;
+
+  subs = new Map<WeakRef<DerivedSignal<any, any>>, Edge>();
+  deps = new Map<DerivedSignal<any, any>, Edge>();
+
+  ref: WeakRef<DerivedSignal<T, Args>> = new WeakRef(this);
+
+  equals: SignalEquals<any>;
+  dirtyHead: Edge | undefined = undefined;
+
+  updatedCount: number = 0;
+  computedCount: number = 0;
+
+  watchCount: number = 0;
+
+  _listeners: ListenerMeta | null = null;
+
+  compute: (...args: Args) => T;
+  args: Args;
+  value: ReactiveValue<T> | undefined;
+
+  tracerMeta?: TracerMeta;
+
+  constructor(
+    isSubscription: boolean,
+    compute: (...args: Args) => T,
+    args: Args,
+    key?: SignalId,
+    scope?: SignalScope,
+    opts?: Partial<SignalOptionsWithInit<T, Args>> & { tracer?: Tracer },
+  ) {
+    this.flags = (isSubscription ? SignalFlags.isSubscription : 0) | SignalState.Dirty;
+    this.scope = scope;
+    this.compute = compute;
+    this.args = args;
+
+    this.equals = equalsFrom(opts?.equals);
+    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),
+        params: args.map(arg => stringifyValue(arg)).join(', '),
+        tracer: opts?.tracer,
+      };
+    }
+  }
+
+  get _state() {
+    return this.flags & SignalFlags.State;
+  }
+
+  set _state(state: SignalState) {
+    this.flags = (this.flags & ~SignalFlags.State) | state;
+  }
+
+  get _isListener() {
+    return (this.flags & SignalFlags.isListener) !== 0;
+  }
+
+  set _isListener(isListener: boolean) {
+    if (isListener) {
+      this.flags |= SignalFlags.isListener;
+    } else {
+      this.flags &= ~SignalFlags.isListener;
+    }
+  }
+
+  get listeners() {
+    return (
+      this._listeners ??
+      (this._listeners = {
+        updatedAt: 0,
+        current: new Set(),
+        cachedBoundAdd: this.addListener.bind(this),
+      })
+    );
+  }
+
+  get(): ReactiveValue<T> {
+    return getSignal(this);
+  }
+
+  addListener(listener: SignalListener) {
+    const { current } = this.listeners;
+
+    if (!current.has(listener)) {
+      if (!this._isListener) {
+        this.watchCount++;
+        this.flags |= SignalFlags.isListener;
+      }
+
+      schedulePull(this);
+
+      current.add(listener);
+    }
+
+    return () => {
+      if (current.has(listener)) {
+        current.delete(listener);
+
+        if (current.size === 0) {
+          scheduleUnwatch(this);
+          this.flags &= ~SignalFlags.isListener;
+        }
+      }
+    };
+  }
+
+  // This method is used in React hooks specifically. It returns a bound add method
+  // that is cached to avoid creating a new one on each call, and it eagerly sets
+  // the listener as watched so that subscriptions that are accessed will be activated.
+  addListenerLazy() {
+    if (!this._isListener) {
+      this.watchCount++;
+      this.flags |= SignalFlags.isListener;
+    }
+
+    return this.listeners.cachedBoundAdd;
+  }
+}
+
+export const runListeners = (signal: DerivedSignal<any, any>) => {
+  const { listeners } = signal;
+
+  if (listeners === null) {
+    return;
+  }
+
+  const { current } = listeners;
+
+  for (const listener of current) {
+    listener();
+  }
+};
+
+export const isSubscription = (signal: unknown): boolean => {
+  return ((signal as any).flags & SignalFlags.isSubscription) !== 0;
+};
+
+export function createDerivedSignal<T, Args extends unknown[]>(
+  compute: (...args: Args) => T,
+  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);
+}

package/src/internals/dirty.ts

@@ -0,0 +1,91 @@
+import { scheduleAsyncPull, schedulePull } from './scheduling.js';
+import { DerivedSignal, isSubscription, SignalState } from './derived.js';
+import { CURRENT_CONSUMER } from './get.js';
+import { Edge } from './edge.js';
+
+export function dirtySignal(signal: DerivedSignal<any, any>) {
+  const prevState = signal._state;
+
+  if (prevState === SignalState.Dirty) {
+    return;
+  }
+
+  signal._state = SignalState.Dirty;
+
+  if (prevState !== SignalState.MaybeDirty) {
+    propagateDirty(signal);
+  }
+}
+
+function propagateDirty(signal: DerivedSignal<any, any>) {
+  if (CURRENT_CONSUMER === signal) {
+    throw new Error(
+      'A signal was dirtied after it was consumed by the current function. This can cause race conditions and infinite rerenders and is not allowed.',
+    );
+  }
+
+  if (isSubscription(signal)) {
+    if (signal.watchCount > 0) {
+      scheduleAsyncPull(signal);
+    }
+
+    // else do nothing, only schedule if connected
+  } else {
+    if (signal._isListener) {
+      schedulePull(signal);
+    }
+
+    dirtySignalConsumers(signal.subs);
+    signal.subs = new Map();
+  }
+}
+
+export function dirtySignalConsumers(map: Map<WeakRef<DerivedSignal<any, any>>, Edge>) {
+  for (const [subRef, edge] of map) {
+    const sub = subRef.deref();
+
+    if (sub === undefined || sub.computedCount !== edge.consumedAt) continue;
+
+    const dirtyState = sub._state;
+
+    switch (dirtyState) {
+      case SignalState.Clean:
+        sub._state = SignalState.MaybeDirty;
+        sub.dirtyHead = edge;
+        edge.nextDirty = undefined;
+        propagateDirty(sub);
+        break;
+
+      case SignalState.Pending:
+      case SignalState.MaybeDirty: {
+        let subEdge = sub.dirtyHead!;
+        const ord = edge.ord;
+
+        if (subEdge.ord > ord) {
+          sub.dirtyHead = edge;
+          edge.nextDirty = subEdge;
+
+          if (dirtyState === SignalState.Pending) {
+            // If the signal is pending, the first edge is the halt edge. If the
+            // new dirty edge is BEFORE the halt edge, then it means that something
+            // changed before the current halt, so we need to cancel the current computation
+            // and recompute.
+            sub._state = SignalState.MaybeDirty;
+            propagateDirty(sub);
+          }
+        } else {
+          let nextDirty = subEdge.nextDirty;
+
+          while (nextDirty !== undefined && nextDirty.ord < ord) {
+            subEdge = nextDirty;
+            nextDirty = subEdge.nextDirty;
+          }
+
+          edge.nextDirty = nextDirty;
+          subEdge!.nextDirty = edge;
+        }
+        break;
+      }
+    }
+  }
+}

package/src/internals/edge.ts

@@ -0,0 +1,109 @@
+import { ReactivePromise } from './async.js';
+import type { DerivedSignal } from './derived.js';
+
+let CURRENT_ORD = 0;
+
+export const enum EdgeType {
+  Signal = 0,
+  Promise = 1,
+}
+
+export interface EdgeTypeDep {
+  [EdgeType.Signal]: DerivedSignal<any, any>;
+  [EdgeType.Promise]: ReactivePromise<any>;
+}
+
+interface BaseEdge {
+  type: EdgeType;
+  dep: EdgeTypeDep[EdgeType];
+  ord: number;
+  updatedAt: number;
+  consumedAt: number;
+
+  nextDirty: Edge | undefined;
+}
+
+export interface SignalEdge extends BaseEdge {
+  type: EdgeType.Signal;
+  dep: DerivedSignal<any, any>;
+}
+
+export interface PromiseEdge extends BaseEdge {
+  type: EdgeType.Promise;
+  dep: ReactivePromise<any>;
+}
+
+export type Edge = SignalEdge | PromiseEdge;
+
+export function createEdge<T extends EdgeType, R extends T extends EdgeType.Signal ? SignalEdge : PromiseEdge>(
+  prevEdge: Edge | undefined,
+  type: T,
+  dep: EdgeTypeDep[T],
+  updatedAt: number,
+  consumedAt: number,
+): R {
+  if (prevEdge === undefined) {
+    return {
+      type,
+      dep,
+      ord: CURRENT_ORD++,
+      updatedAt,
+      consumedAt,
+      nextDirty: undefined,
+    } as R;
+  }
+
+  prevEdge.ord = CURRENT_ORD++;
+  prevEdge.updatedAt = updatedAt;
+  prevEdge.consumedAt = consumedAt;
+  prevEdge.nextDirty = undefined;
+  return prevEdge as R;
+}
+
+export function insertDirty(node: DerivedSignal<any, any>, edge: Edge) {
+  const ord = edge.ord;
+  let currentEdge = node.dirtyHead;
+
+  if (currentEdge === undefined || currentEdge.ord > ord) {
+    node.dirtyHead = edge;
+  } else {
+    let nextEdge = currentEdge.nextDirty;
+
+    while (nextEdge !== undefined && nextEdge.ord < ord) {
+      currentEdge = nextEdge;
+      nextEdge = currentEdge.nextDirty;
+    }
+
+    currentEdge.nextDirty = edge;
+  }
+}
+
+export function findAndRemoveDirty(
+  sub: DerivedSignal<any, any>,
+  dep: DerivedSignal<any, any> | ReactivePromise<any>,
+): Edge | undefined {
+  let edge = sub.dirtyHead;
+
+  if (edge === undefined) {
+    return undefined;
+  }
+
+  if (edge.dep === dep) {
+    sub.dirtyHead = edge.nextDirty;
+    return edge;
+  }
+
+  let nextLink = edge.nextDirty;
+
+  while (nextLink !== undefined) {
+    if (nextLink.dep === dep) {
+      edge.nextDirty = nextLink.nextDirty;
+      return nextLink;
+    }
+
+    edge = nextLink;
+    nextLink = edge.nextDirty;
+  }
+
+  return undefined;
+}