@platforma-sdk/model 1.54.10 → 1.55.0

package/src/block_storage_callbacks.ts

@@ -0,0 +1,326 @@
+/**
+ * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3._done().
+ *
+ * Provides pure functions for storage operations (migration, initialization,
+ * args derivation, updates, debug views). Each function takes its dependencies
+ * explicitly as parameters.
+ *
+ * @module block_storage_callbacks
+ * @internal
+ */
+
+import {
+  BLOCK_STORAGE_KEY,
+  BLOCK_STORAGE_SCHEMA_VERSION,
+  type BlockStorage,
+  type MutateStoragePayload,
+  type StorageDebugView,
+  type PluginRegistry,
+  type VersionedData,
+  createBlockStorage,
+  getStorageData,
+  isBlockStorage,
+  migrateBlockStorage,
+  normalizeBlockStorage,
+  updateStorageData,
+} from "./block_storage";
+
+import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
+import type { DataMigrationResult, DataVersioned } from "./block_migrations";
+
+// =============================================================================
+// Hook interfaces for dependency injection
+// =============================================================================
+
+/** Dependencies for storage migration */
+export interface MigrationHooks {
+  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
+  getPluginRegistry: () => PluginRegistry;
+  migratePluginData: (
+    pluginId: string,
+    versioned: DataVersioned<unknown>,
+  ) => DataMigrationResult<unknown> | undefined;
+  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+}
+
+/** Dependencies for initial storage creation */
+export interface InitialStorageHooks {
+  getDefaultBlockData: () => DataVersioned<unknown>;
+  getPluginRegistry: () => PluginRegistry;
+  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+}
+
+/**
+ * Result of storage normalization
+ */
+export interface NormalizeStorageResult {
+  /** The normalized BlockStorage object */
+  storage: BlockStorage;
+  /** The extracted data (what developers see) */
+  data: unknown;
+}
+
+/**
+ * Normalizes raw storage data and extracts state.
+ * Handles all formats:
+ * - New BlockStorage format (has discriminator)
+ * - Legacy V1/V2 format ({ args, uiState })
+ * - Raw V3 state (any other format)
+ *
+ * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+ * @returns Object with normalized storage and extracted state
+ */
+function normalizeStorage(rawStorage: unknown): NormalizeStorageResult {
+  // Handle undefined/null
+  if (rawStorage === undefined || rawStorage === null) {
+    const storage = createBlockStorage({});
+    return { storage, data: {} };
+  }
+
+  // Parse JSON string if needed
+  let parsed = rawStorage;
+  if (typeof rawStorage === "string") {
+    try {
+      parsed = JSON.parse(rawStorage);
+    } catch {
+      // If parsing fails, treat string as the data
+      const storage = createBlockStorage(rawStorage);
+      return { storage, data: rawStorage };
+    }
+  }
+
+  // Check for BlockStorage format (has discriminator)
+  if (isBlockStorage(parsed)) {
+    const storage = normalizeBlockStorage(parsed);
+    return { storage, data: getStorageData(storage) };
+  }
+
+  // Check for legacy V1/V2 format: { args, uiState }
+  if (isLegacyModelV1ApiFormat(parsed)) {
+    // For legacy format, the whole object IS the data
+    const storage = createBlockStorage(parsed);
+    return { storage, data: parsed };
+  }
+
+  // Raw V3 data - wrap it
+  const storage = createBlockStorage(parsed);
+  return { storage, data: parsed };
+}
+
+/**
+ * Applies a state update to existing storage.
+ * Used when setData is called from the frontend.
+ *
+ * @param currentStorageJson - Current storage as JSON string (must be defined)
+ * @param payload - Update payload with operation type and value
+ * @returns Updated storage as StringifiedJson<BlockStorage>
+ */
+export function applyStorageUpdate(
+  currentStorageJson: string,
+  payload: MutateStoragePayload,
+): StringifiedJson<BlockStorage> {
+  const { storage: currentStorage } = normalizeStorage(currentStorageJson);
+
+  // Update data while preserving other storage fields (version, plugins)
+  const updatedStorage = updateStorageData(currentStorage, payload);
+
+  return stringifyJson(updatedStorage);
+}
+
+/**
+ * Checks if data is in legacy Model API v1 format.
+ * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.
+ */
+function isLegacyModelV1ApiFormat(data: unknown): data is { args?: unknown } {
+  if (data === null || typeof data !== "object") return false;
+  if (isBlockStorage(data)) return false;
+
+  const obj = data as Record<string, unknown>;
+  return "args" in obj;
+}
+
+// =============================================================================
+// Facade Callback Implementations
+// =============================================================================
+
+/**
+ * Gets storage debug view from raw storage data.
+ * Returns structured debug info about the storage state.
+ *
+ * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+ * @returns JSON string with storage debug view
+ */
+export function getStorageDebugView(rawStorage: unknown): StringifiedJson<StorageDebugView> {
+  const { storage } = normalizeStorage(rawStorage);
+  const debugView: StorageDebugView = {
+    dataVersion: storage.__dataVersion,
+    data: storage.__data,
+  };
+  return stringifyJson(debugView);
+}
+
+// =============================================================================
+// Migration Support
+// =============================================================================
+
+/**
+ * Result of storage migration.
+ * Returned by __pl_storage_migrate callback.
+ *
+ * - Error result: { error: string } - serious failure (no context, etc.)
+ * - Success result: { newStorageJson: StringifiedJson<BlockStorage>, info: string } - migration succeeded
+ */
+export type MigrationResult =
+  | { error: string }
+  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };
+
+/**
+ * Runs storage migration using the provided hooks.
+ * This is the main entry point for the middle layer to trigger migrations.
+ *
+ * @param currentStorageJson - Current storage as JSON string (or undefined)
+ * @param hooks - Migration dependencies (block/plugin data migration and creation functions)
+ * @returns MigrationResult
+ */
+export function migrateStorage(
+  currentStorageJson: string | undefined,
+  hooks: MigrationHooks,
+): MigrationResult {
+  // Normalize current storage
+  const { storage: currentStorage } = normalizeStorage(currentStorageJson);
+
+  const newPluginRegistry = hooks.getPluginRegistry();
+
+  // Perform atomic migration of block + all plugins
+  const migrationResult = migrateBlockStorage(currentStorage, {
+    migrateBlockData: hooks.migrateBlockData,
+    migratePluginData: hooks.migratePluginData,
+    newPluginRegistry,
+    createPluginData: hooks.createPluginData,
+  });
+
+  if (!migrationResult.success) {
+    return {
+      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,
+    };
+  }
+
+  // Build info message
+  const oldVersion = currentStorage.__dataVersion;
+  const newVersion = migrationResult.storage.__dataVersion;
+  const info =
+    oldVersion === newVersion
+      ? `No migration needed (${oldVersion})`
+      : `Migrated ${oldVersion} -> ${newVersion}`;
+
+  return {
+    newStorageJson: stringifyJson(migrationResult.storage),
+    info,
+  };
+}
+
+// =============================================================================
+// Initial Storage Creation
+// =============================================================================
+
+/**
+ * Creates complete initial storage (block data + all plugin data) atomically.
+ *
+ * @param hooks - Dependencies for creating initial block and plugin data
+ * @returns Initial storage as branded JSON string
+ */
+export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {
+  const blockDefault = hooks.getDefaultBlockData();
+  const pluginRegistry = hooks.getPluginRegistry();
+
+  const plugins: Record<string, VersionedData<unknown>> = {};
+  for (const pluginId of Object.keys(pluginRegistry)) {
+    const initial = hooks.createPluginData(pluginId);
+    plugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+  }
+
+  const storage: BlockStorage = {
+    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+    __dataVersion: blockDefault.version,
+    __data: blockDefault.data,
+    __pluginRegistry: pluginRegistry,
+    __plugins: plugins,
+  };
+  return stringifyJson(storage);
+}
+
+// =============================================================================
+// Args Derivation from Storage
+// =============================================================================
+
+/**
+ * Result of args derivation from storage.
+ * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.
+ */
+export type ArgsDeriveResult = { error: string } | { error?: undefined; value: unknown };
+
+/**
+ * Derives args from storage using the provided args function.
+ * This extracts data from storage and passes it to the block's args() function.
+ *
+ * @param storageJson - Storage as JSON string
+ * @param argsFunction - The block's args derivation function
+ * @returns ArgsDeriveResult with derived args or error
+ */
+export function deriveArgsFromStorage(
+  storageJson: string,
+  argsFunction: (data: unknown) => unknown,
+): ArgsDeriveResult {
+  // Extract data from storage
+  const { data } = normalizeStorage(storageJson);
+
+  // Call the args function with extracted data
+  try {
+    const result = argsFunction(data);
+    return { value: result };
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `args() threw: ${errorMsg}` };
+  }
+}
+
+/**
+ * Derives prerunArgs from storage.
+ * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.
+ *
+ * @param storageJson - Storage as JSON string
+ * @param argsFunction - The block's args derivation function (fallback)
+ * @param prerunArgsFunction - Optional prerun args derivation function
+ * @returns ArgsDeriveResult with derived prerunArgs or error
+ */
+export function derivePrerunArgsFromStorage(
+  storageJson: string,
+  argsFunction: (data: unknown) => unknown,
+  prerunArgsFunction?: (data: unknown) => unknown,
+): ArgsDeriveResult {
+  // Extract data from storage
+  const { data } = normalizeStorage(storageJson);
+
+  // Try prerunArgs function first if available
+  if (prerunArgsFunction) {
+    try {
+      const result = prerunArgsFunction(data);
+      return { value: result };
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      return { error: `prerunArgs() threw: ${errorMsg}` };
+    }
+  }
+
+  // Fall back to args function
+  try {
+    const result = argsFunction(data);
+    return { value: result };
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `args() threw (fallback): ${errorMsg}` };
+  }
+}
+
+// Export discriminator key and schema version for external checks
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };

package/src/block_storage_facade.ts

@@ -0,0 +1,199 @@
+/**
+ * Block Storage Facade - Contract between bundled blocks and middle layer.
+ *
+ * ============================================================================
+ * VERSIONING
+ * ============================================================================
+ *
+ * Blocks declare their model API version via the `requiresModelAPIVersion` feature flag
+ * (see BlockCodeKnownFeatureFlags). This determines how the middle layer manages block state:
+ *
+ * - Version 1: Legacy BlockModel - state is {args, uiState}, managed directly by middle layer
+ * - Version 2: BlockModelV3 - uses blockStorage with VM-based callbacks (this facade)
+ *
+ * This facade (BlockStorageFacade) is used by blocks with `requiresModelAPIVersion: 2`.
+ * The version number matches the model API version for clarity.
+ *
+ * ============================================================================
+ * BACKWARD COMPATIBILITY WARNING
+ * ============================================================================
+ *
+ * This file documents the FACADE between the SDK (bundled into blocks) and the
+ * middle layer. Once a block is published, its SDK version is frozen. The middle
+ * layer must support ALL previously released callback signatures indefinitely.
+ *
+ * RULES:
+ * 1. NEVER change the signature of existing callbacks
+ * 2. NEVER remove existing callbacks
+ * 3. New callbacks CAN be added (old blocks won't register them, middle layer
+ *    should handle missing callbacks gracefully)
+ * 4. Callback return types can be EXTENDED (add optional fields) but not changed
+ * 5. Callback parameter types should remain compatible (middle layer may need
+ *    to handle both old and new formats)
+ *
+ * The facade consists of callbacks registered via `tryRegisterCallback()` with
+ * the `__pl_` prefix. These are registered by the SDK when a block loads and
+ * called by the middle layer to perform operations.
+ *
+ * ============================================================================
+ * WHAT CAN BE CHANGED FREELY
+ * ============================================================================
+ *
+ * - Middle layer code (lib/node/pl-middle-layer)
+ * - SDK internal implementation (as long as callback contracts are preserved)
+ * - SDK exports used ONLY by middle layer (not by blocks themselves)
+ * - New SDK features that don't affect existing callbacks
+ *
+ * @module block_storage_facade
+ */
+
+import type { MutateStoragePayload } from "./block_storage";
+import type { ConfigRenderLambda } from "./bconfig";
+import { createRenderLambda, tryRegisterCallback } from "./internal";
+import type { StringifiedJson } from "@milaboratories/pl-model-common";
+
+// =============================================================================
+// Facade Version
+// =============================================================================
+
+/**
+ * The current facade version. This value is used for `requiresModelAPIVersion`
+ * feature flag in BlockModelV3.
+ */
+export const BLOCK_STORAGE_FACADE_VERSION = 2;
+
+// =============================================================================
+// Facade Callback Names
+// =============================================================================
+
+/**
+ * All facade callback names as constants.
+ * These are the source of truth - the interface is derived from these.
+ *
+ * IMPORTANT: When adding a new callback:
+ * 1. Add the constant here
+ * 2. Add the callback signature to FacadeCallbackTypes below
+ * 3. The BlockStorageFacade type will automatically include it
+ */
+export const BlockStorageFacadeCallbacks = {
+  StorageApplyUpdate: "__pl_storage_applyUpdate",
+  StorageDebugView: "__pl_storage_debugView",
+  StorageMigrate: "__pl_storage_migrate",
+  ArgsDerive: "__pl_args_derive",
+  PrerunArgsDerive: "__pl_prerunArgs_derive",
+  StorageInitial: "__pl_storage_initial",
+} as const;
+
+/**
+ * Creates a map of lambda handles from a callbacks constant object.
+ * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').
+ */
+function createFacadeHandles<T extends Record<string, string>>(
+  callbacks: T,
+): { [K in T[keyof T]]: ConfigRenderLambda } {
+  return Object.fromEntries(
+    Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]),
+  ) as { [K in T[keyof T]]: ConfigRenderLambda };
+}
+
+/**
+ * Lambda handles for facade callbacks.
+ * Used by the middle layer to invoke callbacks via executeSingleLambda().
+ */
+export const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);
+
+// =============================================================================
+// Facade Interface (source of truth for callback signatures)
+// =============================================================================
+
+/**
+ * The complete facade interface between bundled blocks (SDK) and middle layer.
+ *
+ * This interface defines ALL callbacks that a block registers. The middle layer
+ * calls these callbacks to perform storage operations.
+ *
+ * ALL types are inlined to simplify versioning - when a callback changes,
+ * the entire signature is visible in one place.
+ *
+ * BACKWARD COMPATIBILITY:
+ * - This interface can only be EXTENDED, never shrunk
+ * - Existing callback signatures MUST NOT change
+ * - Middle layer should use Partial<BlockStorageFacade> when dealing with
+ *   blocks of unknown version (older blocks may not have all callbacks)
+ *
+ * Each callback is documented with:
+ * - Purpose and when it's called
+ * - Parameter descriptions
+ * - Return value description
+ */
+export interface BlockStorageFacade {
+  /**
+   * Apply state update to storage.
+   * Called when UI updates block state (setState) or plugin data.
+   * @param currentStorageJson - Current storage as JSON string
+   * @param payload - Update payload with operation type and value
+   * @returns Updated storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (
+    currentStorageJson: StringifiedJson,
+    payload: MutateStoragePayload,
+  ) => StringifiedJson;
+
+  /**
+   * Get debug view of storage.
+   * Called by developer tools to inspect storage state.
+   * @param storageJson - Storage as JSON string (or undefined for new blocks)
+   * @returns JSON string containing StorageDebugView
+   */
+  [BlockStorageFacadeCallbacks.StorageDebugView]: (
+    storageJson: StringifiedJson | undefined,
+  ) => StringifiedJson;
+
+  /**
+   * Run storage migration.
+   * Called when block loads to migrate data to latest version.
+   * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks)
+   * @returns Migration result - either error or success with new storage
+   */
+  [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) =>
+    | { error: string }
+    | {
+        error?: undefined;
+        newStorageJson: StringifiedJson;
+        info: string;
+      };
+
+  /**
+   * Derive args from storage.
+   * Called to get block configuration args from storage.
+   * @param storageJson - Storage as JSON string
+   * @returns Args derivation result - either error or derived value
+   */
+  [BlockStorageFacadeCallbacks.ArgsDerive]: (
+    storageJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; value: unknown };
+
+  /**
+   * Derive prerunArgs from storage.
+   * Called to get prerun args; falls back to args callback if not registered.
+   * @param storageJson - Storage as JSON string
+   * @returns Args derivation result - either error or derived value
+   */
+  [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (
+    storageJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; value: unknown };
+
+  /**
+   * Get initial storage JSON for new blocks.
+   * Called when creating a new block to get complete initial storage.
+   * @returns Initial storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;
+}
+
+/** Register all facade callbacks at once. Ensures all required callbacks are provided. */
+export function registerFacadeCallbacks(callbacks: BlockStorageFacade): void {
+  for (const key of Object.values(BlockStorageFacadeCallbacks)) {
+    tryRegisterCallback(key, callbacks[key] as (...args: any[]) => any);
+  }
+}

package/src/components/PlDataTable/state-migration.ts

@@ -158,10 +158,10 @@ function migrateV4toV5(
   const nextId = () => ++idCounter;
 
   const migratedCache: PlDataTableStateV2CacheEntry[] = state.stateCache.map((entry) => {
-    const leaves: PlDataTableFiltersWithMeta[] = [];
+    const leaves: PlDataTableFiltersWithMeta["filters"] = [];
     for (const f of entry.filtersState) {
       if (f.filter !== null && !f.filter.disabled) {
-        const column = canonicalizeJson<PTableColumnId>(f.id);
+        const column = canonicalizeJson(f.id);
         leaves.push(migrateTableFilter(column, f.filter.value, nextId));
       }
     }
@@ -198,10 +198,10 @@ function migrateV4toV5(
 
 /** Migrate a single per-column PlTableFilter to a tree-based FilterSpec node */
 function migrateTableFilter(
-  column: string,
+  column: CanonicalizedJson<PTableColumnId>,
   filter: PlTableFilter,
   nextId: () => number,
-): PlDataTableFiltersWithMeta {
+): PlDataTableFiltersWithMeta["filters"][number] {
   const id = nextId();
   switch (filter.type) {
     case "isNA":

package/src/components/PlDataTable/table.ts

@@ -26,6 +26,7 @@ import {
   readAnnotation,
   uniqueBy,
   isBooleanExpression,
+  parseJson,
 } from "@milaboratories/pl-model-common";
 import { filterSpecToSpecQueryExpr } from "../../filters";
 import type { RenderCtxBase, TreeNodeAccessor, PColumnDataUniversal } from "../../render";
@@ -186,7 +187,7 @@ export function createPlDataTableV2<A, U>(
   const stateFilters = tableStateNormalized.pTableParams.filters;
   const opsFilters = ops?.filters ?? null;
   const filters: null | PlDataTableFilters =
-    stateFilters !== null && opsFilters !== null
+    stateFilters != null && opsFilters != null
       ? { type: "and", filters: [stateFilters, opsFilters] }
       : (stateFilters ?? opsFilters);
   const filterColumns = filters ? collectFilterSpecColumns(filters) : [];
@@ -218,6 +219,7 @@ export function createPlDataTableV2<A, U>(
     sorting,
     coreColumnPredicate: ops?.coreColumnPredicate,
   });
+
   const fullHandle = ctx.createPTableV2(fullDef);
   if (!fullHandle) return undefined;
 
@@ -245,12 +247,22 @@ export function createPlDataTableV2<A, U>(
     coreColumns.forEach((c) => hiddenColumns.delete(c));
   }
 
-  // Sorting changes the order of result rows — preserve sorted columns from being hidden
+  // Preserve sorted columns from being hidden
   sorting
     .map((s) => s.column)
     .filter((c): c is PTableColumnIdColumn => c.type === "column")
     .forEach((c) => hiddenColumns.delete(c.id));
 
+  // Preserve filter columns from being hidden
+  if (filters) {
+    collectFilterSpecColumns(filters)
+      .flatMap((c) => {
+        const obj = parseJson(c);
+        return obj.type === "column" ? [obj.id] : [];
+      })
+      .forEach((c) => hiddenColumns.delete(c));
+  }
+
   const visibleColumns = columns.filter((c) => !hiddenColumns.has(c.id));
   const visibleLabelColumns = getMatchingLabelColumns(
     visibleColumns.map(getColumnIdAndSpec),
@@ -269,13 +281,14 @@ export function createPlDataTableV2<A, U>(
     coreColumnPredicate,
   });
   const visibleHandle = ctx.createPTableV2(visibleDef);
+
   if (!visibleHandle) return undefined;
 
   return {
     sourceId: tableStateNormalized.pTableParams.sourceId,
     fullTableHandle: fullHandle,
     visibleTableHandle: visibleHandle,
-  } satisfies PlDataTableModel;
+  } as PlDataTableModel;
 }
 
 /** Create sheet entries for PlDataTable */

package/src/components/PlDataTable/v5.ts

@@ -8,8 +8,10 @@ import type {
   PTableSorting,
   PColumnIdAndSpec,
   PTableHandle,
+  RootFilterSpec,
+  PTableColumnId,
 } from "@milaboratories/pl-model-common";
-import type { FilterSpec, FilterSpecLeaf } from "../../filters";
+import type { FilterSpecLeaf } from "../../filters";
 
 export type PlTableColumnId = {
   /** Original column spec */
@@ -60,10 +62,10 @@ export type PlDataTableSheetState = {
 };
 
 /** Tree-based filter state compatible with PlAdvancedFilter's RootFilter */
-export type PlDataTableFilters = FilterSpec<FilterSpecLeaf<string>>;
-export type PlDataTableFiltersWithMeta = FilterSpec<
-  FilterSpecLeaf<string>,
-  { id: number; isExpanded?: boolean }
+export type PlDataTableFilters = RootFilterSpec<FilterSpecLeaf<CanonicalizedJson<PTableColumnId>>>;
+export type PlDataTableFiltersWithMeta = RootFilterSpec<
+  FilterSpecLeaf<CanonicalizedJson<PTableColumnId>>,
+  { id: number; isExpanded?: boolean; source?: "table-filter" | "table-search" }
 >;
 
 export type PlDataTableStateV2CacheEntry = {
@@ -75,6 +77,8 @@ export type PlDataTableStateV2CacheEntry = {
   sheetsState: PlDataTableSheetState[];
   /** Filters state (tree-based, compatible with PlAdvancedFilter) */
   filtersState: null | PlDataTableFiltersWithMeta;
+  /** Fast search string */
+  searchString?: string;
 };
 
 export type PTableParamsV2 =

package/src/filters/converters/filterToQuery.ts

@@ -11,15 +11,14 @@ import { traverseFilterSpec } from "../traverse";
 /** Parses a CanonicalizedJson<PTableColumnId> string into a SpecQueryExpression reference. */
 function resolveColumnRef(columnStr: string): SpecQueryExpression {
   const parsed = JSON.parse(columnStr) as PTableColumnId;
-  if (parsed.type === "axis") {
-    return { type: "axisRef", value: parsed.id as SingleAxisSelector };
-  }
-  return { type: "columnRef", value: parsed.id };
+  return parsed.type === "axis"
+    ? { type: "axisRef", value: parsed.id as SingleAxisSelector }
+    : { type: "columnRef", value: parsed.id };
 }
 
 /** Converts a FilterSpec tree into a SpecQueryExpression. */
-export function filterSpecToSpecQueryExpr(
-  filter: FilterSpec<FilterSpecLeaf<string>>,
+export function filterSpecToSpecQueryExpr<Leaf extends FilterSpecLeaf<string>>(
+  filter: FilterSpec<Leaf>,
 ): SpecQueryExpression {
   return traverseFilterSpec(filter, {
     leaf: leafToSpecQueryExpr,
@@ -39,7 +38,9 @@ export function filterSpecToSpecQueryExpr(
   });
 }
 
-function leafToSpecQueryExpr(filter: FilterSpecLeaf<string>): SpecQueryExpression {
+function leafToSpecQueryExpr<Leaf extends FilterSpecLeaf<string>>(
+  filter: Leaf,
+): SpecQueryExpression {
   switch (filter.type) {
     case "patternEquals":
       return {