@xyn-html/xyn-signal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,88 @@
+# xyn-signal
+
+Lightweight, reactive signal-based state management for JavaScript applications.
+
+## Installation
+
+```bash
+npm install xyn-signal
+```
+
+## Usage
+
+```javascript
+import { createSignal, watch, timing } from 'xyn-signal';
+
+// Create a signal
+const count = createSignal(0);
+
+// Subscribe to changes
+count.subscribe((value) => {
+  console.log('Count changed:', value);
+});
+
+// Update the value
+count.value = 1;
+count.value = 2;
+
+// Object signals with reactive properties
+const user = createSignal({ name: 'John', age: 30 });
+user.value.name = 'Jane'; // Triggers subscribers
+
+// Array signals with reactive methods
+const items = createSignal([1, 2, 3]);
+items.value.push(4); // Triggers subscribers
+
+// Watch multiple signals
+const firstName = createSignal('John');
+const lastName = createSignal('Doe');
+
+watch(firstName)
+  .watch(lastName)
+  .effect(() => {
+    console.log(`Full name: ${firstName.value} ${lastName.value}`);
+  });
+
+// Derived signals
+const { signal: fullName } = watch(firstName)
+  .watch(lastName)
+  .derived(() => `${firstName.value} ${lastName.value}`);
+
+// Timing functions
+const debouncedEffect = timing(300).debounce(() => {
+  console.log('Debounced!');
+});
+
+watch(firstName).effect(debouncedEffect);
+```
+
+## API
+
+### createSignal(initialValue)
+
+Creates a reactive signal that can hold any value type.
+
+- **Primitives**: Simple value storage with change detection
+- **Objects**: Reactive property assignment and deletion
+- **Arrays**: Reactive array methods (push, pop, shift, unshift, splice)
+- **Map/Set**: Reactive collection operations
+
+### watch(signal)
+
+Creates a watcher for observing multiple signals.
+
+- `.watch(signal)` - Chain additional signals
+- `.effect(fn)` - Subscribe to all watched signals
+- `.derived(fn, wrappingFn?)` - Create a derived signal
+
+### timing(delay)
+
+Creates timing-controlled function wrappers.
+
+- `.debounce(fn)` - Execute after inactivity period
+- `.throttle(fn)` - Limit execution rate
+- `.delay(fn)` - Execute after fixed delay
+
+## License
+
+MIT

package/dist/xyn_signal.js

@@ -0,0 +1,581 @@
+/**
+ * @fileoverview XynSignal is a library for creating reactive signals, it is
+ * used in XynHTML to render the data to HTML elements. It may also be used
+ * independently of XynHTML.
+ *
+ * @license MIT
+ * Copyright (c) 2024 XynHTML
+ *
+ * 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.
+ */
+
+/**
+ * @typedef {Object} XynChange
+ * @template T
+ * @property {T} value
+ * @property {T} previousValue
+ * @description XynChange is a class for storing the values of a change.
+ * @example
+ * const change = XynChange.create(1, 0);
+ * console.log(change.value); // 1
+ * console.log(change.previousValue); // 0
+ * console.log(change.values); // { value: 1, previousValue: 0 }
+ */
+class XynChange {
+  #value;
+  #previousValue;
+
+  constructor(value, previousValue) {
+    this.#value = value;
+    this.#previousValue = previousValue;
+  }
+
+  static create(value, previousValue) {
+    return new XynChange(value, previousValue);
+  }
+
+  get value() {
+    return this.#value;
+  }
+
+  get previousValue() {
+    return this.#previousValue;
+  }
+
+  get values() {
+    return {
+      value: this.#value,
+      previousValue: this.#previousValue,
+    };
+  }
+}
+
+/**
+ * @typedef {Object} XynCollectionChange
+ * @template T
+ * @property {int} index
+ * @property {T} value
+ * @property {T} previousValue
+ * @description XynListChange is a class for storing the values of a collection change.
+ * @example
+ * const change = XynListChange.create(0, 1, 0);
+ * console.log(change.index); // 0
+ * console.log(change.value); // 1
+ * console.log(change.previousValue); // 0
+ * console.log(change.values); // { index: 0, value: 1, previousValue: 0 }
+ */
+class XynCollectionChange {
+  #index;
+  #value;
+  #previousValue;
+
+  constructor(index, value, previousValue) {
+    this.#index = index;
+    this.#value = value;
+    this.#previousValue = previousValue;
+  }
+
+  static create(index, value, previousValue) {
+    return new XynCollectionChange(index, value, previousValue);
+  }
+
+  get index() {
+    return this.#index;
+  }
+
+  get value() {
+    return this.#value;
+  }
+
+  get previousValue() {
+    return this.#previousValue;
+  }
+
+  get values() {
+    return {
+      value: this.#value,
+      previousValue: this.#previousValue,
+      index: this.#index,
+    };
+  }
+}
+
+/**
+ * @class None
+ * @description None is a class for storing a value that doesn't exist.
+ * @example
+ * const none = new None("none");
+ * console.log(none.is(new None("none"))); // true
+ * console.log(none.is(new None("other"))); // false
+ * console.log(none.value); // "none"
+ */
+class None {
+  #value;
+
+  constructor(value) {
+    this.#value = value;
+  }
+
+  is(none) {
+    return none instanceof None && this.#value === none.value;
+  }
+
+  get value() {
+    return this.#value;
+  }
+}
+
+/**
+ * @enum {None}
+ * @readonly
+ * @description CollectionValue is an enum of sentinals for the values of a collection change that don't or didn't exist.
+ */
+export const CollectionValue = Object.freeze({
+  INSERT: new None("insert"),
+  DELETE: new None("delete"),
+});
+
+/**
+ * @template T
+ * @param {T} value
+ * @returns {{ value: T, subscribe: (subscriber: Function) => void }}
+ * @description Creates a signal with the given value.
+ * The signal can be subscribed to and will notify subscribers when the value changes.
+ * @example
+ * const signal = createSignal(0);
+ * signal.subscribe(({value, previousValue}) =>
+ * console.log(`Value changed from ${previousValue} to ${value}`)
+ * );
+ */
+export function createSignal(value) {
+  if (typeof value === "function") {
+    value = value();
+  }
+
+  if (value != null) {
+    if (value instanceof Map || value instanceof Set) {
+      return createCollectionSignal(value);
+    }
+    if (Array.isArray(value)) {
+      return createListSignal(value);
+    }
+    if (typeof value === "object" && value !== null) {
+      return createObjectSignal(value);
+    }
+  }
+  const subscribers = new Set();
+
+  /**
+   * @type {Object}
+   * @property {T} value
+   * @property {function(function({value: any, previousValue: any}): void): function(): void} subscribe
+   * @description Subscribes to the signal and returns a function to unsubscribe.
+   * The subscriber function is called with the current value and the previous value.
+   * The subscriber function is called immediately with the current value.
+   * @example
+   * const signal = createSignal(0);
+   * const unsubscribe = signal.subscribe(({value, previousValue}) =>
+   * console.log(`Value changed from ${previousValue} to ${value}`)
+   * );
+   */
+  const signalProxy = new Proxy(
+    {
+      value,
+      subscribe(subscriber) {
+        subscribers.add(subscriber);
+        return () => subscribers.delete(subscriber);
+      },
+    },
+    {
+      get(target, prop) {
+        return Reflect.get(target, prop);
+      },
+      set(target, prop, newValue) {
+        if (prop === "value") {
+          const previousValue = Reflect.get(target, prop);
+          Reflect.set(target, prop, newValue);
+          if (previousValue === newValue) {
+            return true;
+          }
+          subscribers.forEach((subscriber) =>
+            subscriber(XynChange.create(newValue, previousValue)),
+          );
+          return true;
+        }
+        return Reflect.set(target, prop, newValue);
+      },
+      apply(target, thisArg, args) {
+        return Reflect.apply(target, thisArg, args);
+      },
+    },
+  );
+
+  return signalProxy;
+}
+
+/**
+ * @function proxyFactory
+ * @param {Object} obj
+ * @param {Set<Function>} subscribers
+ * @returns {Proxy | Number | String | Boolean | null | undefined | Symbol | BigInt }
+ * @description Creates a proxy for the given object that notifies subscribers when the object changes.
+ * @example
+ * const obj = { a: 1, b: 2 };
+ * const subscribers = new Set();
+ * const proxy = proxyFactory(obj, subscribers);
+ * proxy.a = 3; // Notifies subscribers
+ * proxy.b = 4; // Notifies subscribers
+ * proxy.c = 5; // Notifies subscribers
+ * delete proxy.a; // Notifies subscribers
+ * proxy.a = 6; // Notifies subscribers
+ * proxy.a = 7; // Notifies subscribers
+ */
+function proxyFactory(value, subscribers) {
+  if (value instanceof Map || value instanceof Set) {
+    return createCollectionProxy(value, subscribers);
+  } else if (Array.isArray(value)) {
+    return createListProxy(value, subscribers);
+  } else if (typeof value === "object" && value != null) {
+    return createObjectProxy(value, subscribers);
+  } else if (typeof value === "symbol") {
+    return String(value);
+  }
+  return value;
+}
+
+function createCollectionProxy(collection, subscribers) {
+  return new Proxy(collection, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (typeof value === "function") {
+        return (...args) => {
+          const prevDeleteValue =
+            prop === "delete" ? Reflect.get(target, args[0]) : null;
+
+          const result = value.apply(target, args);
+          if (prop === "get") {
+            return proxyFactory(result, subscribers);
+          }
+          if (prop === "set" || prop === "add") {
+            if (prop === "set" && Reflect.has(target, args[0])) {
+              return result;
+            }
+            subscribers.forEach((subscriber) => {
+              subscriber(
+                XynCollectionChange.create(
+                  args[0],
+                  args[1],
+                  CollectionValue.INSERT,
+                ),
+              );
+            });
+          }
+          if (prop === "delete") {
+            subscribers.forEach((subscriber) => {
+              subscriber(
+                XynCollectionChange.create(
+                  args[0],
+                  CollectionValue.DELETE,
+                  prevDeleteValue,
+                ),
+              );
+            });
+          }
+          if (prop === "clear") {
+            subscribers.forEach((subscriber) => {
+              subscriber(
+                XynCollectionChange.create(
+                  CollectionValue.DELETE,
+                  CollectionValue.DELETE,
+                  CollectionValue.DELETE,
+                ),
+              );
+            });
+          }
+          return result;
+        };
+      }
+
+      if (typeof value === "object" && value !== null) {
+        return proxyFactory(value, subscribers);
+      }
+
+      return value;
+    },
+    getPrototypeOf(target) {
+      return Reflect.getPrototypeOf(target);
+    },
+  });
+}
+
+function createListProxy(list, subscribers) {
+  return new Proxy(list, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+      if (typeof value === "function") {
+        return (...args) => {
+          const result = value.apply(target, args);
+          const LAST_INDEX = Reflect.get(target, "length") - 1;
+
+          if (prop === "push" || prop === "unshift") {
+            subscribers.forEach((subscriber) =>
+              subscriber(
+                XynCollectionChange.create(
+                  prop === "push" ? LAST_INDEX : 0,
+                  args[0],
+                  CollectionValue.INSERT,
+                ),
+              ),
+            );
+          }
+
+          if (prop === "pop" || prop === "shift") {
+            subscribers.forEach((subscriber) =>
+              subscriber(
+                XynCollectionChange.create(
+                  prop === "pop" ? LAST_INDEX : 0,
+                  CollectionValue.DELETE,
+                  result,
+                ),
+              ),
+            );
+          }
+
+          if (prop === "splice") {
+            const [start, deleteCount, ...items] = args;
+            subscribers.forEach((subscriber) =>
+              subscriber(
+                XynCollectionChange.create([start, deleteCount], items, result),
+              ),
+            );
+          }
+
+          return result;
+        };
+      }
+
+      if (typeof value === "object" && value !== null) {
+        return proxyFactory(value, subscribers);
+      }
+
+      return value;
+    },
+    getPrototypeOf(target) {
+      return Reflect.getPrototypeOf(target);
+    },
+  });
+}
+
+function createObjectProxy(obj, subscribers) {
+  return new Proxy(obj, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        value = value();
+      }
+
+      if (typeof value === "object" && value !== null) {
+        return proxyFactory(value, subscribers);
+      }
+
+      return value;
+    },
+    set(target, prop, newValue) {
+      const previousValue = Reflect.get(target, prop);
+      Reflect.set(target, prop, newValue);
+      subscribers.forEach((subscriber) =>
+        subscriber(XynCollectionChange.create(prop, newValue, previousValue)),
+      );
+      return true;
+    },
+    deleteProperty(target, prop) {
+      const previousValue = Reflect.get(target, prop);
+      if (typeof prop === "symbol") {
+        prop = prop.description || prop.toString();
+      }
+      Reflect.deleteProperty(target, prop);
+      subscribers.forEach((subscriber) =>
+        subscriber(
+          XynCollectionChange.create(
+            prop,
+            CollectionValue.DELETE,
+            previousValue,
+          ),
+        ),
+      );
+      return true;
+    },
+    getPrototypeOf(target) {
+      return Reflect.getPrototypeOf(target);
+    },
+  });
+}
+
+function createObjectSignal(obj) {
+  const subscribers = new Set();
+
+  return {
+    value: createObjectProxy(obj, subscribers),
+    subscribe(subscriber) {
+      subscribers.add(subscriber);
+      return () => subscribers.delete(subscriber);
+    },
+  };
+}
+
+function createListSignal(list) {
+  const subscribers = new Set();
+
+  return {
+    value: createListProxy(list, subscribers),
+    subscribe(subscriber) {
+      subscribers.add(subscriber);
+      return () => subscribers.delete(subscriber);
+    },
+  };
+}
+
+function createCollectionSignal(collection) {
+  const subscribers = new Set();
+
+  return {
+    value: createCollectionProxy(collection, subscribers),
+    subscribe(subscriber) {
+      subscribers.add(subscriber);
+      return () => subscribers.delete(subscriber);
+    },
+  };
+}
+
+/**
+ * @typedef {Object} Watch
+ * @property {function(Object): Watch} watch
+ * @property {function(function({value: any, previousValue: any}): void): function(): void} effect
+ * @property {function(function(...any): any): {signal: Object, unsubscribe: function(): void}} derived
+ */
+
+/**
+ * @function watch
+ * @param {Object} signal
+ * @returns {Watch}
+ * @description Watches the given signal and returns an object with methods to watch other signals and create effects.
+ * The effect method takes a subscriber function and returns a function to unsubscribe.
+ * The derived method takes a function and returns a signal and a function to unsubscribe.
+ * @example
+ * const signal = createSignal(0);
+ * const signal2 = createSignal(1);
+ * const unsubscribe = watch(signal)
+ * .watch(signal2)
+ * .effect(({value, previousValue}) => console.log(`Value changed from ${previousValue} to ${value}`));
+ */
+export function watch(signal) {
+  const signals = new Set();
+
+  const watchers = (sig) => {
+    if (sig && typeof sig.subscribe === "function") {
+      signals.add(sig);
+    }
+    return {
+      watch(s) {
+        return watchers(s);
+      },
+      effect(subscriber) {
+        const unsubscribers = Array.from(signals.keys()).map((s) =>
+          s.subscribe(subscriber),
+        );
+
+        return () => {
+          unsubscribers.forEach((unsubscribe) => unsubscribe());
+        };
+      },
+      derived(fn, wrappingFn = (fn) => (change) => fn(change)) {
+        const derivedSignal = createSignal(fn());
+        const unsubscribers = Array.from(signals.keys()).map((s) =>
+          s.subscribe(
+            wrappingFn((change) => {
+              derivedSignal.value = fn(change);
+            }),
+          ),
+        );
+
+        return {
+          signal: derivedSignal,
+          unsubscribe: () =>
+            unsubscribers.forEach((unsubscribe) => unsubscribe()),
+        };
+      },
+    };
+  };
+
+  return watchers(signal);
+}
+
+/**
+ * @typedef {Object} Timing
+ * @property {function(function(...any): void): function(...any): void} debounce
+ * @property {function(function(...any): void): function(...any): void} throttle
+ * @property {function(function(...any): void): function(...any): void} delay
+ * @description Timing is an object with methods to debounce, throttle, and delay functions.
+ */
+
+/**
+ * @function timing
+ * @param {int} delay
+ * @returns {Timing}
+ * @description Returns an object with methods to debounce, throttle, and delay functions.
+ * The debounce method takes a function and returns a function that will only call the given function after the given delay.
+ * The throttle method takes a function and returns a function that will only call the given function once per delay.
+ * The delay method takes a function and returns a function that will call the given function after the given delay.
+ * @example
+ * const debounced = timing(100).debounce(() => console.log("debounced"));
+ * const throttled = timing(100).throttle(() => console.log("throttled"));
+ * const delayed = timing(100).delay(() => console.log("delayed"));
+ * debounced(); // Will log "debounced" after 100ms
+ * throttled(); // Will log "throttled" immediately
+ * throttled(); // Will not log "throttled" again until 100ms have passed
+ * delayed(); // Will log "delayed" after 100ms
+ * debounced(); // Will not log "debounced" again until 100ms have passed
+ */
+export function timing(delay) {
+  return {
+    debounce(fn) {
+      let timeoutId;
+      return (...args) => {
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(fn, delay, ...args);
+      };
+    },
+    throttle(fn) {
+      let lastCall = 0;
+      return (...args) => {
+        const now = Date.now();
+        if (now - lastCall >= delay) {
+          lastCall = now;
+          fn(...args);
+        }
+      };
+    },
+    delay(fn) {
+      return (...args) => {
+        setTimeout(fn, delay, ...args);
+      };
+    },
+  };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@xyn-html/xyn-signal",
+  "version": "0.1.0",
+  "description": "Lightweight, reactive signal-based state management for JavaScript applications",
+  "type": "module",
+  "main": "dist/xyn_signal.js",
+  "module": "dist/xyn_signal.js",
+  "exports": {
+    ".": {
+      "import": "./dist/xyn_signal.js",
+      "default": "./dist/xyn_signal.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "cp ../../src/xyn_signal.js dist/xyn_signal.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "signal",
+    "reactive",
+    "state-management",
+    "javascript",
+    "frontend",
+    "xyn"
+  ],
+  "author": "Jeffrey Tackett",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github/jfftck/XynHTML"
+  },
+  "bugs": {
+    "url": "https://github.com/jfftck/XynHTML"
+  },
+  "homepage": "https://github.com/jfftck/XynHTML"
+}