avosignals 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anatoli Radulov
+
+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,150 @@
+# avosignals
+
+A lightweight, type-safe reactive state management library for TypeScript. It features automatic dependency tracking, efficient updates, and first-class support for **Lit** components.
+
+# Features
+
+- ⚡️ **Fine-Grained Reactivity**: Updates only what needs to change.
+- 🛡️ **Circular Dependency Protection**: Detects and prevents infinite loops during computation.
+
+- 🧹**Automatic Garbage Collection**: Uses `WeakRef` for internal computed subscriptions to prevent memory leaks in derived state graphs.
+
+- 🔒 **Safety Guardrails**: Prevents state mutations during reactive evaluations to ensure data consistency.
+
+- 🔥 **Lit Integration**: Includes a specific controller (`SignalWatcher`) to make Lit components reactive automatically.
+
+# Instalation
+
+### Node / NPM
+```bash
+npm install avosignals
+```
+
+### Browser / Esm.sh
+```html
+<script type="module">
+    import { Signal, Computed, effect } from "https://esm.sh/avosignals"
+</script>
+```
+
+# Core Concepts
+1. Signals
+
+Signals are the atoms of state. They hold a value and notify subscribers when that value changes.
+
+```Typescript
+import { Signal } from 'avosignals';
+
+const count = new Signal(0, 'count');
+
+console.log(count.get()); // 0
+
+count.set(1);
+count.update(c => c + 1); // 2
+```
+
+2. Computed
+
+Computed values are derived signals. They depend on other signals and re-evaluate only when their dependencies change. They are lazy—they only recalculate when read.
+
+```Typescript
+import { Signal, Computed } from 'avosignals';
+
+const count = new Signal(1);
+const double = new Computed(() => count.get() * 2, 'double');
+
+console.log(double.get()); // 2
+
+count.set(10);
+console.log(double.get()); // 20
+```
+
+3. Effects
+
+Effects are side effects that run automatically whenever the signals they access change. Useful for logging, manual DOM manipulation, or syncing with external APIs.
+
+```Typescript
+import { Signal, effect } from 'avosignals';
+
+const count = new Signal(0);
+
+const dispose = effect(() => {
+    console.log(`The count is now ${count.get()}`);
+    
+    // Optional cleanup function (runs before next execution or on dispose)
+    return () => console.log('Cleaning up...');
+});
+
+count.set(1); 
+// Logs: "The count is now 1"
+
+dispose();
+// Logs: 'Cleaning up...'
+```
+
+# Usage with Lit
+
+`avosignals` was built with Lit in mind. The `SignalWatcher` class hooks into the Lit lifecycle to automatically track signals accessed during render. Its core design is to allow for production ready signals which can be easily replaced with Lit's official signals once **TC39 signals** becomes mainstream and production ready.
+
+# The `SignalWatcher` Controller
+
+You do not need to manually subscribe to signals. simply add the controller, and any signal read inside `render()` will trigger a component update when it changes.
+
+```Typescript
+import { LitElement, html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import { Signal, SignalWatcher } from 'avosignals';
+
+// Shared state
+const counter = new Signal(0);
+
+@customElement('my-counter')
+export class MyCounter extends LitElement {
+    // 1. Register the watcher
+    private watcher = new SignalWatcher(this);
+
+    render() {
+        // 2. Access signals directly. 
+        // The component now auto-subscribes to 'counter'.
+        return html`
+            <p>Count: ${counter.get()}</p>
+            <button @click=${() => counter.update(c => c + 1)}>
+                Increment
+            </button>
+        `;
+    }
+}
+```
+
+# Advanced Architecture
+
+### Memory Management (WeakRefs)
+
+Unlike many other signal libraries, `Computed` nodes in avosignals hold weak references to their subscribers where possible. This means if you create a derived signal but stop referencing it in your application, JavaScript's Garbage Collector can clean it up, even if the source signal is still active. This prevents the common "detached listener" memory leaks found in observer patterns.
+
+### Cycle Detection
+
+`avosignals` maintains a stack of active consumers. If a computed value attempts to read itself during its own evaluation **(A -> B -> A)**, the library throws a descriptive error helping you identify the cycle immediately.
+
+### Read/Write Consistency
+
+To ensure unidirectional data flow, `avosignals` forbids writing to a `Signal` while a `Computed` value is currently being evaluated. This prevents side-effects from occurring during the "read" phase of your application loop.
+
+# API Reference
+
+`Signal<T>`
+
+- `constructor(initial: T, name?: string)`
+- `get(): T`: Returns current value and tracks dependency.
+- `set(value: T)`: Updates value and notifies listeners.
+- `update(fn: (prev: T) => T)`: Convenience method for updating based on previous value.
+
+`Computed<T>`
+- `constructor(fn: () => T, name?: string)`
+- `get(): T`: Evaluates (if dirty) and returns the value.
+
+`effect`
+- `effect(fn: () => void | cleanupFn)`: Runs immediately and tracks dependencies. Returns a dispose function.
+
+# License
+MIT

package/dist/avosignals-util.d.ts

@@ -0,0 +1,4 @@
+import { Signal } from "./avosignals";
+export declare function singalToJSON(value: Signal<any>): {
+    [key: string]: any;
+};

package/dist/avosignals-util.js

@@ -0,0 +1,31 @@
+import { Signal } from "./avosignals";
+//TODO - function which returns JSON with possibly nested Signals resolved
+export function singalToJSON(value) {
+    const result = {};
+    const val = value.get();
+    if (Array.isArray(val)) {
+        return val.map(item => {
+            if (item instanceof Signal) {
+                return singalToJSON(item);
+            }
+            else {
+                return item;
+            }
+        });
+    }
+    else if (typeof val === 'object' && val !== null) {
+        for (const key in val) {
+            const item = val[key];
+            if (item instanceof Signal) {
+                result[key] = singalToJSON(item);
+            }
+            else {
+                result[key] = item;
+            }
+        }
+        return result;
+    }
+    else {
+        return val;
+    }
+}

package/dist/avosignals.d.ts

@@ -0,0 +1,53 @@
+import type { LitElement } from "lit";
+type Job = () => void;
+type Unsubscribe = () => void;
+interface Debuggable {
+    _debugParent?: Watcher;
+}
+interface Watcher extends Debuggable {
+    track(signal: Observable<unknown>): void;
+}
+declare abstract class Observable<T> {
+    #private;
+    name?: string;
+    constructor(initial: T, name?: string);
+    protected _get(): T;
+    protected _set(next: T): boolean;
+    subscribe(fn: Job, weak?: boolean): Unsubscribe;
+    _notify(): void;
+    get id(): number;
+    get previousValue(): T | undefined;
+    toString(): string;
+}
+export declare class Signal<T> extends Observable<T> {
+    #private;
+    constructor(initial: T, name?: string);
+    static get activeConsumer(): Watcher;
+    static push(consumer: Watcher): void;
+    static pop(): void;
+    get(): T;
+    set(value: T): void;
+    update(fn: (current: T) => T): void;
+}
+export declare class Computed<T> extends Observable<T> implements Watcher {
+    #private;
+    _debugParent: Watcher | undefined;
+    constructor(fn: () => T, name?: string, options?: {
+        weak?: boolean;
+    });
+    track(signal: Observable<unknown>): void;
+    dispose(): void;
+    get(): T;
+    subscribe(fn: Job, weak?: boolean): Unsubscribe;
+}
+export declare function effect(fn: () => (void | (() => void)), name?: string): () => void;
+export declare class SignalWatcher implements Watcher {
+    #private;
+    _debugParent: Watcher | undefined;
+    constructor(host: LitElement);
+    track(signal: Observable<unknown>): void;
+    hostUpdate(): void;
+    hostUpdated(): void;
+    hostDisconnected(): void;
+}
+export {};

package/dist/avosignals.js

@@ -0,0 +1,232 @@
+let __DEV__ = true; //TODO - add logic to detect debug query param
+function safe_not_equal(a, b) {
+    return a != a
+        ? b == b
+        : a !== b || ((a && typeof a === 'object') || typeof a === 'function');
+}
+function isWeakRef(value) {
+    return value && typeof value.deref === 'function';
+}
+class Observable {
+    static #nextId = 0;
+    #value;
+    #previousValue;
+    #subs = new Set();
+    #id = Observable.#nextId++;
+    name;
+    constructor(initial, name) {
+        this.#value = initial;
+        this.#previousValue = initial;
+        this.name = name;
+    }
+    _get() {
+        if (Signal.activeConsumer) {
+            Signal.activeConsumer.track(this);
+        }
+        return this.#value;
+    }
+    _set(next) {
+        if (!safe_not_equal(next, this.#value))
+            return false;
+        this.#previousValue = this.#value;
+        this.#value = next;
+        this._notify();
+        return true;
+    }
+    subscribe(fn, weak = false) {
+        let entry = fn;
+        if (weak) {
+            entry = new WeakRef(fn);
+        }
+        this.#subs.add(entry);
+        return () => this.#subs.delete(entry);
+    }
+    _notify() {
+        const subs = [...this.#subs];
+        for (const entry of subs) {
+            let job;
+            if (isWeakRef(entry)) {
+                job = entry.deref();
+                // If the object is garbage collected, remove the dead link
+                if (!job) {
+                    this.#subs.delete(entry);
+                    continue;
+                }
+            }
+            else {
+                job = entry;
+            }
+            job();
+        }
+    }
+    get id() {
+        return this.#id;
+    }
+    get previousValue() {
+        return this.#previousValue;
+    }
+    toString() {
+        return this.name
+            ? `${this.constructor.name}(${this.name})`
+            : `${this.constructor.name}#${this.id}`;
+    }
+}
+export class Signal extends Observable {
+    static #stack = [];
+    constructor(initial, name) {
+        super(initial, name);
+    }
+    static get activeConsumer() {
+        return this.#stack[this.#stack.length - 1];
+    }
+    static push(consumer) {
+        if (__DEV__) {
+            consumer._debugParent = this.activeConsumer;
+        }
+        this.#stack.push(consumer);
+    }
+    static pop() {
+        if (__DEV__ && !this.#stack.length) {
+            throw new Error('Signal.pop() without matching push()');
+        }
+        this.#stack.pop();
+    }
+    get() {
+        return this._get();
+    }
+    set(value) {
+        if (__DEV__ && Signal.activeConsumer) {
+            throw new Error(`Signal write during reactive evaluation:\n` +
+                `  writing ${this}\n` +
+                `  while computing ${Signal.activeConsumer}`);
+        }
+        this._set(value);
+    }
+    update(fn) {
+        this.set(fn(this.get()));
+    }
+}
+export class Computed extends Observable {
+    #fn;
+    #dirty = true;
+    #computing = false;
+    #deps = new Map();
+    _debugParent;
+    #weak;
+    // 1. Create a stable, bound reference to the notification logic
+    #notifyCallback = () => {
+        if (this.#dirty)
+            return;
+        this.#dirty = true;
+        this._notify();
+    };
+    constructor(fn, name, options) {
+        super(undefined, name);
+        this.#fn = fn;
+        // Default to TRUE (Weak) for standard computeds to prevent leaks
+        this.#weak = options?.weak ?? true;
+    }
+    track(signal) {
+        if (this.#deps.has(signal))
+            return;
+        // 2. Subscribe using the STABLE callback and WEAK flag
+        const unsub = signal.subscribe(this.#notifyCallback, this.#weak);
+        this.#deps.set(signal, unsub);
+    }
+    dispose() {
+        this.#cleanup();
+    }
+    #cleanup() {
+        for (const unsub of this.#deps.values())
+            unsub();
+        this.#deps.clear();
+    }
+    get() {
+        if (Signal.activeConsumer) {
+            Signal.activeConsumer.track(this);
+        }
+        if (!this.#dirty)
+            return this._get();
+        if (this.#computing) {
+            throw new Error(`Cycle detected in ${this}\n` +
+                `↳ while computing ${this._debugParent ?? 'root'}`);
+        }
+        this.#computing = true;
+        this.#cleanup();
+        Signal.push(this);
+        try {
+            const value = this.#fn();
+            this._set(value);
+        }
+        finally {
+            Signal.pop();
+            this.#dirty = false;
+            this.#computing = false;
+        }
+        return this._get();
+    }
+    subscribe(fn, weak = false) {
+        const unsub = super.subscribe(fn, weak);
+        //ensure we don't affect tracking
+        if (!Signal.activeConsumer)
+            this.get();
+        return unsub;
+    }
+}
+export function effect(fn, name) {
+    let cleanup;
+    const computer = new Computed(() => {
+        if (typeof cleanup === 'function')
+            cleanup();
+        cleanup = fn();
+    }, name, { weak: false });
+    const unsub = computer.subscribe(() => {
+        computer.get();
+    });
+    computer.get();
+    return () => {
+        unsub();
+        computer.dispose();
+        if (typeof cleanup === 'function')
+            cleanup();
+    };
+}
+// Lit
+export class SignalWatcher {
+    #host;
+    #deps = new Map();
+    _debugParent;
+    #active = false;
+    constructor(host) {
+        this.#host = host;
+        host.addController(this);
+    }
+    track(signal) {
+        if (this.#deps.has(signal))
+            return;
+        this.#deps.set(signal, signal.subscribe(() => this.#host.requestUpdate()));
+    }
+    hostUpdate() {
+        for (const unsub of this.#deps.values())
+            unsub();
+        this.#deps.clear();
+        Signal.push(this);
+        this.#active = true;
+    }
+    hostUpdated() {
+        if (this.#active) {
+            Signal.pop();
+            this.#active = false;
+        }
+    }
+    hostDisconnected() {
+        for (const unsub of this.#deps.values())
+            unsub();
+        this.#deps.clear();
+        // optional safety if the component disconnects mid-render
+        if (this.#active) {
+            Signal.pop();
+            this.#active = false;
+        }
+    }
+}

package/dist/singal-watch.d.ts

@@ -0,0 +1,8 @@
+import { LitElement } from "lit";
+import { Signal, SignalWatcher } from "./avosignals";
+export declare class SignalWatch extends LitElement {
+    watcher: SignalWatcher;
+    accessor signals: Signal<unknown>[];
+    _subscribers: (() => void)[];
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/singal-watch.js

@@ -0,0 +1,23 @@
+import { LitElement, html } from "lit";
+import { SignalWatcher } from "./avosignals";
+import { customElement, property } from "lit/decorators.js";
+import { singalToJSON } from "./avosignals-util";
+@customElement("signal-watch")
+export class SignalWatch extends LitElement {
+    watcher = new SignalWatcher(this);
+    @property()
+    accessor signals = [];
+    _subscribers = [];
+    render() {
+        // JSON viewer is included in storybook-head
+        // also see https://github.com/alenaksu/json-viewer
+        return html `
+            ${this.signals.map(signal => html `
+                <div>
+                    <pre>Signal [${signal.name || 'unnamed_' + signal.id}]</pre>
+                    <json-viewer .data=${singalToJSON(signal)}></json-viewer>
+                </div>
+                `)}
+        `;
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "avosignals",
+  "version": "1.0.0",
+  "description": "A lightweight signaling library for web components and modern web applications with Lit integration.",
+  "keywords": [
+    "signals",
+    "events",
+    "typescript",
+    "observer",
+    "reactive"
+  ],
+  "type": "module",
+  "main": "dist/avosignals.js",
+  "types": "dist/avosignals.d.ts",
+  "files": [
+    "dist", "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Anatoli Radulov",
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.4.0",
+    "@vitest/coverage-v8": "^1.4.0",
+    "lit": "3.3.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anatolipr/avos.git"
+  },
+  "bugs": {
+    "url": "https://github.com/anatolipr/avos/issues"
+  },
+  "license": "MIT"
+}