@fjader/svelte 0.2.2 → 0.2.4

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,49 @@ 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;
+    /**
+     * Re-read the dim into the field's value array, mutating in place.
+     *
+     * Re-reading the whole dim rather than only the new rows: categorical
+     * cardinality is small, this runs once per (field, table) pair at setup, and
+     * a full read cannot drift out of sync with the ids the way an incremental
+     * one can if an append is ever missed.
+     */
+    /**
+     * Bumped whenever a dim's rows change: a table folding in, an Other bucket
+     * reserved, a reset. A query that reads a dim (dense padding, an id join)
+     * returns different rows afterwards under the same SQL text, so whatever
+     * caches results by that text must also key on this. Only ever increases.
+     */
+    get version(): number;
     /**
      * 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,