statepod 0.4.0

package/dist/index.mjs

@@ -0,0 +1,564 @@
+import { QuasiURL } from "quasiurl";
+
+var EventEmitter = class {
+  _callbacks = {};
+  _active = true;
+  /**
+  * Adds an event handler.
+  *
+  * Returns an unsubscription function. Once it's invoked, the given
+  * `callback` is removed and no longer called in response to the event.
+  */
+  on(event, callback) {
+    (this._callbacks[event] ??= /* @__PURE__ */ new Set()).add(callback);
+    return () => this.off(event, callback);
+  }
+  /**
+  * Adds a one-time event handler: once the event is emitted, the callback
+  * is called and immediately removed.
+  */
+  once(event, callback) {
+    let oneTimeCallback = (payload) => {
+      this.off(event, oneTimeCallback);
+      callback(payload);
+    };
+    return this.on(event, oneTimeCallback);
+  }
+  /**
+  * Removes the specified `callback` from the handlers of the given event,
+  * and removes all handlers of the given event if `callback` is not
+  * specified.
+  */
+  off(event, callback) {
+    if (callback === void 0) delete this._callbacks[event];
+    else this._callbacks[event]?.delete(callback);
+  }
+  /**
+  * Emits the specified event. Returns `false` if at least one event callback
+  * returns `false`, effectively interrupting the callback call chain.
+  * Otherwise returns `true`.
+  */
+  emit(event, payload) {
+    let callbacks = this._callbacks[event];
+    if (this._active && callbacks?.size) {
+      for (let callback of callbacks) if (callback(payload) === false) return false;
+    }
+    return true;
+  }
+  get active() {
+    return this._active;
+  }
+  start() {
+    if (!this._active) {
+      this._active = true;
+      this.emit("start");
+    }
+  }
+  stop() {
+    if (this._active) {
+      this._active = false;
+      this.emit("stop");
+    }
+  }
+};
+
+/**
+* Serves as an alternative to `instanceof State` which can lead to a false
+* negative when `State` comes from a transitive dependency.
+*/
+function isState(x) {
+  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";
+}
+
+function isImmediatelyInvokedEvent$1(event) {
+  return event === "set";
+}
+/**
+* Data container allowing for subscription to its updates.
+*/
+var State = class extends EventEmitter {
+  _value;
+  _revision = -1;
+  _active = false;
+  _queue = [];
+  constructor(value, options) {
+    super();
+    this._value = value;
+    this._init();
+    if (options?.autoStart !== false) this.start();
+  }
+  _init() {}
+  _call(callback) {
+    if (this._active) callback();
+    else this._queue.push(callback);
+  }
+  on(event, callback) {
+    if (isImmediatelyInvokedEvent$1(event)) this._call(() => {
+      let current = this.getValue();
+      callback({
+        current,
+        previous: current
+      });
+    });
+    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) {
+    if (this._active) this._assignValue(this._resolveValue(update));
+  }
+  _resolveValue(update) {
+    return update instanceof Function ? update(this._value) : update;
+  }
+  _assignValue(value) {
+    let previous = this._value;
+    let current = value;
+    this._value = current;
+    this._revision = Math.random();
+    this.emit("update", {
+      previous,
+      current
+    });
+    this.emit("set", {
+      previous,
+      current
+    });
+  }
+  get revision() {
+    return this._revision;
+  }
+  start() {
+    super.start();
+    for (let callback of this._queue) callback();
+    this._queue = [];
+  }
+};
+
+function getStorage(session = false) {
+  if (typeof window !== "undefined") return session ? window.sessionStorage : window.localStorage;
+}
+function getStorageEntry({ key, session, serialize = JSON.stringify, deserialize = JSON.parse }) {
+  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) {
+      try {
+        storage.setItem(key, serialize(value));
+      } catch {}
+    }
+  };
+}
+/**
+* A container for data persistent across page reloads.
+*/
+var PersistentState = class extends State {
+  /**
+  * @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, options) {
+    super(value, { autoStart: false });
+    let { read, write } = "read" in options ? options : getStorageEntry(options);
+    let update = (value) => {
+      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();
+  }
+};
+
+function isImmediatelyInvokedNavigationEvent(event) {
+  return event === "navigationstart" || event === "navigationcomplete";
+}
+function isImmediatelyInvokedEvent(event) {
+  return event === "ready";
+}
+var URLState = class extends State {
+  constructor(href = null, options) {
+    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(event, callback, invokeImmediately) {
+    if (invokeImmediately !== false) {
+      if (isImmediatelyInvokedNavigationEvent(event)) this._call(() => {
+        callback({ href: this.getValue() });
+      });
+      else if (isImmediatelyInvokedEvent(event)) this._call(() => {
+        callback();
+      });
+    }
+    return super.on(event, callback);
+  }
+  getValue() {
+    return this.toValue(this._value);
+  }
+  setValue(update, options) {
+    if (!this._active) return;
+    let href = this.toValue(this._resolveValue(update));
+    let extendedOptions = {
+      ...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) {
+    if (typeof window === "undefined" || options?.href === void 0 || 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) {
+    if (typeof window === "undefined" || !options || options.scroll === "off") return;
+    let { href, target } = options;
+    if (href === void 0 || 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) {
+    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;
+  }
+};
+
+function isLocationObject(x) {
+  return x !== null && typeof x === "object" && "exec" in x && "compile" in x && "_schema" in x;
+}
+
+function compileURL(urlPattern, data) {
+  if (isLocationObject(urlPattern)) return urlPattern.compile(data);
+  let url = new QuasiURL(urlPattern ?? "");
+  let query = data?.query;
+  if (query) url.search = new URLSearchParams(Object.entries(query).reduce((p, [k, v]) => {
+    if (v !== null && v !== void 0) p[k] = typeof v === "string" ? v : JSON.stringify(v);
+    return p;
+  }, {}));
+  return url.href;
+}
+
+function getNavigationOptions(element) {
+  let { id, spa, history, scroll } = element.dataset;
+  return {
+    href: element.getAttribute("href"),
+    target: element.getAttribute("target"),
+    spa,
+    history,
+    scroll,
+    id
+  };
+}
+
+function isRouteEvent(event) {
+  return event !== null && typeof event === "object" && (!("button" in event) || event.button === 0) && (!("ctrlKey" in event) || !event.ctrlKey) && (!("shiftKey" in event) || !event.shiftKey) && (!("altKey" in event) || !event.altKey) && (!("metaKey" in event) || !event.metaKey);
+}
+
+function toObject(x) {
+  return x.reduce((p, v, k) => {
+    p[String(k)] = v;
+    return p;
+  }, {});
+}
+function matchPattern(pattern, href) {
+  let query = Object.fromEntries(new URLSearchParams(new QuasiURL(href).search));
+  if (typeof pattern === "string") return {
+    ok: pattern === "*" || pattern === href,
+    href,
+    params: {},
+    query
+  };
+  if (pattern instanceof RegExp) {
+    let matches = pattern.exec(href);
+    return {
+      ok: matches !== null,
+      href,
+      params: matches ? {
+        ...toObject(Array.from(matches).slice(1)),
+        ...matches.groups
+      } : {},
+      query
+    };
+  }
+  if (isLocationObject(pattern)) {
+    let result = pattern.exec(href);
+    if (result === null) return {
+      ok: false,
+      href,
+      params: {},
+      query: {}
+    };
+    return {
+      ok: true,
+      href,
+      params: result.params ?? {},
+      query: result.query ?? {}
+    };
+  }
+  return {
+    ok: false,
+    href,
+    params: {},
+    query: {}
+  };
+}
+function matchURL(pattern, href) {
+  if (Array.isArray(pattern)) {
+    for (let p of pattern) {
+      let result = matchPattern(p, href);
+      if (result.ok) return result;
+    }
+    return {
+      ok: false,
+      href,
+      params: {},
+      query: {}
+    };
+  }
+  return matchPattern(pattern, href);
+}
+
+function isElementCollection(x) {
+  return Array.isArray(x) || x instanceof NodeList || x instanceof HTMLCollection;
+}
+function isLinkElement(x) {
+  return x instanceof HTMLAnchorElement || x instanceof HTMLAreaElement;
+}
+function toggleActive(element, 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;
+}
+var Route = class extends URLState {
+  _observeInited = false;
+  constructor(href = null, options) {
+    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, elements = "a, area") {
+    if (typeof window === "undefined") return;
+    if (!this._observeInited) {
+      let handleClick = (event) => {
+        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;
+      return {
+        resolvedContainer,
+        targetElements: isElementCollection(elements) ? Array.from(elements) : [elements]
+      };
+    };
+    let removeClickHandlers = this.on("documentclick", (event) => {
+      if (event.defaultPrevented || !isRouteEvent(event)) return;
+      let resolvedParams = resolveParams();
+      if (!resolvedParams) return;
+      let { resolvedContainer, targetElements } = resolvedParams;
+      let element = null;
+      for (let targetElement of targetElements) {
+        let target = 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) {
+    if (!options?.href) return;
+    let { href, referrer, ...params } = options;
+    let transformedOptions = {
+      href: String(href),
+      referrer: referrer && String(referrer),
+      ...params
+    };
+    this.setValue(transformedOptions.href, transformedOptions);
+  }
+  assign(url) {
+    this.navigate({ href: url });
+  }
+  replace(url) {
+    this.navigate({
+      href: url,
+      history: "replace"
+    });
+  }
+  reload() {
+    this.assign(this.getValue());
+  }
+  go(delta) {
+    if (typeof window !== "undefined" && window.history) window.history.go(delta);
+  }
+  back() {
+    this.go(-1);
+  }
+  forward() {
+    this.go(1);
+  }
+  get href() {
+    return this.getValue();
+  }
+  set href(value) {
+    this.assign(value);
+  }
+  get pathname() {
+    return new QuasiURL(this.href).pathname;
+  }
+  set pathname(value) {
+    let url = new QuasiURL(this.href);
+    url.pathname = String(value);
+    this.assign(url.href);
+  }
+  get search() {
+    return new QuasiURL(this.href).search;
+  }
+  set search(value) {
+    let url = new QuasiURL(this.href);
+    url.search = value;
+    this.assign(url.href);
+  }
+  get hash() {
+    return new QuasiURL(this.href).hash;
+  }
+  set hash(value) {
+    let url = new QuasiURL(this.href);
+    url.hash = value;
+    this.assign(url.href);
+  }
+  toString() {
+    return this.href;
+  }
+  /**
+  * Matches the current location against `urlPattern`.
+  */
+  match(urlPattern) {
+    return matchURL(urlPattern, this.href);
+  }
+  /**
+  * Compiles `urlPattern` to a URL string by filling out the parameters
+  * based on `data`.
+  */
+  compile(urlPattern, data) {
+    return compileURL(urlPattern, data);
+  }
+  at(urlPattern, x, y) {
+    let result = this.match(urlPattern);
+    if (x === void 0 && y === void 0) return result.ok;
+    if (!result.ok) return typeof y === "function" ? y(result) : y;
+    return typeof x === "function" ? x(result) : x;
+  }
+};
+
+export { EventEmitter, PersistentState, Route, State, URLState, compileURL, getNavigationOptions, getStorageEntry, isLocationObject, isRouteEvent, isState, matchURL };

package/index.ts

@@ -0,0 +1,25 @@
+export * from "./src/EventEmitter.ts";
+export * from "./src/isState.ts";
+export * from "./src/PersistentState.ts";
+export * from "./src/Route.ts";
+export * from "./src/State.ts";
+export * from "./src/types/EventCallback.ts";
+export * from "./src/types/EventCallbackMap.ts";
+export * from "./src/types/LinkElement.ts";
+export * from "./src/types/LocationObject.ts";
+export * from "./src/types/LocationPattern.ts";
+export * from "./src/types/LocationValue.ts";
+export * from "./src/types/MatchHandler.ts";
+export * from "./src/types/MatchState.ts";
+export * from "./src/types/NavigationOptions.ts";
+export * from "./src/types/PersistentStorage.ts";
+export * from "./src/types/URLComponents.ts";
+export * from "./src/types/URLConfig.ts";
+export * from "./src/types/URLData.ts";
+export * from "./src/types/URLSchema.ts";
+export * from "./src/URLState.ts";
+export * from "./src/utils/compileURL.ts";
+export * from "./src/utils/getNavigationOptions.ts";
+export * from "./src/utils/isLocationObject.ts";
+export * from "./src/utils/isRouteEvent.ts";
+export * from "./src/utils/matchURL.ts";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "statepod",
+  "version": "0.4.0",
+  "description": "Vanilla TS/JS shared state management and routing",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "demo": "npx auxsrv tests/URL-based_rendering",
+    "preversion": "npx npm-run-all shape test",
+    "shape": "npx codeshape",
+    "test": "npx npm-run-all test1 test2",
+    "test1": "node tests/index.ts",
+    "test2": "npx playwright test --project=chromium",
+    "typecheck": "npx codeshape typecheck"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axtk/statepod.git"
+  },
+  "keywords": [
+    "state",
+    "shared state",
+    "state management",
+    "persistent state",
+    "routing"
+  ],
+  "author": "axtk",
+  "license": "MIT",
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^26.1.1",
+    "auxsrv": "^0.3.19",
+    "url-shape": "^2.1.6",
+    "zod": "^4.4.3"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "quasiurl": "^1.1.15"
+  }
+}

package/src/EventEmitter.ts

@@ -0,0 +1,72 @@
+import type { EventCallback } from "./types/EventCallback.ts";
+import type { EventCallbackMap } from "./types/EventCallbackMap.ts";
+
+export class EventEmitter<
+  P extends Record<string, unknown> = Record<string, void>,
+> {
+  _callbacks: EventCallbackMap<P> = {};
+  _active = true;
+  /**
+   * Adds an event handler.
+   *
+   * Returns an unsubscription function. Once it's invoked, the given
+   * `callback` is removed and no longer called in response to the event.
+   */
+  on<E extends string>(event: E, callback: EventCallback<P[E]>) {
+    (this._callbacks[event] ??= new Set()).add(callback);
+
+    return () => this.off(event, callback);
+  }
+  /**
+   * Adds a one-time event handler: once the event is emitted, the callback
+   * is called and immediately removed.
+   */
+  once<E extends string>(event: E, callback: EventCallback<P[E]>) {
+    let oneTimeCallback = (payload: P[E]) => {
+      this.off(event, oneTimeCallback);
+      callback(payload);
+    };
+
+    return this.on(event, oneTimeCallback);
+  }
+  /**
+   * Removes the specified `callback` from the handlers of the given event,
+   * and removes all handlers of the given event if `callback` is not
+   * specified.
+   */
+  off<E extends string>(event: E, callback?: EventCallback<P[E]>) {
+    if (callback === undefined) delete this._callbacks[event];
+    else this._callbacks[event]?.delete(callback);
+  }
+  /**
+   * Emits the specified event. Returns `false` if at least one event callback
+   * returns `false`, effectively interrupting the callback call chain.
+   * Otherwise returns `true`.
+   */
+  emit<E extends string>(event: E, payload?: P[E]) {
+    let callbacks = this._callbacks[event];
+
+    if (this._active && callbacks?.size) {
+      for (let callback of callbacks) {
+        if (callback(payload!) === false) return false;
+      }
+    }
+
+    return true;
+  }
+  get active() {
+    return this._active;
+  }
+  start() {
+    if (!this._active) {
+      this._active = true;
+      this.emit("start");
+    }
+  }
+  stop() {
+    if (this._active) {
+      this._active = false;
+      this.emit("stop");
+    }
+  }
+}