@svadmin/core 0.49.1 → 0.52.0

package/src/router-provider.ts

@@ -1,15 +1,16 @@
 // Router Provider — abstracts routing strategy (hash, history, SvelteKit, etc.)
+import { definedOptions } from './defined-options';
 
-export type RouterNavigationResult = false | ReturnType<() => void>;
+export type RouterNavigationResult=false|ReturnType<() => void>;
 
 export interface RouterProvider {
   /** Navigate to a path */
   go: (options: {
     to: string;
-    query?: Record<string, string>;
+    query?: Record<string,string>;
     hash?: string;
-    type?: 'push' | 'replace';
-  }) => RouterNavigationResult | Promise<RouterNavigationResult>;
+    type?: 'push'|'replace';
+  }) => RouterNavigationResult|Promise<RouterNavigationResult>;
   /** Navigate back */
   back: () => void;
   /** Parse current URL into structured route info */
@@ -17,7 +18,7 @@ export interface RouterProvider {
     resource?: string;
     action?: string;
     id?: string;
-    params: Record<string, string>;
+    params: Record<string,string>;
     pathname: string;
   };
   /** Formats an internal path into an href string for <a> tags */
@@ -28,102 +29,106 @@ export interface RouterProvider {
 
 export function createHashRouterProvider(): RouterProvider {
   return {
-    go({ to, query, hash, type = 'push' }) {
-      if (typeof window === 'undefined') return;
-      let url = to;
-      if (query) {
-        const params = new URLSearchParams(query).toString();
-        if (params) url += url.includes('?') ? `&${params}` : `?${params}`;
+    go({ to,query,hash,type='push' }) {
+      if(typeof window==='undefined') return;
+      let url=to;
+      if(query) {
+        const params=new URLSearchParams(query).toString();
+        if(params) url+=url.includes('?')? `&${params}`:`?${params}`;
       }
-      if (hash) url += `#${hash}`;
-      if (type === 'replace') {
-        const urlObj = new URL(window.location.href);
-        urlObj.hash = url;
-        window.history.replaceState(null, '', urlObj.href);
+      if(hash) url+=`#${hash}`;
+      if(type==='replace') {
+        const urlObj=new URL(window.location.href);
+        urlObj.hash=url;
+        window.history.replaceState(null,'',urlObj.href);
         window.dispatchEvent(new HashChangeEvent('hashchange'));
       } else {
-        window.location.hash = url;
+        window.location.hash=url;
       }
     },
     back() {
-      if (typeof window === 'undefined') return;
+      if(typeof window==='undefined') return;
       history.back();
     },
     parse() {
-      if (typeof window === 'undefined') {
-        return { resource: undefined, action: undefined, id: undefined, params: {}, pathname: '/' };
+      if(typeof window==='undefined') {
+        return { params: {},pathname: '/' };
       }
-      const hash = window.location.hash.slice(1) || '/';
-      const [pathname, queryString] = hash.split('?');
-      const params: Record<string, string> = {};
-      if (queryString) {
-        for (const [k, v] of new URLSearchParams(queryString).entries()) {
-          params[k] = v;
+      const hash=window.location.hash.slice(1)||'/';
+      const [pathname='/',queryString]=hash.split('?');
+      const params: Record<string,string>={};
+      if(queryString) {
+        for(const [k,v] of new URLSearchParams(queryString).entries()) {
+          params[k]=v;
         }
       }
-      const segments = pathname.split('/').filter(Boolean);
+      const segments=pathname.split('/').filter(Boolean);
       return {
-        resource: segments[0],
-        action: segments[1],
-        id: segments[2],
+        ...definedOptions({
+          resource: segments[0],
+          action: segments[1],
+          id: segments[2],
+        }),
         params,
         pathname,
       };
     },
     formatLink(path) {
-      return '#' + path.replace(/^#/, '');
+      return '#'+path.replace(/^#/,'');
     },
   };
 }
 
 // ─── History Router (HTML5 pushState) ───────────────────────
 
-export function createHistoryRouterProvider(basePath = ''): RouterProvider {
-  const normalizedBase = basePath.endsWith('/') && basePath.length > 1 ? basePath.slice(0, -1) : basePath;
+export function createHistoryRouterProvider(basePath=''): RouterProvider {
+  const normalizedBase=basePath.endsWith('/')&&basePath.length>1? basePath.slice(0,-1):basePath;
   return {
-    go({ to, query, hash, type = 'push' }) {
-      if (typeof window === 'undefined') return;
-      let url = `${normalizedBase}${to}`;
-      if (query) {
-        const params = new URLSearchParams(query).toString();
-        if (params) url += url.includes('?') ? `&${params}` : `?${params}`;
+    go({ to,query,hash,type='push' }) {
+      if(typeof window==='undefined') return;
+      let url=`${normalizedBase}${to}`;
+      if(query) {
+        const params=new URLSearchParams(query).toString();
+        if(params) url+=url.includes('?')? `&${params}`:`?${params}`;
       }
-      if (hash) url += `#${hash}`;
-      if (type === 'replace') {
-        history.replaceState(null, '', url);
+      if(hash) url+=`#${hash}`;
+      if(type==='replace') {
+        history.replaceState(null,'',url);
       } else {
-        history.pushState(null, '', url);
+        history.pushState(null,'',url);
       }
       window.dispatchEvent(new PopStateEvent('popstate'));
     },
     back() {
-      if (typeof window === 'undefined') return;
+      if(typeof window==='undefined') return;
       history.back();
     },
     parse() {
-      if (typeof window === 'undefined') {
-        return { resource: undefined, action: undefined, id: undefined, params: {}, pathname: '/' };
+      if(typeof window==='undefined') {
+        return { params: {},pathname: '/' };
       }
-      const fullPath = window.location.pathname;
-      const pathname = (normalizedBase && fullPath.startsWith(normalizedBase)
-        && (fullPath.length === normalizedBase.length || fullPath[normalizedBase.length] === '/')
-        ? fullPath.slice(normalizedBase.length) || '/'
-        : window.location.pathname);
-      const params: Record<string, string> = {};
-      for (const [k, v] of new URLSearchParams(window.location.search).entries()) {
-        params[k] = v;
+      const fullPath=window.location.pathname;
+      const pathname=(normalizedBase&&fullPath.startsWith(normalizedBase)
+        &&(fullPath.length===normalizedBase.length||fullPath[normalizedBase.length]==='/')
+        ? fullPath.slice(normalizedBase.length)||'/'
+        :window.location.pathname);
+      const params: Record<string,string>={};
+      for(const [k,v] of new URLSearchParams(window.location.search).entries()) {
+        params[k]=v;
       }
-      const segments = pathname.split('/').filter(Boolean);
+      const segments=pathname.split('/').filter(Boolean);
       return {
-        resource: segments[0],
-        action: segments[1],
-        id: segments[2],
+        ...definedOptions({
+          resource: segments[0],
+          action: segments[1],
+          id: segments[2],
+        }),
         params,
         pathname,
       };
     },
     formatLink(path) {
-      return normalizedBase + path;
+      return normalizedBase+path;
     },
   };
 }

package/src/router.ts

@@ -59,7 +59,8 @@ export function matchRoute(
     if (match) {
       const params: Record<string, string> = {};
       keys.forEach((key, i) => {
-        params[key] = match[i + 1];
+        const value = match[i + 1];
+        if (value !== undefined) params[key] = value;
       });
       return { route: pattern, params };
     }
@@ -75,20 +76,24 @@ export async function navigateWithProvider(
   provider: RouterProvider | undefined,
   path: string,
   options?: { replaceState?: boolean },
+  isActive: () => boolean = () => true,
 ): Promise<void> {
+  if (!isActive()) return;
   const from = currentPathWithProvider(provider);
   for (const guard of _beforeGuards) {
     const allowed = await guard(path, from);
-    if (!allowed) return;
+    if (!allowed || !isActive()) return;
   }
+  if (!isActive()) return;
   if (provider) {
     const navigated = await provider.go({ to: path, type: options?.replaceState ? 'replace' : 'push' });
-    if (navigated === false) return;
+    if (navigated === false || !isActive()) return;
   } else if (typeof window !== 'undefined') {
     window.location.hash = '#' + path.replace(/^#/, '');
   }
   _syncGlobalPath();
   for (const guard of _afterGuards) {
+    if (!isActive()) return;
     guard(path, from);
   }
 }

package/src/routing-hooks.svelte.ts

@@ -1,3 +1,4 @@
+import { definedOptions } from './defined-options';
 import { captureAdminContext } from './context.svelte';
 import { useParsed } from './useParsed.svelte';
 import { sanitizeListQueryParams } from './url-sync';
@@ -5,32 +6,32 @@ import { sanitizeListQueryParams } from './url-sync';
 // ─── routing-hooks.svelte.ts ───────────────────────────────────
 
 export function useGetToPath() {
-  const adminContext = captureAdminContext();
-  const parsed = useParsed();
+  const adminContext=captureAdminContext();
+  const parsed=useParsed();
 
-  return (options: { resource?: string; action?: 'list' | 'create' | 'edit' | 'show' | 'clone'; id?: string | number; meta?: Record<string, unknown> }) => {
-    const { resource, action, id, meta } = options;
-    if (!resource) return '/';
+  return (options: { resource?: string; action?: 'list'|'create'|'edit'|'show'|'clone'; id?: string|number; meta?: Record<string,unknown> }) => {
+    const { resource,action,id,meta }=options;
+    if(!resource) return '/';
 
     // Support nested resources: use meta.parentPath or auto-detect from current URL
     let basePath: string;
-    if (meta?.parentPath) {
-      basePath = `${meta.parentPath}/${resource}`;
-    } else if (parsed.resourcePath && parsed.resource === resource) {
+    if(meta?.['parentPath']) {
+      basePath=`${meta['parentPath']}/${resource}`;
+    } else if(parsed.resourcePath&&parsed.resource===resource) {
       // Re-use the current nested path context (e.g., /teams/123/users)
-      basePath = `/${parsed.resourcePath}`;
+      basePath=`/${parsed.resourcePath}`;
     } else {
-      basePath = `/${resource}`;
+      basePath=`/${resource}`;
     }
 
-    let path = basePath;
-    if (action === 'create') path += '/create';
-    else if (action === 'edit' && id) path += `/edit/${id}`;
-    else if (action === 'show' && id) path += `/show/${id}`;
-    else if (action === 'clone' && id) path += `/clone/${id}`;
+    let path=basePath;
+    if(action==='create') path+='/create';
+    else if(action==='edit'&&id) path+=`/edit/${id}`;
+    else if(action==='show'&&id) path+=`/show/${id}`;
+    else if(action==='clone'&&id) path+=`/clone/${id}`;
 
     // Apply router mapping if the router provider defines custom path transformers
-    if (adminContext.routerProvider?.go) {
+    if(adminContext.routerProvider?.go) {
       // SvelteKit path generation can be injected here.
     }
     return path;
@@ -38,29 +39,34 @@ export function useGetToPath() {
 }
 
 export function useGo() {
-  const adminContext = captureAdminContext();
-  const getToPath = useGetToPath();
-
-  return (options: { to?: string; query?: Record<string, unknown>; type?: 'push' | 'replace'; resource?: string; action?: 'list' | 'create' | 'edit' | 'show' | 'clone'; id?: string | number }) => {
-    let targetUrl = options.to;
-    if (!targetUrl && options.resource) {
-      targetUrl = getToPath({ resource: options.resource, action: options.action, id: options.id });
+  const adminContext=captureAdminContext();
+  const getToPath=useGetToPath();
+
+  return (options: { to?: string; query?: Record<string,unknown>; type?: 'push'|'replace'; resource?: string; action?: 'list'|'create'|'edit'|'show'|'clone'; id?: string|number }) => {
+    let targetUrl=options.to;
+    if(!targetUrl&&options.resource) {
+      targetUrl=getToPath({
+        resource: options.resource,...definedOptions({
+          action: options.action,
+          id: options.id,
+        }),
+      });
     }
-    if (!targetUrl) targetUrl = '/';
+    if(!targetUrl) targetUrl='/';
 
-    if (options.query && Object.keys(options.query).length > 0) {
-      const qs = new URLSearchParams(Object.entries(options.query).map(([k, v]) => [k, String(v)])).toString();
-      if (qs) {
-        targetUrl += targetUrl.includes('?') ? `&${qs}` : `?${qs}`;
+    if(options.query&&Object.keys(options.query).length>0) {
+      const qs=new URLSearchParams(Object.entries(options.query).map(([k,v]) => [k,String(v)])).toString();
+      if(qs) {
+        targetUrl+=targetUrl.includes('?')? `&${qs}`:`?${qs}`;
       }
     }
 
-    void adminContext.navigate(targetUrl, options.type === 'replace' ? { replaceState: true } : undefined);
+    void adminContext.navigate(targetUrl,options.type==='replace'? { replaceState: true }:undefined);
   };
 }
 
 export function useBack() {
-  const adminContext = captureAdminContext();
+  const adminContext=captureAdminContext();
   return () => adminContext.back();
 }
 
@@ -69,21 +75,23 @@ export function useBack() {
  * (to avoid full page reloads in SSR apps)
  */
 export function useLink() {
-  const adminContext = captureAdminContext();
+  const adminContext=captureAdminContext();
   return () => {
-    const routerProvider = adminContext.routerProvider as unknown as Record<string, unknown> | undefined;
-    return (routerProvider?.Link as string) ?? 'a';
+    const provider=adminContext.routerProvider;
+    if(!provider||!('Link' in provider)||provider.Link===undefined) return 'a';
+    if(typeof provider.Link!=='string') throw new TypeError('Router Link must be a tag name');
+    return provider.Link;
   };
 }
 
 export function useResource(resourceName?: string) {
-  const adminContext = captureAdminContext();
-  const parsed = useParsed();
+  const adminContext=captureAdminContext();
+  const parsed=useParsed();
 
   // Derived resource — re-evaluates when parsed.resource or resourceName changes
-  const resolvedResource = $derived.by(() => {
-    const target = resourceName ?? parsed.resource;
-    if (!target) return undefined;
+  const resolvedResource=$derived.by(() => {
+    const target=resourceName??parsed.resource;
+    if(!target) return undefined;
     try {
       return adminContext.getResource(target);
     } catch {
@@ -94,46 +102,66 @@ export function useResource(resourceName?: string) {
   return {
     get resource() { return resolvedResource; },
     get resources() { return adminContext.resources; },
-    get identifier() { return resolvedResource?.identifier ?? resolvedResource?.name; },
-    /** 当前 URL 解析出的 parent 资源信息（嵌套资源路由） */
+    get identifier() { return resolvedResource?.identifier??resolvedResource?.name; },
+    /** Parent resource information parsed from the current nested-resource URL. */
     get parent() {
-      const parentParams: Record<string, string> = {};
-      // 只取路径解析出的 parent params，排除 query params 的误判
-      for (const [k, v] of Object.entries(parsed.parentParams)) {
-        if (v) parentParams[k] = v;
+      const parentParams: Record<string,string>={};
+      // Use only parent params parsed from the path and exclude query params.
+      for(const [k,v] of Object.entries(parsed.parentParams)) {
+        if(v) parentParams[k]=v;
       }
-      return Object.keys(parentParams).length > 0 ? parentParams : undefined;
+      return Object.keys(parentParams).length>0? parentParams:undefined;
     },
     /** Resolve a resource by name — useful for dynamic lookups inside callbacks */
     select: (name: string) => {
       try {
-        const res = adminContext.getResource(name);
-        return { resource: res, identifier: res.identifier ?? res.name };
+        const res=adminContext.getResource(name);
+        return { resource: res,identifier: res.identifier??res.name };
       } catch {
-        return { resource: undefined, identifier: undefined };
+        return { resource: undefined,identifier: undefined };
       }
     },
   };
 }
 
 export function useNavigation() {
-  const go = useGo();
-  const parsed = useParsed();
-  const listQuery = (resource?: string) => {
-    const target = resource ?? parsed.resourcePath ?? parsed.resource;
-    const targetResource = target?.split('/').filter(Boolean).at(-1);
-    if (targetResource && parsed.resource && targetResource !== parsed.resource) return {};
-    return sanitizeListQueryParams(parsed.params ?? {});
+  const go=useGo();
+  const parsed=useParsed();
+  const listQuery=(resource?: string) => {
+    const target=resource??parsed.resourcePath??parsed.resource;
+    const targetResource=target?.split('/').filter(Boolean).at(-1);
+    if(targetResource&&parsed.resource&&targetResource!==parsed.resource) return {};
+    return sanitizeListQueryParams(parsed.params??{});
   };
 
   return {
-    create: (resource?: string) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'create', query: listQuery(resource) }),
-    edit: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'edit', id: id ?? parsed.id, query: listQuery(resource) }),
-    clone: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'clone', id: id ?? parsed.id, query: listQuery(resource) }),
-    show: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'show', id: id ?? parsed.id, query: listQuery(resource) }),
-    list: (resource?: string) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'list', query: listQuery(resource) }),
-    push: (url: string) => go({ to: url, type: 'push' }),
-    replace: (url: string) => go({ to: url, type: 'replace' }),
+    create: (resource?: string) => go({
+      type: 'push',...definedOptions({ resource: resource??parsed.resourcePath??parsed.resource }),action: 'create',...definedOptions({
+        query: listQuery(resource)
+      })
+    }),
+    edit: (resource?: string,id?: string|number) => go({
+      type: 'push',...definedOptions({ resource: resource??parsed.resourcePath??parsed.resource }),action: 'edit',...definedOptions({
+        id: id??parsed.id,query: listQuery(resource)
+      })
+    }),
+    clone: (resource?: string,id?: string|number) => go({
+      type: 'push',...definedOptions({ resource: resource??parsed.resourcePath??parsed.resource }),action: 'clone',...definedOptions({
+        id: id??parsed.id,query: listQuery(resource)
+      })
+    }),
+    show: (resource?: string,id?: string|number) => go({
+      type: 'push',...definedOptions({ resource: resource??parsed.resourcePath??parsed.resource }),action: 'show',...definedOptions({
+        id: id??parsed.id,query: listQuery(resource)
+      })
+    }),
+    list: (resource?: string) => go({
+      type: 'push',...definedOptions({ resource: resource??parsed.resourcePath??parsed.resource }),action: 'list',...definedOptions({
+        query: listQuery(resource)
+      })
+    }),
+    push: (url: string) => go({ to: url,type: 'push' }),
+    replace: (url: string) => go({ to: url,type: 'replace' }),
     goBack: useBack(),
   };
 }

package/src/schema-validation.ts

@@ -0,0 +1,92 @@
+import { CloneType, TransformKind, Type, type Static, type TSchema } from '@sinclair/typebox';
+import { TypeGuard } from '@sinclair/typebox/type';
+import { Value } from '@sinclair/typebox/value';
+
+/**
+ * Strengthen optional-property presence with ordinary schemas, without changing
+ * TypeBox's process-wide policy or maintaining a second value validator.
+ */
+function exactSchema(schema: TSchema): TSchema {
+  if (TypeGuard.IsObject(schema)) {
+    schema.properties = Object.fromEntries(
+      Object.entries(schema.properties).map(([key, property]) => [key, exactSchema(property)]),
+    );
+    if (TypeGuard.IsSchema(schema.additionalProperties)) {
+      schema.additionalProperties = exactSchema(schema.additionalProperties);
+    }
+    const optional = Object.entries(schema.properties)
+      .filter(([key]) => !schema.required?.includes(key));
+    if (optional.length === 0) return schema;
+
+    const constraints = optional.map(([key, property]) => Type.Union([
+      Type.Required(Type.Object({ [key]: property })),
+      Type.Not(Type.Object({ [key]: Type.Unknown() })),
+    ]));
+    // The presence constraint owns each optional value's validation. Leaving it
+    // in both places would validate deep optional objects exponentially often.
+    for (const [key] of optional) schema.properties[key] = Type.Unknown();
+    // References must resolve to the strengthened object, not its inner copy.
+    const id = schema.$id;
+    delete schema.$id;
+    const transform = Object.getOwnPropertyDescriptor(schema, TransformKind);
+    Reflect.deleteProperty(schema, TransformKind);
+    const result = Type.Intersect([schema, ...constraints], id === undefined ? {} : { $id: id });
+    if (transform !== undefined) Object.defineProperty(result, TransformKind, transform);
+    return result;
+  }
+  if (TypeGuard.IsArray(schema)) {
+    schema.items = exactSchema(schema.items);
+    if (TypeGuard.IsSchema(schema.contains)) schema.contains = exactSchema(schema.contains);
+  } else if (TypeGuard.IsTuple(schema)) {
+    if (schema.items) schema.items = schema.items.map(exactSchema);
+  } else if (TypeGuard.IsUnion(schema)) {
+    schema.anyOf = schema.anyOf.map(exactSchema);
+  } else if (TypeGuard.IsIntersect(schema)) {
+    schema.allOf = schema.allOf.map(exactSchema);
+    if (TypeGuard.IsSchema(schema.unevaluatedProperties)) {
+      schema.unevaluatedProperties = exactSchema(schema.unevaluatedProperties);
+    }
+  } else if (TypeGuard.IsNot(schema)) {
+    schema.not = exactSchema(schema.not);
+  } else if (TypeGuard.IsRecord(schema)) {
+    schema.patternProperties = Object.fromEntries(
+      Object.entries(schema.patternProperties).map(([key, property]) => [key, exactSchema(property)]),
+    );
+    if (TypeGuard.IsSchema(schema.additionalProperties)) {
+      schema.additionalProperties = exactSchema(schema.additionalProperties);
+    }
+  } else if (TypeGuard.IsImport(schema)) {
+    schema.$defs = Object.fromEntries(
+      Object.entries(schema.$defs).map(([key, definition]) => {
+        if (!TypeGuard.IsSchema(definition)) throw new TypeError('Invalid imported schema definition');
+        return [key, exactSchema(definition)];
+      }),
+    );
+  }
+  return schema;
+}
+
+export function createExactSchemaValidator<S extends TSchema>(schema: S, references: readonly TSchema[] = []) {
+  const checked = exactSchema(CloneType(schema));
+  const checkedReferences = references.map(reference => exactSchema(CloneType(reference)));
+  return {
+    Check(value: unknown): value is Static<S> {
+      return Value.Check(checked, checkedReferences, value);
+    },
+    Errors(value: unknown) {
+      return Value.Errors(checked, checkedReferences, value);
+    },
+  };
+}
+
+const validators = new WeakMap<TSchema, ReturnType<typeof createExactSchemaValidator>>();
+
+/** Schemas are snapshotted on first use; later edits cannot weaken a live boundary. */
+export function checkExact<S extends TSchema>(schema: S, value: unknown): value is Static<S> {
+  let validator = validators.get(schema);
+  if (!validator) {
+    validator = createExactSchemaValidator(schema);
+    validators.set(schema, validator);
+  }
+  return validator.Check(value);
+}

package/src/schema.ts

@@ -0,0 +1,13 @@
+export { createExactSchemaValidator, checkExact } from './schema-validation';
+export { snapshotPlainData } from './plain-data';
+export type { JsonValue } from './plain-data';
+export { decodeAuditEntry, decodeAuditCreate, decodeAuditQuery, decodeAuditEntries } from './audit-contract';
+export { decodeTaskRecord, decodeTaskList, decodeTaskSubmitOptions, TaskError } from './task-contract';
+export { validatedTaskSubscription, taskClientField, requiredTaskClientMethod } from './task-subscription';
+export { closeContractSchema, parseContractRouteId, formatContractRouteId } from './resource-contract';
+export type { SafeSchema, SchemaValue } from './resource-contract';
+export { decodeBaseRecord, decodeOneResult, decodeManyResult, decodeListResult, decodeCustomResult } from './record-decoder';
+export type { RecordDecoder } from './record-decoder';
+export { withValidatedResponses } from './provider-response';
+export { rejectProviderResponse } from './record-decoder';
+export type { DataTransport } from './provider-response';

package/src/select-options.ts

@@ -0,0 +1,95 @@
+import type { BaseRecord } from './types';
+import { HttpError } from './types';
+import type { RecordDecoder } from './record-decoder';
+import { snapshotPlainData, type JsonValue } from './plain-data';
+
+export interface SelectOption {
+  label: string;
+  value: string | number;
+}
+
+export function selectOptionValue(value: unknown): string | number {
+  if (typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value))) return value;
+  throw new HttpError('Invalid select option', 422, undefined, { code: 'INVALID_SELECT_OPTION' });
+}
+
+/** Each user mapper receives an independent record, never a cached query object. */
+export function mapSelectOptions<T extends BaseRecord>(
+  records: T[],
+  label: string | ((item: T) => string),
+  value: string | ((item: T) => string | number),
+  decode: RecordDecoder<T>,
+  isCurrent: () => boolean,
+): SelectOption[] {
+  try {
+    return records.map(record => {
+      if (!isCurrent()) throw new Error('Obsolete select mapping');
+      const labelRecord = decode(snapshotPlainData(record));
+      const mappedLabel = typeof label === 'function' ? label(labelRecord) : labelRecord[label];
+      if (!isCurrent()) throw new Error('Obsolete select mapping');
+      if (typeof label === 'function' && typeof mappedLabel !== 'string') {
+        throw new TypeError('Select label callbacks must return strings');
+      }
+      const valueRecord = decode(snapshotPlainData(record));
+      const mappedValue = typeof value === 'function' ? value(valueRecord) : valueRecord[value];
+      if (!isCurrent()) throw new Error('Obsolete select mapping');
+      return { label: String(selectOptionValue(mappedLabel)), value: selectOptionValue(mappedValue) };
+    });
+  } catch {
+    throw new HttpError('Invalid select option', 422, undefined, { code: 'INVALID_SELECT_OPTION' });
+  }
+}
+
+function sameSnapshot(left: JsonValue | undefined, right: JsonValue | undefined): boolean {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left)) {
+    return Array.isArray(right) && left.length === right.length &&
+      left.every((value, index) => sameSnapshot(value, right[index]));
+  }
+  if (left === null || right === null || typeof left !== 'object' ||
+    typeof right !== 'object' || Array.isArray(right)) return false;
+  const keys = Object.keys(left);
+  const otherKeys = Object.keys(right);
+  return keys.length === otherKeys.length &&
+    keys.every((key, index) => key === otherKeys[index] && sameSnapshot(left[key], right[key]));
+}
+
+/** Memoization includes detached contents because external cache edits may not advance its revision. */
+export function createSelectProjection<T extends BaseRecord, R extends { data: T[] }>(
+  decodeResult: (input: unknown) => R,
+  label: string | ((item: T) => string),
+  value: string | ((item: T) => string | number),
+  decode: RecordDecoder<T>,
+  isCurrent: () => boolean,
+): (input: unknown, version: number) => R & { options: SelectOption[] } {
+  let cached: { input: unknown; version: number; records: JsonValue; options: SelectOption[] | undefined } | undefined;
+  return (input, version) => {
+    const result = decodeResult(input);
+    if (!isCurrent()) throw new HttpError('Obsolete select mapping', 409, undefined, { code: 'QUERY_SESSION_SUPERSEDED' });
+    let records: JsonValue;
+    try { records = snapshotPlainData(result.data); }
+    catch { throw new HttpError('Invalid select option', 422, undefined, { code: 'INVALID_SELECT_OPTION' }); }
+    let entry = cached;
+    if (!entry || entry.input !== input || entry.version !== version || !sameSnapshot(entry.records, records)) {
+      // Publish an incomplete entry first so a same-input recursive mapper cannot recurse indefinitely.
+      entry = { input, version, records, options: undefined };
+      cached = entry;
+      try {
+        entry.options = mapSelectOptions(result.data, label, value, decode, isCurrent);
+      } catch {
+        // Keep this failure memoized until the input, revision or validated contents change.
+      }
+    }
+    if (!entry.options) throw new HttpError('Invalid select option', 422, undefined, { code: 'INVALID_SELECT_OPTION' });
+    return { ...result, options: entry.options.map(option => ({ ...option })) };
+  };
+}
+
+export function mergeSelectOptions(...groups: SelectOption[][]): SelectOption[] {
+  const seen = new Set<string | number>();
+  return groups.flatMap(group => group.filter(option => {
+    if (seen.has(option.value)) return false;
+    seen.add(option.value);
+    return true;
+  }));
+}