@valentin30/signal 0.2.0 → 1.0.0

package/.prettierrc

@@ -0,0 +1,21 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 4,
+  "overrides": [
+    {
+      "files": ["*.json", "*rc", "*.yml", "*.yaml"],
+      "options": {
+        "tabWidth": 2,
+        "trailingComma": "none"
+      }
+    }
+  ],
+  "printWidth": 140,
+  "semi": false,
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "jsxSingleQuote": false,
+  "singleAttributePerLine": false,
+  "bracketSameLine": false
+}

package/package.json

@@ -1,13 +1,87 @@
 {
   "name": "@valentin30/signal",
-  "version": "0.2.0",
+  "type": "module",
+  "version": "1.0.0",
   "description": "My take on signals - lightweight reactive primitives inspired by Preact Signals, written in TypeScript.",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "exports": {
+    ".": {
+      "import": "./dist/core.js",
+      "types": "./dist/core.d.ts"
+    },
+    "./core": {
+      "import": "./dist/core.js",
+      "types": "./dist/core.d.ts"
+    },
+    "./core/signal": {
+      "import": "./dist/core/signal.js",
+      "types": "./dist/core/signal.d.ts"
+    },
+    "./core/computed": {
+      "import": "./dist/core/computed.js",
+      "types": "./dist/core/computed.d.ts"
+    },
+    "./core/context": {
+      "import": "./dist/core/context.js",
+      "types": "./dist/core/context.d.ts"
+    },
+    "./core/scheduler": {
+      "import": "./dist/core/scheduler.js",
+      "types": "./dist/core/scheduler.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    },
+    "./react/use-signal": {
+      "import": "./dist/react/use-signal.js",
+      "types": "./dist/react/use-signal.d.ts"
+    },
+    "./react/use-computed": {
+      "import": "./dist/react/use-computed.js",
+      "types": "./dist/react/use-computed.d.ts"
+    },
+    "./react/use-read": {
+      "import": "./dist/react/use-read.js",
+      "types": "./dist/react/use-read.d.ts"
+    },
+    "./event": {
+      "import": "./dist/event.js",
+      "types": "./dist/event.d.ts"
+    },
+    "./event/channel": {
+      "import": "./dist/event/channel.js",
+      "types": "./dist/event/channel.d.ts"
+    },
+    "./event/effect": {
+      "import": "./dist/event/effect.js",
+      "types": "./dist/event/effect.d.ts"
+    },
+    "./event/notifier": {
+      "import": "./dist/event/notifier.js",
+      "types": "./dist/event/notifier.d.ts"
+    },
+    "./builder": {
+      "import": "./dist/builder.js",
+      "types": "./dist/builder.d.ts"
+    },
+    "./builder/value": {
+      "import": "./dist/builder/value.js",
+      "types": "./dist/builder/value.d.ts"
+    },
+    "./builder/node": {
+      "import": "./dist/builder/node.js",
+      "types": "./dist/builder/node.d.ts"
+    },
+    "./builder/sources": {
+      "import": "./dist/builder/sources.js",
+      "types": "./dist/builder/sources.d.ts"
+    },
+    "./builder/consumers": {
+      "import": "./dist/builder/consumers.js",
+      "types": "./dist/builder/consumers.d.ts"
+    }
+  },
+  "sideEffects": false,
   "scripts": {
     "clean": "rimraf dist",
     "build": "npm run clean && tsup",
@@ -20,7 +94,7 @@
     "type": "git",
     "url": "git+https://github.com/valentin30/signal.git"
   },
-  "author": "Valentin",
+  "author": "Valentin Spasov",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/valentin30/signal/issues"
@@ -28,9 +102,13 @@
   "homepage": "https://github.com/valentin30/signal#readme",
   "devDependencies": {
     "@types/node": "^22.15.29",
+    "@types/react": "^19.1.12",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.1.4"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
   }
 }

package/src/core/computed.ts

@@ -0,0 +1,68 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+import { Consumers } from '@valentin30/signal/core/interfaces/consumers'
+import { Sources } from '@valentin30/signal/core/interfaces/sources'
+import { Value } from '@valentin30/signal/core/interfaces/value'
+
+export class Computed<T> implements Source, Consumer, Value<T> {
+    private invalidated: boolean
+
+    private readonly value: Value<T>
+
+    private readonly sources: Sources<T>
+
+    private readonly consumers: Consumers
+
+    private __v: number
+
+    constructor(value: Value<T>, sources: Sources<T>, consumers: Consumers) {
+        this.invalidated = true
+        this.value = value
+        this.sources = sources
+        this.consumers = consumers
+        this.__v = 0
+    }
+
+    public dirty(): boolean {
+        if (this.consumers.active()) return this.invalidated
+        return this.sources.changed()
+    }
+
+    public read(): T {
+        if (this.dirty()) {
+            this.invalidated = false
+            this.value.write(this.sources.compute())
+        }
+        return this.value.read()
+    }
+
+    public write(): boolean {
+        return false
+    }
+
+    public compare(a: T, b: T): boolean {
+        return this.value.compare(a, b)
+    }
+
+    public invalidate(): void {
+        if (this.invalidated) return
+        this.invalidated = true
+        this.__v++
+        this.consumers.invalidate()
+    }
+
+    public link(consumer: Consumer): void {
+        if (!this.consumers.active()) this.sources.link(this)
+        this.consumers.link(consumer)
+    }
+
+    public unlink(consumer: Consumer): void {
+        this.consumers.unlink(consumer)
+        if (this.consumers.active()) return
+        this.sources.unlink(this)
+    }
+
+    public version(): number {
+        return this.__v
+    }
+}

package/src/core/contracts/consumer.ts

@@ -0,0 +1,3 @@
+export interface Consumer {
+    invalidate(): void
+}

package/src/core/contracts/source.ts

@@ -0,0 +1,7 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+
+export interface Source {
+    link(consumer: Consumer): void
+    unlink(consumer: Consumer): void
+    version(): number
+}

package/src/core/interfaces/consumers.ts

@@ -0,0 +1,8 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+
+export interface Consumers {
+    active(): boolean
+    invalidate(): void
+    link(consumer: Consumer): void
+    unlink(consumer: Consumer): void
+}

package/src/core/interfaces/sources.ts

@@ -0,0 +1,8 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+
+export interface Sources<T> {
+    compute(): T
+    changed(): boolean
+    link(consumer: Consumer): void
+    unlink(consumer: Consumer): void
+}

package/src/core/interfaces/value.ts

@@ -0,0 +1,5 @@
+export interface Value<T> {
+    read(): T
+    write(value: T): boolean
+    compare(a: T, b: T): boolean
+}

package/src/core/signal.ts

@@ -0,0 +1,45 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+import { Consumers } from '@valentin30/signal/core/interfaces/consumers'
+import { Value } from '@valentin30/signal/core/interfaces/value'
+
+export class Signal<T> implements Source, Value<T> {
+    private readonly value: Value<T>
+
+    private readonly consumers: Consumers
+
+    private __v: number
+
+    constructor(value: Value<T>, consumers: Consumers) {
+        this.value = value
+        this.consumers = consumers
+        this.__v = 0
+    }
+
+    public read(): T {
+        return this.value.read()
+    }
+
+    public write(value: T): boolean {
+        if (!this.value.write(value)) return false
+        this.__v++
+        this.consumers.invalidate()
+        return true
+    }
+
+    public compare(a: T, b: T): boolean {
+        return this.value.compare(a, b)
+    }
+
+    public link(consumer: Consumer): void {
+        return this.consumers.link(consumer)
+    }
+
+    public unlink(consumer: Consumer): void {
+        return this.consumers.unlink(consumer)
+    }
+
+    public version(): number {
+        return this.__v
+    }
+}

package/src/modules/common/contracts/addable.ts

@@ -0,0 +1,3 @@
+export interface Addable<T> {
+    add(value: T): void
+}

package/src/modules/common/contracts/disposable.ts

@@ -0,0 +1,3 @@
+export interface Disposable {
+    dispose(): void
+}

package/src/modules/common/contracts/subscriber.ts

@@ -0,0 +1,6 @@
+import { Source } from '@valentin30/signal/core/contracts/source'
+
+export interface Subscriber {
+    link(source: Source): void
+    unlink(source: Source): void
+}

package/src/modules/common/types/callable.ts

@@ -0,0 +1 @@
+export type Callable<Args extends any[], ReturnType> = (...args: Args) => ReturnType

package/src/modules/common/types/callback.ts

@@ -0,0 +1 @@
+export type Callback = () => void

package/src/modules/common/utils/compare.ts

@@ -0,0 +1,3 @@
+export function strict_compare<T>(a: T, b: T): boolean {
+    return a === b || (a !== a && b !== b)
+}

package/src/modules/common/utils/swap.ts

@@ -0,0 +1,23 @@
+let tmp: any = null
+
+export function swap<
+    Value extends ASource[AKey],
+    ASource extends object,
+    AKey extends keyof ASource,
+    BSource extends Record<BKey, Value>,
+    BKey extends keyof BSource,
+>(a: ASource, aKey: AKey, b: BSource, bKey: BKey): void {
+    if (<Value>a[aKey] === <Value>b[bKey]) return
+    tmp = a[aKey]
+    a[aKey] = <Value>b[bKey]
+    b[bKey] = tmp
+    tmp = null
+}
+
+export function unsafe_swap(a: object, aKey: string | number | symbol, b: object, bKey: string | number | symbol): void {
+    if (a[<never>aKey] === b[<never>bKey]) return
+    tmp = a[<never>aKey]
+    a[<never>aKey] = b[<never>bKey]
+    b[<never>bKey] = <never>tmp
+    tmp = null
+}

package/src/modules/consumers/factory.ts

@@ -0,0 +1,26 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Consumers } from '@valentin30/signal/core/interfaces/consumers'
+
+export function ConsumersFactory() {
+    class C extends Set<Consumer> implements Consumers {
+        public active(): boolean {
+            return this.size > 0
+        }
+
+        public invalidate(): void {
+            for (const consumer of this.values()) consumer.invalidate()
+        }
+
+        public link(consumer: Consumer): void {
+            this.add(consumer)
+        }
+
+        public unlink(consumer: Consumer): void {
+            this.delete(consumer)
+        }
+    }
+
+    return function c(): Consumers {
+        return new C()
+    }
+}

package/src/modules/event/channel.ts

@@ -0,0 +1,82 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+import { Disposable } from '@valentin30/signal/modules/common/contracts/disposable'
+import { Subscriber } from '@valentin30/signal/modules/common/contracts/subscriber'
+import { Callback } from '@valentin30/signal/modules/common/types/callback'
+import { Dispatch } from '@valentin30/signal/modules/scheduler/dispatch'
+import { Runner } from '@valentin30/signal/modules/scheduler/runner'
+
+export interface Channel extends Subscriber, Disposable {
+    subscribe(callback: Callback): void
+    unsubscribe(callback: Callback): void
+}
+
+export function ChannelFactory(enqueue: (runner: Runner) => void, dequeue: (runner: Runner) => void) {
+    class Ch implements Channel, Runner, Consumer {
+        private queued: boolean
+
+        private current: Set<Callback>
+
+        private pending: Set<Callback>
+
+        private sources: Set<Source>
+
+        constructor() {
+            this.queued = false
+            this.pending = new Set()
+            this.current = new Set()
+            this.sources = new Set()
+        }
+
+        public run(dispatch: Dispatch): void {
+            for (const callback of this.current) dispatch(callback)
+            this.cleanup()
+        }
+
+        private cleanup(): void {
+            this.queued = false
+            if (this.pending.size === 0) return
+            for (const callback of this.pending) this.current.add(callback)
+            this.pending.clear()
+        }
+
+        public subscribe(callback: Callback): void {
+            if (this.queued) this.pending.add(callback)
+            else this.current.add(callback)
+        }
+
+        public unsubscribe(callback: Callback): void {
+            this.current.delete(callback)
+            this.pending.delete(callback)
+        }
+
+        public link(source: Source): void {
+            source.link(this)
+            this.sources.add(source)
+        }
+
+        public unlink(source: Source): void {
+            source.unlink(this)
+            this.sources.delete(source)
+        }
+
+        public dispose(): void {
+            dequeue(this)
+            this.cleanup()
+            for (const source of this.sources) source.unlink(this)
+            this.current.clear()
+            this.sources.clear()
+        }
+
+        public invalidate(): void {
+            enqueue(this)
+            this.queued = true
+        }
+    }
+
+    return function ch(...sources: Source[]): Channel {
+        const channel = new Ch()
+        for (const source of sources) channel.link(source)
+        return channel
+    }
+}

package/src/modules/event/effect.ts

@@ -0,0 +1,45 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Sources } from '@valentin30/signal/core/interfaces/sources'
+import { Disposable } from '@valentin30/signal/modules/common/contracts/disposable'
+import { Callback } from '@valentin30/signal/modules/common/types/callback'
+import { Runner } from '@valentin30/signal/modules/scheduler/runner'
+
+export function EffectFactory(enqueue: (runner: Runner) => void, dequeue: (runner: Runner) => void) {
+    class Effect implements Runner, Consumer, Disposable {
+        private readonly sources: Sources<Callback | void>
+
+        private cleanup: Callback | void
+
+        constructor(sources: Sources<Callback | void>) {
+            this.sources = sources
+            this.cleanup = void 0
+            this.sources.link(this)
+            enqueue(this)
+        }
+
+        public run(): void {
+            try {
+                this.cleanup?.()
+                this.cleanup = this.sources.compute()
+            } catch (error) {
+                console.error(error)
+            }
+        }
+
+        public invalidate(): void {
+            enqueue(this)
+        }
+
+        public dispose(): void {
+            dequeue(this)
+            this.sources.unlink(this)
+            this.cleanup?.()
+            this.cleanup = void 0
+        }
+    }
+
+    return function effect(sources: Sources<Callback | void>): Callback {
+        const o = new Effect(sources)
+        return () => o.dispose()
+    }
+}

package/src/modules/event/notifier.ts

@@ -0,0 +1,38 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+import { Disposable } from '@valentin30/signal/modules/common/contracts/disposable'
+import { Callback } from '@valentin30/signal/modules/common/types/callback'
+import { Runner } from '@valentin30/signal/modules/scheduler/runner'
+
+export function NotifierFactory(enqueue: (runner: Runner) => void, dequeue: (runner: Runner) => void) {
+    class Notifier implements Runner, Consumer, Disposable {
+        private source: Source | void
+
+        private callback: Callback | void
+
+        constructor(source: Source, callback: Callback) {
+            this.source = source
+            this.callback = callback
+        }
+
+        public invalidate(): void {
+            enqueue(this)
+        }
+
+        public run(): void {
+            this.callback?.()
+        }
+
+        public dispose(): void {
+            dequeue(this)
+            this.source?.unlink(this)
+            this.source = void 0
+            this.callback = void 0
+        }
+    }
+
+    return function notifier(source: Source, callback: Callback): Callback {
+        const o = new Notifier(source, callback)
+        return () => o.dispose()
+    }
+}

package/src/modules/node/factory.ts

@@ -0,0 +1,51 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+import { Node } from '@valentin30/signal/modules/node'
+import { NodeSource } from '@valentin30/signal/modules/node/source'
+
+export function NodeFactory(register: (source: Source) => void) {
+    class N<T> implements Node<T> {
+        private readonly source: NodeSource<T>
+
+        constructor(source: NodeSource<T>) {
+            this.source = source
+        }
+
+        public read(): T {
+            register(this.source)
+            return this.peek()
+        }
+
+        public peek(): T {
+            return this.source.read()
+        }
+
+        public write(value: T): boolean {
+            return this.source.write(value)
+        }
+
+        public equals(other: T): boolean {
+            return this.compare(this.read(), other)
+        }
+
+        public compare(a: T, b: T): boolean {
+            return this.source.compare(a, b)
+        }
+
+        public link(consumer: Consumer): void {
+            return this.source.link(consumer)
+        }
+
+        public unlink(consumer: Consumer): void {
+            return this.source.unlink(consumer)
+        }
+
+        public version(): number {
+            return this.source.version()
+        }
+    }
+
+    return function n<T>(source: NodeSource<T>): Node<T> {
+        return new N(source)
+    }
+}

package/src/modules/node/index.ts

@@ -0,0 +1,13 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+
+export interface Node<T> extends Source {
+    read(): T
+    peek(): T
+    write(value: T): boolean
+    equals(other: T): boolean
+    compare(a: T, b: T): boolean
+    link(consumer: Consumer): void
+    unlink(consumer: Consumer): void
+    version(): number
+}

package/src/modules/node/source.ts

@@ -0,0 +1,11 @@
+import { Consumer } from '@valentin30/signal/core/contracts/consumer'
+import { Source } from '@valentin30/signal/core/contracts/source'
+
+export interface NodeSource<T> extends Source {
+    read(): T
+    write(value: T): boolean
+    compare(a: T, b: T): boolean
+    link(consumer: Consumer): void
+    unlink(consumer: Consumer): void
+    version(): number
+}

package/src/modules/scheduler/dispatch.ts

@@ -0,0 +1,3 @@
+import { Callback } from '@valentin30/signal/modules/common/types/callback'
+
+export type Dispatch = (callback: Callback) => void

package/src/modules/scheduler/runner.ts

@@ -0,0 +1,47 @@
+import { Dispatch } from '@valentin30/signal/modules/scheduler/dispatch'
+
+/**
+ * A schedulable unit of work that can be executed by the scheduler.
+ *
+ * Runners are queued and executed during a scheduler flush cycle.
+ * The scheduler provides a `dispatch` function that enables controlled,
+ * deduplicated execution of callbacks.
+ */
+export interface Runner {
+    /**
+     * Execute the runner's work.
+     *
+     * @param dispatch - A controlled callback executor provided by the scheduler.
+     *
+     * **Dispatch Behavior:**
+     * - Callbacks passed to `dispatch` are deduplicated per flush cycle.
+     * - If the same callback reference is dispatched multiple times
+     *   (by this runner or any other runner), it executes **only once**
+     *   per scheduler flush across the entire application.
+     * - This prevents redundant executions when multiple sources
+     *   trigger the same callback within a single flush.
+     *
+     * **When to use dispatch:**
+     * - Use `dispatch(callback)` when the callback should be deduplicated
+     *   (e.g., Channel subscriptions).
+     * - Call callbacks directly when deduplication is not desired
+     *   (e.g., Effect computations).
+     *
+     * @example
+     * ```ts
+     * // Channel: uses dispatch for deduplication
+     * run(dispatch: Dispatch): void {
+     *     for (const callback of this.subscribers) {
+     *         dispatch(callback) // Same callback runs once per flush
+     *     }
+     * }
+     *
+     * // Effect: runs directly, no deduplication
+     * run(dispatch: Dispatch): void {
+     *     this.cleanup?.()
+     *     this.cleanup = this.compute()
+     * }
+     * ```
+     */
+    run(dispatch: Dispatch): void
+}