@rlabs-inc/signals 0.1.0

package/README.md

@@ -0,0 +1,307 @@
+# @rlabs-inc/signals
+
+**Ultra-lightweight fine-grained reactivity for TypeScript**
+
+A standalone reactive primitives library inspired by Svelte 5 runes, Solid.js, and Vue reactivity. Zero dependencies. ~700 lines of pure TypeScript.
+
+## Features
+
+- **Fine-grained reactivity** - Only effects that read a signal re-run when it changes
+- **Deep reactivity** - Objects and arrays are automatically deeply reactive
+- **Lazy deriveds** - Computed values only recompute when read
+- **Batching** - Group updates to prevent multiple re-runs
+- **Reactive collections** - ReactiveMap, ReactiveSet, and reactiveArray
+- **Zero dependencies** - Pure TypeScript, works everywhere
+- **Tiny** - ~5KB minified
+
+## Installation
+
+```bash
+bun add @rlabs-inc/signals
+# or
+npm install @rlabs-inc/signals
+```
+
+## Quick Start
+
+```typescript
+import { signal, effect, derived, state } from '@rlabs-inc/signals'
+
+// Simple signal
+const count = signal(0)
+
+// Effect runs when dependencies change
+effect(() => {
+  console.log('Count:', count.value)
+})
+// Logs: "Count: 0"
+
+count.value = 1
+// Logs: "Count: 1"
+
+// Derived values
+const doubled = derived(() => count.value * 2)
+console.log(doubled.value) // 2
+
+// Deep reactivity with state()
+const user = state({
+  name: 'John',
+  address: {
+    city: 'NYC'
+  }
+})
+
+effect(() => {
+  console.log('City:', user.address.city)
+})
+// Logs: "City: NYC"
+
+user.address.city = 'LA'
+// Logs: "City: LA"
+```
+
+## API Reference
+
+### signal(initial, options?)
+
+Create a reactive signal that holds a value.
+
+```typescript
+const count = signal(0)
+console.log(count.value) // 0
+
+count.value = 5
+console.log(count.value) // 5
+
+// With custom equality
+const obj = signal({ x: 1 }, {
+  equals: (a, b) => a.x === b.x
+})
+```
+
+### effect(fn)
+
+Create a reactive effect that re-runs when dependencies change.
+
+```typescript
+const name = signal('John')
+
+const dispose = effect(() => {
+  console.log('Hello,', name.value)
+
+  // Optional cleanup function
+  return () => {
+    console.log('Cleaning up...')
+  }
+})
+
+name.value = 'Jane' // Effect re-runs
+
+dispose() // Stop the effect
+```
+
+### derived(fn, options?)
+
+Create a computed/derived value that updates automatically.
+
+```typescript
+const count = signal(5)
+const doubled = derived(() => count.value * 2)
+
+console.log(doubled.value) // 10
+
+count.value = 10
+console.log(doubled.value) // 20
+
+// Alias: derived.by() (Svelte compatibility)
+const tripled = derived.by(() => count.value * 3)
+```
+
+### state(initial)
+
+Create a deeply reactive state object. All nested properties are automatically reactive.
+
+```typescript
+const app = state({
+  user: {
+    name: 'John',
+    preferences: {
+      theme: 'dark'
+    }
+  },
+  items: [1, 2, 3]
+})
+
+effect(() => {
+  console.log(app.user.preferences.theme)
+})
+
+app.user.preferences.theme = 'light' // Triggers effect
+app.items.push(4) // Arrays are reactive too
+```
+
+### batch(fn)
+
+Batch multiple updates into a single reaction cycle.
+
+```typescript
+const a = signal(1)
+const b = signal(2)
+
+effect(() => {
+  console.log('Sum:', a.value + b.value)
+})
+// Logs: "Sum: 3"
+
+batch(() => {
+  a.value = 10
+  b.value = 20
+})
+// Logs: "Sum: 30" (only once, not twice)
+```
+
+### untrack(fn)
+
+Read signals without creating dependencies.
+
+```typescript
+const a = signal(1)
+const b = signal(2)
+
+effect(() => {
+  console.log('a:', a.value) // Creates dependency
+  untrack(() => {
+    console.log('b:', b.value) // Does NOT create dependency
+  })
+})
+
+b.value = 100 // Effect does NOT re-run
+a.value = 100 // Effect re-runs
+```
+
+### watch(source, callback, options?)
+
+Watch a signal and call callback when it changes.
+
+```typescript
+const count = signal(0)
+
+const dispose = watch(
+  () => count.value,
+  (newValue, oldValue) => {
+    console.log(`Changed from ${oldValue} to ${newValue}`)
+  }
+)
+
+count.value = 1 // Logs: "Changed from 0 to 1"
+
+// With immediate option
+watch(
+  () => count.value,
+  (value) => console.log('Value:', value),
+  { immediate: true }
+)
+// Logs immediately: "Value: 1"
+```
+
+### ReactiveMap
+
+A reactive Map that triggers updates on modifications.
+
+```typescript
+const map = new ReactiveMap<string, number>()
+
+effect(() => {
+  console.log('Value:', map.get('key'))
+})
+
+map.set('key', 42) // Triggers effect
+```
+
+### ReactiveSet
+
+A reactive Set that triggers updates on modifications.
+
+```typescript
+const set = new ReactiveSet<string>()
+
+effect(() => {
+  console.log('Has item:', set.has('item'))
+})
+
+set.add('item') // Triggers effect
+```
+
+### reactiveArray(initial?)
+
+Create a reactive array with fine-grained reactivity.
+
+```typescript
+const items = reactiveArray([1, 2, 3])
+
+effect(() => {
+  console.log('First:', items[0])
+  console.log('Length:', items.length)
+})
+
+items[0] = 10    // Triggers effect
+items.push(4)    // Triggers effect
+```
+
+### Utilities
+
+```typescript
+// Create read-only view
+const count = signal(0)
+const ro = readonly(count)
+// ro.value = 5  // TypeScript error
+
+// Read without tracking (alias for untrack)
+const value = peek(() => count.value)
+
+// Check if value is reactive
+isReactive(someObject)
+
+// Get raw object from reactive proxy
+const raw = toRaw(reactiveObject)
+
+// Create effect scope
+const scope = effectScope()
+scope.run(() => {
+  effect(() => { /* ... */ })
+  effect(() => { /* ... */ })
+})
+scope.stop() // Disposes all effects
+```
+
+## Comparison with Svelte 5
+
+| Svelte 5 | @rlabs-inc/signals |
+|----------|-------------------|
+| `$state(value)` | `signal(value)` or `state(obj)` |
+| `$derived(expr)` | `derived(() => expr)` |
+| `$derived.by(fn)` | `derived.by(fn)` or `derived(fn)` |
+| `$effect(fn)` | `effect(fn)` |
+| `SvelteMap` | `ReactiveMap` |
+| `SvelteSet` | `ReactiveSet` |
+
+**Key differences:**
+- No compiler needed - works with plain TypeScript
+- Use `.value` to read/write signals (like Vue/Solid)
+- No Happy DOM or browser environment required
+
+## Why?
+
+We built this because:
+1. We love Svelte 5's reactivity model
+2. We wanted to use it outside Svelte components
+3. We didn't want the overhead of Happy DOM for server-side usage
+4. We needed a lightweight solution for libraries like [FatherStateDB](https://github.com/rlabs-inc/fatherstatedb)
+
+## License
+
+MIT
+
+---
+
+Built with ❤️ by RLabs Inc.

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+/** Cleanup function returned by effects */
+export type CleanupFn = () => void;
+/** Effect function that may return a cleanup */
+export type EffectFn = () => void | CleanupFn;
+/** Equality function for comparing values */
+export type EqualityFn<T> = (a: T, b: T) => boolean;
+/** A reactive signal that holds a value */
+export interface Signal<T> {
+    readonly value: T;
+}
+/** A writable reactive signal */
+export interface WritableSignal<T> extends Signal<T> {
+    value: T;
+}
+/** A derived/computed signal (read-only) */
+export interface Derived<T> extends Signal<T> {
+    readonly value: T;
+}
+/** Options for creating a signal */
+export interface SignalOptions<T> {
+    equals?: EqualityFn<T>;
+}
+/** Default equality check using Object.is */
+export declare const defaultEquals: <T>(a: T, b: T) => boolean;
+/** Shallow equality for objects/arrays */
+export declare const shallowEquals: <T>(a: T, b: T) => boolean;
+/**
+ * Create a reactive signal
+ *
+ * @example
+ * ```ts
+ * const count = signal(0)
+ * console.log(count.value) // 0
+ * count.value = 1
+ * console.log(count.value) // 1
+ * ```
+ */
+export declare function signal<T>(initial: T, options?: SignalOptions<T>): WritableSignal<T>;
+/**
+ * Create a reactive effect that re-runs when dependencies change
+ *
+ * @returns Dispose function to stop the effect
+ *
+ * @example
+ * ```ts
+ * const count = signal(0)
+ * const dispose = effect(() => {
+ *   console.log('Count:', count.value)
+ * })
+ * // Logs: "Count: 0"
+ *
+ * count.value = 1
+ * // Logs: "Count: 1"
+ *
+ * dispose() // Stop the effect
+ * ```
+ */
+export declare function effect(fn: EffectFn): CleanupFn;
+/**
+ * Create a derived/computed value that automatically updates
+ *
+ * @example
+ * ```ts
+ * const count = signal(0)
+ * const doubled = derived(() => count.value * 2)
+ * console.log(doubled.value) // 0
+ *
+ * count.value = 5
+ * console.log(doubled.value) // 10
+ * ```
+ */
+export declare function derived<T>(fn: () => T, options?: SignalOptions<T>): Derived<T>;
+export declare namespace derived {
+    var by: typeof derived;
+}
+/**
+ * Batch multiple updates into a single reaction cycle
+ *
+ * @example
+ * ```ts
+ * const a = signal(1)
+ * const b = signal(2)
+ *
+ * effect(() => console.log(a.value + b.value))
+ * // Logs: 3
+ *
+ * batch(() => {
+ *   a.value = 10
+ *   b.value = 20
+ * })
+ * // Logs: 30 (only once, not twice)
+ * ```
+ */
+export declare function batch<T>(fn: () => T): T;
+/**
+ * Read signals without creating dependencies
+ *
+ * @example
+ * ```ts
+ * const a = signal(1)
+ * const b = signal(2)
+ *
+ * effect(() => {
+ *   console.log(a.value) // Creates dependency
+ *   untrack(() => {
+ *     console.log(b.value) // Does NOT create dependency
+ *   })
+ * })
+ * ```
+ */
+export declare function untrack<T>(fn: () => T): T;
+/**
+ * Create a deeply reactive state object
+ * All nested properties are automatically reactive
+ *
+ * @example
+ * ```ts
+ * const user = state({
+ *   name: 'John',
+ *   address: {
+ *     city: 'NYC'
+ *   }
+ * })
+ *
+ * effect(() => {
+ *   console.log(user.address.city)
+ * })
+ * // Logs: "NYC"
+ *
+ * user.address.city = 'LA'
+ * // Logs: "LA"
+ * ```
+ */
+export declare function state<T extends object>(initial: T): T;
+/**
+ * Get the raw (non-reactive) version of a reactive object
+ */
+export declare function toRaw<T>(proxy: T): T;
+/**
+ * Check if a value is a reactive proxy
+ */
+export declare function isReactive(value: unknown): boolean;
+/**
+ * A reactive Map that triggers updates on modifications
+ *
+ * @example
+ * ```ts
+ * const map = new ReactiveMap<string, number>()
+ *
+ * effect(() => {
+ *   console.log('Size:', map.size)
+ *   console.log('Has foo:', map.has('foo'))
+ * })
+ *
+ * map.set('foo', 42) // Triggers effect
+ * ```
+ */
+export declare class ReactiveMap<K, V> extends Map<K, V> {
+    #private;
+    constructor(entries?: Iterable<readonly [K, V]> | null);
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void;
+    keys(): MapIterator<K>;
+    values(): MapIterator<V>;
+    entries(): MapIterator<[K, V]>;
+    [Symbol.iterator](): MapIterator<[K, V]>;
+}
+/**
+ * A reactive Set that triggers updates on modifications
+ *
+ * @example
+ * ```ts
+ * const set = new ReactiveSet<string>()
+ *
+ * effect(() => {
+ *   console.log('Size:', set.size)
+ *   console.log('Has foo:', set.has('foo'))
+ * })
+ *
+ * set.add('foo') // Triggers effect
+ * ```
+ */
+export declare class ReactiveSet<T> extends Set<T> {
+    #private;
+    constructor(values?: Iterable<T> | null);
+    get size(): number;
+    has(value: T): boolean;
+    add(value: T): this;
+    delete(value: T): boolean;
+    clear(): void;
+    forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: any): void;
+    keys(): SetIterator<T>;
+    values(): SetIterator<T>;
+    entries(): SetIterator<[T, T]>;
+    [Symbol.iterator](): SetIterator<T>;
+}
+/**
+ * Create a reactive array with fine-grained reactivity
+ *
+ * @example
+ * ```ts
+ * const items = reactiveArray([1, 2, 3])
+ *
+ * effect(() => {
+ *   console.log('Length:', items.length)
+ *   console.log('First:', items[0])
+ * })
+ *
+ * items.push(4)    // Triggers effect
+ * items[0] = 10    // Triggers effect
+ * ```
+ */
+export declare function reactiveArray<T>(initial?: T[]): T[];
+/**
+ * Create an effect scope for grouping and disposing multiple effects
+ *
+ * @example
+ * ```ts
+ * const scope = effectScope()
+ *
+ * scope.run(() => {
+ *   effect(() => console.log('Effect 1'))
+ *   effect(() => console.log('Effect 2'))
+ * })
+ *
+ * scope.stop() // Disposes all effects in the scope
+ * ```
+ */
+export declare function effectScope(): {
+    run<T>(fn: () => T): T | undefined;
+    stop(): void;
+    readonly active: boolean;
+};
+/**
+ * Watch a signal or derived and call callback when it changes
+ * Like effect but only runs the callback, not for initial subscription
+ *
+ * @example
+ * ```ts
+ * const count = signal(0)
+ *
+ * watch(
+ *   () => count.value,
+ *   (newValue, oldValue) => {
+ *     console.log(`Changed from ${oldValue} to ${newValue}`)
+ *   }
+ * )
+ *
+ * count.value = 1 // Logs: "Changed from 0 to 1"
+ * ```
+ */
+export declare function watch<T>(source: () => T, callback: (newValue: T, oldValue: T | undefined) => void | CleanupFn, options?: {
+    immediate?: boolean;
+}): CleanupFn;
+/**
+ * Create a readonly signal from a writable signal
+ */
+export declare function readonly<T>(sig: WritableSignal<T>): Signal<T>;
+/**
+ * Compute a value once without reactivity
+ */
+export declare function peek<T>(fn: () => T): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}