@uwdata/mosaic-core 0.17.0 → 0.18.0

package/src/Selection.js

@@ -1,380 +0,0 @@
-/**
- * @import { MosaicClient } from './MosaicClient.js'
- * @import { SelectionClause } from './util/selection-types.js'
- */
-import { literal, or } from '@uwdata/mosaic-sql';
-import { Param } from './Param.js';
-
-/**
- * Test if a value is a Selection instance.
- * @param {*} x The value to test.
- * @returns {x is Selection} True if the input is a Selection, false otherwise.
- */
-export function isSelection(x) {
-  return x instanceof Selection;
-}
-
-function create(options, include) {
-  return new Selection(
-    new SelectionResolver(options),
-    include ? [include].flat() : include
-  );
-}
-
-/**
- * Represents a dynamic set of query filter predicates.
- */
-export class Selection extends Param {
-
-  /**
-   * Create a new Selection instance with an
-   * intersect (conjunction) resolution strategy.
-   * @param {object} [options] The selection options.
-   * @param {boolean} [options.cross=false] Boolean flag indicating
-   *  cross-filtered resolution. If true, selection clauses will not
-   *  be applied to the clients they are associated with.
-   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
-   *  of clauses should correspond to an empty selection with no records. This
-   *  setting determines the default selection state.
-   * @param {Selection|Selection[]} [options.include] Upstream selections whose
-   *  clauses should be included as part of the new selection. Any clauses
-   *  published to upstream selections will be relayed to the new selection.
-   * @returns {Selection} The new Selection instance.
-   */
-  static intersect({ cross = false, empty = false, include = [] } = {}) {
-    return create({ cross, empty }, include);
-  }
-
-  /**
-   * Create a new Selection instance with a
-   * union (disjunction) resolution strategy.
-   * @param {object} [options] The selection options.
-   * @param {boolean} [options.cross=false] Boolean flag indicating
-   *  cross-filtered resolution. If true, selection clauses will not
-   *  be applied to the clients they are associated with.
-   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
-   *  of clauses should correspond to an empty selection with no records. This
-   *  setting determines the default selection state.
-   * @param {Selection|Selection[]} [options.include] Upstream selections whose
-   *  clauses should be included as part of the new selection. Any clauses
-   *  published to upstream selections will be relayed to the new selection.
-   * @returns {Selection} The new Selection instance.
-   */
-  static union({ cross = false, empty = false, include = [] } = {}) {
-    return create({ cross, empty, union: true }, include);
-  }
-
-  /**
-   * Create a new Selection instance with a singular resolution strategy
-   * that keeps only the most recent selection clause.
-   * @param {object} [options] The selection options.
-   * @param {boolean} [options.cross=false] Boolean flag indicating
-   *  cross-filtered resolution. If true, selection clauses will not
-   *  be applied to the clients they are associated with.
-   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
-   *  of clauses should correspond to an empty selection with no records. This
-   *  setting determines the default selection state.
-   * @param {Selection|Selection[]} [options.include] Upstream selections whose
-   *  clauses should be included as part of the new selection. Any clauses
-   *  published to upstream selections will be relayed to the new selection.
-   * @returns {Selection} The new Selection instance.
-   */
-  static single({ cross = false, empty = false, include = [] } = {}) {
-    return create({ cross, empty, single: true }, include);
-  }
-
-  /**
-   * Create a new Selection instance with a
-   * cross-filtered intersect resolution strategy.
-   * @param {object} [options] The selection options.
-   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
-   *  of clauses should correspond to an empty selection with no records. This
-   *  setting determines the default selection state.
-   * @param {Selection|Selection[]} [options.include] Upstream selections whose
-   *  clauses should be included as part of the new selection. Any clauses
-   *  published to upstream selections will be relayed to the new selection.
-   * @returns {Selection} The new Selection instance.
-   */
-  static crossfilter({ empty = false, include = [] } = {}) {
-    return create({ cross: true, empty }, include);
-  }
-
-  /**
-   * Create a new Selection instance.
-   * @param {SelectionResolver} [resolver] The selection resolution
-   *  strategy to apply.
-   * @param {Selection[]} [include] Upstream selections whose clauses
-   * should be included as part of this selection. Any clauses published
-   * to these upstream selections will be relayed to this selection.
-   */
-  constructor(resolver = new SelectionResolver(), include = []) {
-    super([]);
-    this._resolved = this._value;
-    this._resolver = resolver;
-    /** @type {Set<Selection>} */
-    this._relay = new Set;
-    if (Array.isArray(include)) {
-      for (const sel of include) {
-        sel._relay.add(this);
-      }
-    }
-  }
-
-  /**
-   * Create a cloned copy of this Selection instance.
-   * @returns {Selection} A clone of this selection.
-   */
-  clone() {
-    const s = new Selection(this._resolver);
-    s._value = s._resolved = this._value;
-    return s;
-  }
-
-  /**
-   * Create a clone of this Selection with clauses corresponding
-   * to the provided source removed.
-   * @param {*} source The clause source to remove.
-   * @returns {Selection} A cloned and updated Selection.
-   */
-  remove(source) {
-    const s = this.clone();
-    s._value = s._resolved = s._resolver.resolve(this._resolved, { source });
-    s._value.active = { source };
-    return s;
-  }
-
-  /**
-   * The selection clause resolver.
-   */
-  get resolver() {
-    return this._resolver;
-  }
-
-  /**
-   * Indicate if this selection has a single resolution strategy.
-   */
-  get single() {
-    return this._resolver.single;
-  }
-
-  /**
-   * The current array of selection clauses.
-   */
-  get clauses() {
-    return super.value;
-  }
-
-  /**
-   * The current active (most recently updated) selection clause.
-   */
-  get active() {
-    return this.clauses.active;
-  }
-
-  /**
-   * The value corresponding to the current active selection clause.
-   * This method ensures compatibility where a normal Param is expected.
-   */
-  get value() {
-    return this.active?.value;
-  }
-
-  /**
-   * The value corresponding to a given source. Returns undefined if
-   * this selection does not include a clause from this source.
-   * @param {*} source The clause source to look up the value for.
-   */
-  valueFor(source) {
-    return this.clauses.find(c => c.source === source)?.value;
-  }
-
-  /**
-   * Emit an activate event with the given selection clause.
-   * @param {SelectionClause} clause The clause repesenting the potential activation.
-   */
-  activate(clause) {
-    this.emit('activate', clause);
-    this._relay.forEach(sel => sel.activate(clause));
-  }
-
-  /**
-   * Update the selection with a new selection clause.
-   * @param {SelectionClause} clause The selection clause to add.
-   * @returns {this} This Selection instance.
-   */
-  update(clause) {
-    // we maintain an up-to-date list of all resolved clauses
-    // this ensures consistent clause state across unemitted event values
-    this._resolved = this._resolver.resolve(this._resolved, clause, true);
-    this._resolved.active = clause;
-    this._relay.forEach(sel => sel.update(clause));
-    return super.update(this._resolved);
-  }
-
-  /**
-   * Reset the selection state by removing all provided clauses. If no clause
-   * array is provided as an argument, all current clauses are removed. The
-   * reset method (if defined) is invoked on all corresponding clause sources.
-   * The reset is relayed to downstream selections that include this selection.
-   * @param {SelectionClause[]} [clauses] The clauses to remove. If
-   *  unspecified, all current clauses are removed.
-   * @returns {this} This selection instance.
-   */
-  reset(clauses) {
-    clauses ??= this._resolved;
-    clauses.forEach(c => c.source?.reset?.());
-    this._resolved = this._resolved.filter(c => clauses.includes(c));
-    this._relay.forEach(sel => sel.reset(clauses));
-    return super.update(this._resolved = []);
-  }
-
-  /**
-   * Upon value-typed updates, sets the current clause list to the
-   * input value and returns the active clause value.
-   * @param {string} type The event type.
-   * @param {*} value The input event value.
-   * @returns {*} For value-typed events, returns the active clause
-   *  values. Otherwise returns the input event value as-is.
-   */
-  willEmit(type, value) {
-    if (type === 'value') {
-      this._value = value;
-      return this.value;
-    }
-    return value;
-  }
-
-  /**
-   * Upon value-typed updates, returns a dispatch queue filter function.
-   * The return value depends on the selection resolution strategy.
-   * @param {string} type The event type.
-   * @param {*} value The new event value that will be enqueued.
-   * @returns {(value: *) => boolean|null} For value-typed events,
-   *  returns a dispatch queue filter function. Otherwise returns null.
-   */
-  emitQueueFilter(type, value) {
-    return type === 'value'
-      ? this._resolver.queueFilter(value)
-      : null;
-  }
-
-  /**
-   * Indicates if a selection clause should not be applied to a given client.
-   * The return value depends on the selection resolution strategy.
-   * @param {*} client The selection clause.
-   * @param {*} clause The client to test.
-   * @returns True if the client should be skipped, false otherwise.
-   */
-  skip(client, clause) {
-    return this._resolver.skip(client, clause);
-  }
-
-  /**
-   * Return a selection query predicate for the given client.
-   * @param {*} client The client whose data may be filtered.
-   * @param {boolean} [noSkip=false] Disable skipping of active
-   *  cross-filtered sources. If set true, the source of the active
-   *  clause in a cross-filtered selection will not be skipped.
-   * @returns {*} The query predicate for filtering client data,
-   *  based on the current state of this selection.
-   */
-  predicate(client, noSkip = false) {
-    const { clauses } = this;
-    const active = noSkip ? null : clauses.active;
-    return this._resolver.predicate(clauses, active, client);
-  }
-}
-
-/**
- * Implements selection clause resolution strategies.
- */
-export class SelectionResolver {
-
-  /**
-   * Create a new selection resolved instance.
-   * @param {object} [options] The resolution strategy options.
-   * @param {boolean} [options.union=false] Boolean flag to indicate a union strategy.
-   *  If false, an intersection strategy is used.
-   * @param {boolean} [options.cross=false] Boolean flag to indicate cross-filtering.
-   * @param {boolean} [options.single=false] Boolean flag to indicate single clauses only.
-   * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
-   *  of clauses should correspond to an empty selection with no records. This
-   *  setting determines the default selection state.
-   */
-  constructor({ union, cross, single, empty } = {}) {
-    this.union = !!union;
-    this.cross = !!cross;
-    this.single = !!single;
-    this.empty = !!empty;
-  }
-
-  /**
-   * Resolve a list of selection clauses according to the resolution strategy.
-   * @param {*[]} clauseList An array of selection clauses.
-   * @param {*} clause A new selection clause to add.
-   * @returns {*[]} An updated array of selection clauses.
-   */
-  resolve(clauseList, clause, reset = false) {
-    const { source, predicate } = clause;
-    const filtered = clauseList.filter(c => source !== c.source);
-    const clauses = this.single ? [] : filtered;
-    if (this.single && reset) filtered.forEach(c => c.source?.reset?.());
-    if (predicate) clauses.push(clause);
-    return clauses;
-  }
-
-  /**
-   * Indicates if a selection clause should not be applied to a given client.
-   * The return value depends on the resolution strategy.
-   * @param {*} client The selection clause.
-   * @param {*} clause The client to test.
-   * @returns True if the client should be skipped, false otherwise.
-   */
-  skip(client, clause) {
-    return this.cross && clause?.clients?.has(client);
-  }
-
-  /**
-   * Return a selection query predicate for the given client.
-   * @param {import('./util/selection-types.js').SelectionClause[]} clauseList
-   *  An array of selection clauses.
-   * @param {import('./util/selection-types.js').SelectionClause} active
-   *  The current active selection clause.
-   * @param {MosaicClient} client The client whose data may be filtered.
-   * @returns {*} The query predicate for filtering client data,
-   *  based on the current state of this selection.
-   */
-  predicate(clauseList, active, client) {
-    const { empty, union } = this;
-
-    if (empty && !clauseList.length) {
-      return [literal(false)];
-    }
-
-    // do nothing if cross-filtering and client is currently active
-    if (this.skip(client, active)) return undefined;
-
-    // remove client-specific predicates if cross-filtering
-    const predicates = clauseList
-      .filter(clause => !this.skip(client, clause))
-      .map(clause => clause.predicate);
-
-    // return appropriate conjunction or disjunction
-    // an array of predicates is implicitly conjunctive
-    return union && predicates.length > 1 ? or(predicates) : predicates;
-  }
-
-  /**
-   * Returns a filter function for queued selection updates.
-   * @param {*} value The new event value that will be enqueued.
-   * @returns {(value: *) => boolean|null} A dispatch queue filter
-   *  function, or null if all unemitted event values should be filtered.
-   */
-  queueFilter(value) {
-    if (this.cross) {
-      const source = value.active?.source;
-      return clauses => clauses.active?.source !== source;
-    }
-    return null;
-  }
-}

package/src/SelectionClause.js

@@ -1,159 +0,0 @@
-/**
- * @import { ExprNode } from '@uwdata/mosaic-sql'
- * @import { MosaicClient } from './MosaicClient.js'
- */
-import { and, contains, isBetween, isIn, isNotDistinct, literal, or, prefix, regexp_matches, suffix } from '@uwdata/mosaic-sql';
-
-/**
- * @typedef {import('./util/selection-types.js').SelectionClause} SelectionClause
- * @typedef {import('./util/selection-types.js').Scale} Scale
- * @typedef {import('./util/selection-types.js').Extent} Extent
- * @typedef {import('./util/selection-types.js').MatchMethod} MatchMethod
- * @typedef {import('./util/selection-types.js').BinMethod} BinMethod
- */
-
-/**
- * Generate a selection clause for a single selected point value.
- * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {*} value The selected value.
- * @param {object} options Additional clause properties.
- * @param {*} options.source The source component generating this clause.
- * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
- *  with this clause. These clients are not filtered by this clause in
- *  cross-filtering contexts.
- * @returns {SelectionClause} The generated selection clause.
- */
-export function clausePoint(field, value, {
-  source,
-  clients = source ? new Set([source]) : undefined
-}) {
-  /** @type {ExprNode | null} */
-  const predicate = value !== undefined
-    ? isIn(field, [literal(value)])
-    : null;
-  return {
-    meta: { type: 'point' },
-    source,
-    clients,
-    value,
-    predicate
-  };
-}
-
-/**
- * Generate a selection clause for multiple selected point values.
- * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {any[][] | null | undefined} value The selected values, as an array of
- *  arrays. Each subarray contains values for each *fields* entry.
- * @param {object} options Additional clause properties.
- * @param {*} options.source The source component generating this clause.
- * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
- *  with this clause. These clients are not filtered by this clause in
- *  cross-filtering contexts.
- * @returns {SelectionClause} The generated selection clause.
- */
-export function clausePoints(fields, value, {
-  source,
-  clients = source ? new Set([source]) : undefined
-}) {
-  /** @type {ExprNode | null} */
-  let predicate = null;
-  if (value) {
-    const clauses = value.length && fields.length === 1
-      ? [isIn(fields[0], value.map(v => literal(v[0])))]
-      : value.map(v => and(v.map((_, i) => isNotDistinct(fields[i], literal(_)))));
-    predicate = value.length === 0 ? literal(false)
-      : clauses.length > 1 ? or(clauses)
-      : clauses[0];
-  }
-  return {
-    meta: { type: 'point' },
-    source,
-    clients,
-    value,
-    predicate
-  };
-}
-
-/**
- * Generate a selection clause for a selected 1D interval.
- * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {Extent | null | undefined} value The selected interval as a [lo, hi] array.
- * @param {object} options Additional clause properties.
- * @param {*} options.source The source component generating this clause.
- * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
- *  with this clause. These clients are not filtered by this clause in
- *  cross-filtering contexts.
- * @param {Scale} [options.scale] The scale mapping descriptor.
- * @param {BinMethod} [options.bin] A binning method hint.
- * @param {number} [options.pixelSize=1] The interactive pixel size.
- * @returns {SelectionClause} The generated selection clause.
- */
-export function clauseInterval(field, value, {
-  source,
-  clients = source ? new Set([source]) : undefined,
-  bin,
-  scale,
-  pixelSize = 1
-}) {
-  const predicate = value != null ? isBetween(field, value) : null;
-  /** @type {import('./util/selection-types.js').IntervalMetadata} */
-  const meta = { type: 'interval', scales: scale && [scale], bin, pixelSize };
-  return { meta, source, clients, value, predicate };
-}
-
-/**
- * Generate a selection clause for multiple selected intervals.
- * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {Extent[] | null | undefined} value The selected intervals, as an array of extents.
- * @param {object} options Additional clause properties.
- * @param {*} options.source The source component generating this clause.
- * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
- *  with this clause. These clients are not filtered by this clause in
- *  cross-filtering contexts.
- * @param {Scale[]} [options.scales] The scale mapping descriptors,
- *  in an order matching the given *fields* and *value* extents.
- * @param {BinMethod} [options.bin] A binning method hint.
- * @param {number} [options.pixelSize=1] The interactive pixel size.
- * @returns {SelectionClause} The generated selection clause.
- */
-export function clauseIntervals(fields, value, {
-  source,
-  clients = source ? new Set([source]) : undefined,
-  bin,
-  scales = [],
-  pixelSize = 1
-}) {
-  const predicate = value != null
-    ? and(fields.map((f, i) => isBetween(f, value[i])))
-    : null;
-  /** @type {import('./util/selection-types.js').IntervalMetadata} */
-  const meta = { type: 'interval', scales, bin, pixelSize };
-  return { meta, source, clients, value, predicate };
-}
-
-const MATCH_METHODS = { contains, prefix, suffix, regexp: regexp_matches };
-
-/**
- * Generate a selection clause for text search matching.
- * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {string | null | undefined} value The selected text search query string.
- * @param {object} options Additional clause properties.
- * @param {*} options.source The source component generating this clause.
- * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
- *  with this clause. These clients are not filtered by this clause in
- *  cross-filtering contexts.
- * @param {MatchMethod} [options.method] The
- *  text matching method to use. Defaults to `'contains'`.
- * @returns {SelectionClause} The generated selection clause.
- */
-export function clauseMatch(field, value, {
-  source, clients = undefined, method = 'contains'
-}) {
-  let fn = MATCH_METHODS[method];
-  /** @type {ExprNode | null} */
-  const predicate = value ? fn(field, literal(value)) : null;
-  /** @type {import('./util/selection-types.js').MatchMetadata} */
-  const meta = { type: 'match', method };
-  return { meta, source, clients, value, predicate };
-}

package/src/connectors/rest.js

@@ -1,38 +0,0 @@
-/** @import { ExtractionOptions } from '@uwdata/flechette' */
-/** @import { Connector } from './Connector.js' */
-import { decodeIPC } from '../util/decode-ipc.js';
-
-/**
- * Connect to a DuckDB server over an HTTP REST interface.
- * @param {object} [options] Connector options.
- * @param {string} [options.uri] The URI for the DuckDB REST server.
- * @param {ExtractionOptions} [options.ipc] Arrow IPC extraction options.
- * @returns {Connector} A connector instance.
- */
-export function restConnector({
-  uri = 'http://localhost:3000/',
-  ipc = undefined,
-} = {}) {
-  return {
-    async query(query) {
-      const req = fetch(uri, {
-        method: 'POST',
-        mode: 'cors',
-        cache: 'no-cache',
-        credentials: 'omit',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(query)
-      });
-
-      const res = await req;
-
-      if (!res.ok) {
-        throw new Error(`Query failed with HTTP status ${res.status}: ${await res.text()}`);
-      }
-
-      return query.type === 'exec' ? req
-        : query.type === 'arrow' ? decodeIPC(await res.arrayBuffer(), ipc)
-        : res.json();
-    }
-  };
-}

package/src/index-types.ts

@@ -1,5 +0,0 @@
-export * from './index.js';
-export * from './types.js';
-export * from './connectors/Connector.js';
-export * from './util/selection-types.js';
-export {QueryResult} from './util/query-result.js';

package/src/make-client.js

@@ -1,101 +0,0 @@
-/** @import { Coordinator } from './Coordinator.js' */
-/** @import { Selection } from './Selection.js' */
-import { MosaicClient } from './MosaicClient.js';
-import { coordinator as defaultCoordinator } from './Coordinator.js';
-
-/**
- * @typedef {Object} MakeClientOptions
- * @property {Coordinator} [coordinator] Mosaic coordinator.
- *  Defaults to the global coordinator.
- * @property {Selection|null} [selection] A selection whose predicates are
- *  fed into the query function to produce the SQL query.
- * @property {boolean} [enabled] A flag (default `true`) indicating if the
- *  client should initially be enabled or not.
- * @property {boolean} [filterStable] A flag (default `true`) indicating if the
- *  if client queries can be sped up using pre-aggregated data. Should be set
- *  to `false` if filtering changes the groupby domain of the query.
- * @property {function(): Promise<void>} [prepare]
- *  An async function to prepare the client before running queries.
- * @property {function(any): any} [query]
- *  A function that returns a query from a list of selection predicates.
- * @property {function(any): void} [queryResult]
- *  Called by the coordinator to return a query result.
- * @property {function(): void} [queryPending]
- *  Called by the coordinator to report a query execution error.
- * @property {function(any): void} [queryError]
- *  Called by the coordinator to inform the client that a query is pending.
- */
-
-/**
- * Make a new client with the given options, and connect the client to the
- * provided coordinator.
- * @param {MakeClientOptions} options The options for making the client.
- * @returns {MosaicClient & { destroy: () => void }} The resulting client,
- *  along with a method to destroy the client when no longer needed.
- */
-export function makeClient(options) {
-  const {
-    coordinator = defaultCoordinator(),
-    ...clientOptions
-  } = options;
-  const client = new ProxyClient(clientOptions);
-  coordinator.connect(client);
-  return client;
-}
-
-/**
- * An internal class used to implement the makeClient API.
- */
-class ProxyClient extends MosaicClient {
-  /**
-   * @param {MakeClientOptions} options The options for making the client.
-   */
-  constructor({
-    selection = undefined,
-    enabled = true,
-    filterStable = true,
-    ...methods
-  }) {
-    super(selection);
-    this.enabled = enabled;
-
-    /**
-     * @type {MakeClientOptions}
-     * @readonly
-     */
-    this._methods = methods;
-
-    /**
-     * @type {boolean}
-     * @readonly
-     */
-    this._filterStable = filterStable;
-  }
-
-  get filterStable() {
-    return this._filterStable;
-  }
-
-  async prepare() {
-    await this._methods.prepare?.();
-  }
-
-  query(filter) {
-    return this._methods.query?.(filter) ?? null;
-  }
-
-  queryResult(data) {
-    this._methods.queryResult?.(data);
-    return this;
-  }
-
-  queryPending() {
-    this._methods.queryPending?.();
-    return this;
-  }
-
-  queryError(error) {
-    this._methods.queryError?.(error);
-    return this;
-  }
-}

package/src/util/is-activatable.js

@@ -1,8 +0,0 @@
-/**
- * Test if a value implements the Activatable interface.
- * @param {*} value The value to test.
- * @returns {value is import('../types.js').Activatable}
- */
-export function isActivatable(value) {
-  return typeof value?.activate === 'function' && value.activate.length === 0;
-}