@quazardous/qdadm 2.18.0 → 2.20.0

package/src/routeState/WebStoragePersister.ts

@@ -0,0 +1,149 @@
+/**
+ * Route state in `localStorage` or `sessionStorage` (#2146).
+ *
+ * The medium you pick when the state is worth keeping but not worth putting
+ * in a link: a back-office list somebody returns to twenty times a day, whose
+ * URL nobody ever sends anyone.
+ *
+ * ONE ENTRY PER KEY, namespaced — `qdadm:offers:page`. Not one JSON blob per
+ * scope, because web storage is shared with everything else the app keeps
+ * there, and per-key namespacing is what lets this persister pick out its own
+ * entries without owning the medium. It also means devtools shows you
+ * readable state instead of a blob to decode by hand.
+ *
+ * VALUES ARE JSON, so they come back exactly as they went in. That differs
+ * from `UrlPersister`, which coerces (`'42'` reads back as the number 42)
+ * because a query string is meant to be read by people. A list moved from one
+ * to the other can therefore see a filter value change TYPE — worth knowing
+ * before you switch a screen that compares with `===`.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { namespacedKeyLocator, type RouteStateKeyLocator } from './keyLocator'
+
+/** The bit of the Storage API this needs, so a test needs no browser. */
+export interface RouteStateStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+  readonly length: number
+  key(index: number): string | null
+}
+
+export interface WebStoragePersisterOptions {
+  /** `window.localStorage` or `window.sessionStorage`, or a stand-in. */
+  storage: RouteStateStorage
+  /** For diagnostics — which medium answered. */
+  name?: string
+  /** How a (scope, key) pair becomes a storage key. Defaults to `qdadm:scope:key`. */
+  keyLocator?: RouteStateKeyLocator
+}
+
+export class WebStoragePersister implements RouteStatePersister {
+  readonly name: string
+
+  private readonly _storage: RouteStateStorage
+  private readonly _keys: RouteStateKeyLocator
+  private _warned = false
+
+  constructor(options: WebStoragePersisterOptions) {
+    this._storage = options.storage
+    this._keys = options.keyLocator ?? namespacedKeyLocator
+    this.name = options.name ?? 'web-storage'
+  }
+
+  /**
+   * Web storage throws rather than returning null in more situations than
+   * people expect: Safari's private mode, a browser set to block site data,
+   * a quota that filled up.
+   *
+   * We warn ONCE and carry on with the screen working. That is not the silent
+   * no-op [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) forbids — the
+   * failure is announced, and it is the environment's, not a mistake in the
+   * app's configuration. Taking the list down because a page number could not
+   * be remembered would be the worse trade.
+   */
+  private _guard<T>(operation: () => T, fallback: T): T {
+    try {
+      return operation()
+    } catch (error) {
+      if (!this._warned) {
+        this._warned = true
+        console.warn(
+          `[qdadm] Route-state persister "${this.name}" cannot reach its storage; ` +
+            `this screen will not remember its state. ` +
+            `Usually private browsing, blocked site data, or a full quota.`,
+          error
+        )
+      }
+      return fallback
+    }
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    return this._guard(() => {
+      const state: Record<string, unknown> = {}
+      let found = false
+
+      for (const storedKey of this._ownKeys(scope)) {
+        const key = this._keys.decode(scope, storedKey)
+        if (key === null) continue
+        const raw = this._storage.getItem(storedKey)
+        if (raw === null) continue
+        found = true
+        state[key] = decode(raw)
+      }
+
+      return found ? state : null
+    }, null)
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    this._guard(() => {
+      for (const [key, value] of Object.entries(state)) {
+        const storedKey = this._keys.encode(scope, key)
+        // Absent, not stored empty — the same rule every persister follows,
+        // so a pristine screen leaves no trace whichever medium it uses.
+        if (value === null || value === undefined || value === '') {
+          this._storage.removeItem(storedKey)
+        } else {
+          this._storage.setItem(storedKey, JSON.stringify(value))
+        }
+      }
+    }, undefined)
+  }
+
+  clear(scope: string): void {
+    this._guard(() => {
+      for (const storedKey of this._ownKeys(scope)) {
+        if (this._keys.decode(scope, storedKey) !== null) this._storage.removeItem(storedKey)
+      }
+    }, undefined)
+  }
+
+  /**
+   * Snapshot the key names before touching anything.
+   *
+   * `Storage.key(i)` walks a live collection: removing as you iterate
+   * renumbers what is left and skips entries. Reading the names first is the
+   * difference between clearing a scope and clearing every other one of it.
+   */
+  private _ownKeys(scope: string): string[] {
+    const keys: string[] = []
+    for (let i = 0; i < this._storage.length; i++) {
+      const key = this._storage.key(i)
+      if (key !== null && this._keys.decode(scope, key) !== null) keys.push(key)
+    }
+    return keys
+  }
+}
+
+function decode(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    // Written by something other than us, or truncated. Hand back the string
+    // rather than dropping the key: a readable wrong value beats a silent
+    // absent one.
+    return raw
+  }
+}

package/src/routeState/defaultPersister.ts

@@ -0,0 +1,66 @@
+/**
+ * What a list uses when nobody chose (#2146).
+ *
+ * Not simply `UrlPersister`, because not all list state wants the same
+ * medium. Filters, search and the page belong in a link — that is the whole
+ * argument for the URL being the default. Rows-per-page does not: it is a
+ * comfort setting somebody picked once, and a link carrying it would impose
+ * the sender's row count on the reader.
+ *
+ * So the default is a composition, and it says out loud what qdadm was
+ * already doing by accident:
+ *
+ * | State | Medium | Scope |
+ * |---|---|---|
+ * | filters, search, page | query string | the list |
+ * | `pageSize` | cookie, a year | the app |
+ * | `sort` | `sessionStorage` | the list |
+ *
+ * **Sort stays in the session** — decided on #2146 rather than moved to the
+ * URL. Moving it would make a list link carry its ordering, which is a real
+ * gain; it would also mean the sort no longer survives opening a clean
+ * `/offers`, which it has always done. Between a gain nobody asked for and a
+ * loss every existing user would feel, the seam is worth having without the
+ * behaviour change: this expresses today's arrangement rather than replacing
+ * it.
+ */
+import { CompositePersister } from './CompositePersister'
+import { CookiePersister, type CookieJar } from './CookiePersister'
+import { WebStoragePersister, type RouteStateStorage } from './WebStoragePersister'
+import { UrlPersister, type UrlPersisterRoute, type UrlPersisterRouter } from './UrlPersister'
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export interface DefaultRouteStateOptions {
+  router: UrlPersisterRouter
+  route: UrlPersisterRoute
+  /** Stand-in for `document`, for a test or an environment without one. */
+  cookieJar?: CookieJar
+  /** Stand-in for `sessionStorage`, same reason. */
+  sessionStorage?: RouteStateStorage
+}
+
+/** The scope `pageSize` is remembered under: one setting for the whole app. */
+export const APP_ROUTE_STATE_SCOPE = 'app'
+
+export function createDefaultRouteStatePersister(
+  options: DefaultRouteStateOptions
+): RouteStatePersister {
+  const session = new WebStoragePersister({
+    storage: options.sessionStorage ?? globalThis.sessionStorage,
+    name: 'session_storage',
+  })
+
+  return new CompositePersister({
+    fallback: new UrlPersister(options),
+    keys: {
+      pageSize: {
+        persister: new CookiePersister(options.cookieJar ? { jar: options.cookieJar } : {}),
+        scope: APP_ROUTE_STATE_SCOPE,
+      },
+      // Per-list, unlike pageSize: an ordering belongs to the screen you were
+      // looking at, not to the whole app.
+      sort: { persister: session },
+      sortOrder: { persister: session },
+    },
+  })
+}

package/src/routeState/factory.ts

@@ -0,0 +1,86 @@
+/**
+ * Slugs to persisters (#2146).
+ *
+ * Mirrors what `entity/storage/factory.ts` does for storages — an instance, or
+ * a name the framework knows — so a consumer meets one convention rather than
+ * two.
+ *
+ * | Slug | Medium | Reach for it when |
+ * |---|---|---|
+ * | `default` | query string + cookie | what a list uses when nobody chose |
+ * | `url` | query string | EVERYTHING in the link, row count included |
+ * | `local_storage` | `localStorage` | worth keeping, not worth linking |
+ * | `session_storage` | `sessionStorage` | worth keeping until the tab closes |
+ * | `cookie` | one cookie per scope | the SERVER needs to read it |
+ * | `memory` | a shared Map | survives navigation, not a reload |
+ * | `none` | nowhere | this screen forgets, and says so |
+ */
+import type { RouteStatePersister, RouteStatePersisterFactory } from './RouteStatePersister'
+import { UrlPersister, type UrlPersisterRoute, type UrlPersisterRouter } from './UrlPersister'
+import { WebStoragePersister, type RouteStateStorage } from './WebStoragePersister'
+import { CookiePersister, type CookieJar } from './CookiePersister'
+import { MemoryPersister } from './MemoryPersister'
+import { NullPersister } from './NullPersister'
+import { createDefaultRouteStatePersister } from './defaultPersister'
+
+export interface RouteStateFactoryContext {
+  router: UrlPersisterRouter
+  route: UrlPersisterRoute
+  /**
+   * Overrides for the browser globals the storage-backed slugs reach for.
+   *
+   * Only needed off a browser — SSR, or a test that would rather not share
+   * one `localStorage` between cases. Left alone, each slug uses the real
+   * thing, resolved AT BUILD TIME rather than captured here, so a factory
+   * created before the app mounts still works.
+   */
+  localStorage?: RouteStateStorage
+  sessionStorage?: RouteStateStorage
+  cookieJar?: CookieJar
+}
+
+/**
+ * The built-in factory.
+ *
+ * Returns null for a slug it does not know — the CALLER throws, with the name
+ * in the message. Returning a default here would make an unknown slug behave
+ * like `url` and say nothing, which is the failure ADR 0011 forbids and the
+ * one this seam is cleaning up after.
+ */
+export function createRouteStatePersisterFactory(
+  context: RouteStateFactoryContext
+): RouteStatePersisterFactory {
+  return (slug: string): RouteStatePersister | null => {
+    switch (slug) {
+      // Nameable, so "the default, stated out loud" has a way to be said.
+      // It is NOT `url`: the default routes `pageSize` to a cookie, because a
+      // link should not impose the sender's row count on its reader.
+      case 'default':
+        return createDefaultRouteStatePersister({
+          router: context.router,
+          route: context.route,
+          cookieJar: context.cookieJar,
+        })
+      case 'url':
+        return new UrlPersister(context)
+      case 'local_storage':
+        return new WebStoragePersister({
+          storage: context.localStorage ?? globalThis.localStorage,
+          name: 'local_storage',
+        })
+      case 'session_storage':
+        return new WebStoragePersister({
+          storage: context.sessionStorage ?? globalThis.sessionStorage,
+          name: 'session_storage',
+        })
+      case 'cookie':
+        return new CookiePersister(context.cookieJar ? { jar: context.cookieJar } : {})
+      case 'memory':
+        return new MemoryPersister()
+      case 'none':
+        return new NullPersister()
+      default:
+        return null
+    }
+  }
+}

package/src/routeState/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Route-state persistence (#2146).
+ *
+ * The seam that decides WHERE a route remembers what it is showing. The list
+ * is one consumer; a detail page's active tab and a dashboard's date range
+ * are the same problem.
+ */
+export type {
+  RouteStatePersister,
+  RouteStateScope,
+  RouteStatePersisterSpec,
+  RouteStatePersisterFactory,
+} from './RouteStatePersister'
+export { isRouteStatePersister, resolveRouteStatePersister } from './RouteStatePersister'
+export { UrlPersister } from './UrlPersister'
+export type { UrlPersisterOptions, UrlPersisterRouter, UrlPersisterRoute } from './UrlPersister'
+export { createRouteStatePersisterFactory } from './factory'
+export { dottedKeyLocator, namespacedKeyLocator } from './keyLocator'
+export type { RouteStateKeyLocator } from './keyLocator'
+export { WebStoragePersister } from './WebStoragePersister'
+export type { WebStoragePersisterOptions, RouteStateStorage } from './WebStoragePersister'
+export { CookiePersister } from './CookiePersister'
+export type { CookiePersisterOptions, CookieJar } from './CookiePersister'
+export { MemoryPersister, clearRouteStateMemory } from './MemoryPersister'
+export type { MemoryPersisterOptions, RouteStateMemoryStore } from './MemoryPersister'
+export { NullPersister } from './NullPersister'
+export { underscoreScopeLocator } from './keyLocator'
+export type { RouteStateScopeLocator } from './keyLocator'
+export type { RouteStateFactoryContext } from './factory'
+export { CompositePersister } from './CompositePersister'
+export type { CompositePersisterOptions, RoutedKey } from './CompositePersister'
+export { createDefaultRouteStatePersister } from './defaultPersister'

package/src/routeState/keyLocator.ts

@@ -0,0 +1,84 @@
+/**
+ * How a (scope, key) pair becomes a stored key — and back (#2146).
+ *
+ * Hard-coding `offers.page` inside the URL persister would make the naming
+ * scheme a property of qdadm rather than of the app. An app that wants
+ * `o_page`, or a single packed parameter, or a `[]`-suffixed convention its
+ * backend already understands, must be able to say so — the same way it can
+ * already override how a storage is resolved.
+ *
+ * ONE PER PERSISTER TYPE, because the right scheme differs by medium: dots
+ * read well in a query string, colons are the convention in `localStorage`,
+ * and a cookie has its own constraints entirely.
+ *
+ * `decode` returns null for a key that is not ours. That is what lets a
+ * persister pick its own entries out of a medium it shares with everything
+ * else — the whole reason the scope exists.
+ */
+export interface RouteStateKeyLocator {
+  encode(scope: string, key: string): string
+  /** The bare key, or null when this stored key belongs to someone else. */
+  decode(scope: string, storedKey: string): string | null
+  /**
+   * Whether this key carries a scope at all — ANY scope, not just one.
+   *
+   * A legacy-compatibility reader needs this: `offers.page` and `jobs.page`
+   * both belong to somebody, and treating them as unscoped leftovers would
+   * hand one list the other's state. Only a key that is scoped by nobody can
+   * be read as pre-scope state.
+   */
+  looksScoped(storedKey: string): boolean
+  readonly name: string
+}
+
+/** `offers` + `page` → `offers.page`. The default in a query string. */
+export const dottedKeyLocator: RouteStateKeyLocator = {
+  name: 'dotted',
+  encode: (scope, key) => (scope ? `${scope}.${key}` : key),
+  decode: (scope, storedKey) => {
+    if (!scope) return storedKey
+    const prefix = `${scope}.`
+    return storedKey.startsWith(prefix) ? storedKey.slice(prefix.length) : null
+  },
+  looksScoped: (storedKey) => storedKey.includes('.'),
+}
+
+/** `offers` + `page` → `qdadm:offers:page`. The default in web storage. */
+export const namespacedKeyLocator: RouteStateKeyLocator = {
+  name: 'namespaced',
+  encode: (scope, key) => `qdadm:${scope}:${key}`,
+  decode: (scope, storedKey) => {
+    const prefix = `qdadm:${scope}:`
+    return storedKey.startsWith(prefix) ? storedKey.slice(prefix.length) : null
+  },
+  looksScoped: (storedKey) => storedKey.startsWith('qdadm:'),
+}
+
+/**
+ * How a SCOPE becomes a stored name, for media that keep one entry per scope.
+ *
+ * The cookie jar is the case: a cookie rides on every request, so a scope
+ * gets one cookie holding a blob rather than one per key. There is no key
+ * half to encode, which is why this is its own small interface rather than
+ * `RouteStateKeyLocator` called with a key nobody uses.
+ */
+export interface RouteStateScopeLocator {
+  encode(scope: string): string
+  /** The bare scope, or null when this stored name belongs to someone else. */
+  decode(storedName: string): string | null
+  readonly name: string
+}
+
+/**
+ * `offers` → `qdadm_offers`. The default in a cookie jar.
+ *
+ * Underscores rather than the colons web storage uses: a cookie NAME is an
+ * RFC 6265 token, and `:` is a separator there. `qdadm:offers` is not a
+ * cookie name a server is obliged to accept.
+ */
+export const underscoreScopeLocator: RouteStateScopeLocator = {
+  name: 'underscore',
+  encode: (scope) => `qdadm_${scope}`,
+  decode: (storedName) =>
+    storedName.startsWith('qdadm_') ? storedName.slice('qdadm_'.length) : null,
+}