@ribbon-studios/js-utils 3.1.2 → 3.2.0

package/dist/index.cjs

@@ -203,30 +203,151 @@ rfetch.delete = (url, options) => {
   })(rfetch2.is || (rfetch2.is = {}));
 })(rfetch || (rfetch = {}));
 const _RibbonStorage = class _RibbonStorage {
-  static get(storage, key, defaultValue = null) {
+  static get(storage, key, defaultValue) {
     try {
       const value = storage.getItem(key);
-      if (!value) return defaultValue;
+      if (!value) return defaultValue ?? null;
       return JSON.parse(value);
     } catch {
-      return defaultValue;
+      return defaultValue ?? null;
     }
   }
   static set(storage, key, value) {
+    const type = storage === localStorage ? "local" : "session";
     if (value === void 0 || value === null) {
       storage.removeItem(key);
+      _RibbonStorage.$emit("change", {
+        type,
+        key,
+        value: null
+      });
     } else {
       storage.setItem(key, JSON.stringify(value));
+      _RibbonStorage.$emit("change", {
+        type,
+        key,
+        value
+      });
     }
   }
+  static on(key, listener) {
+    const index = _RibbonStorage.$listeners[key].indexOf(listener);
+    if (index !== -1) return;
+    _RibbonStorage.$listeners[key].push(listener);
+  }
+  static off(key, listener) {
+    const index = _RibbonStorage.$listeners[key].indexOf(listener);
+    if (index === -1) return;
+    _RibbonStorage.$listeners[key].splice(index, 1);
+  }
+  /**
+   * Here be dragons! This should never be called externally!
+   * @private
+   */
+  static $emit(key, ...args) {
+    const [event] = args;
+    for (const listener of _RibbonStorage.$listeners[key]) {
+      listener.apply(void 0, args);
+    }
+    switch (event.type) {
+      case "local":
+        _RibbonStorage.local.$emit(key, ...args);
+        break;
+      case "session":
+        _RibbonStorage.session.$emit(key, ...args);
+        break;
+    }
+  }
+  /**
+   * Resets RibbonStorage to a fresh state.
+   * Clearing out listeners and what not.
+   */
+  static reset() {
+    _RibbonStorage.$listeners = {
+      change: []
+    };
+    _RibbonStorage.local.reset();
+    _RibbonStorage.session.reset();
+  }
+  /**
+   * Clears local and session storage.
+   */
+  static clear() {
+    localStorage.clear();
+    sessionStorage.clear();
+  }
 };
+_RibbonStorage.$listeners = {
+  change: []
+};
+window.addEventListener("storage", (event) => {
+  if (event.key === null) return;
+  _RibbonStorage.$emit("change", {
+    type: event.storageArea === localStorage ? "local" : "session",
+    key: event.key,
+    value: event.newValue === null ? null : JSON.parse(event.newValue)
+  });
+});
 _RibbonStorage.local = {
+  $listeners: {
+    change: []
+  },
   get: (key, defaultValue) => _RibbonStorage.get(localStorage, key, defaultValue),
-  set: (key, value) => _RibbonStorage.set(localStorage, key, value)
+  set: (key, value) => _RibbonStorage.set(localStorage, key, value),
+  on(key, listener) {
+    const index = _RibbonStorage.local.$listeners[key].indexOf(listener);
+    if (index !== -1) return;
+    _RibbonStorage.local.$listeners[key].push(listener);
+  },
+  off(key, listener) {
+    const index = _RibbonStorage.local.$listeners[key].indexOf(listener);
+    if (index === -1) return;
+    _RibbonStorage.local.$listeners[key].splice(index, 1);
+  },
+  reset() {
+    _RibbonStorage.local.$listeners = {
+      change: []
+    };
+  },
+  $emit(key, ...args) {
+    for (const listener of _RibbonStorage.local.$listeners[key]) {
+      listener.apply(void 0, args);
+    }
+  }
 };
 _RibbonStorage.session = {
+  /**
+   * Here be dragons!
+   *
+   * If you need to remove a listener use {@link RibbonStorage.off}
+   * to reset all listeners use {@link RibbonStorage.reset}
+   * @private
+   */
+  $listeners: {
+    change: []
+  },
   get: (key, defaultValue) => _RibbonStorage.get(sessionStorage, key, defaultValue),
-  set: (key, value) => _RibbonStorage.set(sessionStorage, key, value)
+  set: (key, value) => _RibbonStorage.set(sessionStorage, key, value),
+  on(key, listener) {
+    const index = _RibbonStorage.session.$listeners[key].indexOf(listener);
+    if (index !== -1) return;
+    _RibbonStorage.session.$listeners[key].push(listener);
+  },
+  off(key, listener) {
+    const index = _RibbonStorage.session.$listeners[key].indexOf(listener);
+    if (index === -1) return;
+    _RibbonStorage.session.$listeners[key].splice(index, 1);
+  },
+  reset() {
+    _RibbonStorage.session.$listeners = {
+      change: []
+    };
+  },
+  $emit(key, ...args) {
+    for (const listener of _RibbonStorage.session.$listeners[key]) {
+      listener.apply(void 0, args);
+    }
+  }
 };
 let RibbonStorage = _RibbonStorage;
 exports.DelimiterType = DelimiterType;

package/dist/index.js

@@ -201,30 +201,151 @@ rfetch.delete = (url, options) => {
   })(rfetch2.is || (rfetch2.is = {}));
 })(rfetch || (rfetch = {}));
 const _RibbonStorage = class _RibbonStorage {
-  static get(storage, key, defaultValue = null) {
+  static get(storage, key, defaultValue) {
     try {
       const value = storage.getItem(key);
-      if (!value) return defaultValue;
+      if (!value) return defaultValue ?? null;
       return JSON.parse(value);
     } catch {
-      return defaultValue;
+      return defaultValue ?? null;
     }
   }
   static set(storage, key, value) {
+    const type = storage === localStorage ? "local" : "session";
     if (value === void 0 || value === null) {
       storage.removeItem(key);
+      _RibbonStorage.$emit("change", {
+        type,
+        key,
+        value: null
+      });
     } else {
       storage.setItem(key, JSON.stringify(value));
+      _RibbonStorage.$emit("change", {
+        type,
+        key,
+        value
+      });
     }
   }
+  static on(key, listener) {
+    const index = _RibbonStorage.$listeners[key].indexOf(listener);
+    if (index !== -1) return;
+    _RibbonStorage.$listeners[key].push(listener);
+  }
+  static off(key, listener) {
+    const index = _RibbonStorage.$listeners[key].indexOf(listener);
+    if (index === -1) return;
+    _RibbonStorage.$listeners[key].splice(index, 1);
+  }
+  /**
+   * Here be dragons! This should never be called externally!
+   * @private
+   */
+  static $emit(key, ...args) {
+    const [event] = args;
+    for (const listener of _RibbonStorage.$listeners[key]) {
+      listener.apply(void 0, args);
+    }
+    switch (event.type) {
+      case "local":
+        _RibbonStorage.local.$emit(key, ...args);
+        break;
+      case "session":
+        _RibbonStorage.session.$emit(key, ...args);
+        break;
+    }
+  }
+  /**
+   * Resets RibbonStorage to a fresh state.
+   * Clearing out listeners and what not.
+   */
+  static reset() {
+    _RibbonStorage.$listeners = {
+      change: []
+    };
+    _RibbonStorage.local.reset();
+    _RibbonStorage.session.reset();
+  }
+  /**
+   * Clears local and session storage.
+   */
+  static clear() {
+    localStorage.clear();
+    sessionStorage.clear();
+  }
 };
+_RibbonStorage.$listeners = {
+  change: []
+};
+window.addEventListener("storage", (event) => {
+  if (event.key === null) return;
+  _RibbonStorage.$emit("change", {
+    type: event.storageArea === localStorage ? "local" : "session",
+    key: event.key,
+    value: event.newValue === null ? null : JSON.parse(event.newValue)
+  });
+});
 _RibbonStorage.local = {
+  $listeners: {
+    change: []
+  },
   get: (key, defaultValue) => _RibbonStorage.get(localStorage, key, defaultValue),
-  set: (key, value) => _RibbonStorage.set(localStorage, key, value)
+  set: (key, value) => _RibbonStorage.set(localStorage, key, value),
+  on(key, listener) {
+    const index = _RibbonStorage.local.$listeners[key].indexOf(listener);
+    if (index !== -1) return;
+    _RibbonStorage.local.$listeners[key].push(listener);
+  },
+  off(key, listener) {
+    const index = _RibbonStorage.local.$listeners[key].indexOf(listener);
+    if (index === -1) return;
+    _RibbonStorage.local.$listeners[key].splice(index, 1);
+  },
+  reset() {
+    _RibbonStorage.local.$listeners = {
+      change: []
+    };
+  },
+  $emit(key, ...args) {
+    for (const listener of _RibbonStorage.local.$listeners[key]) {
+      listener.apply(void 0, args);
+    }
+  }
 };
 _RibbonStorage.session = {
+  /**
+   * Here be dragons!
+   *
+   * If you need to remove a listener use {@link RibbonStorage.off}
+   * to reset all listeners use {@link RibbonStorage.reset}
+   * @private
+   */
+  $listeners: {
+    change: []
+  },
   get: (key, defaultValue) => _RibbonStorage.get(sessionStorage, key, defaultValue),
-  set: (key, value) => _RibbonStorage.set(sessionStorage, key, value)
+  set: (key, value) => _RibbonStorage.set(sessionStorage, key, value),
+  on(key, listener) {
+    const index = _RibbonStorage.session.$listeners[key].indexOf(listener);
+    if (index !== -1) return;
+    _RibbonStorage.session.$listeners[key].push(listener);
+  },
+  off(key, listener) {
+    const index = _RibbonStorage.session.$listeners[key].indexOf(listener);
+    if (index === -1) return;
+    _RibbonStorage.session.$listeners[key].splice(index, 1);
+  },
+  reset() {
+    _RibbonStorage.session.$listeners = {
+      change: []
+    };
+  },
+  $emit(key, ...args) {
+    for (const listener of _RibbonStorage.session.$listeners[key]) {
+      listener.apply(void 0, args);
+    }
+  }
 };
 let RibbonStorage = _RibbonStorage;
 export {

package/dist/storage.d.ts

@@ -1,18 +1,65 @@
 export declare class RibbonStorage {
-    static get<T>(storage: globalThis.Storage, key: string, defaultValue?: T): T;
+    /**
+     * Here be dragons!
+     *
+     * If you need to remove a listener use {@link RibbonStorage.off}
+     * to reset all listeners use {@link RibbonStorage.reset}
+     * @private
+     */
+    static $listeners: RibbonStorage.Listeners;
+    static get<T>(storage: globalThis.Storage, key: string, defaultValue: T): T;
+    static get<T>(storage: globalThis.Storage, key: string, defaultValue?: T): T | null;
     static set<T>(storage: globalThis.Storage, key: string, value: T): void;
+    static on<K extends keyof RibbonStorage.Listeners>(key: K, listener: RibbonStorage.Listeners[K][number]): void;
+    static off<K extends keyof RibbonStorage.Listeners>(key: K, listener: RibbonStorage.Listeners[K][number]): void;
+    /**
+     * Here be dragons! This should never be called externally!
+     * @private
+     */
+    static $emit<K extends keyof RibbonStorage.Listeners>(key: K, ...args: Parameters<RibbonStorage.Listeners[K][number]>): void;
+    /**
+     * Resets RibbonStorage to a fresh state.
+     * Clearing out listeners and what not.
+     */
+    static reset(): void;
+    /**
+     * Clears local and session storage.
+     */
+    static clear(): void;
     /**
      * Shorthands for getting / setting from {@link localStorage}
      */
-    static local: {
-        get: <T>(key: string, defaultValue?: T) => T;
-        set: <T>(key: string, value: T) => void;
-    };
+    static local: RibbonStorage.SubStorage;
     /**
      * Shorthands for getting / setting from {@link sessionStorage}
      */
-    static session: {
-        get: <T>(key: string, defaultValue?: T) => T;
-        set: <T>(key: string, value: T) => void;
+    static session: RibbonStorage.SubStorage;
+}
+export declare namespace RibbonStorage {
+    type Listeners = {
+        change: ((event: ChangeEvent) => void)[];
+    };
+    type ChangeEvent = {
+        type: 'local' | 'session';
+        key: string;
+        /**
+         * This will always be the _parsed_ value!
+         */
+        value: any;
+    };
+    type SubStorage = {
+        $listeners: Listeners;
+        on<K extends keyof Listeners>(key: K, listener: Listeners[K][number]): void;
+        off<K extends keyof Listeners>(key: K, listener: Listeners[K][number]): void;
+        get<T>(key: string, defaultValue: T): T;
+        get<T>(key: string, defaultValue?: T): T | null;
+        get<T>(key: string, defaultValue?: T): T | null;
+        set<T>(key: string, value: T): void;
+        reset(): void;
+        /**
+         * Here be dragons! This should never be called externally!
+         * @private
+         */
+        $emit<K extends keyof Listeners>(key: K, ...args: Parameters<Listeners[K][number]>): void;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ribbon-studios/js-utils",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Collection of generic javascript utilities curated by the Ribbon Studios Team~",
   "type": "module",
   "source": "src/*.ts",