statepod 0.4.0

package/src/PersistentState.ts

@@ -0,0 +1,99 @@
+import { State, type StateOptions, type StatePayloadMap } from "./State.ts";
+import type { PersistentStorage } from "./types/PersistentStorage.ts";
+
+function getStorage(session = false) {
+  if (typeof window !== "undefined")
+    return session ? window.sessionStorage : window.localStorage;
+}
+
+export type StorageEntryOptions<T> = {
+  key: string;
+  session?: boolean;
+  serialize?: (value: T) => string;
+  deserialize?: (serializedValue: string) => T;
+};
+
+export function getStorageEntry<T>({
+  key,
+  session,
+  serialize = JSON.stringify,
+  deserialize = JSON.parse,
+}: StorageEntryOptions<T>): PersistentStorage<T> {
+  let storage = getStorage(session);
+
+  if (!storage) return { read: () => null, write: () => {} };
+
+  return {
+    read() {
+      try {
+        let serializedValue = storage.getItem(key);
+        if (serializedValue !== null) return deserialize(serializedValue);
+      } catch {}
+      return null;
+    },
+    write(value: T) {
+      try {
+        storage.setItem(key, serialize(value));
+      } catch {}
+    },
+  };
+}
+
+export type PersistentStatePayloadMap<T> = StatePayloadMap<T> & {
+  sync: void;
+  synconce: void;
+  effect: void;
+};
+
+/**
+ * A container for data persistent across page reloads.
+ */
+export class PersistentState<
+  T,
+  P extends PersistentStatePayloadMap<T> = PersistentStatePayloadMap<T>,
+> extends State<T, P> {
+  /**
+   * @param value - Initial state value.
+   * @param options - Either of the following:
+   * - A set of browser storage settings: `key` points to the target browser
+   * storage key where the state value should be saved; `session` set to `true`
+   * signals to use `sessionStorage` instead of `localStorage`, with the latter
+   * being the default; the optional `serialize` and `deserialize` define the
+   * way the state value is saved to and restored from the browser storage
+   * entry (default: `JSON.stringify` and `JSON.parse` respectively).
+   * - A storage singleton with a `read` and an optional `write` method
+   * (synchronous or asynchronous).
+   */
+  constructor(
+    value: T,
+    options: (StorageEntryOptions<T> | PersistentStorage<T>) & StateOptions,
+  ) {
+    super(value, { autoStart: false });
+
+    let { read, write } =
+      "read" in options ? options : getStorageEntry(options);
+
+    let update = (value: T | null) => {
+      if (value === null) write?.(this.getValue());
+      else this.setValue(value);
+    };
+
+    let sync = () => {
+      let value = read();
+
+      if (value instanceof Promise) value.then(update);
+      else update(value);
+    };
+
+    if (write) {
+      this.on("update", ({ current }) => {
+        write(current);
+      });
+    }
+
+    this.on("sync", sync);
+    this.on("start", sync);
+
+    if (options?.autoStart !== false) this.start();
+  }
+}

package/src/Route.ts

@@ -0,0 +1,295 @@
+import { QuasiURL } from "quasiurl";
+import type { LinkElement } from "./types/LinkElement.ts";
+import type { LocationPattern } from "./types/LocationPattern.ts";
+import type { LocationValue } from "./types/LocationValue.ts";
+import type { MatchHandler } from "./types/MatchHandler.ts";
+import type { NavigationOptions } from "./types/NavigationOptions.ts";
+import type { URLData } from "./types/URLData.ts";
+import {
+  URLState,
+  type URLStateOptions,
+  type URLStatePayloadMap,
+} from "./URLState.ts";
+import { compileURL } from "./utils/compileURL.ts";
+import { getNavigationOptions } from "./utils/getNavigationOptions.ts";
+import { isRouteEvent } from "./utils/isRouteEvent.ts";
+import { matchURL } from "./utils/matchURL.ts";
+
+export type ContainerElement = Document | Element | null | undefined;
+export type ElementCollection = (string | Node)[] | HTMLCollection | NodeList;
+
+export type ObservedElement =
+  | string
+  | Node
+  | (string | Node)[]
+  | HTMLCollection
+  | NodeList;
+
+function isElementCollection(x: unknown): x is ElementCollection {
+  return (
+    Array.isArray(x) || x instanceof NodeList || x instanceof HTMLCollection
+  );
+}
+
+function isLinkElement(x: unknown): x is LinkElement {
+  return x instanceof HTMLAnchorElement || x instanceof HTMLAreaElement;
+}
+
+function toggleActive(element: Element | Node, route: Route) {
+  if (!isLinkElement(element)) return;
+
+  if (
+    element.hasAttribute("href") &&
+    route.match(route.toValue(element.href)).ok
+  )
+    element.dataset.active = "true";
+  else delete element.dataset.active;
+}
+
+export type RoutePayloadMap = URLStatePayloadMap & {
+  documentclick: MouseEvent;
+};
+
+export type RouteOptions = URLStateOptions;
+
+export class Route extends URLState<RoutePayloadMap> {
+  _observeInited = false;
+  constructor(href: LocationValue | null = null, options?: RouteOptions) {
+    super(String(href ?? ""), options);
+  }
+  /**
+   * Enables SPA navigation with HTML links inside the specified container.
+   *
+   * @example
+   * ```js
+   * let route = new Route();
+   * route.observe(document);
+   * ```
+   */
+  observe(
+    container: ContainerElement | (() => ContainerElement),
+    elements: ObservedElement = "a, area",
+  ) {
+    if (typeof window === "undefined") return;
+
+    if (!this._observeInited) {
+      let handleClick = (event: MouseEvent) => {
+        this.emit("documentclick", event);
+      };
+
+      this.on("start", () => {
+        document.addEventListener("click", handleClick);
+      });
+
+      this.on("stop", () => {
+        document.removeEventListener("click", handleClick);
+      });
+
+      if (this.active) document.addEventListener("click", handleClick);
+
+      this._observeInited = true;
+    }
+
+    let resolveParams = () => {
+      let resolvedContainer =
+        typeof container === "function" ? container() : container;
+
+      if (!resolvedContainer) return;
+
+      let targetElements = isElementCollection(elements)
+        ? Array.from(elements)
+        : [elements];
+
+      return { resolvedContainer, targetElements };
+    };
+
+    let removeClickHandlers = this.on("documentclick", (event: MouseEvent) => {
+      if (event.defaultPrevented || !isRouteEvent(event)) return;
+
+      let resolvedParams = resolveParams();
+
+      if (!resolvedParams) return;
+
+      let { resolvedContainer, targetElements } = resolvedParams;
+      let element: HTMLAnchorElement | HTMLAreaElement | null = null;
+
+      for (let targetElement of targetElements) {
+        let target: Node | null = null;
+
+        if (typeof targetElement === "string")
+          target =
+            event.target instanceof HTMLElement
+              ? event.target.closest(targetElement)
+              : null;
+        else target = targetElement;
+
+        if (isLinkElement(target) && resolvedContainer.contains(target)) {
+          element = target;
+          break;
+        }
+      }
+
+      if (element) {
+        event.preventDefault();
+        this.navigate(getNavigationOptions(element));
+      }
+    });
+
+    let removeURLChangeHandlers = this.on("ready", () => {
+      let resolvedParams = resolveParams();
+
+      if (!resolvedParams) return;
+
+      let { resolvedContainer, targetElements } = resolvedParams;
+
+      for (let targetElement of targetElements) {
+        if (typeof targetElement === "string") {
+          let targets = resolvedContainer.querySelectorAll(targetElement);
+
+          for (let element of targets) toggleActive(element, this);
+        } else if (resolvedContainer.contains(targetElement))
+          toggleActive(targetElement, this);
+      }
+    });
+
+    return () => {
+      removeClickHandlers();
+      removeURLChangeHandlers();
+    };
+  }
+  /**
+   * Navigates to the URL specified with `options.href`.
+   *
+   * @example
+   * ```js
+   * let route = new Route();
+   * route.navigate({ href: "/intro", history: "replace", scroll: "off" });
+   * ```
+   */
+  navigate(options?: NavigationOptions<LocationValue>): void {
+    if (!options?.href) return;
+
+    let { href, referrer, ...params } = options;
+
+    // Stringify `LocationValue` URLs in `options`
+    let transformedOptions = {
+      href: String(href),
+      referrer: referrer && String(referrer),
+      ...params,
+    };
+
+    this.setValue(transformedOptions.href, transformedOptions);
+  }
+  assign(url: LocationValue) {
+    this.navigate({ href: url });
+  }
+  replace(url: LocationValue) {
+    this.navigate({ href: url, history: "replace" });
+  }
+  reload() {
+    this.assign(this.getValue());
+  }
+  go(delta: number) {
+    if (typeof window !== "undefined" && window.history)
+      window.history.go(delta);
+  }
+  back() {
+    this.go(-1);
+  }
+  forward() {
+    this.go(1);
+  }
+  get href(): string {
+    return this.getValue();
+  }
+  set href(value: LocationValue) {
+    this.assign(value);
+  }
+  get pathname(): string {
+    return new QuasiURL(this.href).pathname;
+  }
+  set pathname(value: LocationValue) {
+    let url = new QuasiURL(this.href);
+    url.pathname = String(value);
+    this.assign(url.href);
+  }
+  get search(): string {
+    return new QuasiURL(this.href).search;
+  }
+  set search(value: string | URLSearchParams) {
+    let url = new QuasiURL(this.href);
+    url.search = value;
+    this.assign(url.href);
+  }
+  get hash() {
+    return new QuasiURL(this.href).hash;
+  }
+  set hash(value: string) {
+    let url = new QuasiURL(this.href);
+    url.hash = value;
+    this.assign(url.href);
+  }
+  toString() {
+    return this.href;
+  }
+  /**
+   * Matches the current location against `urlPattern`.
+   */
+  match<P extends LocationPattern>(urlPattern: P) {
+    return matchURL<P>(urlPattern, this.href);
+  }
+  /**
+   * Compiles `urlPattern` to a URL string by filling out the parameters
+   * based on `data`.
+   */
+  compile<T extends LocationValue>(urlPattern: T, data?: URLData<T>) {
+    return compileURL<T>(urlPattern, data);
+  }
+  /**
+   * `at(urlPattern)` returns `true` if `urlPattern` matches the current URL,
+   * and `false` otherwise.
+   *
+   * `at(urlPattern, x, y?)` returns either based on `x` if `urlPattern`
+   * matches the current URL, or based on `y` otherwise. (It loosely resembles
+   * the ternary conditional operator `matchesURLPattern ? x : y`.)
+   *
+   * If the current location matches `urlPattern`, `at(urlPattern, x, y)`
+   * returns:
+   * - `x`, if `x` is not a function;
+   * - `x({ params })`, if `x` is a function, with `params` extracted from
+   * the current URL.
+   *
+   * If the current location doesn't match `urlPattern`, `at(urlPattern, x, y)`
+   * returns:
+   * - `y`, if `y` is not a function;
+   * - `y({ params })`, if `y` is a function, with `params` extracted from
+   * the current URL.
+   */
+  at<P extends LocationPattern>(urlPattern: P): boolean;
+
+  at<P extends LocationPattern, X>(
+    urlPattern: P,
+    x: X | MatchHandler<P, X>,
+  ): X | undefined;
+
+  at<P extends LocationPattern, X, Y>(
+    urlPattern: P,
+    x: X | MatchHandler<P, X>,
+    y: Y | MatchHandler<P, Y>,
+  ): X | Y;
+
+  at<P extends LocationPattern, X, Y>(
+    urlPattern: P,
+    x?: X | MatchHandler<P, X>,
+    y?: Y | MatchHandler<P, Y>,
+  ): X | Y | boolean | undefined {
+    let result = this.match<P>(urlPattern);
+
+    if (x === undefined && y === undefined) return result.ok;
+
+    if (!result.ok)
+      return typeof y === "function" ? (y as MatchHandler<P, Y>)(result) : y;
+
+    return typeof x === "function" ? (x as MatchHandler<P, X>)(result) : x;
+  }
+}

package/src/State.ts

@@ -0,0 +1,101 @@
+import { EventEmitter } from "./EventEmitter.ts";
+import type { EventCallback } from "./types/EventCallback.ts";
+
+export type StateUpdate<T> = (value: T) => T;
+
+export type StateUpdatePayload<T> = {
+  previous: T;
+  current: T;
+};
+
+export type StatePayloadMap<T> = Record<string, void> & {
+  update: StateUpdatePayload<T>;
+  // Similar to "update", but its callback is also immediately invoked when added
+  set: StateUpdatePayload<T>;
+  start: void;
+  stop: void;
+};
+
+export type StateOptions = {
+  /**
+   * Whether to call `start()` at initialization.
+   * @default true
+   */
+  autoStart?: boolean;
+};
+
+function isImmediatelyInvokedEvent(event: unknown): event is "set" {
+  return event === "set";
+}
+
+/**
+ * Data container allowing for subscription to its updates.
+ */
+export class State<
+  T,
+  P extends StatePayloadMap<T> = StatePayloadMap<T>,
+> extends EventEmitter<P> {
+  _value: T;
+  _revision = -1;
+  _active = false;
+  // For immediately invoked event callbacks added during inactivity
+  _queue: (() => void)[] = [];
+  constructor(value: T, options?: StateOptions) {
+    super();
+    this._value = value;
+    this._init();
+    if (options?.autoStart !== false) this.start();
+  }
+  _init() {}
+  _call(callback: () => void) {
+    if (this._active) callback();
+    else this._queue.push(callback);
+  }
+  on<E extends string>(event: E, callback: EventCallback<P[E]>) {
+    if (isImmediatelyInvokedEvent(event))
+      this._call(() => {
+        let current = this.getValue();
+
+        callback({ current, previous: current } as P[typeof event]);
+      });
+
+    return super.on(event, callback);
+  }
+  getValue() {
+    return this._value;
+  }
+  /**
+   * Updates the state value.
+   *
+   * @param update - A new value or an update function `(value) => nextValue`
+   * that returns a new state value based on the current state value.
+   */
+  setValue(update: T | StateUpdate<T>) {
+    if (this._active) this._assignValue(this._resolveValue(update));
+  }
+  _resolveValue(update: T | StateUpdate<T>) {
+    return update instanceof Function ? update(this._value) : update;
+  }
+  _assignValue(value: T) {
+    let previous = this._value;
+    let current = value;
+
+    this._value = current;
+    this._revision = Math.random();
+
+    this.emit("update", { previous, current });
+
+    // Unlike "update" callbacks, "set" callbacks are also immediately
+    // invoked when added
+    this.emit("set", { previous, current });
+  }
+  get revision() {
+    return this._revision;
+  }
+  start() {
+    super.start();
+
+    for (let callback of this._queue) callback();
+    this._queue = [];
+  }
+}

package/src/URLState.ts

@@ -0,0 +1,161 @@
+import { QuasiURL } from "quasiurl";
+import {
+  State,
+  type StateOptions,
+  type StatePayloadMap,
+  type StateUpdate,
+} from "./State.ts";
+import type { EventCallback } from "./types/EventCallback.ts";
+import type { NavigationOptions } from "./types/NavigationOptions.ts";
+
+export type URLStatePayloadMap = StatePayloadMap<string> & {
+  navigationstart: NavigationOptions;
+  // Similar to the "update" event, but with a `NavigationOptions` payload
+  navigation: NavigationOptions;
+  navigationcomplete: NavigationOptions;
+  ready: void;
+};
+
+function isImmediatelyInvokedNavigationEvent(
+  event: unknown,
+): event is "navigationstart" | "navigationcomplete" {
+  return event === "navigationstart" || event === "navigationcomplete";
+}
+
+function isImmediatelyInvokedEvent(event: unknown): event is "ready" {
+  return event === "ready";
+}
+
+export type URLStateOptions = StateOptions;
+
+export class URLState<
+  P extends URLStatePayloadMap = URLStatePayloadMap,
+> extends State<string, P> {
+  constructor(href: string | null = null, options?: URLStateOptions) {
+    super(href ?? "", options);
+  }
+  _init() {
+    super._init();
+
+    if (typeof window === "undefined") return;
+
+    let handleURLChange = () => {
+      this.setValue(window.location.href, { source: "popstate" });
+    };
+
+    this.on("start", () => {
+      window.addEventListener("popstate", handleURLChange);
+      this.emit("ready");
+    });
+
+    this.on("stop", () => {
+      window.removeEventListener("popstate", handleURLChange);
+    });
+  }
+  on<E extends string>(
+    event: E,
+    callback: EventCallback<P[E]>,
+    invokeImmediately?: boolean,
+  ) {
+    if (invokeImmediately !== false) {
+      if (isImmediatelyInvokedNavigationEvent(event))
+        this._call(() => {
+          callback({ href: this.getValue() } as P[typeof event]);
+        });
+      else if (isImmediatelyInvokedEvent(event))
+        this._call(() => {
+          (callback as EventCallback<void>)();
+        });
+    }
+
+    return super.on(event, callback);
+  }
+  getValue() {
+    return this.toValue(this._value);
+  }
+  setValue(update: string | StateUpdate<string>, options?: NavigationOptions) {
+    if (!this._active) return;
+
+    let href = this.toValue(this._resolveValue(update));
+
+    let extendedOptions: NavigationOptions = {
+      ...options,
+      href,
+      referrer: this.getValue(),
+    };
+
+    if (
+      this.emit("navigationstart", extendedOptions) &&
+      this._transition(extendedOptions) !== false
+    ) {
+      this._assignValue(href);
+      this.emit("navigation", extendedOptions);
+
+      if (this.emit("navigationcomplete", extendedOptions)) {
+        this._complete(extendedOptions);
+        this.emit("ready");
+      }
+    }
+  }
+  _transition(options?: NavigationOptions): boolean | void | undefined {
+    if (
+      typeof window === "undefined" ||
+      options?.href === undefined ||
+      options?.source === "popstate"
+    )
+      return;
+
+    let { href, target, spa, history } = options;
+
+    if (target && target !== "_self") {
+      window.open(href, target);
+      return false;
+    }
+
+    let url = new QuasiURL(href);
+
+    if (
+      spa === "off" ||
+      !window.history ||
+      (url.origin !== "" && url.origin !== window.location.origin)
+    ) {
+      window.location[history === "replace" ? "replace" : "assign"](href);
+      return false;
+    }
+
+    window.history[history === "replace" ? "replaceState" : "pushState"](
+      {},
+      "",
+      href,
+    );
+  }
+  _complete(options?: NavigationOptions): boolean | void | undefined {
+    if (typeof window === "undefined" || !options || options.scroll === "off")
+      return;
+
+    let { href, target } = options;
+
+    if (href === undefined || (target && target !== "_self")) return;
+
+    let { hash } = new QuasiURL(href);
+
+    requestAnimationFrame(() => {
+      let targetElement =
+        hash === ""
+          ? null
+          : document.querySelector(`${hash}, a[name="${hash.slice(1)}"]`);
+
+      if (targetElement) targetElement.scrollIntoView();
+      else window.scrollTo(0, 0);
+    });
+  }
+  toValue(x: string) {
+    if (typeof window === "undefined") return x;
+
+    let url = new QuasiURL(x || window.location.href);
+
+    if (url.origin === window.location.origin) url.origin = "";
+
+    return url.href;
+  }
+}

package/src/isState.ts

@@ -0,0 +1,20 @@
+import type { State, StatePayloadMap } from "./State.ts";
+
+/**
+ * Serves as an alternative to `instanceof State` which can lead to a false
+ * negative when `State` comes from a transitive dependency.
+ */
+export function isState<T, P extends StatePayloadMap<T> = StatePayloadMap<T>>(
+  x: unknown,
+): x is State<T, P> {
+  return (
+    x !== null &&
+    typeof x === "object" &&
+    "on" in x &&
+    typeof x.on === "function" &&
+    "emit" in x &&
+    typeof x.emit === "function" &&
+    "setValue" in x &&
+    typeof x.setValue === "function"
+  );
+}

package/src/types/EventCallback.ts

@@ -0,0 +1 @@
+export type EventCallback<T> = (payload: T) => boolean | undefined | void;

package/src/types/EventCallbackMap.ts

@@ -0,0 +1,5 @@
+import type { EventCallback } from "./EventCallback.ts";
+
+export type EventCallbackMap<Map extends Record<string, unknown>> = Partial<{
+  [K in keyof Map]: Set<EventCallback<Map[K]>>;
+}>;

package/src/types/LinkElement.ts

@@ -0,0 +1 @@
+export type LinkElement = HTMLAnchorElement | HTMLAreaElement;

package/src/types/LocationObject.ts

@@ -0,0 +1,11 @@
+import type { URLComponents } from "./URLComponents.ts";
+import type { URLSchema } from "./URLSchema.ts";
+
+// URL builder output
+export type LocationObject = {
+  _schema: URLSchema | undefined;
+  exec: (x: string) => URLComponents | null;
+  // biome-ignore lint/suspicious/noExplicitAny: third-party
+  compile: (x: any) => string;
+  toString: () => string;
+};

package/src/types/LocationPattern.ts

@@ -0,0 +1,6 @@
+import type { LocationValue } from "./LocationValue.ts";
+import type { URLConfig } from "./URLConfig.ts";
+
+export type LocationPattern = URLConfig["strict"] extends true
+  ? LocationValue | LocationValue[]
+  : LocationValue | RegExp | (LocationValue | RegExp)[];