@quazardous/qdadm 2.19.0 → 2.20.0

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,
+}