@adobe/data 0.1.3 → 0.2.1

package/src/observe/create-observable-state.ts

@@ -0,0 +1,51 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+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.*/
+import { Notify, Observe } from "./types.js";
+
+/**
+ * Creates a simple state observe function and a setValue function to update the value.
+ * When observed, the current state if any will be immediately and synchronously sent to the observer callback.
+ * @param initialValue The initial value of the state.
+ */
+export function createObservableState<T>(
+  initialValue?: T
+): [Observe<T>, (value: T) => void] {
+  let value: T | undefined = initialValue;
+  const observers = new Set<Notify<T>>();
+  return [
+    (observer) => {
+      observers.add(observer);
+      if (value !== undefined) {
+        observer(value);
+      }
+      return () => {
+        observers.delete(observer);
+      };
+    },
+    (newValue) => {
+      value = newValue;
+      for (const observer of observers) {
+        observer(newValue);
+      }
+    },
+  ];
+}

package/src/observe/create-persisted-state.test.ts

@@ -0,0 +1,143 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+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.*/
+import { assert } from 'riteway/vitest';
+import { describe, test, beforeEach } from 'vitest';
+import { createPersistedState } from './create-persisted-state.js';
+
+describe('createPersistedState', () => {
+  // Mock storage implementation
+  class MockStorage implements Storage {
+    private store: Record<string, string> = {};
+    getItem(key: string): string | null {
+      return this.store[key] || null;
+    }
+    setItem(key: string, value: string): void {
+      this.store[key] = value;
+    }
+    clear(): void {
+      this.store = {};
+    }
+    removeItem(key: string): void {
+      delete this.store[key];
+    }
+    key(index: number): string | null {
+      return Object.keys(this.store)[index] || null;
+    }
+    get length(): number {
+      return Object.keys(this.store).length;
+    }
+  }
+
+  let mockStorage: Storage;
+
+  beforeEach(() => {
+    mockStorage = new MockStorage();
+  });
+
+  test('should initialize with initial value when storage is empty', () => {
+    const [observe, setter] = createPersistedState('test-key', 42 as number, mockStorage);
+
+    let observedValue: number | undefined;
+    observe((value) => {
+      observedValue = value;
+    });
+
+    assert({
+      given: 'initial value with empty storage',
+      should: 'use provided initial value',
+      actual: observedValue,
+      expected: 42,
+    });
+  });
+
+  test('should persist value updates to storage', () => {
+    const [_observe, setter] = createPersistedState('test-key', 42 as number, mockStorage);
+
+    setter(100);
+
+    assert({
+      given: 'value update',
+      should: 'persist to storage',
+      actual: JSON.parse(mockStorage.getItem('test-key') || 'null'),
+      expected: 100,
+    });
+  });
+
+  test('should load existing value from storage', () => {
+    // First create and set a value
+    const [_observe1, setter1] = createPersistedState('test-key', 42 as number, mockStorage);
+    setter1(100);
+
+    // Create new observe function with same key but different initial value
+    const [observe2, _setter2] = createPersistedState('test-key', 42 as number, mockStorage);
+
+    let observedValue: number | undefined;
+    observe2((value) => {
+      observedValue = value;
+    });
+
+    assert({
+      given: 'existing value in storage',
+      should: 'use stored value instead of initial value',
+      actual: observedValue,
+      expected: 100,
+    });
+  });
+
+  test('should handle invalid JSON in storage', () => {
+    mockStorage.setItem('test-key', 'invalid-json');
+
+    const [observe, _setter] = createPersistedState('test-key', 42 as number, mockStorage);
+
+    let observedValue: number | undefined;
+    observe((value) => {
+      observedValue = value;
+    });
+
+    assert({
+      given: 'invalid JSON in storage',
+      should: 'fall back to initial value',
+      actual: observedValue,
+      expected: 42,
+    });
+  });
+
+  test('should notify multiple observers of updates', () => {
+    const [observe, setter] = createPersistedState('test-key', 42 as number, mockStorage);
+
+    const observed: number[] = [];
+    const observed2: number[] = [];
+
+    observe((value) => observed.push(value));
+    observe((value) => observed2.push(value));
+
+    setter(100);
+    setter(200);
+
+    assert({
+      given: 'multiple observers',
+      should: 'notify all observers of updates',
+      actual: [observed, observed2],
+      expected: [[42, 100, 200], [42, 100, 200]],
+    });
+  });
+});

package/src/observe/create-persisted-state.ts

@@ -0,0 +1,60 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+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.*/
+import { Data } from "../index.js";
+import { createObservableState } from "./create-observable-state.js";
+import { Observe } from "./types.js";
+
+/**
+ * Creates a simple state observable that also returns a function to update the value.
+ * The state is persisted to the provided storage.
+ * Since this is stored in localStorage or sessionStorage it should not be used for large data.
+ * @param key The key to use for storage.
+ * @param initialValue The initial value of the state.
+ * @param storage The storage to use for persistence.
+ */
+export function createPersistedState<T extends Data>(
+  key: string,
+  initialValue?: T,
+  storage = localStorage
+): [Observe<T>, (value: T) => void] {
+  // Try to load initial state from storage
+  let storedValue: T | undefined;
+  const storedData = storage.getItem(key);
+  if (storedData) {
+    try {
+      storedValue = JSON.parse(storedData) as T;
+    } catch (e) {
+      console.warn(`Error parsing stored data for key ${key}:`, e);
+    }
+  }
+
+  // Create observable state with either stored or initial value
+  const [observable, setValue] = createObservableState(storedValue ?? initialValue);
+
+  // Wrap setValue to persist changes to storage
+  const setValueAndStore = (value: T) => {
+    setValue(value);
+    storage.setItem(key, JSON.stringify(value));
+  };
+
+  return [observable, setValueAndStore];
+}

package/src/observe/create-query-state.ts

@@ -0,0 +1,70 @@
+import { Data } from "../data.js";
+import { createObservableState } from "./create-observable-state.js";
+import { Observe } from "./types.js"; 
+
+type SetValue<T> = (value: T) => void;
+
+/**
+ * Creates an observable state that syncs with URL query parameters.
+ * @param key - The query parameter key to use
+ * @param initialValue - The initial value if no query parameter exists
+ * @param options - Configuration options
+ * @returns A tuple containing the observe function and the setValue function
+ */
+export const createQueryState = <T extends Data>(
+    key: string,
+    initialValue: T,
+    options: {
+        serialize?: (value: T) => string;
+        deserialize?: (value: string) => T;
+        replaceState?: boolean;
+    } = {}
+): [Observe<T>, SetValue<T>] => {
+    const {
+        serialize = (v) => JSON.stringify(v),
+        deserialize = (v) => JSON.parse(v),
+        replaceState = false
+    } = options;
+
+    // Get initial value from URL if it exists
+    const urlParams = new URLSearchParams(window.location.search);
+    const urlValue = urlParams.get(key);
+    const initial = urlValue ? deserialize(urlValue) : initialValue;
+
+    // Create the observable state
+    const [observe, setValue] = createObservableState<T>(initial);
+
+    // Create a wrapped setValue that updates both state and URL
+    const setQueryValue: SetValue<T> = (newValue: T) => {
+        setValue(newValue);
+        
+        const url = new URL(window.location.href);
+        const serialized = serialize(newValue);
+        
+        if (serialized === serialize(initialValue)) {
+            url.searchParams.delete(key);
+        } else {
+            url.searchParams.set(key, serialized);
+        }
+
+        // Update URL without page reload
+        if (replaceState) {
+            window.history.replaceState({}, '', url.toString());
+        } else {
+            window.history.pushState({}, '', url.toString());
+        }
+    };
+
+    // Listen for browser back/forward navigation
+    window.addEventListener('popstate', () => {
+        const urlParams = new URLSearchParams(window.location.search);
+        const urlValue = urlParams.get(key);
+        if (urlValue) {
+            setValue(deserialize(urlValue));
+        } else {
+            setValue(initialValue);
+        }
+    });
+
+    return [observe, setQueryValue];
+}; 

package/{observe/from-array.js → src/observe/from-array.ts}

@@ -20,11 +20,22 @@ 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.*/
 import { fromProperties } from "./from-properties.js";
+import { Observe } from "./types.js";
 import { withMap } from "./with-map.js";
+
 /**
  * Given an array of observe functions, returns a single observe function that will yield an array of each value.
  */
-export function fromArray(observeFunctions) {
-    return withMap(fromProperties(Object.fromEntries(observeFunctions.map((observable, index) => [index.toString(), observable]))), (values) => Object.values(values));
+
+export function fromArray<T>(
+  observeFunctions: Observe<T>[]
+): Observe<T[]> {
+  return withMap(
+    fromProperties(
+      Object.fromEntries(
+        observeFunctions.map((observable, index) => [index.toString(), observable])
+      )
+    ),
+    (values) => Object.values(values)
+  );
 }
-//# sourceMappingURL=from-array.js.map

package/{service/service.js → src/observe/from-constant.ts}

@@ -19,8 +19,17 @@ 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.*/
-export function isService(value) {
-    const maybeService = value;
-    return typeof maybeService?.serviceName === 'string';
+import { Observe } from "./types.js";
+
+/**
+ * Converts a constant value into an Observe<T> function.
+ */
+
+export function fromConstant<T>(value: T): Observe<T> {
+  return (observer) => {
+    observer(value);
+    return () => {
+      //  deliberately empty.
+    };
+  };
 }
-//# sourceMappingURL=service.js.map

package/{observe/from-element-id.js → src/observe/from-element-id.ts}

@@ -20,51 +20,56 @@ 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.*/
 import { fromConstant } from "./from-constant.js";
+import { Observe } from "./types.js";
+
 /**
  * Uses DOM MutationObserver to watch for the addition or removal of an element with a specific id.
  * @param id The id of the element to watch for.
  * @returns a new Observe<Element | null> which yields null if element does not exist.
  */
-export function fromElementId(ancestor, id) {
-    if (id === "") {
-        return fromConstant(null);
-    }
-    return (observer) => {
-        let lastElement = null;
-        const notify = () => {
-            const newElement = document.getElementById(id);
-            if (!lastElement || newElement !== lastElement) {
-                lastElement = newElement;
-                observer(newElement);
-            }
-        };
-        notify();
-        const mutationObserver = new MutationObserver((mutations) => {
-            let changed = false;
-            for (const mutation of mutations) {
-                if (mutation.type === "childList") {
-                    for (const node of mutation.addedNodes) {
-                        if (node.id === id) {
-                            changed = true;
-                        }
-                    }
-                    if (!changed) {
-                        for (const node of mutation.removedNodes) {
-                            if (node.id === id) {
-                                changed = true;
-                            }
-                        }
-                    }
-                }
+
+export function fromElementId<T extends HTMLElement = HTMLElement>(
+  ancestor: HTMLElement | ShadowRoot,
+  id: string
+): Observe<T | null> {
+  if (id === "") {
+    return fromConstant(null);
+  }
+  return (observer) => {
+    let lastElement: T | null = null;
+    const notify = () => {
+      const newElement = document.getElementById(id) as T | null;
+      if (!lastElement || newElement !== lastElement) {
+        lastElement = newElement;
+        observer(newElement);
+      }
+    };
+    notify();
+    const mutationObserver = new MutationObserver((mutations) => {
+      let changed = false;
+      for (const mutation of mutations) {
+        if (mutation.type === "childList") {
+          for (const node of mutation.addedNodes) {
+            if ((node as T).id === id) {
+              changed = true;
             }
-            if (changed) {
-                notify();
+          }
+          if (!changed) {
+            for (const node of mutation.removedNodes) {
+              if ((node as T).id === id) {
+                changed = true;
+              }
             }
-        });
-        mutationObserver.observe(ancestor, { childList: true, subtree: true });
-        return () => {
-            mutationObserver.disconnect();
-        };
+          }
+        }
+      }
+      if (changed) {
+        notify();
+      }
+    });
+    mutationObserver.observe(ancestor, { childList: true, subtree: true });
+    return () => {
+      mutationObserver.disconnect();
     };
+  };
 }
-//# sourceMappingURL=from-element-id.js.map

package/src/observe/from-element-properties-and-events.ts

@@ -0,0 +1,47 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+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.*/
+import { Observe } from "./types.js";
+
+//  private helper function to create an observable from an element property and events.
+export function fromElementPropertyAndEvents<
+  T extends HTMLElement,
+  K extends keyof T,
+  E extends keyof HTMLElementEventMap,
+>(element: T, property: K, events: E[]): Observe<T[K]> {
+  return (observer) => {
+    const listener = () => {
+      observer(element[property]);
+    };
+
+    for (const event of events) {
+      element.addEventListener(event, listener);
+    }
+
+    observer(element[property]);
+
+    return () => {
+      for (const event of events) {
+        element.removeEventListener(event, listener);
+      }
+    };
+  };
+}

package/{observe/from-element-property.js → src/observe/from-element-property.ts}

@@ -20,26 +20,32 @@ 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.*/
 import { fromElementPropertyAndEvents } from "./from-element-properties-and-events.js";
+import { Observe } from "./types.js";
+
 //  private helper function to create an observable from an element property and a mutation observer.
-function fromElementPropertyAndMutationObserver(element, property) {
-    return (observer) => {
-        observer(element[property]);
-        const mutationObserver = new MutationObserver((mutations) => {
-            //  this should only be called when the property changes.
-            //  check that this specific property was changed
-            for (const mutation of mutations) {
-                if (mutation.attributeName === property) {
-                    observer(element[property]);
-                    break;
-                }
-            }
-        });
-        mutationObserver.observe(element, { attributes: true });
-        return () => {
-            mutationObserver.disconnect();
-        };
+function fromElementPropertyAndMutationObserver<
+  T extends HTMLElement,
+  K extends keyof T,
+>(element: T, property: K): Observe<T[K]> {
+  return (observer) => {
+    observer(element[property]);
+    const mutationObserver = new MutationObserver((mutations) => {
+      //  this should only be called when the property changes.
+      //  check that this specific property was changed
+      for (const mutation of mutations) {
+        if (mutation.attributeName === property) {
+          observer(element[property]);
+          break;
+        }
+      }
+    });
+    mutationObserver.observe(element, { attributes: true });
+    return () => {
+      mutationObserver.disconnect();
     };
+  };
 }
+
 /**
  * Returns an observable that will notify observers when the element property changes.
  * If there are any events provided, then the observer will be notified when the event is triggered.
@@ -49,12 +55,14 @@ function fromElementPropertyAndMutationObserver(element, property) {
  * @param events The events that will trigger a new notification of changed values.
  * @returns
  */
-export function fromElementProperty(element, property, events = []) {
-    if (events.length > 0) {
-        return fromElementPropertyAndEvents(element, property, events);
-    }
-    else {
-        return fromElementPropertyAndMutationObserver(element, property);
-    }
+export function fromElementProperty<
+  T extends HTMLElement,
+  K extends keyof T,
+  E extends keyof HTMLElementEventMap,
+>(element: T, property: K, events: E[] = []): Observe<T[K]> {
+  if (events.length > 0) {
+    return fromElementPropertyAndEvents(element, property, events);
+  } else {
+    return fromElementPropertyAndMutationObserver(element, property);
+  }
 }
-//# sourceMappingURL=from-element-property.js.map

package/src/observe/from-promise-with-error.ts

@@ -0,0 +1,51 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+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.*/
+import { Observe } from "./types.js";
+
+/**
+ * Creates a new Observer that will notify observers exactly once when the promise is resolved.
+ * In the event of an error, the observer will be notified with the error.
+ * Note that the promise is only created when the first observer is added so it is lazy.
+ */
+export function fromPromiseWithError<T, E extends Error>(
+  promiseFactory: () => Promise<T>
+): Observe<T | E> {
+  let promise: Promise<T> | undefined = undefined;
+  return (observer) => {
+    let cancelled = false;
+    promise = promise ?? promiseFactory();
+    promise
+      .then((value) => {
+        if (!cancelled) {
+          observer(value);
+        }
+      })
+      .catch((error: E) => {
+        if (!cancelled) {
+          observer(error);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  };
+}