stateshape 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alexander Tkačenko
+
+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.

package/README.md

@@ -0,0 +1,166 @@
+# stateshape
+
+Vanilla TS/JS state management for sharing data across decoupled parts of the code and routing. Routing is essentially shared state management, too, with the shared data being the URL.
+
+This package exposes the following classes:
+
+```
+EventEmitter ──► State ──► PersistentState
+                    │
+                    └────► URLState ──► Route
+```
+
+Roughly, their purpose boils down to the following:
+
+- `EventEmitter` is for triggering actions without tightly coupling the interacting components
+- `State` is `EventEmitter` that stores data and emits an event when the data gets updated, it's for dynamic data sharing without tight coupling
+- `PersistentState` is `State` that syncs its data to the browser storage and restores it on page reload
+- `URLState` is `State` that stores the URL + syncs with the browser's URL in a SPA fashion
+- `Route` is `URLState` + native-like APIs for SPA navigation and an API for URL matching
+
+Contents: [State](#state) · [PersistentState](#persistentstate) · [Route](#route) · [Annotated examples](#annotated-examples) · [Integrations](#integrations)
+
+## `State`
+
+A thin data container for dynamic data sharing without tight coupling.
+
+```js
+import { State } from "stateshape";
+
+const counterState = new State(42);
+
+document.querySelector("button").addEventListener("click", () => {
+  counterState.setValue((value) => value + 1);
+});
+
+counterState.on("set", ({ current }) => {
+  document.querySelector("output").textContent = String(current);
+});
+```
+
+In this example, a button changes a counter value and an `<output>` element shows the updating value. Both elements are only aware of the shared counter state, but not of each other.
+
+A `"set"` event callback is called each time the state value changes and immediately when the callback is added. Subscribe to the `"update"` event to have the callback respond only to the subsequent state changes without the immediate invocation.
+
+## `PersistentState`
+
+A variety of `State` that syncs its data to the browser storage and restores it on page reload. Otherwise, almost identical to `State` in usage.
+
+```diff
+- import { State } from "stateshape";
++ import { PersistentState } from "stateshape";
+
+- const counterState = new State(42);
++ const counterState = new PersistentState(42, { key: "counter" });
+
+  document.querySelector("button").addEventListener("click", () => {
+    counterState.setValue((value) => value + 1);
+  });
+
+  counterState.on("set", ({ current }) => {
+    document.querySelector("output").textContent = String(current);
+  });
+```
+
+By default, `PersistentState` stores its data at the specified `key` in `localStorage` and transforms the data with `JSON.stringify()` and `JSON.parse()`. Switch to `sessionStorage` by setting `options.session` to `true` in `new PersistentState(value, options)`. Set custom `serialize()` and `deserialize()` in `options` to override the default data transforms used with the browser storage. Alternatively, use custom `{ read(), write()? }` as `options` to set up custom interaction with an external storage.
+
+Instances of `PersistentState` automatically sync their values with the browser storage when created and updated. At other times, call `.emit("sync")` on a `PersistentState` instance to sync its value from the browser storage when needed.
+
+## `Route`
+
+Stores the URL, exposes a native-like API for SPA navigation and an API for URL matching.
+
+```js
+import { Route } from "stateshape";
+
+const route = new Route();
+```
+
+Navigate to other URLs in a SPA fashion similarly to the native APIs:
+
+```js
+route.href = "/intro";
+route.assign("/intro");
+route.replace("/intro");
+```
+
+Or in a more fine-grained manner:
+
+```js
+route.navigate({ href: "/intro", history: "replace", scroll: "off" });
+```
+
+Check the current URL value like a regular `string` with `route.href`:
+
+```js
+route.href === "/intro";
+route.href.startsWith("/sections/");
+/^\/sections\/\d+\/?/.test(route.href);
+```
+
+Or, alternatively, with `route.at(url, x, y)` which is similar to the ternary conditional operator `atURL ? x : y`:
+
+```js
+document.querySelector("header").className = route.at("/", "full", "compact");
+```
+
+Use `route.at(url, x, y)` with dynamic values that require values from the URL pattern's capturing groups:
+
+```js
+document.querySelector("h1").textContent = route.at(
+  /^\/sections\/(?<id>\d+)\/?/,
+  ({ params }) => `Section ${params.id}`,
+);
+```
+
+Enable SPA navigation with HTML links inside the specified container (or the entire `document`) without any changes to the HTML:
+
+```js
+route.observe(document);
+```
+
+Tweak the links' navigation behavior by adding a relevant combination of the optional `data-` attributes (corresponding to the `route.navigate()` options):
+
+```html
+<a href="/intro">Intro</a>
+<a href="/intro" data-history="replace">Intro</a>
+<a href="/intro" data-scroll="off">Intro</a>
+<a href="/intro" data-spa="off">Intro</a>
+```
+
+Define what should be done when the URL changes:
+
+```js
+route.on("navigationcomplete", ({ href }) => {
+  renderContent();
+});
+```
+
+Define what should be done before the URL changes (in a way effectively similar to routing middleware):
+
+```js
+route.on("navigationstart", ({ href }) => {
+  if (hasUnsavedInput)
+    return false; // Quit the navigation, prevent the current URL change
+
+  if (href === "/") {
+    route.href = "/intro"; // SPA redirection
+    return false;
+  }
+});
+```
+
+## Annotated examples
+
+- [Shared state](https://codesandbox.io/p/sandbox/lqt3z2?file=%252Fsrc%252Findex.ts), counter app, State
+- [Shared form input state](https://codesandbox.io/p/sandbox/4q7f99?file=%252Fsrc%252Findex.ts), simple form, State
+- [Persistent shared state](https://codesandbox.io/p/sandbox/c9gt3r?file=%252Fsrc%252Findex.ts), counter app, PersistentState
+- [URL-based rendering](https://codesandbox.io/p/sandbox/kt6m5l?file=%252Fsrc%252Findex.ts), Route
+- [Type-safe URL-based rendering](https://codesandbox.io/p/sandbox/qg7qg3?file=%2Fsrc%2Findex.ts), Route, url-shape, zod
+- [SPA redirection](https://codesandbox.io/p/sandbox/rpl3gh?file=%252Fsrc%252Findex.ts), Route
+
+Find also the code of these examples in the repo's [`tests`](https://github.com/axtk/stateshape/tree/main/tests) directory.
+
+## Integrations
+
+[`react-stateshape`](https://www.npmjs.com/package/react-stateshape)

package/dist/index.cjs

@@ -0,0 +1,517 @@
+let quasiurl = require("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 isImmediatelyInvokedEvent(event) {
+  return event === "navigationstart" || event === "navigationcomplete";
+}
+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.on("stop", () => {
+      window.removeEventListener("popstate", handleURLChange);
+    });
+  }
+  on(event, callback, invokeImmediately) {
+    if (isImmediatelyInvokedEvent(event) && invokeImmediately !== false) this._call(() => {
+      callback({ href: this.getValue() });
+    });
+    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);
+    }
+  }
+  _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.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.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.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.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.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);
+}
+
+let isElementCollection = (x) => Array.isArray(x) || x instanceof NodeList || x instanceof HTMLCollection;
+let isLinkElement = (x) => x instanceof HTMLAnchorElement || x instanceof HTMLAreaElement;
+var Route = class extends URLState {
+  _clicks = /* @__PURE__ */ new Set();
+  constructor(href = null, options) {
+    super(String(href ?? ""), options);
+  }
+  _init() {
+    super._init();
+    if (typeof window === "undefined") return;
+    let handleClick = (event) => {
+      for (let callback of this._clicks) callback(event);
+    };
+    this.on("start", () => {
+      document.addEventListener("click", handleClick);
+    });
+    this.on("stop", () => {
+      document.removeEventListener("click", handleClick);
+    });
+  }
+  observe(container, elements = "a, area") {
+    let handleClick = (event) => {
+      if (!this._active || event.defaultPrevented || !isRouteEvent(event)) return;
+      let resolvedContainer = typeof container === "function" ? container() : container;
+      if (!resolvedContainer) return;
+      let element = null;
+      let targetElements = isElementCollection(elements) ? Array.from(elements) : [elements];
+      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));
+      }
+    };
+    this._clicks.add(handleClick);
+    return () => {
+      this._clicks.delete(handleClick);
+    };
+  }
+  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.QuasiURL(this.href).pathname;
+  }
+  set pathname(value) {
+    let url = new quasiurl.QuasiURL(this.href);
+    url.pathname = String(value);
+    this.assign(url.href);
+  }
+  get search() {
+    return new quasiurl.QuasiURL(this.href).search;
+  }
+  set search(value) {
+    let url = new quasiurl.QuasiURL(this.href);
+    url.search = value;
+    this.assign(url.href);
+  }
+  get hash() {
+    return new quasiurl.QuasiURL(this.href).hash;
+  }
+  set hash(value) {
+    let url = new quasiurl.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, matchOutput, mismatchOutput) {
+    let result = this.match(urlPattern);
+    if (!result.ok) return typeof mismatchOutput === "function" ? mismatchOutput(result) : mismatchOutput;
+    return typeof matchOutput === "function" ? matchOutput(result) : matchOutput;
+  }
+};
+
+exports.EventEmitter = EventEmitter;
+exports.PersistentState = PersistentState;
+exports.Route = Route;
+exports.State = State;
+exports.URLState = URLState;
+exports.compileURL = compileURL;
+exports.getNavigationOptions = getNavigationOptions;
+exports.getStorageEntry = getStorageEntry;
+exports.isLocationObject = isLocationObject;
+exports.isRouteEvent = isRouteEvent;
+exports.isState = isState;
+exports.matchURL = matchURL;