@fjader/svelte 0.2.2 → 0.2.3

package/dist/query-engine/QueryEngine.d.ts

@@ -3,8 +3,9 @@
  * mark registration for batch filter-driven re-queries.
  *
  * The mark layer's only interface to DuckDB. All query execution goes through
- * queryEngine.query(sql, opts) for ad-hoc queries, or registerMark() +
- * onFilterChange() for the reactive registration path.
+ * queryEngine.query(sql, opts) for ad-hoc queries, or registerMark() for the
+ * reactive registration path: FilterGroup calls onClauseChange() when one
+ * clause changes, and onFilterChange() when all of a group's do (clearAll).
  *
  * v1: Direct execution (await connection.query(sql))
  * v2: Cancel-on-supersede — keyed on callerId, drops stale in-flight queries.
@@ -22,8 +23,9 @@ import { type QueryParts } from '../components/marks/lifecycle/query-builder';
 import type { ActivationSource } from './preagg/plan';
 export type { ActiveDim, ActivationSource } from './preagg/plan';
 import { MarkHandle } from './MarkHandle.svelte';
-import { type DimValue, type FieldIdentity, type IdentityField } from './categorical-identity';
+import { type DimValue, type FieldIdentity, type IdentityField, type SyntheticId } from './categorical-identity';
 import type { FilterGroup } from './FilterGroup.svelte';
+import { type Clause, type MarkRoute } from './CrossfilterSelection.svelte';
 import type { TransformCompiler } from '../transforms/TransformCompiler';
 export interface QueryOpts {
     /** Caller identifier for cancel-on-supersede. When a new query arrives
@@ -82,6 +84,8 @@ export interface QueryDescriptor {
     parts: QueryParts;
     schema: Map<string, ColumnSchema>;
     transformCompiler: TransformCompiler;
+    /** What routing needs to know about the mark. Absent in tests that route nothing. */
+    route?: MarkRoute;
 }
 export declare class QueryEngine {
     #private;
@@ -127,27 +131,40 @@ export declare class QueryEngine {
      */
     dimTableFor(field: string): string;
     /**
-     * Dim values for `field`, indexed by id — the decode side of the string -> id
-     * encode. Not display labels: formatting belongs to the scale/axis layer.
+     * The field's categories as of now, in id order, without the synthetic Other
+     * buckets: a bucket is not a category of the data, and another chart's bucket
+     * must not appear on an axis, a facet or a colour legend that has none.
      *
-     * The LIVE array — hold the reference, do not snapshot it. A second table
-     * registering the same field appends to the dim afterwards and this array
-     * grows in place.
+     * With `table`, only the categories that table holds: the dim spans every
+     * table registering the field, and an axis over one table must not show a
+     * slot for a category only another has. Without it (a scale shared per field,
+     * like ordinal colour), every category of the dim.
+     *
+     * A snapshot, not the live array: for decoding ids, hold `identityFor(field)`.
+     */
+    categoryValues(field: string, table?: string): DimValue[];
+    /**
+     * The table of ids `table` holds for `field`, for `dense()` to pad from, or
+     * null before the table has folded into the field's dim.
      */
-    identityValues(field: string): DimValue[];
+    presentTableFor(field: string, table: string): string | null;
     /**
      * The field's id <-> value bijection. One live object owning both
      * directions, so a holder cannot end up with a value array and a reverse map
-     * that disagree. Prefer this over identityValues() anywhere the reverse
+     * that disagree. Prefer this over categoryValues() anywhere the reverse
      * direction is needed; do not rebuild it locally.
      */
     identityFor(field: string): FieldIdentity;
+    /** The field's current bijection, or null; never creates one (see CategoricalIdentity). */
+    peekIdentity(field: string): FieldIdentity | null;
     /**
-     * Reserve an id for a value present in no table — the synthetic "Other"
-     * bucket from `topN({ includeOthers })`. Call after ensureColumns.
-     * Returns an existing id when a real category already carries the label.
+     * Acquire an id for a value present in no table — the synthetic "Other"
+     * bucket from `topN({ includeOthers })` — with the label it displays. Call
+     * after ensureColumns; release it when its holder goes.
      */
-    reserveSyntheticIdentity(field: string, label: string): Promise<number>;
+    acquireSyntheticIdentity(field: string, label: string): Promise<SyntheticId>;
+    /** Give back an id from `acquireSyntheticIdentity`, for the next acquire to reuse. */
+    releaseSyntheticIdentity(synthetic: SyntheticId): void;
     /**
      * Subscribe to identity resets. Returns an unsubscribe function.
      *
@@ -234,10 +251,29 @@ export declare class QueryEngine {
     /** When a filter last changed, in any group, for settling (performance.now()). */
     get lastFilterChangeAt(): number;
     /**
-     * Called by FilterGroup when any filter clause changes.
-     * Iterates registered marks for this group and batch-queries them.
+     * Called by FilterGroup when its clauses change wholesale (clearAll):
+     * re-queries every mark in the group.
      */
     onFilterChange(group: FilterGroup): void;
+    /**
+     * Called by FilterGroup when the clause of `sourceId` changes: `prev` is the
+     * clause it replaced or removed, `next` the one now in force (null when
+     * removed).
+     *
+     * Re-queries only the group's marks that either one filters. A mark neither
+     * filters has the same SQL as before, so querying it would only assemble that
+     * SQL to find the cached result, on every brush frame. A mark that reads the
+     * clause's categorical field dims by it instead, and a mark in a chart that
+     * skips the source is not filtered by it: neither is re-queried.
+     */
+    onClauseChange(group: FilterGroup, sourceId: string, prev: Clause | undefined, next: Clause | null): void;
+    /**
+     * Called by FilterGroup when a registration that skips `chart` comes or
+     * goes while its source has a clause: re-queries the group's marks in that
+     * chart, whose filters may have changed. A mark whose SQL did not change
+     * stops at the cache and the same-Table guard.
+     */
+    onChartRouteChange(group: FilterGroup, chart: object): void;
     /**
      * Pre-aggregate marks for a filter group before a source is used: builds a
      * preagg table per mark the source filters (see Preagg.activate). Called

package/dist/query-engine/QueryEngine.js

@@ -3,8 +3,9 @@
  * mark registration for batch filter-driven re-queries.
  *
  * The mark layer's only interface to DuckDB. All query execution goes through
- * queryEngine.query(sql, opts) for ad-hoc queries, or registerMark() +
- * onFilterChange() for the reactive registration path.
+ * queryEngine.query(sql, opts) for ad-hoc queries, or registerMark() for the
+ * reactive registration path: FilterGroup calls onClauseChange() when one
+ * clause changes, and onFilterChange() when all of a group's do (clearAll).
  *
  * v1: Direct execution (await connection.query(sql))
  * v2: Cancel-on-supersede — keyed on callerId, drops stale in-flight queries.
@@ -21,6 +22,7 @@ import { assembleQuery, castNumeric, splitWindowSelect } from '../components/mar
 import { Preagg } from './preagg/Preagg';
 import { MarkHandle } from './MarkHandle.svelte';
 import { CategoricalIdentity } from './categorical-identity';
+import { NO_ROUTE } from './CrossfilterSelection.svelte';
 /**
  * How long a queued build waits behind mark queries before it is sent anyway,
  * by default. During a drag on the base table a mark query is always waiting
@@ -197,32 +199,64 @@ export class QueryEngine {
         return this.#identity.dimTable(field);
     }
     /**
-     * Dim values for `field`, indexed by id — the decode side of the string -> id
-     * encode. Not display labels: formatting belongs to the scale/axis layer.
+     * The field's categories as of now, in id order, without the synthetic Other
+     * buckets: a bucket is not a category of the data, and another chart's bucket
+     * must not appear on an axis, a facet or a colour legend that has none.
      *
-     * The LIVE array — hold the reference, do not snapshot it. A second table
-     * registering the same field appends to the dim afterwards and this array
-     * grows in place.
+     * With `table`, only the categories that table holds: the dim spans every
+     * table registering the field, and an axis over one table must not show a
+     * slot for a category only another has. Without it (a scale shared per field,
+     * like ordinal colour), every category of the dim.
+     *
+     * A snapshot, not the live array: for decoding ids, hold `identityFor(field)`.
      */
-    identityValues(field) {
-        return this.#identity.values(field);
+    categoryValues(field, table) {
+        const identity = this.#identity.identity(field);
+        const values = identity.values;
+        const present = table ? this.#identity.presentIds(field, table) : null;
+        if (identity.synthetic.size === 0 && !present)
+            return values.slice();
+        const out = [];
+        for (let id = 0; id < values.length; id++) {
+            if (identity.synthetic.has(id))
+                continue;
+            if (present && !present.has(id))
+                continue;
+            out.push(values[id]);
+        }
+        return out;
+    }
+    /**
+     * The table of ids `table` holds for `field`, for `dense()` to pad from, or
+     * null before the table has folded into the field's dim.
+     */
+    presentTableFor(field, table) {
+        return this.#identity.presentTable(field, table);
     }
     /**
      * The field's id <-> value bijection. One live object owning both
      * directions, so a holder cannot end up with a value array and a reverse map
-     * that disagree. Prefer this over identityValues() anywhere the reverse
+     * that disagree. Prefer this over categoryValues() anywhere the reverse
      * direction is needed; do not rebuild it locally.
      */
     identityFor(field) {
         return this.#identity.identity(field);
     }
+    /** The field's current bijection, or null; never creates one (see CategoricalIdentity). */
+    peekIdentity(field) {
+        return this.#identity.peekIdentity(field);
+    }
     /**
-     * Reserve an id for a value present in no table — the synthetic "Other"
-     * bucket from `topN({ includeOthers })`. Call after ensureColumns.
-     * Returns an existing id when a real category already carries the label.
+     * Acquire an id for a value present in no table — the synthetic "Other"
+     * bucket from `topN({ includeOthers })` — with the label it displays. Call
+     * after ensureColumns; release it when its holder goes.
      */
-    reserveSyntheticIdentity(field, label) {
-        return this.#identity.reserveSynthetic(field, label);
+    acquireSyntheticIdentity(field, label) {
+        return this.#identity.acquireSynthetic(field, label);
+    }
+    /** Give back an id from `acquireSyntheticIdentity`, for the next acquire to reuse. */
+    releaseSyntheticIdentity(synthetic) {
+        this.#identity.releaseSynthetic(synthetic);
     }
     /**
      * Subscribe to identity resets. Returns an unsubscribe function.
@@ -559,27 +593,55 @@ export class QueryEngine {
         return this.#lastFilterChangeAt;
     }
     /**
-     * Called by FilterGroup when any filter clause changes.
-     * Iterates registered marks for this group and batch-queries them.
+     * Called by FilterGroup when its clauses change wholesale (clearAll):
+     * re-queries every mark in the group.
      */
     onFilterChange(group) {
         this.#lastFilterChangeAt = performance.now();
-        const batch = [];
         for (const [markId, reg] of this.#marks) {
-            if (reg.filterGroup === group) {
-                batch.push([markId, reg]);
-            }
+            if (reg.filterGroup === group)
+                this.#queryMark(markId, reg);
         }
-        if (batch.length > 0) {
-            this.#executeBatch(batch);
+    }
+    /**
+     * Called by FilterGroup when the clause of `sourceId` changes: `prev` is the
+     * clause it replaced or removed, `next` the one now in force (null when
+     * removed).
+     *
+     * Re-queries only the group's marks that either one filters. A mark neither
+     * filters has the same SQL as before, so querying it would only assemble that
+     * SQL to find the cached result, on every brush frame. A mark that reads the
+     * clause's categorical field dims by it instead, and a mark in a chart that
+     * skips the source is not filtered by it: neither is re-queried.
+     */
+    onClauseChange(group, sourceId, prev, next) {
+        this.#lastFilterChangeAt = performance.now();
+        const { selection } = group;
+        for (const [markId, reg] of this.#marks) {
+            if (reg.filterGroup !== group)
+                continue;
+            const route = reg.descriptor.route ?? NO_ROUTE;
+            if ((prev && selection.applies(sourceId, prev, route)) ||
+                (next && selection.applies(sourceId, next, route))) {
+                this.#queryMark(markId, reg);
+            }
         }
     }
-    #executeBatch(batch) {
-        for (const [markId, reg] of batch)
-            this.#queryMark(markId, reg);
+    /**
+     * Called by FilterGroup when a registration that skips `chart` comes or
+     * goes while its source has a clause: re-queries the group's marks in that
+     * chart, whose filters may have changed. A mark whose SQL did not change
+     * stops at the cache and the same-Table guard.
+     */
+    onChartRouteChange(group, chart) {
+        for (const [markId, reg] of this.#marks) {
+            if (reg.filterGroup === group && reg.descriptor.route?.chart === chart) {
+                this.#queryMark(markId, reg);
+            }
+        }
     }
     /**
-     * Query a single mark: on a filter change (via #executeBatch) or a params
+     * Query a single mark: on a filter change or a params
      * change (via _onParamsChange). Reads a preagg table when one answers; if
      * that read fails, the table is set aside and the base table is queried once.
      */
@@ -611,7 +673,7 @@ export class QueryEngine {
     /** The query a mark runs on its base table, applying every clause. */
     #baseSQL(markId, reg) {
         const { descriptor, handle } = reg;
-        return this.#assembleSQL(descriptor, descriptor.table, reg.filterGroup.selection.predicate(markId), handle.params);
+        return this.#assembleSQL(descriptor, descriptor.table, reg.filterGroup.selection.predicate(reg.descriptor.route ?? NO_ROUTE), handle.params);
     }
     /**
      * Assemble SQL from a query descriptor + filter + per-mark params.

package/dist/query-engine/categorical-identity.d.ts

@@ -11,14 +11,16 @@
  *    later tables APPEND unseen values with continuing ids. It never reorders and
  *    never renumbers, so an id already baked into a vertex buffer stays valid and
  *    no earlier mark has to requery. `value` carries the source column's own type
- *    and `label` is NULL, except on a synthetic row (`reserveSynthetic`), where
- *    that is inverted.
+ *    and `label` is NULL, except on a synthetic row (`acquireSynthetic`), where
+ *    that is inverted, and on the NULL category's row, where both are NULL.
  *
  * 2. A **per-table view**, `<table>_v_s<session>`, selecting `*` plus one
  *    `__dplot_<field>_idx` column per requested field. Always LEFT JOIN with
  *    COALESCE(-1): an inner join silently drops rows whose value is not in the
- *    dim (NULLs, values added later), which is data loss presenting as a
- *    rendering bug. -1 is the unmapped sentinel, unified in `1ac4fd4`.
+ *    dim (a value a later append will add), which is data loss presenting as a
+ *    rendering bug. -1 is the unmapped sentinel, unified in `1ac4fd4`. A NULL
+ *    value is not unmapped: the dim has a row for it (value NULL, label NULL),
+ *    joined with IS NOT DISTINCT FROM, so NULL is a category like any other.
  *
  * 3. An **additive coalescer**, `ensureColumns()`. Concurrent callers union into
  *    a pending set, one CREATE OR REPLACE VIEW runs with the full union, and a
@@ -41,6 +43,18 @@
  * the series scale all read the same columns from the same dim, and none of
  * them is special-cased here.
  */
+/**
+ * A synthetic id handed out by `acquireSynthetic`: what to release it with.
+ * `generation` ties it to the dims it was acquired from, so a release after a
+ * reset does not offer a dropped row to the next acquire.
+ */
+export interface SyntheticId {
+    readonly field: string;
+    readonly id: number;
+    /** The label it displays: the requested one, or `"<label> (rest)"` beside a real one. */
+    readonly label: string;
+    readonly generation: number;
+}
 /** The subset of QueryEngine this module needs. Keeps it testable in isolation. */
 export interface IdentityExec {
     exec(sql: string | string[]): Promise<void>;
@@ -89,7 +103,15 @@ export interface IdentityField {
  * (SameValueZero, which covers bigint). That is why the round trip is correct
  * today; it is the declared types that were wrong.
  */
-export type DimValue = string | number | bigint;
+export type DimValue = string | number | bigint | null;
+/**
+ * How a category value is shown: as itself, except the NULL category, which has
+ * no text of its own. The one formatter for axis ticks, legend entries, facet
+ * labels and tooltips, so NULL reads the same everywhere. Selections keep the
+ * raw `null`: this is display only.
+ */
+export declare const NULL_CATEGORY_LABEL = "(null)";
+export declare function categoryLabel<T>(value: T): T | string;
 /**
  * A field's id <-> value bijection, both directions in one object.
  *
@@ -105,11 +127,32 @@ export type DimValue = string | number | bigint;
  * once and stay correct when a second table appends to the dim.
  */
 export declare class FieldIdentity {
-    /** id -> source value. Dense and 0-based, so position is the id. */
+    /**
+     * id -> source value. Dense and 0-based, so position is the id. A synthetic
+     * id (an Other bucket) holds its display label here.
+     */
     readonly values: DimValue[];
-    /** source value -> id. The exact inverse of `values`. */
+    /**
+     * source value -> id, for real values only: the inverse of `values` with the
+     * synthetic ids left out. A label is not a value, and several synthetic ids
+     * may share one, so nothing resolves a bucket by its label.
+     */
     readonly ids: Map<DimValue, number>;
-    constructor(values?: readonly DimValue[]);
+    /** The synthetic ids (Other buckets): rows of the dim no source row joins to. */
+    readonly synthetic: Set<number>;
+    /**
+     * The NULL category's id, or null while the data has no NULL. An ordinary
+     * category: ranked, drawn, selectable; `values[nullId]` is `null`, and `ids`
+     * maps `null` to it, so value lookups need no special case.
+     */
+    nullId: number | null;
+    /**
+     * The identity key this is the bijection for, as `identityKeyFor` derives
+     * it: what a scale that adopted it is keyed by for selection activity.
+     * Empty for one built outside the engine, as tests do.
+     */
+    readonly key: string;
+    constructor(values?: readonly DimValue[], key?: string);
     /**
      * Bumped by `reset`, so a holder of this LIVE object can tell whether it
      * moved since it last looked. Appends, a same-length replacement and an
@@ -117,16 +160,21 @@ export declare class FieldIdentity {
      * comparing `values.length` is not.
      */
     version: number;
-    /** Replace both directions. The only writer. */
-    reset(values: readonly DimValue[]): void;
+    /**
+     * Replace both directions. The only writer. `synthetic` names the ids that
+     * are buckets rather than values: they keep their label in `values` and stay
+     * out of `ids`.
+     */
+    reset(values: readonly DimValue[], synthetic?: Iterable<number>): void;
     /** True once the dim has been built and holds at least one value. */
     get present(): boolean;
 }
 /**
- * Above this many distinct values a band axis is refused outright.
- * The shared slot buffer holds 16384 floats across every band and point scale,
- * so a single axis this large cannot render whatever else is on the page — the
- * limit is capacity, not taste.
+ * Above this many distinct values a band axis is refused outright. The shared
+ * slot buffer (IDENTITY_SLOT_CAPACITY floats) holds every band and point
+ * scale's slots and every selected field's activity, one run per filter group,
+ * so an axis this large would crowd out the rest of the page — the limit is
+ * capacity, not taste.
  */
 export declare const MAX_IDENTITY_CARDINALITY = 10000;
 /**
@@ -148,9 +196,9 @@ export declare class CategoricalIdentity {
     /** SQL producing `field`'s value, once a mark has registered it; undefined before. */
     sqlFor(field: string): string | undefined;
     /**
-     * Whether `field`'s dim has folded in `table`, so every non-NULL value the
-     * table holds has an id and `-1` can only mean NULL. A dim another table
-     * built may lack this table's values; a refused dim covers nothing.
+     * Whether `field`'s dim has folded in `table`, so every value the table holds,
+     * NULL included, has an id and `-1` never appears. A dim another table built
+     * may lack this table's values; a refused dim covers nothing.
      */
     dimCovers(field: string, table: string): boolean;
     /** The field whose id column is `column`, or null if no dim has that column. */
@@ -159,6 +207,14 @@ export declare class CategoricalIdentity {
     viewHas(table: string, field: string): boolean;
     /** Name of the dim table for `field`. */
     dimTable(field: string): string;
+    /**
+     * The table of ids `table` holds for `field`, or null before that table has
+     * folded into the dim. What `dense()` pads from, so a chart never pads a
+     * category only another table has.
+     */
+    presentTable(field: string, table: string): string | null;
+    /** The ids `table` holds for `field`, or null before that table has folded in. */
+    presentIds(field: string, table: string): ReadonlySet<number> | null;
     /** Name of the view that carries id columns for `table`. */
     viewTable(table: string): string;
     /**
@@ -188,6 +244,12 @@ export declare class CategoricalIdentity {
      * it before the dim exists.
      */
     identity(field: string): FieldIdentity;
+    /**
+     * The field's current bijection, or null if nothing has asked for it since
+     * the last reset. Unlike `identity`, never creates one: for a holder checking
+     * whether the identity it applied is still the live one, on every frame.
+     */
+    peekIdentity(field: string): FieldIdentity | null;
     /** Fields the view for `table` currently exposes. Empty when there is no view. */
     columnsFor(table: string): string[];
     /**
@@ -200,24 +262,34 @@ export declare class CategoricalIdentity {
         categorical?: (string | IdentityField)[];
     }): Promise<void>;
     /**
-     * Reserve an id for a value that exists in no table — the synthetic "Other"
-     * bucket a `topN({ includeOthers })` produces.
+     * Acquire an id for a value that exists in no table — the synthetic "Other"
+     * bucket a `topN({ includeOthers })` produces — and return it with the label
+     * it displays.
+     *
+     * A released id with the same label is reused before a dim row is inserted,
+     * so remounting a chart does not grow the dim or the field's activity block.
+     * Keyed by label too, so a reused id never needs relabelling.
      *
-     * Goes through the same writer as every other id, so `values(f)[otherId]` is
-     * the label and no consumer has to know it was synthetic. Serialized on the
-     * per-field chain, so it cannot interleave with an append.
+     * Goes through the same writer as every other id, so `values(f)[id]` is the
+     * label; `synthetic` records that it is a bucket, which keeps it out of the
+     * value -> id map. Serialized on the per-field chain, so it cannot interleave
+     * with an append.
      *
      * Non-negative by construction: `scaleBand` discards `value < 0.0` before the
      * slot lookup, so a negative sentinel could never render.
      *
-     * **Reuses the id if a real category already carries this label**, rather
-     * than inserting a duplicate value — see the fan-out note above. Callers get
-     * an id that may already be in the data, which the transform has to fold
-     * into rather than append beside.
+     * **A real category carrying the label stays a category.** The bucket takes
+     * `"<label> (rest)"` instead, so two bars never share a label and the real
+     * one stays selectable. The check runs at acquire; a reload re-acquires.
      *
      * Requires the dim to exist: call after `ensureColumns` has resolved.
      */
-    reserveSynthetic(field: string, label: string): Promise<number>;
+    acquireSynthetic(field: string, label: string): Promise<SyntheticId>;
+    /**
+     * Give an acquired id back for the next acquire of the same label. One from
+     * before a reset names a row of a dropped dim, and is ignored.
+     */
+    releaseSynthetic(synthetic: SyntheticId): void;
     /**
      * Drop every view and dim and forget all state. Called on data reload, where
      * the ids are stale by definition — the same values may not exist any more,