@pythia-software/query-table-react 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,32 +1,459 @@
+// src/useComputedColumns.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  applyQuery,
+  compileFormula,
+  computedFieldName,
+  groupPreview,
+  isComputedField,
+  memoryComputedColumnStore,
+  readFieldValue,
+  toServerQuery,
+  validateComputedColumn,
+  isSelectable
+} from "@pythia-software/query-table-core";
+
+// src/formulaWorker.ts
+import {
+  formulaRuntime
+} from "@pythia-software/query-table-core";
+var createFormulaWorker = () => {
+  const code = `const evaluate = ${formulaRuntime.toString()}; self.onmessage = e => { const { ast, inputs } = e.data; self.postMessage(inputs.map(row => evaluate(ast, row))); };`;
+  const url = URL.createObjectURL(
+    new Blob([code], { type: "text/javascript" })
+  );
+  try {
+    return new Worker(url);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+};
+function evaluateFormulaRows(ast, inputs, signal, factory = createFormulaWorker) {
+  if (signal?.aborted)
+    return Promise.reject(new DOMException("Aborted", "AbortError"));
+  if (!inputs.length) return Promise.resolve([]);
+  return new Promise((resolve, reject) => {
+    let worker;
+    try {
+      worker = factory();
+    } catch (e) {
+      reject(
+        new Error(
+          `Formula worker unavailable: ${e instanceof Error ? e.message : String(e)}`
+        )
+      );
+      return;
+    }
+    let timer;
+    const started = Date.now();
+    let offset = 0;
+    const results = [];
+    const cleanup = () => {
+      clearTimeout(timer);
+      worker.terminate();
+      signal?.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+      cleanup();
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    const send = () => {
+      if (Date.now() - started > 3e4) {
+        cleanup();
+        reject(
+          new Error(
+            "Formula exceeded the 30-second processing budget. Reduce the row count or simplify the formula."
+          )
+        );
+        return;
+      }
+      timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            "Formula timed out. Check the regex or reduce the row count."
+          )
+        );
+      }, 2e3);
+      try {
+        worker.postMessage({ ast, inputs: inputs.slice(offset, offset + 200) });
+      } catch (e) {
+        cleanup();
+        reject(e);
+      }
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    worker.onerror = () => {
+      cleanup();
+      reject(new Error("Formula worker failed."));
+    };
+    worker.onmessage = (event) => {
+      clearTimeout(timer);
+      results.push(...event.data);
+      offset += event.data.length;
+      if (offset >= inputs.length) {
+        cleanup();
+        resolve(results);
+      } else send();
+    };
+    send();
+  });
+}
+
+// src/useComputedColumns.ts
+function useComputedColumns(options) {
+  const { schema, query, rows, transport, clientRows, workerFactory } = options;
+  const store = useMemo(
+    () => options.store ?? memoryComputedColumnStore(),
+    [options.store]
+  );
+  const [catalogue, setCatalogue] = useState(null);
+  const definitions = useMemo(
+    () => catalogue?.dataset === schema.name && catalogue.store === store ? catalogue.items : [],
+    [catalogue, schema.name, store]
+  );
+  const [loading, setLoading] = useState(false), [error, setError] = useState(null);
+  const catalogueRequest = useRef(null);
+  const reload = useCallback(async () => {
+    catalogueRequest.current?.abort();
+    const ac = new AbortController();
+    catalogueRequest.current = ac;
+    setLoading(true);
+    setError(null);
+    try {
+      const items = await store.list(schema.name, ac.signal);
+      if (ac.signal.aborted) return;
+      const valid = items.map(validateComputedColumn).sort((a, b) => a.id.localeCompare(b.id));
+      if (new Set(valid.map((c) => c.id)).size !== valid.length)
+        throw new Error("Duplicate computed column IDs.");
+      setCatalogue(
+        (previous) => previous?.dataset === schema.name && previous.store === store && JSON.stringify(previous.items) === JSON.stringify(valid) ? previous : { dataset: schema.name, store, items: valid }
+      );
+    } catch (e) {
+      if (!ac.signal.aborted)
+        setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      if (!ac.signal.aborted) setLoading(false);
+    }
+  }, [store, schema.name]);
+  useEffect(() => {
+    void reload();
+    return () => catalogueRequest.current?.abort();
+  }, [reload]);
+  useEffect(
+    () => store.subscribe?.(schema.name, () => {
+      void reload();
+    }),
+    [store, schema.name, reload]
+  );
+  useEffect(() => {
+    const focus = () => {
+      void reload();
+    };
+    window.addEventListener("focus", focus);
+    return () => window.removeEventListener("focus", focus);
+  }, [reload]);
+  const inputFields = useMemo(
+    () => schema.fields.filter(isSelectable).filter(
+      (f) => f.source.kind === "backend" || f.source.accessor && f.source.dependencies
+    ),
+    [schema]
+  );
+  const compile = useCallback(
+    (source, editingId) => {
+      const stack = new Set(editingId ? [editingId] : []);
+      let expanded = 0;
+      const resolve = (name) => {
+        if (!isComputedField(name)) return void 0;
+        const id = name.slice("@computed/".length), def = definitions.find((d) => d.id === id);
+        if (!def) throw new Error(`Computed column unavailable: ${id}`);
+        if (stack.has(id))
+          throw new Error(`Circular computed-column reference: ${def.label}`);
+        if (stack.size >= 20 || ++expanded > 100)
+          throw new Error("Computed dependency graph is too large.");
+        stack.add(id);
+        try {
+          return compileFormula(def.expression.source, inputFields, resolve);
+        } finally {
+          stack.delete(id);
+        }
+      };
+      return compileFormula(source, inputFields, resolve);
+    },
+    [inputFields, definitions]
+  );
+  const plans = useMemo(
+    () => new Map(
+      definitions.map((def) => {
+        try {
+          return [
+            def.id,
+            { plan: compile(def.expression.source, def.id) }
+          ];
+        } catch (e) {
+          return [
+            def.id,
+            { error: e instanceof Error ? e.message : String(e) }
+          ];
+        }
+      })
+    ),
+    [definitions, compile]
+  );
+  const backendDependencies = useCallback(
+    (plan) => [
+      ...new Set(
+        plan.dependencies.flatMap((name) => {
+          const f = inputFields.find((f2) => f2.name === name);
+          return f?.source.kind === "backend" ? [name] : f?.source.dependencies ?? [];
+        })
+      )
+    ].filter(
+      (name) => schema.fields.some(
+        (f) => f.name === name && f.source.kind === "backend"
+      )
+    ).sort(),
+    [schema, inputFields]
+  );
+  const inputsFor = useCallback(
+    (plan, batch) => {
+      let size = 0;
+      return batch.map((row) => {
+        const values = /* @__PURE__ */ Object.create(null);
+        for (const name of plan.dependencies) {
+          const field = inputFields.find((f) => f.name === name);
+          const raw = readFieldValue(field, row);
+          values[name] = raw instanceof Date ? raw.toISOString() : raw;
+        }
+        size += JSON.stringify(values).length;
+        if (size > 16e6)
+          throw new Error(
+            "Input sample exceeds 16 MB. Reduce the rows to process."
+          );
+        return values;
+      });
+    },
+    [inputFields]
+  );
+  const activeSelect = query.select.length ? query.select : schema.defaultSelect ?? [];
+  const activeIds = activeSelect.filter((c) => isComputedField(c.field)).map((c) => c.field.slice("@computed/".length)).sort().join(",");
+  const [evaluated, setEvaluated] = useState(null);
+  useEffect(() => {
+    const ac = new AbortController();
+    const values = /* @__PURE__ */ new Map();
+    void (async () => {
+      for (const id of activeIds.split(",").filter(Boolean)) {
+        const entry = plans.get(id);
+        if (!entry?.plan) continue;
+        try {
+          values.set(
+            id,
+            await evaluateFormulaRows(
+              entry.plan.ast,
+              inputsFor(entry.plan, rows),
+              ac.signal,
+              workerFactory
+            )
+          );
+        } catch (e) {
+          if (ac.signal.aborted) return;
+          values.set(
+            id,
+            rows.map(() => ({
+              value: null,
+              error: e instanceof Error ? e.message : String(e)
+            }))
+          );
+        }
+      }
+      if (!ac.signal.aborted) setEvaluated({ rows, plans, values });
+    })();
+    return () => ac.abort();
+  }, [activeIds, rows, plans, inputsFor, workerFactory]);
+  const displaySchema = useMemo(() => {
+    const indices = new Map(rows.map((row, i) => [row, i]));
+    const fields = definitions.map((def) => {
+      const entry = plans.get(def.id);
+      return {
+        name: computedFieldName(def.id),
+        label: def.label,
+        type: entry?.plan?.type === "null" ? "text" : entry?.plan?.type ?? "text",
+        group: "Computed columns",
+        source: {
+          kind: "derived",
+          computedId: def.id,
+          dependencies: entry?.plan ? backendDependencies(entry.plan) : [],
+          accessor: (row) => {
+            if (entry?.error) return { computedError: entry.error };
+            const result = evaluated?.rows === rows && evaluated.plans === plans ? evaluated.values.get(def.id)?.[indices.get(row) ?? -1] : void 0;
+            return result?.error ? { computedError: result.error } : result ? result.value : { computedError: "Calculating\u2026" };
+          }
+        },
+        filter: { enabled: false },
+        sort: { enabled: false },
+        aggregate: { measure: false, groupable: false }
+      };
+    });
+    for (const col of activeSelect)
+      if (isComputedField(col.field) && !fields.some((f) => f.name === col.field))
+        fields.push({
+          name: col.field,
+          label: col.field.slice(10),
+          type: "text",
+          source: {
+            kind: "derived",
+            computedId: col.field.slice(10),
+            accessor: () => ({
+              computedError: loading ? "Loading definition\u2026" : "Definition unavailable. Reload the catalogue or contact its owner."
+            })
+          },
+          filter: { enabled: false },
+          sort: { enabled: false },
+          aggregate: { measure: false, groupable: false }
+        });
+    return { ...schema, fields: [...schema.fields, ...fields] };
+  }, [
+    schema,
+    definitions,
+    plans,
+    backendDependencies,
+    evaluated,
+    rows,
+    query.select,
+    schema.defaultSelect,
+    loading
+  ]);
+  const save = useCallback(
+    async (column, expectedRevision) => {
+      compile(column.expression.source, column.id);
+      const saved = validateComputedColumn(
+        await store.save(schema.name, column, expectedRevision)
+      );
+      setCatalogue((prev) => ({
+        dataset: schema.name,
+        store,
+        items: [
+          ...prev?.dataset === schema.name && prev.store === store ? prev.items.filter((d) => d.id !== saved.id) : [],
+          saved
+        ]
+      }));
+      return saved;
+    },
+    [compile, store, schema.name]
+  );
+  const preview = useCallback(
+    async (source, count, signal, editingId, includeInputs = true) => {
+      if (!Number.isInteger(count) || count < 1 || count > 1e4)
+        throw new Error("Choose between 1 and 10,000 rows.");
+      const plan = compile(source, editingId);
+      let batch = [], total = 0;
+      if (transport) {
+        const request = toServerQuery(
+          {
+            ...query,
+            select: [
+              .../* @__PURE__ */ new Set([schema.idField, ...backendDependencies(plan)])
+            ].map((field) => ({ field })),
+            limit: Math.min(count, 500),
+            offset: 0
+          },
+          schema
+        );
+        while (batch.length < count) {
+          if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+          const res = await transport.fetchRows(
+            {
+              ...request,
+              offset: batch.length,
+              limit: Math.min(500, count - batch.length)
+            },
+            signal
+          );
+          total = res.total;
+          batch.push(...res.rows.slice(0, count - batch.length));
+          if (!res.rows.length || batch.length >= total) break;
+        }
+      } else {
+        const result = applyQuery(
+          clientRows ?? [],
+          { ...query, limit: count, offset: 0 },
+          schema
+        );
+        batch = result.rows;
+        total = result.total;
+      }
+      const inputs = inputsFor(plan, batch), results = await evaluateFormulaRows(
+        plan.ast,
+        inputs,
+        signal,
+        workerFactory
+      );
+      return groupPreview(
+        includeInputs ? plan.dependencies : [],
+        inputs,
+        results,
+        total
+      );
+    },
+    [
+      compile,
+      transport,
+      query,
+      schema,
+      backendDependencies,
+      clientRows,
+      inputsFor,
+      workerFactory
+    ]
+  );
+  return {
+    displaySchema,
+    api: {
+      definitions,
+      catalogue: displaySchema.fields,
+      loading,
+      error,
+      reload,
+      save,
+      compile,
+      preview
+    }
+  };
+}
+
 // src/useQueryTable.ts
-import { useCallback as useCallback5, useEffect as useEffect3, useMemo as useMemo5, useRef as useRef2, useState as useState5 } from "react";
+import { useCallback as useCallback6, useEffect as useEffect4, useMemo as useMemo6, useRef as useRef3, useState as useState6 } from "react";
 import {
   EMPTY_QUERY,
-  applyQuery,
+  applyQuery as applyQuery2,
   decodeQuery,
   encodeQuery,
   memoryStorageAdapter,
   normalizeQueryState,
-  readFieldValue,
+  readFieldValue as readFieldValue2,
   selectedFields as selectedFields2,
-  toServerQuery,
-  queriesEqual
+  toServerQuery as toServerQuery2,
+  queriesEqual,
+  isOrGroup,
+  predicatesOf,
+  negateClause,
+  opsForField
 } from "@pythia-software/query-table-core";
 
 // src/useAggregations.ts
-import { useEffect, useMemo, useState } from "react";
+import { useEffect as useEffect2, useMemo as useMemo2, useState as useState2 } from "react";
 import { applyAggregations, toAggregationQuery } from "@pythia-software/query-table-core";
 var EMPTY_RESULT = { metrics: [] };
-function useAggregations(query, schema, transport, clientRows, debounceMs, nonce) {
-  const [results, setResults] = useState(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-  const key = useMemo(
+function useAggregations(query, schema, transport, clientRows, debounceMs, nonce, validateQuery) {
+  const [results, setResults] = useState2(null);
+  const [loading, setLoading] = useState2(false);
+  const [error, setError] = useState2(null);
+  const key = useMemo2(
     () => JSON.stringify({ where: query.where, aggregations: query.aggregations ?? [] }),
     [query.where, query.aggregations]
   );
   const hasAggregations = (query.aggregations?.length ?? 0) > 0;
-  useEffect(() => {
+  useEffect2(() => {
     if (!hasAggregations) {
       setResults(null);
       setError(null);
@@ -39,6 +466,7 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
       setLoading(true);
       setError(null);
       try {
+        validateQuery?.(query);
         let res;
         if (transport?.fetchAggregations) {
           res = await transport.fetchAggregations(toAggregationQuery(query, schema), ac.signal);
@@ -49,7 +477,10 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
         }
         if (!cancelled) setResults(res);
       } catch (e) {
-        if (!cancelled && !ac.signal.aborted) setError(e);
+        if (!cancelled && !ac.signal.aborted) {
+          setError(e);
+          setResults(null);
+        }
       } finally {
         if (!cancelled) setLoading(false);
       }
@@ -60,16 +491,16 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
       clearTimeout(t);
       ac.abort();
     };
-  }, [key, hasAggregations, transport, clientRows, schema, debounceMs, nonce]);
+  }, [key, hasAggregations, transport, clientRows, schema, debounceMs, nonce, validateQuery]);
   return { results, loading, error };
 }
 
 // src/useSelection.ts
-import { useCallback, useMemo as useMemo2, useRef, useState as useState2 } from "react";
+import { useCallback as useCallback2, useMemo as useMemo3, useRef as useRef2, useState as useState3 } from "react";
 function useSelection(displayedIds) {
-  const [selected, setSelected] = useState2(() => /* @__PURE__ */ new Set());
-  const anchor = useRef(null);
-  const toggle = useCallback(
+  const [selected, setSelected] = useState3(() => /* @__PURE__ */ new Set());
+  const anchor = useRef2(null);
+  const toggle = useCallback2(
     (id, shiftKey = false) => {
       setSelected((prev) => {
         const next = new Set(prev);
@@ -97,7 +528,7 @@ function useSelection(displayedIds) {
     },
     [displayedIds]
   );
-  const setPage = useCallback((ids, select) => {
+  const setPage = useCallback2((ids, select) => {
     setSelected((prev) => {
       const next = new Set(prev);
       for (const id of ids) {
@@ -107,7 +538,21 @@ function useSelection(displayedIds) {
       return next;
     });
   }, []);
-  const pageState = useCallback(
+  const replace = useCallback2((ids) => {
+    const next = new Set(ids);
+    anchor.current = null;
+    setSelected(next);
+  }, []);
+  const retain = useCallback2((ids) => {
+    const allowed = new Set(ids);
+    anchor.current = null;
+    setSelected((prev) => {
+      const next = /* @__PURE__ */ new Set();
+      for (const id of prev) if (allowed.has(id)) next.add(id);
+      return next;
+    });
+  }, []);
+  const pageState = useCallback2(
     (pageIds) => {
       if (pageIds.length === 0) return "none";
       let n = 0;
@@ -116,35 +561,37 @@ function useSelection(displayedIds) {
     },
     [selected]
   );
-  const clear = useCallback(() => {
+  const clear = useCallback2(() => {
     anchor.current = null;
     setSelected(/* @__PURE__ */ new Set());
   }, []);
-  return useMemo2(
+  return useMemo3(
     () => ({
       selected,
       isSelected: (id) => selected.has(id),
       toggle,
       setPage,
+      replace,
+      retain,
       pageState,
       clear,
       count: selected.size
     }),
-    [selected, toggle, setPage, pageState, clear]
+    [selected, toggle, setPage, replace, retain, pageState, clear]
   );
 }
 
 // src/useSelect.ts
-import { useCallback as useCallback2, useMemo as useMemo3 } from "react";
+import { useCallback as useCallback3, useMemo as useMemo4 } from "react";
 import { selectedFields } from "@pythia-software/query-table-core";
 function useSelect(query, setQuery, schema) {
-  const fields = useMemo3(() => selectedFields(schema, query), [schema, query]);
-  const visible = useMemo3(() => fields.map((f) => columnFor(query.select, f.name)), [fields, query.select]);
-  const hidden = useMemo3(() => {
+  const fields = useMemo4(() => selectedFields(schema, query), [schema, query]);
+  const visible = useMemo4(() => fields.map((f) => columnFor(query.select, f.name)), [fields, query.select]);
+  const hidden = useMemo4(() => {
     const shown = new Set(fields.map((f) => f.name));
     return schema.fields.filter((f) => !shown.has(f.name) && (f.select?.enabled ?? true));
   }, [schema, fields]);
-  const writeSelect = useCallback2(
+  const writeSelect = useCallback3(
     (mutate) => {
       setQuery((prev) => {
         const current = prev.select.length ? prev.select : visible;
@@ -153,9 +600,9 @@ function useSelect(query, setQuery, schema) {
     },
     [setQuery, visible]
   );
-  const show = useCallback2((field) => writeSelect((c) => c.some((x) => x.field === field) ? c : [...c, { field }]), [writeSelect]);
-  const hide = useCallback2((field) => writeSelect((c) => c.filter((x) => x.field !== field)), [writeSelect]);
-  const move = useCallback2(
+  const show = useCallback3((field) => writeSelect((c) => c.some((x) => x.field === field) ? c : [...c, { field }]), [writeSelect]);
+  const hide = useCallback3((field) => writeSelect((c) => c.filter((x) => x.field !== field)), [writeSelect]);
+  const move = useCallback3(
     (field, toIndex) => writeSelect((c) => {
       const from = c.findIndex((x) => x.field === field);
       if (from === -1) return c;
@@ -165,11 +612,11 @@ function useSelect(query, setQuery, schema) {
     }),
     [writeSelect]
   );
-  const setWidth = useCallback2(
+  const setWidth = useCallback3(
     (field, width) => writeSelect((c) => c.map((x) => x.field === field ? { ...x, width: Math.round(width) } : x)),
     [writeSelect]
   );
-  const reset = useCallback2(() => setQuery((prev) => ({ ...prev, select: [] })), [setQuery]);
+  const reset = useCallback3(() => setQuery((prev) => ({ ...prev, select: [] })), [setQuery]);
   return { visible, fields, hidden, show, hide, move, setWidth, reset };
 }
 function columnFor(select, name) {
@@ -178,11 +625,11 @@ function columnFor(select, name) {
 }
 
 // src/useColumnDrag.ts
-import { useCallback as useCallback3, useMemo as useMemo4, useState as useState3 } from "react";
+import { useCallback as useCallback4, useMemo as useMemo5, useState as useState4 } from "react";
 function useColumnDrag() {
-  const [state, setState] = useState3(null);
-  const start = useCallback3((field, index) => setState({ source: field, overIndex: index }), []);
-  const over = useCallback3(
+  const [state, setState] = useState4(null);
+  const start = useCallback4((field, index) => setState({ source: field, overIndex: index }), []);
+  const over = useCallback4(
     (index) => (
       // Keep the SAME object reference when unchanged so React can bail out of the
       // re-render — onDragOver fires continuously while the cursor moves.
@@ -190,8 +637,8 @@ function useColumnDrag() {
     ),
     []
   );
-  const end = useCallback3(() => setState(null), []);
-  const preview = useCallback3(
+  const end = useCallback4(() => setState(null), []);
+  const preview = useCallback4(
     (order) => {
       if (!state) return order;
       const without = order.filter((n) => n !== state.source);
@@ -201,7 +648,7 @@ function useColumnDrag() {
     },
     [state]
   );
-  return useMemo4(
+  return useMemo5(
     () => ({
       source: state?.source ?? null,
       overIndex: state?.overIndex ?? null,
@@ -216,12 +663,12 @@ function useColumnDrag() {
 }
 
 // src/useSavedQueries.ts
-import { useCallback as useCallback4, useEffect as useEffect2, useState as useState4 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect3, useState as useState5 } from "react";
 function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
-  const [items, setItems] = useState4([]);
-  const [defaultId, setDefaultId] = useState4(null);
-  const [loading, setLoading] = useState4(true);
-  const refresh = useCallback4(async () => {
+  const [items, setItems] = useState5([]);
+  const [defaultId, setDefaultId] = useState5(null);
+  const [loading, setLoading] = useState5(true);
+  const refresh = useCallback5(async () => {
     setLoading(true);
     try {
       const [savedItems, defaultSaved] = await Promise.all([
@@ -234,10 +681,10 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
       setLoading(false);
     }
   }, [storage, key]);
-  useEffect2(() => {
+  useEffect3(() => {
     void refresh();
   }, [refresh]);
-  const save = useCallback4(
+  const save = useCallback5(
     async (name) => {
       const saved = await storage.saveNamed(key, name, currentQuery, now());
       await refresh();
@@ -245,25 +692,25 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
     },
     [storage, key, currentQuery, now, refresh]
   );
-  const load = useCallback4(
+  const load = useCallback5(
     (id) => {
       const found = items.find((q) => q.id === id);
       if (found) applyQueryState(found.query);
     },
     [items, applyQueryState]
   );
-  const setDefault = useCallback4(
+  const setDefault = useCallback5(
     async (id) => {
       await storage.setDefaultSaved?.(key, id);
       await refresh();
     },
     [storage, key, refresh]
   );
-  const clearDefault = useCallback4(async () => {
+  const clearDefault = useCallback5(async () => {
     await storage.setDefaultSaved?.(key, null);
     await refresh();
   }, [storage, key, refresh]);
-  const remove = useCallback4(
+  const remove = useCallback5(
     async (id) => {
       if (id === defaultId) await storage.setDefaultSaved?.(key, null);
       await storage.deleteSaved(key, id);
@@ -286,11 +733,14 @@ function defaultsFor(schema) {
     offset: 0
   });
 }
+function cloneWhereTerm(term) {
+  return isOrGroup(term) ? { any: term.any.map((c) => ({ ...c })) } : { ...term };
+}
 function cloneQueryState(q) {
   const clone = {
     select: q.select.map((column) => ({ ...column })),
-    where: q.where.map((clause) => ({ ...clause })),
-    orderBy: q.orderBy.map((term) => ({ ...term })),
+    where: q.where.map(cloneWhereTerm),
+    orderBy: q.orderBy.map((term) => term.extract ? { ...term, extract: { ...term.extract } } : { ...term }),
     limit: q.limit,
     offset: q.offset
   };
@@ -321,7 +771,7 @@ function asDistinctValue(value) {
 }
 function fieldHasNullInRows(field, rows) {
   for (const row of rows) {
-    if (isNullLike(readFieldValue(field, row))) return true;
+    if (isNullLike(readFieldValue2(field, row))) return true;
   }
   return false;
 }
@@ -331,7 +781,7 @@ function distinctValuesFromRows(field, rows, search) {
   const seen = /* @__PURE__ */ new Set();
   let hasMore = false;
   for (const row of rows) {
-    const raw = asDistinctValue(readFieldValue(field, row));
+    const raw = asDistinctValue(readFieldValue2(field, row));
     if (raw == null || seen.has(raw)) continue;
     if (target && !raw.toLowerCase().includes(target)) continue;
     if (values.length < AUTOCOMPLETE_LIMIT) {
@@ -355,30 +805,31 @@ function resolveInitial(opts) {
 }
 function useQueryTable(opts) {
   const { schema, transport, clientRows, initialQuery, syncUrl = false, debounceMs = 200 } = opts;
-  const storage = useMemo5(() => opts.storage ?? memoryStorageAdapter(), [opts.storage]);
+  const storage = useMemo6(() => opts.storage ?? memoryStorageAdapter(), [opts.storage]);
   const now = opts.now ?? Date.now;
-  const nowRef = useRef2(now);
-  const onRefreshRef = useRef2(opts.onRefresh);
-  const defaults = useMemo5(() => defaultsFor(schema), [schema]);
-  const byName = useMemo5(() => new Map(schema.fields.map((f) => [f.name, f])), [schema]);
-  const initRef = useRef2(resolveInitial(opts));
-  const aggIdRef = useRef2(0);
-  const [query, setQueryState] = useState5(initRef.current.q);
-  const undoStack = useRef2([cloneQueryState(initRef.current.q)]);
-  const redoStack = useRef2([]);
-  const [rows, setRows] = useState5([]);
-  const [total, setTotal] = useState5(null);
-  const [loading, setLoading] = useState5(false);
-  const [error, setError] = useState5(null);
-  const [nonce, setNonce] = useState5(0);
-  const [autoRefreshStatus, setAutoRefreshStatus] = useState5(null);
-  useEffect3(() => {
+  const nowRef = useRef3(now);
+  const onRefreshRef = useRef3(opts.onRefresh);
+  const defaults = useMemo6(() => defaultsFor(schema), [schema]);
+  const byName = useMemo6(() => new Map(schema.fields.map((f) => [f.name, f])), [schema]);
+  const initRef = useRef3(resolveInitial(opts));
+  const aggIdRef = useRef3(0);
+  const [storedQuery, setQueryState] = useState6(initRef.current.q);
+  const query = useMemo6(() => opts.canonicalizeQuery?.(storedQuery) ?? storedQuery, [storedQuery, opts.canonicalizeQuery]);
+  const undoStack = useRef3([cloneQueryState(initRef.current.q)]);
+  const redoStack = useRef3([]);
+  const [rows, setRows] = useState6([]);
+  const [total, setTotal] = useState6(null);
+  const [loading, setLoading] = useState6(false);
+  const [error, setError] = useState6(null);
+  const [nonce, setNonce] = useState6(0);
+  const [autoRefreshStatus, setAutoRefreshStatus] = useState6(null);
+  useEffect4(() => {
     nowRef.current = now;
   }, [now]);
-  useEffect3(() => {
+  useEffect4(() => {
     onRefreshRef.current = opts.onRefresh;
   }, [opts.onRefresh]);
-  const setQuery = useCallback5((next) => {
+  const setQuery = useCallback6((next) => {
     setQueryState((prev) => {
       const candidate = typeof next === "function" ? next(prev) : next;
       const nextQuery = normalizeQueryState(candidate, defaults);
@@ -388,7 +839,7 @@ function useQueryTable(opts) {
       return cloneQueryState(nextQuery);
     });
   }, [defaults]);
-  useEffect3(() => {
+  useEffect4(() => {
     if (initRef.current.fromUrl || initialQuery) return;
     let cancelled = false;
     void (async () => {
@@ -405,19 +856,29 @@ function useQueryTable(opts) {
       cancelled = true;
     };
   }, []);
-  const queryKey = useMemo5(() => encodeQuery(query), [query]);
-  const serverRowQuery = useMemo5(() => toServerQuery(query, schema), [queryKey, schema]);
-  const rowQueryKey = useMemo5(
+  const { api: computed, displaySchema } = useComputedColumns({
+    schema,
+    query,
+    rows,
+    ...opts.computedColumnStore ? { store: opts.computedColumnStore } : {},
+    ...opts.formulaWorkerFactory ? { workerFactory: opts.formulaWorkerFactory } : {},
+    ...transport ? { transport } : {},
+    ...clientRows ? { clientRows } : {}
+  });
+  const queryKey = useMemo6(() => encodeQuery(query), [query]);
+  const serverRowQuery = useMemo6(() => toServerQuery2(query, displaySchema), [queryKey, displaySchema]);
+  const rowQueryKey = useMemo6(
     () => transport ? `server:${JSON.stringify(serverRowQuery)}` : `client:${JSON.stringify([query.where, query.orderBy, query.limit, query.offset])}`,
     [transport, serverRowQuery, query.where, query.orderBy, query.limit, query.offset]
   );
-  useEffect3(() => {
+  useEffect4(() => {
     const ac = new AbortController();
     let cancelled = false;
     const run = async () => {
       setLoading(true);
       setError(null);
       try {
+        opts.validateQuery?.(query);
         if (transport) {
           const res = await transport.fetchRows(serverRowQuery, ac.signal);
           if (!cancelled) {
@@ -425,14 +886,18 @@ function useQueryTable(opts) {
             setTotal(res.total);
           }
         } else {
-          const res = applyQuery(clientRows ?? [], query, schema);
+          const res = applyQuery2(clientRows ?? [], query, schema);
           if (!cancelled) {
             setRows(res.rows);
             setTotal(res.total);
           }
         }
       } catch (e) {
-        if (!cancelled && !ac.signal.aborted) setError(e);
+        if (!cancelled && !ac.signal.aborted) {
+          setError(e);
+          setRows([]);
+          setTotal(null);
+        }
       } finally {
         if (!cancelled) setLoading(false);
       }
@@ -443,8 +908,8 @@ function useQueryTable(opts) {
       clearTimeout(t);
       ac.abort();
     };
-  }, [rowQueryKey, transport, clientRows, schema, debounceMs, nonce]);
-  useEffect3(() => {
+  }, [rowQueryKey, transport, clientRows, schema, debounceMs, nonce, opts.validateQuery]);
+  useEffect4(() => {
     if (!syncUrl || typeof window === "undefined") return;
     const url = new URL(window.location.href);
     const token = encodeQuery(query);
@@ -452,18 +917,18 @@ function useQueryTable(opts) {
     else url.searchParams.delete("q");
     window.history.replaceState(null, "", url.toString());
   }, [queryKey, syncUrl, query]);
-  useEffect3(() => {
+  useEffect4(() => {
     const t = setTimeout(() => void storage.saveLast(schema.name, query), 400);
     return () => clearTimeout(t);
   }, [queryKey, storage, schema.name, query]);
-  const idField = useMemo5(() => schema.fields.find((f) => f.name === schema.idField), [schema]);
-  const rowId = useCallback5(
-    (row) => idField ? readFieldValue(idField, row) : null,
+  const idField = useMemo6(() => schema.fields.find((f) => f.name === schema.idField), [schema]);
+  const rowId = useCallback6(
+    (row) => idField ? readFieldValue2(idField, row) : null,
     [idField]
   );
-  const displayedIds = useMemo5(() => rows.map(rowId).filter((id) => id != null), [rows, rowId]);
+  const displayedIds = useMemo6(() => rows.map(rowId).filter((id) => id != null), [rows, rowId]);
   const selection = useSelection(displayedIds);
-  const select = useSelect(query, setQuery, schema);
+  const select = useSelect(query, setQuery, displaySchema);
   const columnDrag = useColumnDrag();
   const saved = useSavedQueries(
     schema.name,
@@ -472,10 +937,10 @@ function useQueryTable(opts) {
     storage,
     now
   );
-  const aggState = useAggregations(query, schema, transport, clientRows, debounceMs, nonce);
+  const aggState = useAggregations(query, schema, transport, clientRows, debounceMs, nonce, opts.validateQuery);
   const canUndo = undoStack.current.length > 0;
   const canRedo = redoStack.current.length > 0;
-  const undo = useCallback5(() => {
+  const undo = useCallback6(() => {
     setQueryState((prev) => {
       const previous = undoStack.current.pop();
       if (!previous) return prev;
@@ -483,7 +948,7 @@ function useQueryTable(opts) {
       return cloneQueryState(previous);
     });
   }, []);
-  const redo = useCallback5(() => {
+  const redo = useCallback6(() => {
     setQueryState((prev) => {
       const next = redoStack.current.pop();
       if (!next) return prev;
@@ -491,19 +956,95 @@ function useQueryTable(opts) {
       return cloneQueryState(next);
     });
   }, []);
-  const patch = useCallback5((p) => setQuery((prev) => ({ ...prev, ...p })), [setQuery]);
-  const addFilter = useCallback5((clause) => setQuery((q) => ({ ...q, offset: 0, where: [...q.where, clause] })), [setQuery]);
-  const updateFilter = useCallback5(
-    (index, clause) => setQuery((q) => ({ ...q, offset: 0, where: q.where.map((c, i) => i === index ? clause : c) })),
+  const patch = useCallback6((p) => setQuery((prev) => ({ ...prev, ...p })), [setQuery]);
+  const addFilter = useCallback6((clause) => setQuery((q) => ({ ...q, offset: 0, where: [...q.where, clause] })), [setQuery]);
+  const updateFilter = useCallback6(
+    (index, clause) => setQuery((q) => ({ ...q, offset: 0, where: q.where.map((t, i) => i === index ? clause : t) })),
     [setQuery]
   );
-  const removeFilter = useCallback5(
+  const removeFilter = useCallback6(
     (index) => setQuery((q) => ({ ...q, offset: 0, where: q.where.filter((_, i) => i !== index) })),
     [setQuery]
   );
-  const clearFilters = useCallback5(() => setQuery((q) => ({ ...q, offset: 0, where: [] })), [setQuery]);
-  const resetAll = useCallback5(() => setQuery(() => cloneQueryState(defaults)), [setQuery, defaults]);
-  const addAggregation = useCallback5(
+  const clearFilters = useCallback6(() => setQuery((q) => ({ ...q, offset: 0, where: [] })), [setQuery]);
+  const updatePredicate = useCallback6(
+    (termIndex, predIndex, clause) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      where: q.where.map((term, i) => {
+        if (i !== termIndex) return term;
+        if (isOrGroup(term)) return { any: term.any.map((c, j) => j === predIndex ? clause : c) };
+        return clause;
+      })
+    })),
+    [setQuery]
+  );
+  const removePredicate = useCallback6(
+    (termIndex, predIndex) => setQuery((q) => {
+      const where = [];
+      q.where.forEach((term, i) => {
+        if (i !== termIndex) {
+          where.push(term);
+          return;
+        }
+        if (isOrGroup(term)) {
+          const members = term.any.filter((_, j) => j !== predIndex);
+          if (members.length === 1) where.push(members[0]);
+          else if (members.length > 1) where.push({ any: members });
+          return;
+        }
+      });
+      return { ...q, offset: 0, where };
+    }),
+    [setQuery]
+  );
+  const negateOne = useCallback6(
+    (clause) => {
+      const field = byName.get(clause.field);
+      return negateClause(clause, field ? opsForField(field) : void 0);
+    },
+    [byName]
+  );
+  const negatePredicate = useCallback6(
+    (termIndex, predIndex) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      where: q.where.map((term, i) => {
+        if (i !== termIndex) return term;
+        if (isOrGroup(term)) return { any: term.any.map((c, j) => j === predIndex ? negateOne(c) : c) };
+        return negateOne(term);
+      })
+    })),
+    [setQuery, negateOne]
+  );
+  const reorderFilters = useCallback6(
+    (fromIndex, toIndex) => setQuery((q) => {
+      if (fromIndex < 0 || fromIndex >= q.where.length) return q;
+      const where = [...q.where];
+      const [moved] = where.splice(fromIndex, 1);
+      where.splice(Math.max(0, Math.min(toIndex, where.length)), 0, moved);
+      return { ...q, offset: 0, where };
+    }),
+    [setQuery]
+  );
+  const mergeFilters = useCallback6(
+    (sourceIndex, targetIndex) => setQuery((q) => {
+      if (sourceIndex === targetIndex) return q;
+      const source = q.where[sourceIndex];
+      const target = q.where[targetIndex];
+      if (!source || !target) return q;
+      const merged = { any: [...predicatesOf(target), ...predicatesOf(source)] };
+      const where = [];
+      q.where.forEach((term, i) => {
+        if (i === sourceIndex) return;
+        where.push(i === targetIndex ? merged : term);
+      });
+      return { ...q, offset: 0, where };
+    }),
+    [setQuery]
+  );
+  const resetAll = useCallback6(() => setQuery(() => cloneQueryState(defaults)), [setQuery, defaults]);
+  const addAggregation = useCallback6(
     (partial) => {
       const id = `a${nowRef.current()}-${aggIdRef.current++}`;
       const clause = { id, op: "count", groupBy: [], ...partial };
@@ -512,14 +1053,14 @@ function useQueryTable(opts) {
     },
     [setQuery]
   );
-  const updateAggregation = useCallback5(
+  const updateAggregation = useCallback6(
     (id, patch2) => setQuery((q) => ({
       ...q,
       aggregations: (q.aggregations ?? []).map((a) => a.id === id ? mergeAggregation(a, patch2) : a)
     })),
     [setQuery]
   );
-  const moveAggregation = useCallback5(
+  const moveAggregation = useCallback6(
     (id, toIndex) => setQuery((q) => {
       const current = q.aggregations ?? [];
       const from = current.findIndex((a) => a.id === id);
@@ -531,24 +1072,24 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const removeAggregation = useCallback5(
+  const removeAggregation = useCallback6(
     (id) => setQuery((q) => ({ ...q, aggregations: (q.aggregations ?? []).filter((a) => a.id !== id) })),
     [setQuery]
   );
-  const clearAggregations = useCallback5(
+  const clearAggregations = useCallback6(
     () => setQuery((q) => ({ ...q, aggregations: [] })),
     [setQuery]
   );
-  const setSort = useCallback5((orderBy) => setQuery((q) => ({ ...q, offset: 0, orderBy })), [setQuery]);
-  const toggleSort = useCallback5(
+  const setSort = useCallback6((orderBy) => setQuery((q) => ({ ...q, offset: 0, orderBy })), [setQuery]);
+  const toggleSort = useCallback6(
     (field, additive = false) => setQuery((q) => ({ ...q, offset: 0, orderBy: nextOrderBy(q.orderBy, field, additive) })),
     [setQuery]
   );
-  const setLimit = useCallback5((limit) => patch({ limit, offset: 0 }), [patch]);
-  const setOffset = useCallback5((offset) => patch({ offset }), [patch]);
-  const nextPage = useCallback5(() => setQuery((q) => ({ ...q, offset: q.offset + q.limit })), [setQuery]);
-  const prevPage = useCallback5(() => setQuery((q) => ({ ...q, offset: Math.max(0, q.offset - q.limit) })), [setQuery]);
-  const filterValues = useCallback5(
+  const setLimit = useCallback6((limit) => patch({ limit, offset: 0 }), [patch]);
+  const setOffset = useCallback6((offset) => patch({ offset }), [patch]);
+  const nextPage = useCallback6(() => setQuery((q) => ({ ...q, offset: q.offset + q.limit })), [setQuery]);
+  const prevPage = useCallback6(() => setQuery((q) => ({ ...q, offset: Math.max(0, q.offset - q.limit) })), [setQuery]);
+  const filterValues = useCallback6(
     async (field, search) => {
       if (!transport?.fetchDistinctValues) {
         const f = byName.get(field);
@@ -565,12 +1106,38 @@ function useQueryTable(opts) {
     },
     [transport, byName, clientRows]
   );
-  const refresh = useCallback5(() => {
+  const fieldStats = useCallback6(
+    async (fields, signal) => {
+      const requested = [...new Set(fields)];
+      if (transport?.fetchFieldStats) {
+        const backendFields = requested.filter(
+          (name) => byName.get(name)?.source.kind === "backend"
+        );
+        return backendFields.length ? transport.fetchFieldStats(backendFields, signal) : {};
+      }
+      if (!clientRows) return {};
+      const result = {};
+      for (const name of requested) {
+        if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+        const field = byName.get(name);
+        if (!field) continue;
+        const distinct = /* @__PURE__ */ new Set();
+        for (const row of clientRows) {
+          const value = readFieldValue2(field, row);
+          if (value !== null) distinct.add(JSON.stringify(value));
+        }
+        result[name] = { distinct: distinct.size };
+      }
+      return result;
+    },
+    [transport, byName, clientRows]
+  );
+  const refresh = useCallback6(() => {
     setNonce((n) => n + 1);
     onRefreshRef.current?.();
   }, []);
-  const stopAutoRefresh = useCallback5(() => setAutoRefreshStatus(null), []);
-  const startAutoRefresh = useCallback5(
+  const stopAutoRefresh = useCallback6(() => setAutoRefreshStatus(null), []);
+  const startAutoRefresh = useCallback6(
     ({ frequencyMs, turnOffAfterMs }) => {
       const pollCount = frequencyMs > 0 && turnOffAfterMs > 0 ? Math.floor(turnOffAfterMs / frequencyMs) : 0;
       if (pollCount < 1 || pollCount > MAX_AUTO_REFRESH_POLLS) {
@@ -590,7 +1157,7 @@ function useQueryTable(opts) {
   );
   const autoRefreshFrequencyMs = autoRefreshStatus?.frequencyMs ?? null;
   const autoRefreshStopsAt = autoRefreshStatus?.stopsAt ?? null;
-  useEffect3(() => {
+  useEffect4(() => {
     if (autoRefreshFrequencyMs == null || autoRefreshStopsAt == null) return;
     const tick = () => {
       if (nowRef.current() >= autoRefreshStopsAt) {
@@ -614,7 +1181,7 @@ function useQueryTable(opts) {
       clearTimeout(timeout);
     };
   }, [autoRefreshFrequencyMs, autoRefreshStopsAt, refresh]);
-  const autoRefresh = useMemo5(
+  const autoRefresh = useMemo6(
     () => ({
       status: autoRefreshStatus,
       start: startAutoRefresh,
@@ -622,7 +1189,7 @@ function useQueryTable(opts) {
     }),
     [autoRefreshStatus, startAutoRefresh, stopAutoRefresh]
   );
-  const refreshRow = useCallback5(
+  const refreshRow = useCallback6(
     async (id) => {
       if (!transport?.fetchRow) return;
       const updated = await transport.fetchRow(id);
@@ -630,8 +1197,8 @@ function useQueryTable(opts) {
     },
     [transport, rowId]
   );
-  const visibleFields = useMemo5(() => selectedFields2(schema, query), [schema, query]);
-  const aggregations = useMemo5(
+  const visibleFields = useMemo6(() => selectedFields2(displaySchema, query), [displaySchema, query]);
+  const aggregations = useMemo6(
     () => ({
       clauses: query.aggregations ?? [],
       results: aggState.results,
@@ -675,11 +1242,18 @@ function useQueryTable(opts) {
     updateFilter,
     removeFilter,
     clearFilters,
+    updatePredicate,
+    removePredicate,
+    negatePredicate,
+    reorderFilters,
+    mergeFilters,
     resetAll,
     filterValues,
+    fieldStats,
     toggleSort,
     setSort,
     select,
+    computed,
     setLimit,
     setOffset,
     nextPage,
@@ -696,7 +1270,7 @@ function nextOrderBy(existing, field, additive) {
   if (!additive) {
     if (i === 0 && existing.length === 1) {
       const flipped = existing[0].dir === "desc" ? "asc" : "desc";
-      return [{ field, dir: flipped }];
+      return [{ ...existing[0], dir: flipped }];
     }
     return [{ field, dir: "desc" }];
   }
@@ -704,12 +1278,14 @@ function nextOrderBy(existing, field, additive) {
   const cur = existing[i];
   if (cur.dir === "desc") {
     const next = [...existing];
-    next[i] = { field, dir: "asc" };
+    next[i] = { ...cur, dir: "asc" };
     return next;
   }
   return existing.filter((_, k) => k !== i);
 }
 export {
+  createFormulaWorker,
+  evaluateFormulaRows,
   useAggregations,
   useColumnDrag,
   useQueryTable,