refactor: use url state parameters

BREAKING CHANGE:
getEncodedState replaces getLocationHash
onEncodedState replaces setLocationHash

Author: iamogbz

README.md

@@ -15,14 +15,14 @@ import { useCallback } from "react";
 import { useUrlState } from "react-state-url-fragment";
 
 export function usePageState<T>(defaultState?: T) {
-  const getLocationHash = useCallback(() => location.hash.substring(1), []);
-  const setLocationHash = useCallback((hash) => (location.hash = hash), []);
+  const getEncodedState = useCallback(() => location.hash.substring(1), []);
+  const onEncodedState = useCallback((hash) => (location.hash = hash), []);
   const handleDecodeError = defaultState && (() => defaultState);
 
   return useUrlState<T>({
-    getLocationHash,
+    getEncodedState,
     handleDecodeError,
-    setLocationHash,
+    onEncodedState,
   });
 }
 ```

demo/src/components/hooks/useAuthState.ts

@@ -10,17 +10,17 @@ const AUTH_STORAGE_KEY = "auth-storage-key";
 export function useAuthState(
   defaultState?: AuthState,
 ): UseUrlStateResult<AuthState> {
-  const getLocationHash = useCallback(function getStorageValue() {
+  const getEncodedState = useCallback(function getStorageValue() {
     return window.localStorage.getItem(AUTH_STORAGE_KEY) ?? "";
   }, []);
-  const setLocationHash = useCallback(function setStorageValue(hash: string) {
+  const onEncodedState = useCallback(function setStorageValue(hash: string) {
     window.localStorage.setItem(AUTH_STORAGE_KEY, hash);
   }, []);
   const handleDecodeError = defaultState && (() => defaultState);
 
   return useUrlState<AuthState>({
-    getLocationHash,
+    getEncodedState,
     handleDecodeError,
-    setLocationHash,
+    onEncodedState,
   });
 }

demo/src/components/hooks/usePageState.ts

@@ -8,15 +8,15 @@ type PageState = {
 export function usePageState<T = PageState>(
   defaultState?: T,
 ): UseUrlStateResult<T> {
-  const getLocationHash = useCallback(() => location.hash.substring(1), []);
-  const setLocationHash = useCallback((hash: string) => {
+  const getEncodedState = useCallback(() => location.hash.substring(1), []);
+  const onEncodedState = useCallback((hash: string) => {
     location.hash = hash;
   }, []);
   const handleDecodeError = defaultState && (() => defaultState);
 
   return useUrlState<T>({
-    getLocationHash,
+    getEncodedState,
     handleDecodeError,
-    setLocationHash,
+    onEncodedState,
   });
 }

src/hooks/useUrlState.test.ts

@@ -6,7 +6,7 @@ import { useUrlState } from "./useUrlState";
 describe("useUrlState", () => {
   const emptyUrlStateDecoded = {};
   const emptyUrlStateEncoded = "e30%3D";
-  const setLocationHash = jest.fn();
+  const onEncodedState = jest.fn();
   const fallbackEmptyUrlState = jest.fn(() => emptyUrlStateDecoded);
   const urlStateEncodedInvalid = "#!!invalid@!";
 
@@ -27,9 +27,9 @@ describe("useUrlState", () => {
 
       const { result } = renderHook(() =>
         useUrlState({
-          getLocationHash: () => encodedState,
+          getEncodedState: () => encodedState,
           handleDecodeError,
-          setLocationHash,
+          onEncodedState: onEncodedState,
         }),
       );
 
@@ -48,17 +48,20 @@ describe("useUrlState", () => {
     ${"next state is function"} | ${jest.fn(() => emptyUrlStateDecoded)}
   `("sets location hash to encoded state value", ({ nextStateAction }) => {
     const { result } = renderHook(() =>
-      useUrlState({ getLocationHash: () => urlStateEncoded, setLocationHash }),
+      useUrlState({
+        getEncodedState: () => urlStateEncoded,
+        onEncodedState: onEncodedState,
+      }),
     );
     const [, setState] = result.current;
 
-    expect(setLocationHash).not.toHaveBeenCalled();
+    expect(onEncodedState).not.toHaveBeenCalled();
     setState(nextStateAction);
     if (typeof nextStateAction === "function") {
       expect(nextStateAction).toHaveBeenCalledTimes(1);
       expect(nextStateAction).toHaveBeenLastCalledWith(urlStateDecoded);
     }
-    expect(setLocationHash).toHaveBeenCalledTimes(1);
-    expect(setLocationHash).toHaveBeenLastCalledWith(emptyUrlStateEncoded);
+    expect(onEncodedState).toHaveBeenCalledTimes(1);
+    expect(onEncodedState).toHaveBeenLastCalledWith(emptyUrlStateEncoded);
   });
 });

src/hooks/useUrlState.ts

@@ -8,21 +8,21 @@ export type UseUrlStateResult<T> = [
 ];
 
 export function useUrlState<T>(props: {
-  setLocationHash(urlEncodedState: string): void;
-  getLocationHash(): string;
+  onEncodedState(urlEncodedState: string): void;
+  getEncodedState(): string;
   handleDecodeError?(urlEncodedState: string): T;
 }): UseUrlStateResult<T> {
-  const { getLocationHash, handleDecodeError, setLocationHash } = props;
+  const { getEncodedState, handleDecodeError, onEncodedState } = props;
 
   const state = useRef<T | null>(null);
   state.current = useMemo(() => {
-    const encodedState = getLocationHash();
+    const encodedState = getEncodedState();
     try {
       return urlDecode<T>(encodedState);
     } catch (e) {
       return handleDecodeError?.(encodedState) ?? null;
     }
-  }, [getLocationHash, handleDecodeError]);
+  }, [getEncodedState, handleDecodeError]);
 
   const setState: UseUrlStateResult<T>[1] = useCallback(
     function setState(nextStateAction) {
@@ -31,9 +31,9 @@ export function useUrlState<T>(props: {
           ? (nextStateAction as CallableFunction)(state.current)
           : nextStateAction;
       const hash = urlEncode(newState);
-      setLocationHash(hash);
+      onEncodedState(hash);
     },
-    [setLocationHash],
+    [onEncodedState],
   );
 
   return [state.current, setState];