/src/signals.ts at v1.0.0

// This module contains Signal, Derived, and Effect implementation.
// This module should not contain any DOM API or Web API.
// This module should work on any JS engine that supports ES2019 or later.

// -- SYMBOLS
// This file uses Symbol as a method and property names in order
// to archive module-level private methods/properties. Symbol-as-a-private-prop
// also has an additional benefit over ES Private Class Fields: JS code emitted
// by tsc does not include ugly polyfill using `WeakMap` and helper functions.
const CHILDREN = Symbol();
const RECIEVE_UPDATE = Symbol();
const DEPENDENCIES = Symbol();

const DEPENDANTS = Symbol();
const IS_DISPOSED = Symbol();

const VALUE = Symbol();

const COMPUTE_FN = Symbol();
const COMPUTE = Symbol();

const EFFECT_FN = Symbol();
const RUN_EFFECT = Symbol();
const CLEANUP_FN = Symbol();

// -- INTERFACES

/**
 * Object with manual lifetime management, in order to clear up references
 * so GC can collect as many.
 */
export interface Disposable {
  /**
   * Computation skip flag.
   */
  [IS_DISPOSED]: boolean;

  /**
   * Dispose (destroy) this object.
   *
   * Although you can still access this object's properties after disposal,
   * updates to this object does not have any effect.
   */
  dispose(): void;
}

/**
 * Computation is a computation function associated to >= 0 Reactives.
 * A computation function of a Computation got re-invoked everytime
 */
export interface Computation extends Disposable {
  /**
   * A set of child Signal/Derived/Effect created inside the computation
   * function of this Computation. This is different to dependency graph used for
   * reactive update notification. The main purpose of this data is to dispose
   * those children when the computation function of this Computation is about to
   * be invoked.
   */
  [CHILDREN]: Set<Disposable>;

  [DEPENDENCIES]: Set<ReactiveValue<any>>;

  /**
   * Re-run a computation function of this Computation.
   */
  [RECIEVE_UPDATE](effectQueue: Set<Effect>): void;
}

/**
 * ReactiveValue is an object that holds a value and be able to notify the changes
 * to the value to the ReactiveValue's dependants.
 */
export interface ReactiveValue<T> {
  /**
   * A set of Disposable Computation that subscribing to this ReactiveValue's changes.
   */
  [DEPENDANTS]: Set<Computation>;

  /**
   * Get the current value of this ReactiveValue.
   *
   * This method associates this ReactiveValue (Signal or Derived) to
   * surrounding Computation (Effect or Derived) in order to re-run Computation
   * when this ReactiveValue changed.
   *
   * @param context - Optinal Computation object. If this presents, the ReactiveValue
   *                  associates to this Computation instead of the surrounding one.
   */
  get(context?: Computation): T;

  /**
   * (as a getter) An alias for `get` method.
   */
  get value(): T;

  /**
   * Get the current value of this ReactiveValue.
   *
   * In contrast to `.get()`, this method does not associate to any Computation.
   */
  once(): T;
}

// -- GLOBALS
// In order to archieve implicit dependency management, some amount of
// global reference is unavoidable, unfortunately.

// Global stack of Computation.
// The purpose of this reference is to automatically track Computation -> ReactiveValue
// dependencies. When ReactiveValue's value gets accessed, the current Computation
// registers the ReactiveValue as a dependency. (technically, a ReactiveValue
// registers the Computation as the ReactiveValue's dependant, but they're basically same)
let currentComputation: Computation | null = null;

// -- CLASSES
// This module extensivly uses classes. While I prefer FP, class is suitable
// for this usecase than plain object or black magic function.
// * JS's language construct
// * Familiar to JS devs
// * Runtime check using `instanceof`
// * Java/C# guys are happy also (idk)

export class Signal<T> implements Disposable, ReactiveValue<T> {
  /**
   * Current value of the Signal.
   */
  [VALUE]: T;

  [DEPENDANTS]: ReactiveValue<T>[typeof DEPENDANTS];

  [IS_DISPOSED]: boolean;

  constructor(value: T) {
    this[VALUE] = value;
    this[DEPENDANTS] = new Set();
    this[IS_DISPOSED] = false;

    if (currentComputation) {
      currentComputation[CHILDREN].add(this);
    }
  }

  once() {
    return this[VALUE];
  }

  get(context?: Computation) {
    const ctx = context || currentComputation;
    if (ctx && !ctx[IS_DISPOSED]) {
      this[DEPENDANTS].add(ctx);
      ctx[DEPENDENCIES].add(this);
    }

    return this[VALUE];
  }

  /**
   * (as a getter) An alias for `get` method.
   */
  get value() {
    return this.get();
  }

  /**
   * Change a value of the Signal to `value`.
   * This triggers re-run of every associated Deriveds and Effects.
   */
  set(value: T) {
    if (this[IS_DISPOSED] || value === this[VALUE]) {
      return;
    }

    this[VALUE] = value;

    // Without this queue, same effect runs multiple times due to computations
    // also cause effect update. For example,
    //
    // ```ts
    // const $s = signal(1);
    // const $c = derived(() => $s.get());
    // effect(() => {
    //   $s.get();
    //   $c.get();
    // });
    // $s.set(2);
    // ```
    //
    // runs the effect three times: initial, update for $s, and update for $c.
    const effectQueue = new Set<Effect>();
    // Needs to clone the DEPENDANTS, because RECIEVE_UPDATEs modifies the Set.
    // Without cloning, infinite recursion happens.
    for (const d of Array.from(this[DEPENDANTS])) {
      d[RECIEVE_UPDATE](effectQueue);
    }

    for (const effect of effectQueue) {
      effect[RUN_EFFECT]();
    }
    effectQueue.clear();
  }

  /**
   * (as a setter) An alias for `set` method.
   */
  set value(value: T) {
    this.set(value);
  }

  /**
   * Change a value of the Signal based on the current value.
   * This triggers re-run of every associated Deriveds and Effects.
   *
   * The first argument of the function is a current value of the Signal.
   */
  update(f: (currentValue: T) => T) {
    this.set(f(this[VALUE]));
  }

  dispose() {
    if (this[IS_DISPOSED]) {
      return;
    }

    this[IS_DISPOSED] = true;

    for (const d of this[DEPENDANTS]) {
      d[DEPENDENCIES].delete(this);
    }
    this[DEPENDANTS].clear();
  }
}

export class Derived<T> implements Disposable, Computation, ReactiveValue<T> {
  [COMPUTE_FN]: () => T;

  [DEPENDANTS]: ReactiveValue<T>[typeof DEPENDANTS];
  [DEPENDENCIES]: Computation[typeof DEPENDENCIES];
  [CHILDREN]: Computation[typeof CHILDREN];
  [IS_DISPOSED]: boolean;

  [VALUE]: T;

  constructor(fn: () => T) {
    this[COMPUTE_FN] = fn;
    this[DEPENDANTS] = new Set();
    this[CHILDREN] = new Set();
    this[DEPENDENCIES] = new Set();
    this[IS_DISPOSED] = false;

    this[VALUE] = this[COMPUTE]();

    if (currentComputation) {
      currentComputation[CHILDREN].add(this);
    }
  }

  [RECIEVE_UPDATE](effectQueue: Set<Effect>) {
    if (this[IS_DISPOSED]) {
      return;
    }

    for (const d of this[DEPENDENCIES]) {
      d[DEPENDANTS].delete(this);
    }
    this[DEPENDENCIES].clear();

    for (const s of this[CHILDREN]) {
      s.dispose();
    }
    this[CHILDREN].clear();

    const value = this[COMPUTE]();
    if (value === this[VALUE]) {
      return;
    }

    this[VALUE] = value;

    // Needs to clone the DEPENDANTS, because RECIEVE_UPDATEs modifies the Set.
    // Without cloning, infinite recursion happens.
    for (const d of Array.from(this[DEPENDANTS])) {
      d[RECIEVE_UPDATE](effectQueue);
    }
  }

  [COMPUTE](): T {
    const savedComputation = currentComputation;
    currentComputation = this;

    try {
      return this[COMPUTE_FN]();
    } finally {
      currentComputation = savedComputation;
    }
  }

  once() {
    return this[VALUE];
  }

  get(context?: Computation) {
    const ctx = context || currentComputation;
    if (ctx) {
      this[DEPENDANTS].add(ctx);
      ctx[DEPENDENCIES].add(this);
    }

    return this[VALUE];
  }

  get value() {
    return this.get();
  }

  dispose() {
    if (this[IS_DISPOSED]) {
      return;
    }

    this[IS_DISPOSED] = true;

    this[DEPENDANTS].clear();

    for (const d of this[DEPENDENCIES]) {
      d[DEPENDANTS].delete(this);
    }
    this[DEPENDENCIES].clear();

    for (const s of this[CHILDREN]) {
      s.dispose();
    }
    this[CHILDREN].clear();
  }
}

export type EffectFunction = (context: Computation) => void | (() => void);

export class Effect implements Disposable, Computation {
  [EFFECT_FN]: EffectFunction;

  [CHILDREN]: Computation[typeof CHILDREN];
  [DEPENDENCIES]: Computation[typeof DEPENDENCIES];
  [IS_DISPOSED]: boolean;

  [CLEANUP_FN]: (() => void) | null;

  constructor(f: EffectFunction) {
    this[CHILDREN] = new Set();
    this[DEPENDENCIES] = new Set();
    this[EFFECT_FN] = f;
    this[IS_DISPOSED] = false;
    this[CLEANUP_FN] = null;

    if (currentComputation) {
      currentComputation[CHILDREN].add(this);
    }

    // For initial run, it's safe to run the Effect without scheduling
    // because it's impossible to run the same Effect twice from user code.
    this[RUN_EFFECT]();
  }

  [RECIEVE_UPDATE](effectQueue: Set<Effect>) {
    if (this[IS_DISPOSED]) {
      return;
    }

    for (const d of this[DEPENDENCIES]) {
      d[DEPENDANTS].delete(this);
    }
    this[DEPENDENCIES].clear();

    for (const d of this[CHILDREN]) {
      d.dispose();
    }
    this[CHILDREN].clear();

    effectQueue.add(this);
  }

  [RUN_EFFECT]() {
    if (this[IS_DISPOSED]) {
      return;
    }

    // Run cleanup functions before updating
    if (this[CLEANUP_FN]) {
      try {
        this[CLEANUP_FN]();
      } finally {
        this[CLEANUP_FN] = null;
      }
    }

    const savedComputation = currentComputation;
    try {
      currentComputation = this;

      this[CLEANUP_FN] = this[EFFECT_FN](this) || null;
    } finally {
      currentComputation = savedComputation;
    }
  }

  dispose() {
    if (this[IS_DISPOSED]) {
      return;
    }

    this[IS_DISPOSED] = true;

    if (this[CLEANUP_FN]) {
      try {
        this[CLEANUP_FN]();
      } finally {
        this[CLEANUP_FN] = null;
      }
    }

    for (const d of this[DEPENDENCIES]) {
      d[DEPENDANTS].delete(this);
    }
    this[DEPENDENCIES].clear();

    for (const s of this[CHILDREN]) {
      s.dispose();
    }
    this[CHILDREN].clear();
  }
}

// -- PUBLIC FUNCTIONS
// These are dumb functions just call class constructor.
// It's up to the user which style (class or function) to use.

/**
 * Creates a Signal.
 * @param value - Initial value of the Signal.
 */
export function signal<T>(value: T): Signal<T> {
  return new Signal(value);
}

/**
 * Creates a Derived based on zero or more other Signals.
 * You can think of Derived as a read-only Signal, whose
 * value is derived from other Signals.
 * @param f - Callback function that returns a value of the Derived.
 *            Everytime one of the Signal inside the callback gets updated,
 *            this callback function would be invoked too.
 */
export function derived<T>(f: () => T): Derived<T> {
  return new Derived(f);
}

/**
 * Creates an Effect.
 */
export function effect(f: EffectFunction): Effect {
  return new Effect(f);
}

// -- HELPERS

/**
 * Convenient helper type for creating "A, or Signal/Derived whose value is A".
 */
export type ReactiveOrStatic<T> = T | ReactiveValue<T>;

/**
 * Narrows down `ReactiveOrStatic` to `ReactiveValue` (Signal or Derived).
 */
export function isReactive<T>(x: ReactiveOrStatic<T>): x is ReactiveValue<T> {
  return x instanceof Signal || x instanceof Derived;
}