@esportsplus/reactivity 0.22.3 → 0.23.1

package/readme.md

@@ -1,2 +1,276 @@
-https://github.com/milomg/r3
-https://github.com/stackblitz/alien-signals
+# @esportsplus/reactivity
+
+A fine-grained reactivity system with compile-time transformations. Write reactive code with natural JavaScript syntax while the compiler generates optimized signal-based code.
+
+## Installation
+
+```bash
+pnpm add @esportsplus/reactivity
+```
+
+## Core Concepts
+
+The library provides a `reactive()` function that acts as a compile-time macro. At build time, transformer plugins convert `reactive()` calls into optimized signal/computed primitives.
+
+### Reactive Primitives
+
+```typescript
+import { reactive, effect } from '@esportsplus/reactivity';
+
+// Signals - reactive values
+let count = reactive(0);
+let name = reactive('John');
+
+// Read values naturally
+console.log(count);  // 0
+console.log(name);   // 'John'
+
+// Write with simple assignment
+count = 10;
+name = 'Jane';
+
+// Compound assignments work
+count += 5;
+count++;
+
+// Computed values - derived from other reactive values
+let doubled = reactive(() => count * 2);
+console.log(doubled);  // 30
+```
+
+### Reactive Objects
+
+```typescript
+import { reactive } from '@esportsplus/reactivity';
+
+let user = reactive({
+    age: 25,
+    name: 'John',
+    // Computed properties are arrow functions
+    canVote: () => user.age >= 18
+});
+
+console.log(user.name);     // 'John'
+console.log(user.canVote);  // true
+
+user.age = 17;
+console.log(user.canVote);  // false
+
+// Cleanup resources
+user.dispose();
+```
+
+### Reactive Arrays
+
+```typescript
+import { reactive } from '@esportsplus/reactivity';
+
+let state = reactive({
+    items: [1, 2, 3],
+    total: () => state.items.reduce((a, b) => a + b, 0)
+});
+
+console.log(state.total);  // 6
+
+state.items.push(4, 5);
+console.log(state.total);  // 15
+
+// Listen to array events
+state.items.on('push', ({ items }) => {
+    console.log('Added:', items);
+});
+```
+
+### Effects
+
+```typescript
+import { effect, reactive } from '@esportsplus/reactivity';
+
+let count = reactive(0);
+
+let cleanup = effect(() => {
+    console.log('Count is:', count);
+});
+
+count = 1;  // logs: Count is: 1
+count = 2;  // logs: Count is: 2
+
+cleanup();  // stops the effect
+```
+
+## Transformer Plugins
+
+The library requires a build-time transformer to convert `reactive()` calls into optimized code. Three plugins are available:
+
+### Vite Plugin
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { plugin as reactivity } from '@esportsplus/reactivity/plugins/vite';
+
+export default defineConfig({
+    plugins: [
+        reactivity()
+    ]
+});
+```
+
+### esbuild Plugin
+
+```typescript
+import esbuild from 'esbuild';
+import reactivity from '@esportsplus/reactivity/plugins/esbuild';
+
+await esbuild.build({
+    entryPoints: ['src/index.ts'],
+    bundle: true,
+    outfile: 'dist/index.js',
+    plugins: [
+        reactivity()
+    ]
+});
+```
+
+### TypeScript Custom Transformer
+
+For direct TypeScript compilation using `ttsc` or `ts-patch`:
+
+```json
+// tsconfig.json
+{
+    "compilerOptions": {
+        "plugins": [
+            { "transform": "@esportsplus/reactivity/plugins/tsc" }
+        ]
+    }
+}
+```
+
+## Plugin Options
+
+All plugins accept the same options:
+
+```typescript
+interface TransformOptions {
+    // Inject automatic disposal tracking (experimental)
+    autoDispose?: boolean;
+}
+```
+
+Example with options:
+
+```typescript
+// vite.config.ts
+import { plugin as reactivity } from '@esportsplus/reactivity/plugins/vite';
+
+export default defineConfig({
+    plugins: [
+        reactivity({ autoDispose: true })
+    ]
+});
+```
+
+## How It Works
+
+The transformer converts your code at compile time:
+
+**Input:**
+```typescript
+let count = reactive(0);
+let doubled = reactive(() => count * 2);
+
+count = 5;
+console.log(doubled);
+```
+
+**Output:**
+```typescript
+import { computed, read, set, signal } from '@esportsplus/reactivity';
+
+let count = signal(0);
+let doubled = computed(() => read(count) * 2);
+
+set(count, 5);
+console.log(read(doubled));
+```
+
+Reactive objects are transformed into classes:
+
+**Input:**
+```typescript
+let user = reactive({
+    name: 'John',
+    greeting: () => `Hello, ${user.name}`
+});
+```
+
+**Output:**
+```typescript
+class ReactiveObject_1 {
+    #name = signal('John');
+    #greeting = null;
+
+    get name() { return read(this.#name); }
+    set name(v) { set(this.#name, v); }
+    get greeting() { return read(this.#greeting ??= computed(() => `Hello, ${this.name}`)); }
+
+    dispose() {
+        if (this.#greeting) dispose(this.#greeting);
+    }
+}
+
+let user = new ReactiveObject_1();
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `reactive(value)` | Creates a signal from a primitive value |
+| `reactive(() => expr)` | Creates a computed value |
+| `reactive({...})` | Creates a reactive object with signals and computeds |
+| `reactive([...])` | Creates a reactive array |
+| `effect(fn)` | Runs a function that re-executes when dependencies change |
+| `root(fn)` | Creates an untracked scope for effects |
+| `onCleanup(fn)` | Registers a cleanup function for the current effect |
+
+### Low-Level Functions
+
+These are typically only used by the transformer output:
+
+| Function | Description |
+|----------|-------------|
+| `signal(value)` | Creates a raw signal |
+| `computed(fn)` | Creates a raw computed |
+| `read(node)` | Reads a signal or computed value |
+| `set(signal, value)` | Sets a signal value |
+| `dispose(computed)` | Disposes a computed and its dependencies |
+
+### Type Guards
+
+| Function | Description |
+|----------|-------------|
+| `isSignal(value)` | Checks if value is a Signal |
+| `isComputed(value)` | Checks if value is a Computed |
+
+## ReactiveArray Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `clear` | `undefined` | Array was cleared |
+| `concat` | `{ items: T[] }` | Items were concatenated |
+| `pop` | `{ item: T }` | Item was popped |
+| `push` | `{ items: T[] }` | Items were pushed |
+| `reverse` | `undefined` | Array was reversed |
+| `set` | `{ index, item }` | Item was set at index |
+| `shift` | `{ item: T }` | Item was shifted |
+| `sort` | `{ order: number[] }` | Array was sorted |
+| `splice` | `{ start, deleteCount, items }` | Array was spliced |
+| `unshift` | `{ items: T[] }` | Items were unshifted |
+
+## License
+
+MIT

package/src/constants.ts

@@ -44,4 +44,4 @@ export {
     STATE_IN_HEAP,
     STATE_NONE,
     STATE_RECOMPUTING
-};
+};

package/src/index.ts

@@ -1,4 +1,4 @@
-export { default as reactive } from './reactive';
 export { STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED } from './constants';
+export { default as reactive } from './reactive';
 export * from './system';
 export * from './types';

package/src/reactive/array.ts

@@ -1,6 +1,7 @@
 import { isArray } from '@esportsplus/utilities';
-import { REACTIVE_ARRAY } from '~/constants';
-import { isReactiveObject } from './object';
+import { read, set, signal } from '~/system';
+import { REACTIVE_ARRAY, REACTIVE_OBJECT } from '~/constants';
+import type { Signal } from '~/types';
 
 
 type Events<T> = {
@@ -43,17 +44,46 @@ type Listener<V> = {
 type Listeners = Record<string, (Listener<any> | null)[]>;
 
 
+function isReactiveObject(value: unknown): value is { dispose(): void } {
+    return value !== null && typeof value === 'object' && (value as any)[REACTIVE_OBJECT] === true;
+}
+
+
 class ReactiveArray<T> extends Array<T> {
+    private _length: Signal<number>;
+
     listeners: Listeners = {};
 
 
     constructor(...items: T[]) {
         super(...items);
+        this._length = signal(items.length);
+    }
+
+
+    $length() {
+        return read(this._length);
     }
 
+    $set(i: number, value: T) {
+        let prev = this[i];
+
+        if (prev === value) {
+            return;
+        }
+
+        this[i] = value;
+
+        if (i >= super.length) {
+            set(this._length, i + 1);
+        }
+
+        this.dispatch('set', { index: i, item: value });
+    }
 
     clear() {
         this.dispose();
+        set(this._length, 0);
         this.dispatch('clear');
     }
 
@@ -78,6 +108,7 @@ class ReactiveArray<T> extends Array<T> {
         }
 
         if (added.length) {
+            set(this._length, super.length);
             this.dispatch('concat', { items: added });
         }
 
@@ -125,6 +156,8 @@ class ReactiveArray<T> extends Array<T> {
                 item.dispose();
             }
         }
+
+        set(this._length, 0);
     }
 
     on<K extends keyof Events<T>>(event: K, listener: Listener<Events<T>[K]>) {
@@ -164,9 +197,12 @@ class ReactiveArray<T> extends Array<T> {
         let item = super.pop();
 
         if (item !== undefined) {
+            set(this._length, super.length);
+
             if (isReactiveObject(item)) {
                 item.dispose();
             }
+
             this.dispatch('pop', { item });
         }
 
@@ -174,8 +210,13 @@ class ReactiveArray<T> extends Array<T> {
     }
 
     push(...items: T[]) {
+        if (!items.length) {
+            return super.length;
+        }
+
         let length = super.push(...items);
 
+        set(this._length, length);
         this.dispatch('push', { items });
 
         return length;
@@ -192,9 +233,12 @@ class ReactiveArray<T> extends Array<T> {
         let item = super.shift();
 
         if (item !== undefined) {
+            set(this._length, super.length);
+
             if (isReactiveObject(item)) {
                 item.dispose();
             }
+
             this.dispatch('shift', { item });
         }
 
@@ -250,6 +294,8 @@ class ReactiveArray<T> extends Array<T> {
         let removed = super.splice(start, deleteCount, ...items);
 
         if (items.length > 0 || removed.length > 0) {
+            set(this._length, super.length);
+
             for (let i = 0, n = removed.length; i < n; i++) {
                 let item = removed[i];
 
@@ -267,6 +313,7 @@ class ReactiveArray<T> extends Array<T> {
     unshift(...items: T[]) {
         let length = super.unshift(...items);
 
+        set(this._length, length);
         this.dispatch('unshift', { items });
 
         return length;

package/src/reactive/index.ts

@@ -1,58 +1,34 @@
-import { isArray, isObject, Prettify } from '@esportsplus/utilities';
-import { onCleanup, root } from '~/system';
+import { REACTIVE_OBJECT } from '~/constants';
 import { ReactiveArray } from './array';
-import { ReactiveObject } from './object';
-
-
-type API<T> =
-    T extends Record<PropertyKey, unknown>
-        ? Prettify<{ [K in keyof T]: Infer<T[K]> } & { dispose: VoidFunction } >
-        : T extends (infer U)[]
-            ? ReactiveArray<U>
-            : never;
-
-type Guard<T> = T extends { dispose: any } ? { never: '[ dispose ] are reserved keys' } : T;
-
-type Infer<T> =
-    T extends (...args: unknown[]) => Promise<infer R>
-        ? R | undefined
-        : T extends (...args: any[]) => infer R
-            ? R
-            : T extends (infer U)[]
-                ? ReactiveArray<U>
-                : T extends ReactiveObject<any>
-                    ? T
-                    : T extends Record<PropertyKey, unknown>
-                        ? { [K in keyof T]: T[K] }
-                        : T;
-
-
-export default <T extends Record<PropertyKey, any> | unknown[]>(input: Guard<T>): API<T> => {
-    let dispose = false,
-        value = root(() => {
-            let response: API<T> | undefined;
-
-            if (isObject(input)) {
-                response = new ReactiveObject(input) as any as API<T>;
-            }
-            else if (isArray(input)) {
-                response = new ReactiveArray(...input) as API<T>;
-            }
-
-            if (response) {
-                if (root.disposables) {
-                    dispose = true;
-                }
-
-                return response;
-            }
-
-            throw new Error(`@esportsplus/reactivity: 'reactive' received invalid input - ${JSON.stringify(input)}`);
-        });
-
-    if (dispose) {
-        onCleanup(() => value.dispose());
-    }
-
-    return value;
-};
+
+
+// Branded type to prevent assignment to computed values
+declare const READONLY: unique symbol;
+
+type ReactiveObject<T extends Record<PropertyKey, unknown>> = T & {
+    [REACTIVE_OBJECT]: true;
+    dispose(): void;
+};
+
+type ReactiveObjectGuard<T> = T extends { dispose: any } ? { never: '[ dispose ] is a reserved key' } : T;
+
+
+// Function input → branded return type (prevents assignment)
+function reactive<T extends () => unknown>(_input: T): ReturnType<T> & { readonly [READONLY]: true };
+// Object literal → existing ReactiveObject behavior
+function reactive<T extends Record<PropertyKey, any>>(_input: ReactiveObjectGuard<T>): ReactiveObject<T>;
+// Array literal → existing ReactiveArray behavior
+function reactive<T>(_input: T[]): ReactiveArray<T>;
+// Everything else → passthrough type (allows assignment)
+function reactive<T>(_input: T): T;
+function reactive(_input: unknown): unknown {
+    throw new Error(
+        '@esportsplus/reactivity: reactive() called at runtime. ' +
+        'Ensure vite-plugin-reactivity-compile is configured.'
+    );
+}
+
+
+export default reactive;
+export { reactive, ReactiveArray };
+export type { ReactiveObject };

package/src/system.ts

@@ -1,10 +1,19 @@
-import { isObject } from '@esportsplus/utilities';
 import {
-    COMPUTED, SIGNAL,
-    STABILIZER_IDLE, STABILIZER_RESCHEDULE, STABILIZER_RUNNING, STABILIZER_SCHEDULED,
-    STATE_CHECK, STATE_DIRTY, STATE_IN_HEAP, STATE_NONE, STATE_NOTIFY_MASK, STATE_RECOMPUTING
+    COMPUTED,
+    SIGNAL,
+    STABILIZER_IDLE,
+    STABILIZER_RESCHEDULE,
+    STABILIZER_RUNNING,
+    STABILIZER_SCHEDULED,
+    STATE_CHECK,
+    STATE_DIRTY,
+    STATE_IN_HEAP,
+    STATE_NONE,
+    STATE_NOTIFY_MASK,
+    STATE_RECOMPUTING
 } from './constants';
 import { Computed, Link, Signal } from './types';
+import { isObject } from '@esportsplus/utilities';
 
 
 let depth = 0,
@@ -558,4 +567,4 @@ export {
     read, root,
     set, signal
 };
-export type { Computed, Signal };
+export type { Computed, Signal };

package/src/transformer/detector.ts

@@ -0,0 +1,65 @@
+import { mightNeedTransform as checkTransform } from '@esportsplus/typescript/transformer';
+import ts from 'typescript';
+
+
+interface DetectContext {
+    hasImport: boolean;
+    hasUsage: boolean;
+}
+
+
+const REACTIVE_REGEX = /\breactive\b/;
+
+
+function visit(ctx: DetectContext, node: ts.Node): void {
+    if (ctx.hasImport && ctx.hasUsage) {
+        return;
+    }
+
+    if (
+        ts.isImportDeclaration(node) &&
+        node.importClause?.namedBindings &&
+        ts.isNamedImports(node.importClause.namedBindings)
+    ) {
+        let elements = node.importClause.namedBindings.elements;
+
+        for (let i = 0, n = elements.length; i < n; i++) {
+            let el = elements[i],
+                name = el.propertyName?.text ?? el.name.text;
+
+            if (name === 'reactive') {
+                ctx.hasImport = true;
+                break;
+            }
+        }
+    }
+
+    if (
+        ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'reactive'
+    ) {
+        ctx.hasUsage = true;
+    }
+
+    ts.forEachChild(node, n => visit(ctx, n));
+}
+
+
+const mightNeedTransform = (code: string): boolean => {
+    if (!checkTransform(code, { regex: REACTIVE_REGEX })) {
+        return false;
+    }
+
+    let ctx: DetectContext = {
+            hasImport: false,
+            hasUsage: false
+        };
+
+    visit(ctx, ts.createSourceFile('detect.ts', code, ts.ScriptTarget.Latest, false));
+
+    return ctx.hasImport && ctx.hasUsage;
+};
+
+
+export { mightNeedTransform };

package/src/transformer/index.ts

@@ -0,0 +1,78 @@
+import type { Bindings, TransformOptions, TransformResult } from '~/types';
+import { injectAutoDispose } from './transforms/auto-dispose';
+import { mightNeedTransform } from './detector';
+import { transformReactiveArrays } from './transforms/reactive-array';
+import { transformReactiveObjects } from './transforms/reactive-object';
+import { transformReactivePrimitives } from './transforms/reactive-primitives';
+import ts from 'typescript';
+
+
+const createTransformer = (options?: TransformOptions): ts.TransformerFactory<ts.SourceFile> => {
+    return () => {
+        return (sourceFile: ts.SourceFile): ts.SourceFile => {
+            let result = transform(sourceFile, options);
+
+            return result.transformed ? result.sourceFile : sourceFile;
+        };
+    };
+};
+
+const transform = (sourceFile: ts.SourceFile, options?: TransformOptions): TransformResult => {
+    let bindings: Bindings = new Map(),
+        code = sourceFile.getFullText(),
+        current = sourceFile,
+        original = code,
+        result: string;
+
+    if (!mightNeedTransform(code)) {
+        return { code, sourceFile, transformed: false };
+    }
+
+    // Run all transforms, only re-parse between transforms if code changed
+    result = transformReactiveObjects(current, bindings);
+
+    if (result !== code) {
+        current = ts.createSourceFile(sourceFile.fileName, result, sourceFile.languageVersion, true);
+        code = result;
+    }
+
+    result = transformReactiveArrays(current, bindings);
+
+    if (result !== code) {
+        current = ts.createSourceFile(sourceFile.fileName, result, sourceFile.languageVersion, true);
+        code = result;
+    }
+
+    result = transformReactivePrimitives(current, bindings);
+
+    if (result !== code) {
+        current = ts.createSourceFile(sourceFile.fileName, result, sourceFile.languageVersion, true);
+        code = result;
+    }
+
+    if (options?.autoDispose) {
+        result = injectAutoDispose(current);
+
+        if (result !== code) {
+            current = ts.createSourceFile(sourceFile.fileName, result, sourceFile.languageVersion, true);
+            code = result;
+        }
+    }
+
+    if (code === original) {
+        return { code, sourceFile, transformed: false };
+    }
+
+    return {
+        code,
+        sourceFile: current,
+        transformed: true
+    };
+};
+
+
+export { createTransformer, mightNeedTransform, transform };
+export { injectAutoDispose } from './transforms/auto-dispose';
+export { transformReactiveArrays } from './transforms/reactive-array';
+export { transformReactiveObjects } from './transforms/reactive-object';
+export { transformReactivePrimitives } from './transforms/reactive-primitives';