flatsignals 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 kevintakeda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# FlatSignals
+
+FlatSignals is an extremely fast reactivity library (~0.7kb).
+
+- Lightning-fast batch updates.
+- No graph traversals.
+- Dynamic dependencies managed in O(1) time.
+- Automatic disposals.
+- Computeds are lazy by default.
+
+## Benchmarks
+
+You can execute the [benchmarks](https://github.com/kevintakeda/flatsignals/tree/main/benchmarks) by running `pnpm bench`.
+
+```console
+flatsignals - benchmarks/signals.bench.ts > one to many sparse (32x)
+  1.60x faster than @preact/signals
+  1.70x faster than @reactively/core
+  1.95x faster than alien-signals
+  2.27x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > wide propagation (32x)
+  1.72x faster than @preact/signals
+  1.74x faster than alien-signals
+  2.22x faster than @reactively/core
+  2.94x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > deep propagation (32x)
+  1.02x faster than alien-signals
+  1.29x faster than @preact/signals
+  1.55x faster than @reactively/core
+  1.97x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > dynamic
+  2.82x faster than @preact/signals
+  2.98x faster than @reactively/core
+  3.54x faster than @maverick-js/signals
+  4.56x faster than alien-signals
+
+flatsignals - benchmarks/signals.bench.ts > batch 25%
+  1.26x faster than @preact/signals
+  1.56x faster than alien-signals
+  1.66x faster than @reactively/core
+  1.97x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > batch 50%
+  1.48x faster than @preact/signals
+  1.62x faster than alien-signals
+  1.72x faster than @reactively/core
+  2.09x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > packed 30%
+  1.49x faster than @reactively/core
+  1.77x faster than alien-signals
+  1.77x faster than @preact/signals
+  1.99x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > dense batch ~1/3 (2x layers)
+  1.72x faster than @preact/signals
+  2.17x faster than @reactively/core
+  2.25x faster than alien-signals
+  2.86x faster than @maverick-js/signals
+
+flatsignals - benchmarks/signals.bench.ts > dense batch ~1/3 (4x layers)
+  1.98x faster than @preact/signals
+  2.11x faster than @reactively/core
+  2.75x faster than alien-signals
+  3.05x faster than @maverick-js/signals
+
+alien-signals - benchmarks/signals.bench.ts > one to one to one (32x)
+  1.00x faster than @preact/signals
+  1.05x faster than flatsignals
+  1.16x faster than @maverick-js/signals
+  1.94x faster than @reactively/core
+```
+
+## Tradeoffs
+
+1. Supports only 32 signals per root.
+2. Set operations have 𝑂(𝑁) complexity, where 𝑁 is the number of computations. However, multiple updates can be batched into a single operation.
+3. When data sources change, all dependent nodes are marked dirty, even if intermediate values stay the same.

package/dist/index.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+// src/index.ts
+var ROOT = null;
+var COMPUTED = null;
+var BATCHING = false;
+var ROOT_QUEUE = [];
+var Scope = class {
+  /* @internal */
+  _disposing = false;
+  /* @internal */
+  _disposals = null;
+  constructor() {
+    getScope()?._onDispose(this._dispose.bind(this));
+  }
+  /* @internal */
+  _dispose() {
+    if (this._disposing) return;
+    this._disposing = true;
+    this._disposals?.forEach((fn) => fn());
+    this._disposing = false;
+  }
+  /* @internal */
+  _onDispose(fn) {
+    if (!this._disposals) this._disposals = [];
+    this._disposals.push(fn);
+  }
+};
+var Root = class extends Scope {
+  /* @internal computeds */
+  _c = [];
+  /* @internal disposed computeds */
+  _x = [];
+  /* @internal id generator */
+  _i = 0;
+  /* @internal batch mask */
+  #batch = 0;
+  /* @internal */
+  _dispose() {
+    super._dispose();
+    this._c = [];
+    this._x = [];
+    this._i = 0;
+  }
+  /* @internal Add source */
+  _as() {
+    return this._i++ % 32;
+  }
+  /* @internal Add computed */
+  _ac(c) {
+    if (this._x.length) {
+      const u = this._x.pop();
+      this._c[u] = c;
+      return u;
+    } else {
+      return this._c.push(c) - 1;
+    }
+  }
+  /* @internal Destroy computed */
+  _dc(idx) {
+    this._x.push(idx);
+  }
+  /* @internal */
+  _queue(mask) {
+    if (!this.#batch) {
+      ROOT_QUEUE.push(this);
+    }
+    this.#batch |= mask;
+    if (!BATCHING) this._flush(true);
+  }
+  /* @internal */
+  _flush(force = false) {
+    if (!this.#batch || !force) return;
+    for (const item of this._c) {
+      if (!item._dirty && (item._sources & this.#batch) !== 0) {
+        item._dirty = true;
+        if (item._effect) item.val;
+      }
+    }
+    this.#batch = 0;
+  }
+};
+var DataSignal = class {
+  #root;
+  #val;
+  #id = 0;
+  equals = defaultEquality;
+  constructor(val) {
+    if (!ROOT) ROOT = new Root();
+    this.#root = ROOT;
+    this.#val = val;
+    this.#id |= 1 << this.#root._as();
+  }
+  get val() {
+    if (COMPUTED) {
+      COMPUTED._sources |= this.#id;
+    }
+    return this.#val;
+  }
+  set val(val) {
+    if (this.equals(val, this.#val)) return;
+    this.#val = val;
+    this.#root._queue(this.#id);
+  }
+};
+var Computation = class extends Scope {
+  #root;
+  #id;
+  #val;
+  #fn;
+  /* @internal */
+  _effect = false;
+  /* @internal */
+  _sources = 0;
+  /* @internal */
+  _dirty = true;
+  /* @internal destroyed */
+  _d = false;
+  constructor(compute, val, effect2) {
+    if (!ROOT) ROOT = new Root();
+    super();
+    this.#root = ROOT;
+    this.#fn = compute;
+    this.#val = val;
+    this.#id = this.#root._ac(this);
+    if (effect2) {
+      this._effect = effect2;
+      this.val;
+    }
+  }
+  get val() {
+    this.#root._flush();
+    const prevCurrent = COMPUTED;
+    if (this._dirty) {
+      super._dispose();
+      COMPUTED = this;
+      this._sources = 0;
+      this.#val = this.#fn();
+      this._dirty = false;
+      COMPUTED = prevCurrent;
+    }
+    if (prevCurrent) {
+      prevCurrent._sources |= this._sources;
+    }
+    return this.#val;
+  }
+  get peek() {
+    return this.#val;
+  }
+  getRoot() {
+    return this.#root;
+  }
+  /* @internal */
+  _dispose() {
+    if (this._d) return;
+    super._dispose();
+    this._sources = 0;
+    this._dirty = false;
+    this._d = true;
+    this.#root._dc(this.#id);
+  }
+};
+function defaultEquality(a, b) {
+  return a === b;
+}
+function getScope() {
+  return COMPUTED || ROOT;
+}
+function withScope(scope, fn) {
+  const prevComputed = COMPUTED, prevRoot = ROOT;
+  if (scope instanceof Computation) COMPUTED = scope;
+  ROOT = COMPUTED?.getRoot() ?? ROOT;
+  const result = fn();
+  COMPUTED = prevComputed;
+  ROOT = prevRoot;
+  return result;
+}
+function onDispose(fn) {
+  getScope()?._onDispose(fn);
+}
+function batch(fn) {
+  if (BATCHING) return fn();
+  BATCHING = true;
+  fn();
+  if (ROOT_QUEUE.length) {
+    for (const el of ROOT_QUEUE) el._flush(true);
+    ROOT_QUEUE = [];
+  }
+  BATCHING = false;
+}
+function root(fn, existingRoot) {
+  const prevRoot = ROOT;
+  const prevScope = getScope();
+  ROOT = existingRoot ?? new Root();
+  prevScope?._onDispose(ROOT._dispose.bind(ROOT));
+  const result = fn(ROOT._dispose.bind(ROOT));
+  ROOT = prevRoot;
+  return result;
+}
+function signal(value) {
+  return new DataSignal(value);
+}
+function computed(val) {
+  return new Computation(val);
+}
+function effect(fn) {
+  const sig = new Computation(fn, void 0, true);
+  return sig._dispose.bind(sig);
+}
+
+exports.Computation = Computation;
+exports.DataSignal = DataSignal;
+exports.Root = Root;
+exports.Scope = Scope;
+exports.batch = batch;
+exports.computed = computed;
+exports.effect = effect;
+exports.getScope = getScope;
+exports.onDispose = onDispose;
+exports.root = root;
+exports.signal = signal;
+exports.withScope = withScope;

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+declare class Scope {
+    constructor();
+}
+declare class Root extends Scope {
+    #private;
+}
+declare class DataSignal<T = any> {
+    #private;
+    equals: typeof defaultEquality;
+    constructor(val?: T);
+    get val(): T;
+    set val(val: T);
+}
+declare class Computation<T = unknown> extends Scope {
+    #private;
+    constructor(compute?: () => T, val?: T, effect?: boolean);
+    get val(): T;
+    get peek(): T;
+    getRoot(): Root;
+}
+declare function defaultEquality(a: unknown, b: unknown): boolean;
+declare function getScope(): Scope | null;
+declare function withScope(scope: Scope, fn: () => void): void;
+declare function onDispose(fn: () => void): void;
+declare function batch(fn: () => void): void;
+declare function root<T>(fn: (dispose: () => void) => T, existingRoot?: Root): T;
+declare function signal<T>(value: T): DataSignal<T>;
+declare function signal<T = undefined>(): DataSignal<T | undefined>;
+declare function computed<T>(val: () => T): Computation<T>;
+declare function effect<T = unknown>(fn: () => T): () => void;
+
+export { Computation, DataSignal, Root, Scope, batch, computed, effect, getScope, onDispose, root, signal, withScope };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+declare class Scope {
+    constructor();
+}
+declare class Root extends Scope {
+    #private;
+}
+declare class DataSignal<T = any> {
+    #private;
+    equals: typeof defaultEquality;
+    constructor(val?: T);
+    get val(): T;
+    set val(val: T);
+}
+declare class Computation<T = unknown> extends Scope {
+    #private;
+    constructor(compute?: () => T, val?: T, effect?: boolean);
+    get val(): T;
+    get peek(): T;
+    getRoot(): Root;
+}
+declare function defaultEquality(a: unknown, b: unknown): boolean;
+declare function getScope(): Scope | null;
+declare function withScope(scope: Scope, fn: () => void): void;
+declare function onDispose(fn: () => void): void;
+declare function batch(fn: () => void): void;
+declare function root<T>(fn: (dispose: () => void) => T, existingRoot?: Root): T;
+declare function signal<T>(value: T): DataSignal<T>;
+declare function signal<T = undefined>(): DataSignal<T | undefined>;
+declare function computed<T>(val: () => T): Computation<T>;
+declare function effect<T = unknown>(fn: () => T): () => void;
+
+export { Computation, DataSignal, Root, Scope, batch, computed, effect, getScope, onDispose, root, signal, withScope };

package/dist/index.js

@@ -0,0 +1,209 @@
+// src/index.ts
+var ROOT = null;
+var COMPUTED = null;
+var BATCHING = false;
+var ROOT_QUEUE = [];
+var Scope = class {
+  /* @internal */
+  _disposing = false;
+  /* @internal */
+  _disposals = null;
+  constructor() {
+    getScope()?._onDispose(this._dispose.bind(this));
+  }
+  /* @internal */
+  _dispose() {
+    if (this._disposing) return;
+    this._disposing = true;
+    this._disposals?.forEach((fn) => fn());
+    this._disposing = false;
+  }
+  /* @internal */
+  _onDispose(fn) {
+    if (!this._disposals) this._disposals = [];
+    this._disposals.push(fn);
+  }
+};
+var Root = class extends Scope {
+  /* @internal computeds */
+  _c = [];
+  /* @internal disposed computeds */
+  _x = [];
+  /* @internal id generator */
+  _i = 0;
+  /* @internal batch mask */
+  #batch = 0;
+  /* @internal */
+  _dispose() {
+    super._dispose();
+    this._c = [];
+    this._x = [];
+    this._i = 0;
+  }
+  /* @internal Add source */
+  _as() {
+    return this._i++ % 32;
+  }
+  /* @internal Add computed */
+  _ac(c) {
+    if (this._x.length) {
+      const u = this._x.pop();
+      this._c[u] = c;
+      return u;
+    } else {
+      return this._c.push(c) - 1;
+    }
+  }
+  /* @internal Destroy computed */
+  _dc(idx) {
+    this._x.push(idx);
+  }
+  /* @internal */
+  _queue(mask) {
+    if (!this.#batch) {
+      ROOT_QUEUE.push(this);
+    }
+    this.#batch |= mask;
+    if (!BATCHING) this._flush(true);
+  }
+  /* @internal */
+  _flush(force = false) {
+    if (!this.#batch || !force) return;
+    for (const item of this._c) {
+      if (!item._dirty && (item._sources & this.#batch) !== 0) {
+        item._dirty = true;
+        if (item._effect) item.val;
+      }
+    }
+    this.#batch = 0;
+  }
+};
+var DataSignal = class {
+  #root;
+  #val;
+  #id = 0;
+  equals = defaultEquality;
+  constructor(val) {
+    if (!ROOT) ROOT = new Root();
+    this.#root = ROOT;
+    this.#val = val;
+    this.#id |= 1 << this.#root._as();
+  }
+  get val() {
+    if (COMPUTED) {
+      COMPUTED._sources |= this.#id;
+    }
+    return this.#val;
+  }
+  set val(val) {
+    if (this.equals(val, this.#val)) return;
+    this.#val = val;
+    this.#root._queue(this.#id);
+  }
+};
+var Computation = class extends Scope {
+  #root;
+  #id;
+  #val;
+  #fn;
+  /* @internal */
+  _effect = false;
+  /* @internal */
+  _sources = 0;
+  /* @internal */
+  _dirty = true;
+  /* @internal destroyed */
+  _d = false;
+  constructor(compute, val, effect2) {
+    if (!ROOT) ROOT = new Root();
+    super();
+    this.#root = ROOT;
+    this.#fn = compute;
+    this.#val = val;
+    this.#id = this.#root._ac(this);
+    if (effect2) {
+      this._effect = effect2;
+      this.val;
+    }
+  }
+  get val() {
+    this.#root._flush();
+    const prevCurrent = COMPUTED;
+    if (this._dirty) {
+      super._dispose();
+      COMPUTED = this;
+      this._sources = 0;
+      this.#val = this.#fn();
+      this._dirty = false;
+      COMPUTED = prevCurrent;
+    }
+    if (prevCurrent) {
+      prevCurrent._sources |= this._sources;
+    }
+    return this.#val;
+  }
+  get peek() {
+    return this.#val;
+  }
+  getRoot() {
+    return this.#root;
+  }
+  /* @internal */
+  _dispose() {
+    if (this._d) return;
+    super._dispose();
+    this._sources = 0;
+    this._dirty = false;
+    this._d = true;
+    this.#root._dc(this.#id);
+  }
+};
+function defaultEquality(a, b) {
+  return a === b;
+}
+function getScope() {
+  return COMPUTED || ROOT;
+}
+function withScope(scope, fn) {
+  const prevComputed = COMPUTED, prevRoot = ROOT;
+  if (scope instanceof Computation) COMPUTED = scope;
+  ROOT = COMPUTED?.getRoot() ?? ROOT;
+  const result = fn();
+  COMPUTED = prevComputed;
+  ROOT = prevRoot;
+  return result;
+}
+function onDispose(fn) {
+  getScope()?._onDispose(fn);
+}
+function batch(fn) {
+  if (BATCHING) return fn();
+  BATCHING = true;
+  fn();
+  if (ROOT_QUEUE.length) {
+    for (const el of ROOT_QUEUE) el._flush(true);
+    ROOT_QUEUE = [];
+  }
+  BATCHING = false;
+}
+function root(fn, existingRoot) {
+  const prevRoot = ROOT;
+  const prevScope = getScope();
+  ROOT = existingRoot ?? new Root();
+  prevScope?._onDispose(ROOT._dispose.bind(ROOT));
+  const result = fn(ROOT._dispose.bind(ROOT));
+  ROOT = prevRoot;
+  return result;
+}
+function signal(value) {
+  return new DataSignal(value);
+}
+function computed(val) {
+  return new Computation(val);
+}
+function effect(fn) {
+  const sig = new Computation(fn, void 0, true);
+  return sig._dispose.bind(sig);
+}
+
+export { Computation, DataSignal, Root, Scope, batch, computed, effect, getScope, onDispose, root, signal, withScope };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "flatsignals",
+  "version": "0.1.0",
+  "description": "FlatSignals is an extremely fast reactivity library (~0.7kb)",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "bench": "vitest bench",
+    "test:watch": "vitest",
+    "size": "size-limit"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@maverick-js/signals": "^6.0.0",
+    "@preact/signals-core": "^1.12.1",
+    "@reactively/core": "^0.0.8",
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@types/node": "^22.18.11",
+    "alien-signals": "^3.0.1",
+    "size-limit": "^11.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "1 kB"
+    }
+  ]
+}