@realglebivanov/reactive 1.0.0

package/.tool-versions

@@ -0,0 +1 @@
+nodejs 25.4.0

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Gleb Ivanov <realglebivanov@gmail.com>
+
+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,158 @@
+# Reactive
+
+## Quick Start
+
+```typescript
+import {
+    observable,
+    cond,
+    template,
+    iterable,
+    component,
+    mapObservable,
+    router,
+    tags,
+    dedupObservable
+} from "@realglebivanov/reactive";
+
+import { ReactiveArray } from "@realglebivanov/reactive";
+
+const LOREM = `
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+      Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+      Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.`;
+
+const { a, p, h1, h2, div, span, button, ul, li, img, input } = tags;
+
+const shoppingItems = new ReactiveArray([
+    { name: "milk", price$: observable("1.99") },
+    { name: "sour cream", price$: observable("2.99") },
+    { name: "cheese", price$: observable("0.99") }
+]);
+
+const counter = () => component({
+    cache: true,
+    props: { counter: "Counter" },
+    observables: () => ({
+        count$: observable(0),
+        hard$: observable(false),
+        veryHard$: observable(true)
+    }),
+    derivedObservables: ({ count$, hard$ }) => ({
+        imageSource$: mapObservable(
+            (hard) => hard ? "KashaHard.gif" : "Kasha.png",
+            dedupObservable(hard$)),
+        hexCounter$: mapObservable((x) => x.toString(2), count$)
+    }),
+    render: function ({ count$, hard$, veryHard$, imageSource$, hexCounter$ }) {
+        const onClick = () => {
+            count$.update((count) => count + 1);
+            hard$.update((hard) => !hard);
+        };
+
+        return div(
+            h2(cond({
+                if$: mapObservable(
+                    (hard, veryHard) => hard && veryHard, hard$, veryHard$),
+                then: "Rock hard, baby",
+                otherwise: "Wood needed"
+            })),
+            div(span(template`${this.props.counter}: ${hexCounter$}`)),
+            div(img("Kasha.png").att$("src", imageSource$).clk(onClick))
+        );
+    }
+});
+
+const shoppingForm = () => component({
+    render: () => div(
+        div(span('Name: '), input('text').att('id', 'itemName')),
+        div(span('Price: '), input('text').att('id', 'itemPrice')),
+        button(span('Add')).clk(() => {
+            const itemName = document.getElementById('itemName') as HTMLInputElement;
+            const itemPrice = document.getElementById('itemPrice') as HTMLInputElement;
+
+            if (itemName.value == "" || itemPrice.value == "") return;
+
+            shoppingItems.push({
+                name: itemName.value,
+                price$: observable(itemPrice.value)
+            });
+
+            itemName.value = "";
+            itemPrice.value = "";
+        })
+    )
+});
+
+const shoppingList = () => component({
+    observables: () => ({ shoppingItems$: shoppingItems.observable$ }),
+    render: ({ shoppingItems$ }) => div(
+        h2("Shopping items"),
+        ul(
+            iterable({
+                it$: shoppingItems$,
+                buildFn: (_, item) => li(span(template`${item.name} - ${item.price$}`)),
+                keyFn: (_, item) => item.name,
+            })
+        )
+    )
+});
+
+const exampleRouter = router({
+    "/": div(
+        h1("Grecha.js"),
+        div(a("Foo").att("href", "#/foo")),
+        div(a("Bar").att("href", "#/bar")),
+        counter(),
+        shoppingList(),
+        shoppingForm()
+    ),
+    "/foo": component({
+        observables: () => ({ count$: observable(0) }),
+        derivedObservables: ({ count$ }) => ({
+            paragraphStyle$: mapObservable(
+                (count) => `color: ${numberToHexColor(count * 999999)}`, count$)
+        }),
+        render: ({ count$, paragraphStyle$ }) => div(
+            h1("Foo"),
+            p(LOREM).att$("style", paragraphStyle$),
+            button("Change color").clk(() => count$.update((x) => x + 1)),
+            div(a("Home").att("href", "#")),
+        )
+    }),
+    "/bar": div(
+        h1("Bar"),
+        p(LOREM),
+        div(a("Home").att("href", "#"))
+    )
+}, { notFoundRoute: "/" });
+
+function numberToHexColor(number: number) {
+    let hex = (number % 0xffffff).toString(16);
+    while (hex.length < 6) hex = "0" + hex;
+    return "#" + hex;
+}
+
+exampleRouter.mount(document.getElementById('entry')!);
+exampleRouter.activate();
+
+```
+## Restrictions & Edge Cases
+
+### 1. Component Observables
+-  Subscriptions to observables declared outside of a component **will not be automatically cleaned up**. Users must manage them manually to avoid memory leaks.
+
+### 2. ReactiveArray
+- `ReactiveArray` is **primitive** and **not a full replacement for native arrays**.  
+- Only the following events are supported:
+  - `{ type: "replace", items: T[] }` — replaces the entire array
+  - `{ type: "append", items: T[] }` — appends items at the end
+  - `{ type: "remove", items: Map<number, T> }` — removes items at given indices
+  - `{ type: "replaceKeys", items: Map<number, T> }` — replaces items at specific indices  
+
+### 3. Iterable
+- Iterable expects a **reactive source** (`Observable<Event<T>>`) or a normal collection (`Array`/`Map`), which is automatically wrapped in a replace event.  
+
+### 5. Performance Considerations
+- For very large arrays or frequent updates, consider using **your own ReactiveArray-like implementation** that emit fine-grained events (`append`, `replaceKeys`, `remove`) instead of full replacements.  

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@realglebivanov/reactive",
+  "version": "1.0.0",
+  "description": "A simple and permissive observable-driven UI toolkit",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "reactive",
+    "observable",
+    "ui",
+    "toolkit",
+    "framework",
+    "typescript",
+    "no-deps",
+    "no-dependencies"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "serve": "npx serve dist/",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realglebivanov/reactive.git"
+  },
+  "author": "realglebivanov <realglebivanov@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/realglebivanov/reactive/issues"
+  },
+  "homepage": "https://github.com/realglebivanov/reactive#readme",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/public/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Grecha.js</title>
+</head>
+
+<body>
+  <div id="entry"></div>
+  <script src="./example.js" type="module"></script>
+</body>
+
+</html>

package/src/example.ts

@@ -0,0 +1,133 @@
+import {
+    observable,
+    cond,
+    template,
+    iterable,
+    component,
+    mapObservable,
+    router,
+    tags,
+    dedupObservable
+} from "@realglebivanov/reactive";
+
+import { ReactiveArray } from "@realglebivanov/reactive";
+
+const LOREM = `
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+      Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+      Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.`;
+
+const { a, p, h1, h2, div, span, button, ul, li, img, input } = tags;
+
+const shoppingItems = new ReactiveArray([
+    { name: "milk", price$: observable("1.99") },
+    { name: "sour cream", price$: observable("2.99") },
+    { name: "cheese", price$: observable("0.99") }
+]);
+
+const counter = () => component({
+    cache: true,
+    props: { counter: "Counter" },
+    observables: () => ({
+        count$: observable(0),
+        hard$: observable(false),
+        veryHard$: observable(true)
+    }),
+    derivedObservables: ({ count$, hard$ }) => ({
+        imageSource$: mapObservable(
+            (hard) => hard ? "KashaHard.gif" : "Kasha.png",
+            dedupObservable(hard$)),
+        hexCounter$: mapObservable((x) => x.toString(2), count$)
+    }),
+    render: function ({ count$, hard$, veryHard$, imageSource$, hexCounter$ }) {
+        const onClick = () => {
+            count$.update((count) => count + 1);
+            hard$.update((hard) => !hard);
+        };
+
+        return div(
+            h2(cond({
+                if$: mapObservable(
+                    (hard, veryHard) => hard && veryHard, hard$, veryHard$),
+                then: "Rock hard, baby",
+                otherwise: "Wood needed"
+            })),
+            div(span(template`${this.props.counter}: ${hexCounter$}`)),
+            div(img("Kasha.png").att$("src", imageSource$).clk(onClick))
+        );
+    }
+});
+
+const shoppingForm = () => component({
+    render: () => div(
+        div(span('Name: '), input('text').att('id', 'itemName')),
+        div(span('Price: '), input('text').att('id', 'itemPrice')),
+        button(span('Add')).clk(() => {
+            const itemName = document.getElementById('itemName') as HTMLInputElement;
+            const itemPrice = document.getElementById('itemPrice') as HTMLInputElement;
+
+            if (itemName.value == "" || itemPrice.value == "") return;
+
+            shoppingItems.push({
+                name: itemName.value,
+                price$: observable(itemPrice.value)
+            });
+
+            itemName.value = "";
+            itemPrice.value = "";
+        })
+    )
+});
+
+const shoppingList = () => component({
+    observables: () => ({ shoppingItems$: shoppingItems.observable$ }),
+    render: ({ shoppingItems$ }) => div(
+        h2("Shopping items"),
+        ul(
+            iterable({
+                it$: shoppingItems$,
+                buildFn: (_, item) => li(span(template`${item.name} - ${item.price$}`)),
+                keyFn: (_, item) => item.name,
+            })
+        )
+    )
+});
+
+const exampleRouter = router({
+    "/": div(
+        h1("Grecha.js"),
+        div(a("Foo").att("href", "#/foo")),
+        div(a("Bar").att("href", "#/bar")),
+        counter(),
+        shoppingList(),
+        shoppingForm()
+    ),
+    "/foo": component({
+        observables: () => ({ count$: observable(0) }),
+        derivedObservables: ({ count$ }) => ({
+            paragraphStyle$: mapObservable(
+                (count) => `color: ${numberToHexColor(count * 999999)}`, count$)
+        }),
+        render: ({ count$, paragraphStyle$ }) => div(
+            h1("Foo"),
+            p(LOREM).att$("style", paragraphStyle$),
+            button("Change color").clk(() => count$.update((x) => x + 1)),
+            div(a("Home").att("href", "#")),
+        )
+    }),
+    "/bar": div(
+        h1("Bar"),
+        p(LOREM),
+        div(a("Home").att("href", "#"))
+    )
+}, { notFoundRoute: "/" });
+
+function numberToHexColor(number: number) {
+    let hex = (number % 0xffffff).toString(16);
+    while (hex.length < 6) hex = "0" + hex;
+    return "#" + hex;
+}
+
+exampleRouter.mount(document.getElementById('entry')!);
+exampleRouter.activate();

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './tag';
+export * from './observables';
+export * from './nodes';
+export * from './router';
+export * from './task';
+export * from './reactive';

package/src/lifecycle.ts

@@ -0,0 +1,44 @@
+export interface Lifecycle {
+    mount(parentNode: Node): void,
+    activate(): void,
+    deactivate(): void,
+    unmount(): void
+}
+
+export enum ReactiveNodeStatus {
+    Active,
+    Inactive,
+    Mounted,
+    Unmounted
+};
+
+export const buildLifecycleHooks = (handlers: Lifecycle[]): Lifecycle => {
+    let status = ReactiveNodeStatus.Unmounted;
+
+    return {
+        mount: (parentNode: Node) => {
+            if (status !== ReactiveNodeStatus.Unmounted)
+                return console.warn(`Mounting in status ${ReactiveNodeStatus[status]}`);
+            for (const handler of handlers) handler.mount(parentNode);
+            status = ReactiveNodeStatus.Mounted;
+        },
+        activate: () => {
+            if (status !== ReactiveNodeStatus.Mounted && status !== ReactiveNodeStatus.Inactive)
+                return console.warn(`Activating in status ${ReactiveNodeStatus[status]}`);
+            for (const handler of handlers) handler.activate();
+            status = ReactiveNodeStatus.Active;
+        },
+        deactivate: () => {
+            if (status !== ReactiveNodeStatus.Active)
+                return console.warn(`Deactivating in status ${ReactiveNodeStatus[status]}`);
+            for (const handler of handlers) handler.deactivate()
+            status = ReactiveNodeStatus.Inactive;
+        },
+        unmount() {
+            if (status !== ReactiveNodeStatus.Inactive)
+                return console.warn(`Unmounting in status ${ReactiveNodeStatus[status]}`);
+            for (const handler of handlers) handler.unmount();
+            status = ReactiveNodeStatus.Unmounted;
+        },
+    };
+};

package/src/nodes/component.ts

@@ -0,0 +1,107 @@
+import {
+    scopedObservable,
+    ScopedObservable,
+    type Observable
+} from "../observables";
+import { toReactiveNode, type ReactiveNode } from "./reactive";
+
+type Observables = Record<string, Observable<any>>;
+type ScopedObservables<T extends Observables> = {
+    [K in keyof T]: ScopedObservable<T[K]>
+};
+
+type RenderFn<O extends Observables, T extends Node, P> =
+    (this: Context<T, P>, observables: ScopedObservables<O>) => ReactiveNode<T>;
+
+type UserOpts<O1 extends Observables, O2 extends Observables, T extends Node, P> =
+    Partial<Opts<O1, O2, T, P>> & { render: RenderFn<O1 & O2, T, P> };
+
+type Opts<O1 extends Observables, O2 extends Observables, T extends Node, P> = {
+    render: RenderFn<O1 & O2, T, P>,
+    observables: () => O1,
+    derivedObservables: (observables: O1) => O2,
+    cache: boolean,
+    props: P
+};
+
+const defaultOpts = {
+    observables: () => ({}),
+    derivedObservables: () => ({}),
+    cache: false,
+    props: {}
+};
+
+export const component = <
+    O1 extends Observables,
+    O2 extends Observables,
+    T extends Node,
+    P
+>(opts: UserOpts<O1, O2, T, P>): ReactiveNode<Comment> => new Component<O1, O2, T, P>(
+    Object.assign({}, defaultOpts, opts)
+).toReactiveNode();
+
+class Context<T extends Node, P> {
+    node: ReactiveNode<T> | undefined;
+    constructor(public parent: Node, public props: P) { }
+}
+
+class Component<O1 extends Observables, O2 extends Observables, T extends Node, P> {
+    private node: ReactiveNode<T> | undefined;
+    private observables: ScopedObservables<O1 & O2> | undefined;
+    private context: Context<T, P> | undefined;
+
+    constructor(private opts: Opts<O1, O2, T, P>) { }
+
+    toReactiveNode() {
+        return toReactiveNode(document.createComment('Component'), [{
+            mount: (parentNode: Node) => {
+                if (this.node === undefined || !this.opts.cache)
+                    this.setupNode(parentNode);
+                this.node?.mount(parentNode);
+            },
+            activate: () => this.node?.activate(),
+            deactivate: () => {
+                this.node?.deactivate();
+                if (this.observables === undefined) return;
+                for (const key in this.observables)
+                    this.observables[key as keyof O1 & O2].unsubscribeAll();
+            },
+            unmount: () => {
+                this.node?.unmount();
+                if (!this.opts.cache) this.cleanUp();
+            }
+        }]);
+    }
+
+    private setupNode(parentNode: Node) {
+        this.observables = this.buildObservables();
+        this.context = new Context(parentNode, this.opts.props);
+        this.node = this.opts.render.call(this.context, this.observables);
+        this.context.node = this.node;
+    }
+
+    private cleanUp() {
+        if (this.context !== undefined) this.context.node = undefined;
+        this.node = undefined;
+        this.observables = undefined;
+    }
+
+    private buildObservables() {
+        const coreObservables = this.opts.observables();
+        const derivedObservables = this.opts.derivedObservables(coreObservables);
+        const observables =
+            Object.assign({}, coreObservables, derivedObservables);
+        return this.toScoped<O1 & O2>(observables);
+    }
+
+    private toScoped<O extends Observables>(observables: O): ScopedObservables<O> {
+        const scopedObservables: Partial<ScopedObservables<O>> = {};
+
+        for (const key in observables) {
+            const k: keyof O = key;
+            scopedObservables[k] = scopedObservable(observables[k]);
+        }
+
+        return scopedObservables as ScopedObservables<O>;
+    }
+}

package/src/nodes/cond.ts

@@ -0,0 +1,79 @@
+import { dedupObservable, type Observable } from "../observables";
+import { reactiveTextNode, toReactiveNode, type ReactiveNode } from "./reactive";
+
+type ReactiveNodeBuilder<T extends Node> = (() => ReactiveNode<T>);
+
+type Params<A extends Node, B extends Node> = {
+    if$: Observable<boolean>,
+    then: ReactiveNodeBuilder<A> | string,
+    otherwise: ReactiveNodeBuilder<B> | string
+};
+
+type CurrentNode<A extends Node, B extends Node> =
+    ReactiveNode<A> | ReactiveNode<B> | ReactiveNode<Text>;
+
+export const cond = <A extends Node, B extends Node>(
+    { if$, then, otherwise }: Params<A, B>
+): ReactiveNode<Comment> => new Cond<A, B>(
+    dedupObservable(if$),
+    then,
+    otherwise
+).toReactiveNode();
+
+class Cond<A extends Node, B extends Node> {
+    private id = Symbol('Cond');
+    private currentNode: CurrentNode<A, B> | undefined;
+
+    constructor(
+        private if$: Observable<boolean>,
+        private then: ReactiveNodeBuilder<A> | string,
+        private otherwise: ReactiveNodeBuilder<B> | string
+    ) { }
+
+    toReactiveNode() {
+        const anchor = document.createComment('Cond');
+        const updateFn = (value: boolean) => this.updateNode(anchor, value);
+
+        return toReactiveNode(anchor, [{
+            mount: (parentNode: Node) => parentNode.appendChild(anchor),
+            activate: () => this.if$.subscribeInit(this.id, updateFn),
+            deactivate: () => {
+                this.if$.unsubscribe(this.id);
+                this.currentNode?.deactivate();
+            },
+            unmount: () => {
+                this.currentNode?.unmount();
+                this.currentNode = undefined;
+                anchor.remove();
+            }
+        }]);
+    }
+
+    private updateNode(anchor: Node, value: boolean) {
+        const newNode = value ?
+            this.buildNode<A>(this.then) :
+            this.buildNode<B>(this.otherwise);
+        try {
+            this.switchNode(anchor, newNode);
+        } catch (e) {
+            console.error(e);
+        }
+    }
+
+    private buildNode<T extends Node>(node: string | ReactiveNodeBuilder<T>) {
+        if (typeof (node) === 'function')
+            return node();
+        if (typeof (node) === 'string')
+            return reactiveTextNode(node);
+
+        throw new Error('Then/otherwise should be either string or function');
+    }
+
+    private switchNode(anchor: Node, newNode: CurrentNode<A, B>) {
+        this.currentNode?.deactivate();
+        this.currentNode?.unmount();
+        newNode.mount(anchor.parentNode!);
+        newNode.activate();
+        this.currentNode = newNode;
+    }
+}

package/src/nodes/index.ts

@@ -0,0 +1,7 @@
+export * from './component';
+export * from './cond';
+export * from './iterable';
+export * from './iterable/collection';
+export * from './iterable/item';
+export * from './template';
+export * from './reactive';