hash-event-listener

README.md

@@ -39,6 +39,25 @@ const jsonBlob = getHashParamValueJsonFromWindow<Thing>("key");
 setHashParamValueJsonInWindow("key", jsonBlob);
 ```
 
+Use plain JavaScript hash param listeners (non-React):
+
+```typescript
+import {
+  addEventListenerHashParamJson,
+  setHashParamValueJsonInWindow,
+} from "@metapages/hash-query";
+
+const dispose = addEventListenerHashParamJson<Thing>("key", (value) => {
+  // Fires once after a tick with current value, then on each hashchange.
+  console.log("hash param changed:", value);
+});
+
+setHashParamValueJsonInWindow("key", { foo: "bar" });
+
+// Later: remove listener
+dispose();
+```
+
 ## How it works
 
 
@@ -62,12 +81,56 @@ useHashParamBoolean,
 useHashParamFloat,
 useHashParamInt,
 useHashParamJson,
+useHashParamUriEncoded,
 } from "@metapages/hash-query/react-hooks";
 
 ```
 
 Usage is the same as the JSON example above (get/set value)
 
+### Plain JavaScript listeners (typed):
+
+```typescript
+import {
+  addEventListenerHashParamBase64,
+  addEventListenerHashParamBoolean,
+  addEventListenerHashParamFloat,
+  addEventListenerHashParamInt,
+  addEventListenerHashParamJson,
+  addEventListenerHashParamUriEncoded,
+} from "@metapages/hash-query";
+
+const cleanupBase64 = addEventListenerHashParamBase64("name", (value) => {
+  // value: string | undefined (decoded from base64)
+});
+const cleanupBoolean = addEventListenerHashParamBoolean("enabled", (value) => {
+  // value: boolean | undefined
+});
+const cleanupFloat = addEventListenerHashParamFloat("ratio", (value) => {
+  // value: number | undefined
+});
+const cleanupInt = addEventListenerHashParamInt("count", (value) => {
+  // value: number | undefined
+});
+const cleanupJson = addEventListenerHashParamJson<{ foo: string }>(
+  "blob",
+  (value) => {
+    // value: { foo: string } | undefined
+  }
+);
+const cleanupUri = addEventListenerHashParamUriEncoded("q", (value) => {
+  // value: string | undefined (decoded from URI encoding)
+});
+
+// Each listener fires once after a tick with current value, then on hashchange.
+cleanupBase64();
+cleanupBoolean();
+cleanupFloat();
+cleanupInt();
+cleanupJson();
+cleanupUri();
+```
+
 ### Setting multiple hash parameters at once:
 
 ```typescript
@@ -134,4 +197,16 @@ setHashParamValueBase64EncodedInUrl
 getHashParamValueBase64DecodedFromUrl
 setHashParamValueBase64EncodedInWindow
 getHashParamValueBase64DecodedFromWindow
+# UriEncoded Functions
+setHashParamValueUriEncodedInUrl
+getHashParamValueUriDecodedFromUrl
+setHashParamValueUriEncodedInWindow
+getHashParamValueUriDecodedFromWindow
+# Listener Functions
+addEventListenerHashParamBase64
+addEventListenerHashParamBoolean
+addEventListenerHashParamFloat
+addEventListenerHashParamInt
+addEventListenerHashParamJson
+addEventListenerHashParamUriEncoded
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metapages/hash-query",
-  "version": "0.9.12",
+  "version": "0.10.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/metapages/hash-query.git"

src/core/index.ts

@@ -574,6 +574,110 @@ export const getHashParamValueUriDecodedFromWindow = (
   return getHashParamValueUriDecodedFromUrl(globalThis.location.href, key);
 };
 
+type HashParamValueListener<T> = (value: T | undefined) => void;
+
+const addEventListenerHashParam = <T>(
+  key: string,
+  getValue: (key: string) => T | undefined,
+  onHashParamChange: HashParamValueListener<T>
+): (() => void) => {
+  if (!isBrowser()) {
+    return () => {};
+  }
+
+  let disposed = false;
+  const onHashChange = (_: HashChangeEvent) => {
+    if (disposed) {
+      return;
+    }
+    onHashParamChange(getValue(key));
+  };
+
+  globalThis.addEventListener("hashchange", onHashChange);
+
+  // Defer initial call so consumers can subscribe and then process consistently.
+  setTimeout(() => {
+    if (disposed) {
+      return;
+    }
+    onHashParamChange(getValue(key));
+  }, 0);
+
+  return () => {
+    if (disposed) {
+      return;
+    }
+    disposed = true;
+    globalThis.removeEventListener("hashchange", onHashChange);
+  };
+};
+
+export const addEventListenerHashParamBase64 = (
+  key: string,
+  onHashParamChange: HashParamValueListener<string>
+): (() => void) => {
+  return addEventListenerHashParam(
+    key,
+    getHashParamValueBase64DecodedFromWindow,
+    onHashParamChange
+  );
+};
+
+export const addEventListenerHashParamBoolean = (
+  key: string,
+  onHashParamChange: HashParamValueListener<boolean>
+): (() => void) => {
+  return addEventListenerHashParam(
+    key,
+    getHashParamValueBooleanFromWindow,
+    onHashParamChange
+  );
+};
+
+export const addEventListenerHashParamFloat = (
+  key: string,
+  onHashParamChange: HashParamValueListener<number>
+): (() => void) => {
+  return addEventListenerHashParam(
+    key,
+    getHashParamValueFloatFromWindow,
+    onHashParamChange
+  );
+};
+
+export const addEventListenerHashParamInt = (
+  key: string,
+  onHashParamChange: HashParamValueListener<number>
+): (() => void) => {
+  return addEventListenerHashParam(
+    key,
+    getHashParamValueIntFromWindow,
+    onHashParamChange
+  );
+};
+
+export const addEventListenerHashParamJson = <T>(
+  key: string,
+  onHashParamChange: HashParamValueListener<T>
+): (() => void) => {
+  return addEventListenerHashParam(
+    key,
+    getHashParamValueJsonFromWindow,
+    onHashParamChange
+  );
+};
+
+export const addEventListenerHashParamUriEncoded = (
+  key: string,
+  onHashParamChange: HashParamValueListener<string>
+): (() => void) => {
+  return addEventListenerHashParam(
+    key,
+    getHashParamValueUriDecodedFromWindow,
+    onHashParamChange
+  );
+};
+
 export const deleteHashParamFromWindow = (
   key: string,
   opts?: SetHashParamOpts