npm - @medyll/idae-stator - Versions diffs - 0.45.0 → 0.51.2 - Mend

@medyll/idae-stator 0.45.0 → 0.51.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2024 medyll
-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.
+MIT License
+Copyright (c) 2024 medyll
+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 CHANGED Viewed

@@ -1,92 +1,122 @@
-# Stator Demo
-This is a demonstration of the **Stator** library, which provides reactive state management for JavaScript applications.
-## Features
-- Reactive state creation using `stator`.
-- Automatic state change detection with `onchange` handlers.
-- Manual and automatic state updates.
-- Simple UI updates based on state changes.
-## Code Example
-Below is an example of how to use the Stator library:
-```javascript
-// Import the stator library
-import { stator } from './Stator.ts';
-// Create reactive states
-let countState = stator(0);
-let countObje = stator({ index: 0 });
-let monobjSte = stator({ index: 0 });
-// State change handlers
-countState.onchange = (oldValue, newValue) => {
-    console.log('countState', oldValue, newValue);
-};
-countObje.onchange = (oldValue, newValue) => {
-    console.log('countObje', oldValue, newValue);
-};
-// Increment the value every 30 seconds
-setInterval(() => {
-    // Uncomment to enable automatic increment
-    // countState.stator++;
-    // monobjSte.stator.index++;
-}, 30000);
-// Function to manually increment the count
-function incrementCount() {
-    countState.stator++;
-    monobjSte.stator.index++;
-    updateUI();
-}
-// Function to update the UI
-function updateUI() {
-    document.getElementById('count').textContent = `${countState.stator}-${countObje.stator.index}`;
-}
-// Initialize the UI
-window.onload = () => {
-    updateUI();
-    console.log(monobjSte, countState.stator);
-};
-```
-## HTML Structure
-The following HTML structure is used for the demo:
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Stator Demo</title>
-</head>
-<body>
-    <h1>Stator Demo</h1>
-    <p>Count: <span id="count">0-0</span></p>
-    <button onclick="incrementCount()">Increment</button>
-</body>
-</html>
-```
-## How It Works
-1. **Reactive States**: The `stator` function creates reactive states that automatically notify changes.
-2. **State Handlers**: The `onchange` handlers log state changes to the console.
-3. **UI Updates**: The `updateUI` function updates the DOM based on the current state values.
-4. **Manual Increment**: The `incrementCount` function allows manual state updates via a button click.
-## Usage
-1. Clone the repository and include the `Stator.js` library in your project.
-2. Use the provided code to create reactive states and bind them to your UI.
-3. Customize the logic as needed for your application.
-Enjoy building reactive applications with **Stator**!
+# @medyll/idae-stator ⚡
+**idae-stator** is a lightweight, universal, and deeply reactive state management library for JavaScript and TypeScript. It uses native `Proxy` to track changes at any depth and provides a unified `EventTarget` API for both Browser and Node.js environments.
+## 🚀 Key Features
+* **Deep Reactivity:** Automatically tracks mutations in nested objects and arrays.
+* **Zero Dependencies:** Extremely small footprint.
+* **Universal (Isomorphic):** Works out of the box in the Browser, Node.js, and SSR environments.
+* **Flexible API:** Support for both standard `onchange` callbacks and `addEventListener` patterns.
+* **Developer Friendly:** Seamless integration with TypeScript, providing full intellisense for your state structures.
+* **Smart Updates:** Built-in protection against redundant notifications for primitive values.
+---
+## 📦 Installation
+```bash
+npm install @medyll/idae-stator
+```
+---
+## 🛠 Usage
+### Basic Reactivity
+```typescript
+import { stator } from '@medyll/idae-stator';
+const state = stator({ count: 0 });
+state.onchange = (newValue) => {
+  console.log(`Count updated to: ${newValue.count}`);
+};
+state.count++; // Console: Count updated to: 1
+```
+### Deep Nesting & Arrays
+The library handles deep structures without any extra configuration.
+```typescript
+const appState = stator({
+  user: {
+    profile: { name: 'Mydde' },
+    tags: ['dev', 'js']
+  }
+});
+appState.onchange = (val) => console.log('State changed!');
+// All these mutations trigger the reactivity:
+appState.user.profile.name = 'Mydde Dev';
+appState.user.tags.push('stator');
+```
+### Event-Driven Pattern
+If you prefer standard web events or need multiple listeners:
+```typescript
+const state = stator({ status: 'idle' });
+state.addEventListener('change', (event) => {
+  const { newValue } = event.detail;
+  console.log('New status:', newValue.status);
+});
+state.status = 'loading';
+```
+### Type Safety (TypeScript)
+**idae-stator** preserves your types and augments them with reactive properties.
+```typescript
+interface User {
+  id: number;
+  role: string;
+}
+const state = stator<User>({ id: 1, role: 'admin' });
+// 'state' is now typed as AugmentedState<User>
+```
+---
+## ⚙️ Technical Overview
+### The Reactivity Engine
+The core of the library is built around a recursive `Proxy` system. When you access a nested object, **idae-stator** wraps it on-the-fly (and caches it using a `WeakMap`) to ensure that every leaf of your data tree becomes an observable entry point.
+### Universal Event Bus
+To ensure compatibility with Node.js (where `EventTarget` was historically missing or inconsistent), **idae-stator** implements a smart polyfill:
+1. **Browser:** Uses native `window.EventTarget`.
+2. **Legacy/DOM:** Uses an invisible DOM element as an event bridge.
+3. **Node.js:** Uses a custom high-performance event registry.
+---
+## 💎 Utility Properties
+* **`state.stator`**: Access the raw data directly.
+* **`state.toString()`**: Returns a `JSON.stringify` version of your state.
+* **`state.valueOf()`**: Returns the underlying value for comparisons.
+* **`Symbol.toPrimitive`**: Allows the state to be used directly in arithmetic (e.g., `state + 1`).
+---
+## 📜 License
+MIT © [Medyll](https://github.com/medyll)

package/cli.js ADDED Viewed

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const pkgJson = require(path.join(__dirname, 'package.json'));
+const packageName = pkgJson.name.replace(/^@[^/]+\//, '');
+const cmd = process.argv[2];
+if (cmd === 'get-readme') {
+  const readmePath = path.join(__dirname, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    const content = fs.readFileSync(readmePath, 'utf8');
+    console.log(content);
+  } else {
+    console.error('README.md not found in this package.');
+    process.exit(1);
+  }
+} else if (cmd === 'install-skill') {
+  const readline = require('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  const skillSrc = path.join(__dirname, 'SKILL.md');
+  const skillDest = path.resolve(__dirname, `../../../.github/skills/${packageName}/SKILL.md`);
+  if (!fs.existsSync(skillSrc)) {
+    console.error('SKILL.md not found in this package.');
+    process.exit(1);
+  }
+  rl.question(`This will copy SKILL.md to .github/skills/${packageName}/SKILL.md. Continue? (y/n): `, (answer) => {
+    if (answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes') {
+      fs.mkdirSync(path.dirname(skillDest), { recursive: true });
+      fs.copyFileSync(skillSrc, skillDest);
+      console.log(`SKILL.md installed to .github/skills/${packageName}/SKILL.md`);
+    } else {
+      console.log('Operation cancelled.');
+    }
+    rl.close();
+  });
+} else {
+  console.log('Usage: <cli> get-readme | install-skill');
+  process.exit(1);
+}

package/dist/stator/Stator.d.ts CHANGED Viewed

@@ -1,32 +1,46 @@
-/** Represents primitive types */
-type Primitive = string | number | boolean;
+/** * Represents JavaScript primitive types
+ */
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 /**
- * Represents the state type
- * For primitives, it wraps the value in an object
- * For non-primitives, it keeps the original type
+ * Basic state wrapper structure
  */
 type State<T> = {
     value: T;
 };
 /**
  * Callback function type for state changes
- * @param oldValue The previous value of the state
- * @param newValue The new value of the state
  */
-type StateChangeHandler<T> = (oldValue: T, newValue: T) => void;
+type StateChangeHandler<T> = (newValue: T) => void;
 /**
- * Augmented state type that includes the onchange handler
+ * Augmented state type providing reactivity, event subscription, and utility methods
  */
 type AugmentedState<T> = State<T> & {
+    /** The callback triggered on any state mutation */
     onchange?: StateChangeHandler<T>;
+    /** Standard event listener for 'change' events */
+    addEventListener: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void;
+    /** Removes a previously attached 'change' event listener */
+    removeEventListener: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => void;
+    /** Manually dispatches an event */
+    triggerChange: (event: Event) => boolean;
+    /** Returns a JSON string representation of the state */
     toString: () => string;
+    /** Returns the raw underlying value */
     valueOf: () => T;
+    /** Handles implicit type conversion (string/number) */
     [Symbol.toPrimitive]: (hint: string) => Primitive;
+    /** Access to the raw state data */
+    stator: T;
 };
 /**
- * Creates a stateful object with change tracking
- * @param initialState The initial state value
- * @returns A proxy object that wraps the state and provides change tracking
+ * Creates a deeply reactive state object.
+ * * Features:
+ * - Deep reactivity via Proxy (works with nested objects and arrays)
+ * - EventTarget compatible (works in Browser and Node.js)
+ * - No redundant notifications on array mutations
+ * - Memory efficient using WeakMap for proxy tracking
+ * * @param initialState The initial value to wrap
+ * @returns A reactive Proxy object
  */
 export declare function stator<T>(initialState: T): AugmentedState<T>;
 export {};

package/dist/stator/Stator.js CHANGED Viewed

@@ -1,103 +1,171 @@
 /**
- * Creates a stateful object with change tracking
- * @param initialState The initial state value
- * @returns A proxy object that wraps the state and provides change tracking
+ * Creates a deeply reactive state object.
+ * * Features:
+ * - Deep reactivity via Proxy (works with nested objects and arrays)
+ * - EventTarget compatible (works in Browser and Node.js)
+ * - No redundant notifications on array mutations
+ * - Memory efficient using WeakMap for proxy tracking
+ * * @param initialState The initial value to wrap
+ * @returns A reactive Proxy object
  */
 export function stator(initialState) {
     /**
-     * Checks if a value is of primitive type
-     * @param val The value to check
-     * @returns True if the value is a primitive, false otherwise
+     * Internal EventTarget polyfill to ensure cross-environment compatibility (Node/Browser)
+     */
+    class StatorEventTarget {
+        et;
+        constructor() {
+            if (typeof window !== 'undefined' && typeof window.EventTarget !== 'undefined') {
+                this.et = new window.EventTarget();
+            }
+            else if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
+                this.et = document.createElement('span');
+            }
+            else {
+                // Fallback for Node.js environments without built-in EventTarget
+                let listeners = {};
+                this.et = {
+                    addEventListener(type, listener) {
+                        if (!listeners[type])
+                            listeners[type] = new Set();
+                        listeners[type].add(listener);
+                    },
+                    removeEventListener(type, listener) {
+                        listeners[type]?.delete(listener);
+                    },
+                    dispatchEvent(event) {
+                        const ls = listeners[event.type];
+                        if (!ls)
+                            return true;
+                        for (const l of Array.from(ls)) {
+                            if (typeof l === 'function')
+                                l.call(undefined, event);
+                            else if (l && typeof l.handleEvent === 'function')
+                                l.handleEvent(event);
+                        }
+                        return true;
+                    }
+                };
+            }
+        }
+        addEventListener(...args) { this.et.addEventListener(...args); }
+        removeEventListener(...args) { this.et.removeEventListener(...args); }
+        triggerChange(event) { return this.et.dispatchEvent(event); }
+    }
+    const eventTarget = new StatorEventTarget();
+    const proxyCache = new WeakMap();
+    let onchange;
+    let onchangeListener;
+    /**
+     * Type guard to check for primitive values
      */
     function isPrimitive(val) {
-        return (typeof val === "string" ||
-            typeof val === "number" ||
-            typeof val === "boolean");
+        return val === null || (typeof val !== "object" && typeof val !== "function");
     }
     /**
-     * Logs errors with a custom prefix
-     * @param message The error message
-     * @param error The error object
+     * Dispatches the change event to all subscribers
      */
-    function logError(message, error) {
-        console.error(`[Stator Error] ${message}`, error);
+    function notify(newValue) {
+        eventTarget.triggerChange(new CustomEvent('change', { detail: { newValue } }));
     }
-    // Create the state object
-    const state = { value: initialState };
-    // Default onchange handler
-    let onchange;
-    // Proxy handler to intercept property access and modifications
-    const handler = {
-        get(target, property, receiver) {
-            try {
-                if (property === "onchange") {
-                    return onchange;
-                }
-                if (property === "stator") {
-                    return target.value;
-                }
-                if (property === "toString") {
-                    return function () {
-                        return String(target.value);
-                    };
-                }
-                if (property === "valueOf") {
-                    return function () {
-                        return target.value;
-                    };
-                }
+    /**
+     * Recursively creates a Proxy for nested objects or arrays
+     */
+    function deepProxy(obj, info) {
+        if (isPrimitive(obj))
+            return obj;
+        if (proxyCache.has(obj))
+            return proxyCache.get(obj);
+        const handler = {
+            get(target, property, receiver) {
+                // Special internal property mapping
+                const reserved = {
+                    onchange: info.getOnChange(),
+                    addEventListener: eventTarget.addEventListener.bind(eventTarget),
+                    removeEventListener: eventTarget.removeEventListener.bind(eventTarget),
+                    triggerChange: eventTarget.triggerChange.bind(eventTarget),
+                    stator: target,
+                    valueOf: () => target,
+                    toString: () => JSON.stringify(target),
+                    [Symbol.for('nodejs.util.inspect.custom')]: () => target
+                };
+                if (property in reserved)
+                    return reserved[property];
                 if (property === Symbol.toPrimitive) {
-                    return function (hint) {
-                        if (hint === "number")
-                            return Number(target.value);
-                        if (hint === "string")
-                            return String(target.value);
-                        return isPrimitive(target.value)
-                            ? target.value
-                            : String(target.value);
-                    };
+                    return (hint) => hint === "number" ? Number(target) : JSON.stringify(target);
                 }
-                return Reflect.get(target.value, property, receiver);
+                let value = Reflect.get(target, property, receiver);
+                return isPrimitive(value) ? value : deepProxy(value, info);
+            },
+            set(target, property, value, receiver) {
+                const oldValue = target[property];
+                const proxiedValue = isPrimitive(value) ? value : deepProxy(value, info);
+                const result = Reflect.set(target, property, proxiedValue, receiver);
+                // Only notify if the value actually changed to prevent loops
+                if (oldValue !== proxiedValue) {
+                    notify(info.rootState.value);
+                }
+                return result;
+            },
+            deleteProperty(target, property) {
+                const result = Reflect.deleteProperty(target, property);
+                notify(info.rootState.value);
+                return result;
             }
-            catch (error) {
-                logError(`Error getting property ${String(property)}:`, error);
-                throw error;
+        };
+        const proxy = new Proxy(obj, handler);
+        proxyCache.set(obj, proxy);
+        return proxy;
+    }
+    const stateWrapper = { value: undefined };
+    const sharedInfo = { getOnChange: () => onchange, rootState: stateWrapper };
+    // Initialize the state value
+    stateWrapper.value = isPrimitive(initialState) ? initialState : deepProxy(initialState, sharedInfo);
+    /**
+     * Root Proxy Handler
+     */
+    const rootHandler = {
+        get(target, property, receiver) {
+            if (property === "value" || property === "stator")
+                return target.value;
+            if (property === "onchange")
+                return onchange;
+            if (property === "addEventListener")
+                return eventTarget.addEventListener.bind(eventTarget);
+            if (property === "removeEventListener")
+                return eventTarget.removeEventListener.bind(eventTarget);
+            // Allow direct property access on the state object (e.g., state.someProp)
+            if (!isPrimitive(target.value)) {
+                return Reflect.get(target.value, property, receiver);
             }
+            return Reflect.get(target, property, receiver);
         },
-        set(target, property, value, receiver) {
+        set(target, property, value) {
+            // Logic for the onchange callback property
             if (property === "onchange") {
-                if (typeof value !== "function") {
-                    throw new TypeError("onchange must be a function");
-                }
-                onchange = value;
-                return true;
-            }
-            try {
-                const oldValue = target.value;
-                let newValue;
-                if (property === "stator") {
-                    newValue = value;
-                    target.value = value;
+                if (onchangeListener)
+                    eventTarget.removeEventListener("change", onchangeListener);
+                if (typeof value === "function") {
+                    onchange = value;
+                    onchangeListener = (e) => onchange?.(e.detail.newValue);
+                    eventTarget.addEventListener("change", onchangeListener);
                 }
-                else if (typeof target.value === "object" && target.value !== null) {
-                    Reflect.set(target.value, property, value);
-                    newValue = { ...target.value };
+                else if (value == null) {
+                    onchange = undefined;
                 }
                 else {
-                    throw new Error("Cannot set property on primitive value");
-                }
-                if (onchange && !Object.is(oldValue, newValue)) {
-                    onchange(oldValue, newValue);
+                    throw new TypeError("onchange must be a function or undefined");
                 }
                 return true;
             }
-            catch (error) {
-                logError(`Error setting property ${String(property)}:`, error);
-                throw error;
+            // Logic for updating the core value
+            if (property === "value" || property === "stator") {
+                target.value = isPrimitive(value) ? value : deepProxy(value, sharedInfo);
+                notify(target.value);
+                return true;
             }
-        },
-        // ... (other methods unchanged)
+            return false;
+        }
     };
-    // Create and return the proxied state object
-    return new Proxy(state, handler);
+    return new Proxy(stateWrapper, rootHandler);
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,13 @@
 {
   "name": "@medyll/idae-stator",
-  "version": "0.45.0",
+  "bin": {
+    "idae-stator": "./cli.js"
+  },
+  "version": "0.51.2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/medyll/idae.git"
+  },
   "description": "A lightweight and efficient state management library designed for building reactive and scalable JavaScript applications.",
   "exports": {
     ".": {
@@ -16,7 +23,12 @@
   "peerDependencies": {
     "svelte": "^5.0.0-next"
   },
+  "publishConfig": {
+    "access": "public",
+    "directory": "."
+  },
   "devDependencies": {
+    "@semantic-release/github": "^10.3.5",
     "@sveltejs/adapter-auto": "^5.0.0",
     "@sveltejs/kit": "^2.20.2",
     "@sveltejs/package": "^2.3.10",
@@ -35,7 +47,7 @@
     "typescript-eslint": "^8.28.0",
     "vite": "^6.2.3",
     "vitest": "^3.0.9",
-    "@medyll/idae-prettier-config": "1.2.1"
+    "@medyll/idae-eslint-config": "0.1.5"
   },
   "keywords": [
     "state-management",
@@ -46,14 +58,6 @@
   ],
   "author": "Your Name <your.email@example.com>",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/your-repo/idae-stator.git"
-  },
-  "bugs": {
-    "url": "https://github.com/your-repo/idae-stator/issues"
-  },
-  "homepage": "https://github.com/your-repo/idae-stator#readme",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
@@ -69,6 +73,6 @@
     "test": "vitest",
     "lint": "prettier --check . && eslint .",
     "format": "prettier --write .",
-    "package:pre": "node scripts/package-pre.js"
+    "prepackage": "node scripts/package-pre.js"
   }
 }