@slimr/react 3.0.69 → 3.0.71

package/README.md

@@ -46,6 +46,24 @@ const MyComponent = forwardRef((props, ref1) => {
 })
 ```
 
+### Observable
+
+Provides a variable with observable capabilities, like pub/sub and React hook integration.
+
+```tsx
+  import { Observable } from '@slimr/react';
+  const myObservable = new Observable('myObservable', 0);
+  myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+  setTimeout(() => { myObservable.val = 42; }, 1000);
+  setTimeout(() => { myObservable.set(50); }, 2000);
+  setTimeout(() => { myObservable.set(last => last + 1); }, 3000);
+
+  function MyComponent() {
+    myObservable.use();
+    return <div>{myObservable.value}</div>;
+  }
+```
+
 ### useDeepCompareMemo and useShallowCompareMemo
 
 like react-use's useDeepEffects, but for memos

package/cjs/Observable.d.ts

@@ -0,0 +1,60 @@
+type ObservableSetter<T> = (value: T) => T;
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ *
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+export declare class Observable<T> {
+    name: string;
+    private _value;
+    private subscribers;
+    constructor(name: string, initialValue: T);
+    publish(): Promise<void[]>;
+    /**
+     * Sets a new value for the observable and notifies subscribers if the value changed.
+     *
+     * @param newValueOrSetter - The new value or a function that takes the current value and returns the new value.
+     * @returns The new value.
+     */
+    set(setter: ObservableSetter<T>): Promise<void>;
+    set(newValue: T): Promise<void>;
+    /**
+     * Register a callback to be called when the observable value changes.
+     * @param cb - The callback to be called when the value changes.
+     * @returns
+     */
+    subscribe(cb: (value: T) => void): () => void;
+    unsubscribe(cb: (value: T) => void): void;
+    /**
+     * A React hook to use this observable in a component
+     *
+     * It does not return the value, but subscribes to changes and forces re-render
+     * when the value changes.
+     *
+     * @usage
+     * ```tsx
+     * const myObservable = new Observable('myObservable', 0);
+     *
+     * function MyComponent() {
+     *   myObservable.use();
+     *   return <div>{myObservable.value}</div>;
+     * }
+     * ```
+     */
+    use(): void;
+    get val(): T;
+    set val(newValue: T);
+}
+export {};

package/cjs/Observable.js

@@ -0,0 +1,94 @@
+"use strict";
+// this file has exports to create an observable and useObservable react hook
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Observable = void 0;
+const util_1 = require("@slimr/util");
+const react_1 = require("react");
+// @ts-expect-error
+globalThis.observables = {};
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ *
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+class Observable {
+    name;
+    _value;
+    subscribers;
+    constructor(name, initialValue) {
+        this.name = name;
+        this._value = initialValue;
+        this.subscribers = new Set();
+        // @ts-expect-error
+        globalThis.observables[name] = this;
+    }
+    async publish() {
+        return Promise.all([...this.subscribers].map(subscriber => subscriber(this._value)));
+    }
+    async set(newValueOrSetter) {
+        const newValue = typeof newValueOrSetter === 'function'
+            ? newValueOrSetter(this._value)
+            : newValueOrSetter;
+        if (!(0, util_1.areEqualDeep)(this._value, newValue)) {
+            this._value = newValue;
+            await this.publish();
+        }
+    }
+    /**
+     * Register a callback to be called when the observable value changes.
+     * @param cb - The callback to be called when the value changes.
+     * @returns
+     */
+    subscribe(cb) {
+        // promisify the callback so it behaves like an async function even if it's not
+        // so that we can await all subscribers in publish()
+        const cbPromise = async (newValue) => cb(newValue);
+        this.subscribers.add(cbPromise);
+        return () => this.unsubscribe(cb);
+    }
+    unsubscribe(cb) {
+        this.subscribers.delete(cb);
+    }
+    /**
+     * A React hook to use this observable in a component
+     *
+     * It does not return the value, but subscribes to changes and forces re-render
+     * when the value changes.
+     *
+     * @usage
+     * ```tsx
+     * const myObservable = new Observable('myObservable', 0);
+     *
+     * function MyComponent() {
+     *   myObservable.use();
+     *   return <div>{myObservable.value}</div>;
+     * }
+     * ```
+     */
+    use() {
+        const [_, setValue] = (0, react_1.useState)(this.val);
+        (0, react_1.useEffect)(() => this.subscribe(setValue), []);
+    }
+    get val() {
+        // Freeze the value to avoid cases where the internal object may be mutated
+        // without triggering subscribers.
+        return Object.freeze(this._value);
+    }
+    set val(newValue) {
+        this.set(newValue);
+    }
+}
+exports.Observable = Observable;
+//# sourceMappingURL=Observable.js.map

package/cjs/Observable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Observable.js","sourceRoot":"","sources":["../src/Observable.ts"],"names":[],"mappings":";AAAA,6EAA6E;;;AAE7E,sCAA2C;AAC3C,iCAA4C;AAI5C,mBAAmB;AACnB,UAAU,CAAC,WAAW,GAAG,EAAE,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,UAAU;IACrB,IAAI,CAAS;IACL,MAAM,CAAI;IACV,WAAW,CAA0B;IAE7C,YAAY,IAAY,EAAE,YAAe;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,IAAI,GAAG,EAAE,CAAC;QAC7B,mBAAmB;QACnB,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;IAUD,KAAK,CAAC,GAAG,CAAC,gBAAqB;QAC7B,MAAM,QAAQ,GACZ,OAAO,gBAAgB,KAAK,UAAU;YACpC,CAAC,CAAE,gBAAwC,CAAC,IAAI,CAAC,MAAM,CAAC;YACxD,CAAC,CAAC,gBAAgB,CAAC;QACvB,IAAI,CAAC,IAAA,mBAAY,EAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;YACvB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,EAAsB;QAC9B,+EAA+E;QAC/E,oDAAoD;QACpD,MAAM,SAAS,GAAG,KAAK,EAAE,QAAW,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,WAAW,CAAC,EAAsB;QAChC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,GAAG;QACD,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzC,IAAA,iBAAS,EAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAA;IAC/C,CAAC;IAED,IAAI,GAAG;QACL,2EAA2E;QAC3E,kCAAkC;QAClC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,GAAG,CAAC,QAAW;QACjB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC;CACF;AAlFD,gCAkFC"}

package/cjs/Observable.ts

@@ -0,0 +1,110 @@
+// this file has exports to create an observable and useObservable react hook
+
+import { areEqualDeep } from '@slimr/util';
+import { useState, useEffect } from 'react';
+
+type ObservableSetter<T> = (value: T) => T;
+
+// @ts-expect-error
+globalThis.observables = {};
+
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ * 
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *  
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+export class Observable<T> {
+  name: string;
+  private _value: T;
+  private subscribers: Set<(value: T) => void>;
+
+  constructor(name: string, initialValue: T) {
+    this.name = name;
+    this._value = initialValue;
+    this.subscribers = new Set();
+    // @ts-expect-error
+    globalThis.observables[name] = this;
+  }
+
+  async publish() {
+    return Promise.all([...this.subscribers].map(subscriber => subscriber(this._value)));
+  }
+
+  /**
+   * Sets a new value for the observable and notifies subscribers if the value changed.
+   * 
+   * @param newValueOrSetter - The new value or a function that takes the current value and returns the new value.
+   * @returns The new value.
+   */
+  async set(setter: ObservableSetter<T>): Promise<void>;
+  async set(newValue: T): Promise<void>;
+  async set(newValueOrSetter: any): Promise<void> {
+    const newValue =
+      typeof newValueOrSetter === 'function'
+        ? (newValueOrSetter as ObservableSetter<T>)(this._value)
+        : newValueOrSetter;
+    if (!areEqualDeep(this._value, newValue)) {
+      this._value = newValue;
+      await this.publish();
+    }
+  }
+
+  /**
+   * Register a callback to be called when the observable value changes.
+   * @param cb - The callback to be called when the value changes.
+   * @returns 
+   */
+  subscribe(cb: (value: T) => void): () => void {
+    // promisify the callback so it behaves like an async function even if it's not
+    // so that we can await all subscribers in publish()
+    const cbPromise = async (newValue: T) => cb(newValue);
+    this.subscribers.add(cbPromise);
+    return () => this.unsubscribe(cb);
+  }
+
+  unsubscribe(cb: (value: T) => void): void {
+    this.subscribers.delete(cb);
+  }
+
+  /**
+   * A React hook to use this observable in a component
+   * 
+   * It does not return the value, but subscribes to changes and forces re-render
+   * when the value changes.
+   * 
+   * @usage
+   * ```tsx
+   * const myObservable = new Observable('myObservable', 0);
+   * 
+   * function MyComponent() {
+   *   myObservable.use();
+   *   return <div>{myObservable.value}</div>;
+   * }
+   * ```
+   */
+  use() {
+    const [_, setValue] = useState(this.val);
+    useEffect(() => this.subscribe(setValue), [])
+  }
+
+  get val(): T {
+    // Freeze the value to avoid cases where the internal object may be mutated
+    // without triggering subscribers.
+    return Object.freeze(this._value);
+  }
+  set val(newValue: T) {
+    this.set(newValue);
+  }
+}

package/cjs/index.d.ts

@@ -7,4 +7,5 @@ export * from "react-use";
 export * from "./merge-refs.js";
 export * from "./useColorScheme.js";
 export * from "./useMemos.js";
+export * from "./Observable.js";
 export * from "./useSet2.js";

package/cjs/index.js

@@ -23,5 +23,6 @@ __exportStar(require("react-use"), exports);
 __exportStar(require("./merge-refs.js"), exports);
 __exportStar(require("./useColorScheme.js"), exports);
 __exportStar(require("./useMemos.js"), exports);
+__exportStar(require("./Observable.js"), exports);
 __exportStar(require("./useSet2.js"), exports);
 //# sourceMappingURL=index.js.map

package/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA4B;AAC5B,kDAA+B;AAC/B,gDAA6B;AAC7B,gDAA6B;AAC7B,6CAA0B;AAC1B,4CAAyB;AAEzB,kDAA+B;AAC/B,sDAAmC;AACnC,gDAA6B;AAC7B,+CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA4B;AAC5B,kDAA+B;AAC/B,gDAA6B;AAC7B,gDAA6B;AAC7B,6CAA0B;AAC1B,4CAAyB;AAEzB,kDAA+B;AAC/B,sDAAmC;AACnC,gDAA6B;AAC7B,kDAA+B;AAC/B,+CAA4B"}

package/cjs/index.ts

@@ -8,4 +8,5 @@ export * from "react-use"
 export * from "./merge-refs.js"
 export * from "./useColorScheme.js"
 export * from "./useMemos.js"
+export * from "./Observable.js"
 export * from "./useSet2.js"

package/esm/Observable.d.ts

@@ -0,0 +1,60 @@
+type ObservableSetter<T> = (value: T) => T;
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ *
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+export declare class Observable<T> {
+    name: string;
+    private _value;
+    private subscribers;
+    constructor(name: string, initialValue: T);
+    publish(): Promise<void[]>;
+    /**
+     * Sets a new value for the observable and notifies subscribers if the value changed.
+     *
+     * @param newValueOrSetter - The new value or a function that takes the current value and returns the new value.
+     * @returns The new value.
+     */
+    set(setter: ObservableSetter<T>): Promise<void>;
+    set(newValue: T): Promise<void>;
+    /**
+     * Register a callback to be called when the observable value changes.
+     * @param cb - The callback to be called when the value changes.
+     * @returns
+     */
+    subscribe(cb: (value: T) => void): () => void;
+    unsubscribe(cb: (value: T) => void): void;
+    /**
+     * A React hook to use this observable in a component
+     *
+     * It does not return the value, but subscribes to changes and forces re-render
+     * when the value changes.
+     *
+     * @usage
+     * ```tsx
+     * const myObservable = new Observable('myObservable', 0);
+     *
+     * function MyComponent() {
+     *   myObservable.use();
+     *   return <div>{myObservable.value}</div>;
+     * }
+     * ```
+     */
+    use(): void;
+    get val(): T;
+    set val(newValue: T);
+}
+export {};

package/esm/Observable.js

@@ -0,0 +1,90 @@
+// this file has exports to create an observable and useObservable react hook
+import { areEqualDeep } from '@slimr/util';
+import { useState, useEffect } from 'react';
+// @ts-expect-error
+globalThis.observables = {};
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ *
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+export class Observable {
+    name;
+    _value;
+    subscribers;
+    constructor(name, initialValue) {
+        this.name = name;
+        this._value = initialValue;
+        this.subscribers = new Set();
+        // @ts-expect-error
+        globalThis.observables[name] = this;
+    }
+    async publish() {
+        return Promise.all([...this.subscribers].map(subscriber => subscriber(this._value)));
+    }
+    async set(newValueOrSetter) {
+        const newValue = typeof newValueOrSetter === 'function'
+            ? newValueOrSetter(this._value)
+            : newValueOrSetter;
+        if (!areEqualDeep(this._value, newValue)) {
+            this._value = newValue;
+            await this.publish();
+        }
+    }
+    /**
+     * Register a callback to be called when the observable value changes.
+     * @param cb - The callback to be called when the value changes.
+     * @returns
+     */
+    subscribe(cb) {
+        // promisify the callback so it behaves like an async function even if it's not
+        // so that we can await all subscribers in publish()
+        const cbPromise = async (newValue) => cb(newValue);
+        this.subscribers.add(cbPromise);
+        return () => this.unsubscribe(cb);
+    }
+    unsubscribe(cb) {
+        this.subscribers.delete(cb);
+    }
+    /**
+     * A React hook to use this observable in a component
+     *
+     * It does not return the value, but subscribes to changes and forces re-render
+     * when the value changes.
+     *
+     * @usage
+     * ```tsx
+     * const myObservable = new Observable('myObservable', 0);
+     *
+     * function MyComponent() {
+     *   myObservable.use();
+     *   return <div>{myObservable.value}</div>;
+     * }
+     * ```
+     */
+    use() {
+        const [_, setValue] = useState(this.val);
+        useEffect(() => this.subscribe(setValue), []);
+    }
+    get val() {
+        // Freeze the value to avoid cases where the internal object may be mutated
+        // without triggering subscribers.
+        return Object.freeze(this._value);
+    }
+    set val(newValue) {
+        this.set(newValue);
+    }
+}
+//# sourceMappingURL=Observable.js.map

package/esm/Observable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Observable.js","sourceRoot":"","sources":["../src/Observable.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAI5C,mBAAmB;AACnB,UAAU,CAAC,WAAW,GAAG,EAAE,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,UAAU;IACrB,IAAI,CAAS;IACL,MAAM,CAAI;IACV,WAAW,CAA0B;IAE7C,YAAY,IAAY,EAAE,YAAe;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;QAC3B,IAAI,CAAC,WAAW,GAAG,IAAI,GAAG,EAAE,CAAC;QAC7B,mBAAmB;QACnB,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;IAUD,KAAK,CAAC,GAAG,CAAC,gBAAqB;QAC7B,MAAM,QAAQ,GACZ,OAAO,gBAAgB,KAAK,UAAU;YACpC,CAAC,CAAE,gBAAwC,CAAC,IAAI,CAAC,MAAM,CAAC;YACxD,CAAC,CAAC,gBAAgB,CAAC;QACvB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC;YACvB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,EAAsB;QAC9B,+EAA+E;QAC/E,oDAAoD;QACpD,MAAM,SAAS,GAAG,KAAK,EAAE,QAAW,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,WAAW,CAAC,EAAsB;QAChC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,GAAG;QACD,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzC,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAA;IAC/C,CAAC;IAED,IAAI,GAAG;QACL,2EAA2E;QAC3E,kCAAkC;QAClC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,GAAG,CAAC,QAAW;QACjB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrB,CAAC;CACF"}

package/esm/Observable.ts

@@ -0,0 +1,110 @@
+// this file has exports to create an observable and useObservable react hook
+
+import { areEqualDeep } from '@slimr/util';
+import { useState, useEffect } from 'react';
+
+type ObservableSetter<T> = (value: T) => T;
+
+// @ts-expect-error
+globalThis.observables = {};
+
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ * 
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *  
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+export class Observable<T> {
+  name: string;
+  private _value: T;
+  private subscribers: Set<(value: T) => void>;
+
+  constructor(name: string, initialValue: T) {
+    this.name = name;
+    this._value = initialValue;
+    this.subscribers = new Set();
+    // @ts-expect-error
+    globalThis.observables[name] = this;
+  }
+
+  async publish() {
+    return Promise.all([...this.subscribers].map(subscriber => subscriber(this._value)));
+  }
+
+  /**
+   * Sets a new value for the observable and notifies subscribers if the value changed.
+   * 
+   * @param newValueOrSetter - The new value or a function that takes the current value and returns the new value.
+   * @returns The new value.
+   */
+  async set(setter: ObservableSetter<T>): Promise<void>;
+  async set(newValue: T): Promise<void>;
+  async set(newValueOrSetter: any): Promise<void> {
+    const newValue =
+      typeof newValueOrSetter === 'function'
+        ? (newValueOrSetter as ObservableSetter<T>)(this._value)
+        : newValueOrSetter;
+    if (!areEqualDeep(this._value, newValue)) {
+      this._value = newValue;
+      await this.publish();
+    }
+  }
+
+  /**
+   * Register a callback to be called when the observable value changes.
+   * @param cb - The callback to be called when the value changes.
+   * @returns 
+   */
+  subscribe(cb: (value: T) => void): () => void {
+    // promisify the callback so it behaves like an async function even if it's not
+    // so that we can await all subscribers in publish()
+    const cbPromise = async (newValue: T) => cb(newValue);
+    this.subscribers.add(cbPromise);
+    return () => this.unsubscribe(cb);
+  }
+
+  unsubscribe(cb: (value: T) => void): void {
+    this.subscribers.delete(cb);
+  }
+
+  /**
+   * A React hook to use this observable in a component
+   * 
+   * It does not return the value, but subscribes to changes and forces re-render
+   * when the value changes.
+   * 
+   * @usage
+   * ```tsx
+   * const myObservable = new Observable('myObservable', 0);
+   * 
+   * function MyComponent() {
+   *   myObservable.use();
+   *   return <div>{myObservable.value}</div>;
+   * }
+   * ```
+   */
+  use() {
+    const [_, setValue] = useState(this.val);
+    useEffect(() => this.subscribe(setValue), [])
+  }
+
+  get val(): T {
+    // Freeze the value to avoid cases where the internal object may be mutated
+    // without triggering subscribers.
+    return Object.freeze(this._value);
+  }
+  set val(newValue: T) {
+    this.set(newValue);
+  }
+}

package/esm/index.d.ts

@@ -7,4 +7,5 @@ export * from "react-use";
 export * from "./merge-refs.js";
 export * from "./useColorScheme.js";
 export * from "./useMemos.js";
+export * from "./Observable.js";
 export * from "./useSet2.js";

package/esm/index.js

@@ -7,5 +7,6 @@ export * from "react-use";
 export * from "./merge-refs.js";
 export * from "./useColorScheme.js";
 export * from "./useMemos.js";
+export * from "./Observable.js";
 export * from "./useSet2.js";
 //# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AAEzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AAEzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA"}

package/esm/index.ts

@@ -8,4 +8,5 @@ export * from "react-use"
 export * from "./merge-refs.js"
 export * from "./useColorScheme.js"
 export * from "./useMemos.js"
+export * from "./Observable.js"
 export * from "./useSet2.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slimr/react",
-  "version": "3.0.69",
+  "version": "3.0.71",
   "author": "Brian Dombrowski",
   "license": "ISC",
   "private": false,
@@ -31,12 +31,12 @@
     "start": "nodemon -w src -e '*' -x 'npm run build && cd ../demo && npm start'"
   },
   "dependencies": {
-    "@slimr/forms": "^5.0.43",
-    "@slimr/markdown": "^2.1.85",
-    "@slimr/router": "^2.1.71",
-    "@slimr/styled": "^2.1.82",
-    "@slimr/swr": "^2.1.70",
-    "@slimr/util": "^3.2.71",
+    "@slimr/forms": "^5.0.45",
+    "@slimr/markdown": "^2.1.87",
+    "@slimr/router": "^2.1.73",
+    "@slimr/styled": "^2.1.84",
+    "@slimr/swr": "^2.1.72",
+    "@slimr/util": "^3.2.73",
     "react-use": "17"
   },
   "peerDependencies": {

package/src/Observable.ts

@@ -0,0 +1,110 @@
+// this file has exports to create an observable and useObservable react hook
+
+import { areEqualDeep } from '@slimr/util';
+import { useState, useEffect } from 'react';
+
+type ObservableSetter<T> = (value: T) => T;
+
+// @ts-expect-error
+globalThis.observables = {};
+
+/**
+ * Provides a variable with observable capabilities, like pub/sub and React hook integration.
+ * 
+ * @usage
+ * ```tsx
+ *   const myObservable = new Observable('myObservable', 0);
+ *   myObservable.subscribe((newValue) => { console.log('New value:', newValue); });
+ *   setTimeout(() => { myObservable.val = 42; }, 1000);
+ *   setTimeout(() => { myObservable.set(50); }, 2000);
+ *   setTimeout(() => { myObservable.set(last => last + 1); }, 1000);
+ *  
+ *   function MyComponent() {
+ *     myObservable.use();
+ *     return <div>{myObservable.value}</div>;
+ *   }
+ * ```
+ */
+export class Observable<T> {
+  name: string;
+  private _value: T;
+  private subscribers: Set<(value: T) => void>;
+
+  constructor(name: string, initialValue: T) {
+    this.name = name;
+    this._value = initialValue;
+    this.subscribers = new Set();
+    // @ts-expect-error
+    globalThis.observables[name] = this;
+  }
+
+  async publish() {
+    return Promise.all([...this.subscribers].map(subscriber => subscriber(this._value)));
+  }
+
+  /**
+   * Sets a new value for the observable and notifies subscribers if the value changed.
+   * 
+   * @param newValueOrSetter - The new value or a function that takes the current value and returns the new value.
+   * @returns The new value.
+   */
+  async set(setter: ObservableSetter<T>): Promise<void>;
+  async set(newValue: T): Promise<void>;
+  async set(newValueOrSetter: any): Promise<void> {
+    const newValue =
+      typeof newValueOrSetter === 'function'
+        ? (newValueOrSetter as ObservableSetter<T>)(this._value)
+        : newValueOrSetter;
+    if (!areEqualDeep(this._value, newValue)) {
+      this._value = newValue;
+      await this.publish();
+    }
+  }
+
+  /**
+   * Register a callback to be called when the observable value changes.
+   * @param cb - The callback to be called when the value changes.
+   * @returns 
+   */
+  subscribe(cb: (value: T) => void): () => void {
+    // promisify the callback so it behaves like an async function even if it's not
+    // so that we can await all subscribers in publish()
+    const cbPromise = async (newValue: T) => cb(newValue);
+    this.subscribers.add(cbPromise);
+    return () => this.unsubscribe(cb);
+  }
+
+  unsubscribe(cb: (value: T) => void): void {
+    this.subscribers.delete(cb);
+  }
+
+  /**
+   * A React hook to use this observable in a component
+   * 
+   * It does not return the value, but subscribes to changes and forces re-render
+   * when the value changes.
+   * 
+   * @usage
+   * ```tsx
+   * const myObservable = new Observable('myObservable', 0);
+   * 
+   * function MyComponent() {
+   *   myObservable.use();
+   *   return <div>{myObservable.value}</div>;
+   * }
+   * ```
+   */
+  use() {
+    const [_, setValue] = useState(this.val);
+    useEffect(() => this.subscribe(setValue), [])
+  }
+
+  get val(): T {
+    // Freeze the value to avoid cases where the internal object may be mutated
+    // without triggering subscribers.
+    return Object.freeze(this._value);
+  }
+  set val(newValue: T) {
+    this.set(newValue);
+  }
+}

package/src/index.ts

@@ -8,4 +8,5 @@ export * from "react-use"
 export * from "./merge-refs.js"
 export * from "./useColorScheme.js"
 export * from "./useMemos.js"
+export * from "./Observable.js"
 export * from "./useSet2.js"