@liteforge/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SchildW3rk
+
+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,173 @@
+# @liteforge/core
+
+Fine-grained reactive primitives for LiteForge.
+
+## Installation
+
+```bash
+npm install @liteforge/core
+```
+
+## Overview
+
+`@liteforge/core` provides the reactive foundation for LiteForge applications. It includes signals for reactive state, computed values for derived state, effects for side effects, and batching for performance optimization.
+
+## API
+
+### signal
+
+Creates a reactive value that notifies subscribers when it changes.
+
+```ts
+import { signal } from '@liteforge/core'
+
+const count = signal(0)
+
+// Read the value
+count()  // 0
+
+// Set a new value
+count.set(5)
+
+// Update based on previous value
+count.update(n => n + 1)  // 6
+
+// Peek without subscribing
+count.peek()  // 6
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | Debug name for devtools |
+| `equals` | `(a, b) => boolean` | Custom equality function |
+
+```ts
+const user = signal({ name: 'Alice' }, {
+  name: 'currentUser',
+  equals: (a, b) => a.name === b.name
+})
+```
+
+### computed
+
+Creates a derived value that automatically tracks dependencies.
+
+```ts
+import { signal, computed } from '@liteforge/core'
+
+const firstName = signal('John')
+const lastName = signal('Doe')
+
+const fullName = computed(() => `${firstName()} ${lastName()}`)
+
+fullName()  // "John Doe"
+
+firstName.set('Jane')
+fullName()  // "Jane Doe"
+```
+
+Computed values are lazy and cached — they only recalculate when dependencies change and only when read.
+
+### effect
+
+Runs a function whenever its dependencies change.
+
+```ts
+import { signal, effect } from '@liteforge/core'
+
+const count = signal(0)
+
+const dispose = effect(() => {
+  console.log(`Count is now: ${count()}`)
+})
+// Logs: "Count is now: 0"
+
+count.set(1)
+// Logs: "Count is now: 1"
+
+// Stop the effect
+dispose()
+```
+
+### batch
+
+Groups multiple signal updates into a single notification cycle.
+
+```ts
+import { signal, effect, batch } from '@liteforge/core'
+
+const a = signal(1)
+const b = signal(2)
+
+effect(() => {
+  console.log(`a=${a()}, b=${b()}`)
+})
+// Logs once: "a=1, b=2"
+
+batch(() => {
+  a.set(10)
+  b.set(20)
+})
+// Logs once: "a=10, b=20"
+```
+
+Without batch, the effect would run twice (once for each signal update).
+
+### onCleanup
+
+Registers a cleanup function to run before an effect re-executes or is disposed.
+
+```ts
+import { signal, effect, onCleanup } from '@liteforge/core'
+
+const userId = signal(1)
+
+effect(() => {
+  const id = userId()
+  const controller = new AbortController()
+  
+  fetch(`/api/users/${id}`, { signal: controller.signal })
+    .then(r => r.json())
+    .then(console.log)
+  
+  onCleanup(() => {
+    controller.abort()
+  })
+})
+```
+
+## Types
+
+```ts
+import type {
+  Signal,
+  ReadonlySignal,
+  SignalOptions,
+  EffectFn,
+  DisposeFn,
+  EffectOptions,
+  ComputeFn,
+  ComputedOptions
+} from '@liteforge/core'
+```
+
+## Debug Utilities
+
+For integration with devtools:
+
+```ts
+import { enableDebug, disableDebug, createDebugBus } from '@liteforge/core'
+
+enableDebug()
+
+const bus = createDebugBus()
+bus.on('signal:update', (payload) => {
+  console.log(`Signal ${payload.name} changed to ${payload.value}`)
+})
+```
+
+## License
+
+MIT

package/dist/batch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * LiteForge Batch
+ *
+ * Batch multiple signal updates together to avoid redundant effect executions.
+ */
+/**
+ * Batch multiple signal updates together.
+ *
+ * Effects will only be notified once after the batch completes,
+ * even if multiple signals are updated. Supports nested batches.
+ *
+ * @param fn - Function containing signal updates to batch
+ *
+ * @example
+ * ```ts
+ * const firstName = signal('John');
+ * const lastName = signal('Doe');
+ *
+ * effect(() => {
+ *   console.log(firstName(), lastName());
+ * });
+ * // logs: "John Doe"
+ *
+ * batch(() => {
+ *   firstName.set('Jane');
+ *   lastName.set('Smith');
+ * });
+ * // logs: "Jane Smith" (only once, not twice)
+ * ```
+ */
+export declare function batch(fn: () => void): void;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAO1C"}

package/dist/batch.js

@@ -0,0 +1,41 @@
+/**
+ * LiteForge Batch
+ *
+ * Batch multiple signal updates together to avoid redundant effect executions.
+ */
+import { startBatch, endBatch } from './internals.js';
+/**
+ * Batch multiple signal updates together.
+ *
+ * Effects will only be notified once after the batch completes,
+ * even if multiple signals are updated. Supports nested batches.
+ *
+ * @param fn - Function containing signal updates to batch
+ *
+ * @example
+ * ```ts
+ * const firstName = signal('John');
+ * const lastName = signal('Doe');
+ *
+ * effect(() => {
+ *   console.log(firstName(), lastName());
+ * });
+ * // logs: "John Doe"
+ *
+ * batch(() => {
+ *   firstName.set('Jane');
+ *   lastName.set('Smith');
+ * });
+ * // logs: "Jane Smith" (only once, not twice)
+ * ```
+ */
+export function batch(fn) {
+    startBatch();
+    try {
+        fn();
+    }
+    finally {
+        endBatch();
+    }
+}
+//# sourceMappingURL=batch.js.map

package/dist/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,KAAK,CAAC,EAAc;IAClC,UAAU,EAAE,CAAC;IACb,IAAI,CAAC;QACH,EAAE,EAAE,CAAC;IACP,CAAC;YAAS,CAAC;QACT,QAAQ,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/cleanup.d.ts

@@ -0,0 +1,30 @@
+/**
+ * LiteForge Cleanup
+ *
+ * Register cleanup functions to run before an effect re-executes
+ * or when the effect is disposed.
+ */
+/**
+ * Register a cleanup function for the current effect.
+ *
+ * The cleanup function will be called:
+ * - Before the effect re-runs (when dependencies change)
+ * - When the effect is disposed
+ *
+ * @param fn - The cleanup function to register
+ * @throws Error if called outside of an effect
+ *
+ * @example
+ * ```ts
+ * effect(() => {
+ *   const handler = () => console.log(count());
+ *   window.addEventListener('resize', handler);
+ *
+ *   onCleanup(() => {
+ *     window.removeEventListener('resize', handler);
+ *   });
+ * });
+ * ```
+ */
+export declare function onCleanup(fn: () => void): void;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAE9C"}

package/dist/cleanup.js

@@ -0,0 +1,33 @@
+/**
+ * LiteForge Cleanup
+ *
+ * Register cleanup functions to run before an effect re-executes
+ * or when the effect is disposed.
+ */
+import { registerCleanup } from './internals.js';
+/**
+ * Register a cleanup function for the current effect.
+ *
+ * The cleanup function will be called:
+ * - Before the effect re-runs (when dependencies change)
+ * - When the effect is disposed
+ *
+ * @param fn - The cleanup function to register
+ * @throws Error if called outside of an effect
+ *
+ * @example
+ * ```ts
+ * effect(() => {
+ *   const handler = () => console.log(count());
+ *   window.addEventListener('resize', handler);
+ *
+ *   onCleanup(() => {
+ *     window.removeEventListener('resize', handler);
+ *   });
+ * });
+ * ```
+ */
+export function onCleanup(fn) {
+    registerCleanup(fn);
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../src/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,SAAS,CAAC,EAAc;IACtC,eAAe,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC"}

package/dist/computed.d.ts

@@ -0,0 +1,46 @@
+/**
+ * LiteForge Computed
+ *
+ * A Computed is a read-only signal derived from other signals.
+ * It lazily evaluates and caches its value until dependencies change.
+ */
+import type { ReadonlySignal } from './signal.js';
+/** Function that computes the derived value */
+export type ComputeFn<T> = () => T;
+/** Options for creating a computed value. */
+export interface ComputedOptions {
+    /** Debug label for DevTools. If not provided, an auto-generated ID is used. */
+    label?: string;
+    /**
+     * Mark computed as internal (DevTools-owned).
+     * Internal computeds don't emit debug events to avoid infinite loops.
+     * @internal
+     */
+    __internal?: boolean;
+}
+/**
+ * Create a computed (derived) signal.
+ *
+ * The computation only runs when the value is read AND dependencies have changed.
+ * The result is cached until a dependency changes.
+ *
+ * @param fn - Function that computes the derived value
+ * @param options - Optional configuration including debug label
+ * @returns A read-only signal
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ * const doubled = computed(() => count() * 2);
+ *
+ * doubled(); // → 0 (computed on first read)
+ * count.set(5);
+ * doubled(); // → 10 (recomputed because count changed)
+ * doubled(); // → 10 (cached, not recomputed)
+ *
+ * // With debug label
+ * const tripled = computed(() => count() * 3, { label: 'tripled' });
+ * ```
+ */
+export declare function computed<T>(fn: ComputeFn<T>, options?: ComputedOptions): ReadonlySignal<T>;
+//# sourceMappingURL=computed.d.ts.map

package/dist/computed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../src/computed.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAUlD,+CAA+C;AAC/C,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAEnC,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAChB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,CAAC,CAAC,CA0HnB"}

package/dist/computed.js

@@ -0,0 +1,144 @@
+/**
+ * LiteForge Computed
+ *
+ * A Computed is a read-only signal derived from other signals.
+ * It lazily evaluates and caches its value until dependencies change.
+ */
+import { observerStack, getCurrentObserver, notifySubscribers, } from './internals.js';
+import { generateDebugId, emitComputedRecalc, } from './debug.js';
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Create a computed (derived) signal.
+ *
+ * The computation only runs when the value is read AND dependencies have changed.
+ * The result is cached until a dependency changes.
+ *
+ * @param fn - Function that computes the derived value
+ * @param options - Optional configuration including debug label
+ * @returns A read-only signal
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ * const doubled = computed(() => count() * 2);
+ *
+ * doubled(); // → 0 (computed on first read)
+ * count.set(5);
+ * doubled(); // → 10 (recomputed because count changed)
+ * doubled(); // → 10 (cached, not recomputed)
+ *
+ * // With debug label
+ * const tripled = computed(() => count() * 3, { label: 'tripled' });
+ * ```
+ */
+export function computed(fn, options) {
+    let value;
+    let dirty = true; // Start dirty so first read computes
+    // Debug info
+    const debugLabel = options?.label;
+    const debugId = debugLabel ?? generateDebugId('computed');
+    const isInternal = options?.__internal === true;
+    // Subscribers to this computed (other effects/computeds that read us)
+    const subscribers = new Set();
+    // Map from execute function to tagged subscriber (for efficient removal)
+    const subscriberMap = new Map();
+    // Track our own dependencies
+    const observer = {
+        execute: markDirty,
+        cleanup: () => { }, // Computeds don't need cleanup
+        dependencies: new Set(),
+        isEffect: false, // Mark as computed for synchronous dirty propagation
+    };
+    /**
+     * Mark as dirty and notify downstream subscribers.
+     * Called when any upstream dependency changes.
+     */
+    function markDirty() {
+        if (!dirty) {
+            dirty = true;
+            // Notify our subscribers that we might have changed
+            // Computeds are notified synchronously, effects are scheduled
+            notifySubscribers(subscribers);
+        }
+    }
+    /**
+     * Recompute the value if dirty.
+     */
+    function recompute() {
+        // Clear old dependencies
+        for (const depSet of observer.dependencies) {
+            for (const sub of depSet) {
+                if (sub.fn === observer.execute) {
+                    depSet.delete(sub);
+                    break;
+                }
+            }
+        }
+        observer.dependencies.clear();
+        // Track new dependencies during computation
+        observerStack.push(observer);
+        const startTime = performance.now();
+        try {
+            value = fn();
+        }
+        finally {
+            observerStack.pop();
+        }
+        const duration = performance.now() - startTime;
+        // Emit recalc event (zero cost if debug not enabled, skip for internal)
+        if (!isInternal) {
+            emitComputedRecalc(debugId, debugLabel, value, duration);
+        }
+        dirty = false;
+    }
+    /**
+     * Read the computed value.
+     */
+    function read() {
+        // Subscribe the current observer to this computed
+        const currentObserver = getCurrentObserver();
+        if (currentObserver) {
+            let taggedSub = subscriberMap.get(currentObserver.execute);
+            if (!taggedSub) {
+                taggedSub = {
+                    fn: currentObserver.execute,
+                    isEffect: currentObserver.isEffect,
+                };
+                subscriberMap.set(currentObserver.execute, taggedSub);
+            }
+            subscribers.add(taggedSub);
+            currentObserver.dependencies.add(subscribers);
+        }
+        // Recompute if necessary
+        if (dirty) {
+            recompute();
+        }
+        return value;
+    }
+    /**
+     * Peek at the value without subscribing.
+     */
+    function peek() {
+        if (dirty) {
+            recompute();
+        }
+        return value;
+    }
+    // Attach peek method
+    read.peek = peek;
+    // Attach debug info (read-only)
+    Object.defineProperty(read, '__debugId', {
+        value: debugId,
+        writable: false,
+        enumerable: false,
+    });
+    Object.defineProperty(read, '__debugLabel', {
+        value: debugLabel,
+        writable: false,
+        enumerable: false,
+    });
+    return read;
+}
+//# sourceMappingURL=computed.js.map

package/dist/computed.js.map

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