@uwdata/mosaic-core 0.17.0 → 0.19.0

package/src/SelectionClause.ts

@@ -0,0 +1,357 @@
+import { isMosaicClient, MosaicClient } from './MosaicClient.js';
+import { type ExprNode, type ExprValue, type ScaleOptions, type ScaleDomain, and, contains, isBetween, isIn, isNotDistinct, literal, or, prefix, regexp_matches, suffix, listHasAny, listHasAll, lower } from '@uwdata/mosaic-sql';
+
+/**
+ * Selection clause metadata to guide possible query optimizations.
+ * Sub-interfaces provide more information about the specifics of a
+ * given selection based on the selection type.
+ */
+export interface ClauseMetadata {
+  /**
+   * The selection type, such as `'point'`, `'interval'`, or `'match'`.
+   */
+  type: string;
+}
+
+/**
+ * Selection clause metadata indicating selection of one or more discrete
+ * point values, typically based on equality or is distinctiveness checks.
+ */
+export interface PointMetadata extends ClauseMetadata {
+  type: 'point';
+}
+
+/**
+ * Selection clause metadata indicating text search matching.
+ */
+export interface MatchMetadata extends ClauseMetadata {
+  type: 'match';
+  /** The text search matching method used. */
+  method?: 'contains' | 'prefix' | 'suffix' | 'regexp' | (string & {});
+}
+
+/** A binning method name. */
+export type BinMethod = 'floor' | 'ceil' | 'round';
+
+/**
+ * Selection clause metadata for one or more selected intervals. This
+ * metadata can be used to determine appropriate data-space binning
+ * schemes that correspond to pixel-level bins in screen space.
+ */
+export interface IntervalMetadata extends ClauseMetadata {
+  type: 'interval';
+  /**
+   * The interactive pixel size used by the generating component.
+   * Values larger than one indicate intervals that "snap-to" values
+   * greater than a single pixel. If unspecified, assumed to be `1`.
+   */
+  pixelSize?: number;
+  /**
+   * An array of one or more scale descriptors that describe the
+   * mapping from data values to screen pixels.
+   */
+  scales?: ScaleOptions[];
+  /**
+   * A hint for the binning method to use when discretizing the
+   * interval domain. If unspecified, the default is `'floor'`.
+   */
+  bin?: BinMethod
+}
+
+export type ClauseSource = object & { reset?: () => void; };
+
+/**
+ * A selection clause representing filtering criteria
+ * to apply within a Mosaic Selection.
+ */
+export interface SelectionClause {
+  /**
+   * A unique identifier (according to object equality) for the source
+   * component that generated this clause. In many cases, this is a
+   * reference to the originating component itself.
+   */
+  source: ClauseSource;
+  /**
+   * A set of Mosaic clients associated with this clause that should not
+   * be updated when this clause is applied in a cross-filtering context.
+   */
+  clients?: Set<MosaicClient>;
+  /**
+   * A selected value associated with this clause. For example, for a 1D
+   * interval selection clause the value may be a [lo, hi] array.
+   */
+  value: unknown;
+  /**
+   * A predicate SQL expression suitable for use in a query WHERE clause.
+   * The predicate should apply filtering criteria consistent with this
+   * clause's *value* property.
+   */
+  predicate: ExprNode | null;
+  /**
+   * Optional clause metadata that varies based on the selection type.
+   * The metadata can be used to optimize selection queries, for example
+   * by creating materialized views of pre-aggregated data when applicable.
+   */
+  meta?: ClauseMetadata;
+}
+
+interface PointOptions {
+  source: ClauseSource;
+  clients?: Set<MosaicClient>;
+}
+
+/**
+ * Generate a selection clause for a single selected point value.
+ * @param field The table column or expression to select.
+ * @param value The selected value.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns The generated selection clause.
+ */
+export function clausePoint(
+  field: ExprValue,
+  value: unknown, {
+    source,
+    clients = isMosaicClient(source) ? new Set([source]) : undefined
+  }: PointOptions
+): SelectionClause {
+  const predicate: ExprNode | null = 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 fields The table columns or expressions to select.
+ * @param value The selected values, as an array of
+ *  arrays. Each subarray contains values for each *fields* entry.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns The generated selection clause.
+ */
+export function clausePoints(
+  fields: ExprValue[],
+  value: unknown[][] | null | undefined,
+  {
+    source,
+    clients = isMosaicClient(source) ? new Set([source]) : undefined
+  }: PointOptions
+): SelectionClause {
+  let predicate: ExprNode | null = null;
+  if (value?.length) {
+    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
+  };
+}
+
+/** Interval selection clause options. */
+interface IntervalOptions {
+  source: ClauseSource;
+  clients?: Set<MosaicClient>;
+  bin?: BinMethod;
+  pixelSize?: number;
+}
+
+/**
+ * Generate a selection clause for a selected 1D interval.
+ * @param field The table column or expression to select.
+ * @param value The selected interval as a [lo, hi] array.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param options.scale The scale mapping descriptor.
+ * @param options.bin A binning method hint.
+ * @param options.pixelSize The interactive pixel size.
+ * @returns The generated selection clause.
+ */
+export function clauseInterval(
+  field: ExprValue,
+  value: ScaleDomain | null | undefined,
+  {
+    source,
+    clients = isMosaicClient(source) ? new Set([source]) : undefined,
+    bin,
+    scale,
+    pixelSize = 1
+  }: IntervalOptions & { scale?: ScaleOptions }
+): SelectionClause {
+  const predicate = value != null ? isBetween(field, value) : null;
+  const meta: IntervalMetadata = {
+    type: 'interval',
+    scales: scale && [scale],
+    bin,
+    pixelSize
+  };
+  return { meta, source, clients, value, predicate };
+}
+
+/**
+ * Generate a selection clause for multiple selected intervals.
+ * @param fields The table columns or expressions to select.
+ * @param value The selected intervals, as an array of extents.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param options.scales The scale mapping descriptors,
+ *  in an order matching the given *fields* and *value* extents.
+ * @param options.bin A binning method hint.
+ * @param options.pixelSize The interactive pixel size.
+ * @returns The generated selection clause.
+ */
+export function clauseIntervals(
+  fields: ExprValue[],
+  value: ScaleDomain[] | null | undefined,
+  {
+    source,
+    clients = isMosaicClient(source) ? new Set([source]) : undefined,
+    bin,
+    scales = [],
+    pixelSize = 1
+  }: IntervalOptions & { scales?: ScaleOptions[] }
+): SelectionClause {
+  const predicate = value != null
+    ? and(fields.map((f, i) => isBetween(f, value[i])))
+    : null;
+  const meta: IntervalMetadata = {
+    type: 'interval',
+    scales,
+    bin,
+    pixelSize
+  };
+  return { meta, source, clients, value, predicate };
+}
+
+const identity = (x: string | ExprNode) => x;
+
+const MATCH_METHODS = { contains, prefix, suffix, regexp: regexp_matches };
+
+/** Text search matching methods. */
+export type MatchMethod = keyof typeof MATCH_METHODS;
+
+/** Text matching selection clause options. */
+export interface MatchOptions {
+  source: ClauseSource;
+  clients?: Set<MosaicClient>;
+  method?: MatchMethod;
+  caseSensitive?: boolean;
+}
+
+/**
+ * Generate a selection clause for text search matching over a single column.
+ * @param field The table column or expression to match.
+ * @param value The selected text search query string.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients Mosaic clients associated with this clause.
+ *  These clients are not filtered by this clause in cross-filtering contexts.
+ * @param options.method The text matching method to use, default `'contains'`.
+ * @param options.caseSensitive Flag for case sensitive matching, default `false`.
+ * @returns The generated selection clause.
+ */
+export function clauseMatch(
+  field: string | ExprNode,
+  value: string | null | undefined,
+  {
+    source,
+    clients = undefined,
+    method = 'contains',
+    caseSensitive = false
+  }: MatchOptions
+): SelectionClause {
+  const fn = MATCH_METHODS[method as keyof typeof MATCH_METHODS];
+  const transform = caseSensitive ? identity: lower;
+  const predicate = value ? fn(transform(field), transform(literal(value))) : null;
+  const meta: MatchMetadata = { type: 'match', method };
+  return { meta, source, clients, value, predicate };
+}
+
+/**
+ * Generate a selection clause for text search matching over multiple columns.
+ * A match will succeed if any field successfully matches.
+ * @param fields The table columns or expressions to match.
+ * @param value The selected text search query string.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients Mosaic clients associated with this clause.
+ *  These clients are not filtered by this clause in cross-filtering contexts.
+ * @param options.method The text matching method to use, default `'contains'`.
+ * @param options.caseSensitive Flag for case sensitive matching, default `false`.
+ * @returns The generated selection clause.
+ */
+export function clauseMatchAny(
+  fields: (string | ExprNode)[],
+  value: string | null,
+  {
+    source,
+    clients = undefined,
+    method = 'contains',
+    caseSensitive = false
+  }: MatchOptions
+): SelectionClause {
+  value = value || null;
+  const fn = MATCH_METHODS[method];
+  const transform = caseSensitive ? identity : lower;
+  const query = transform(literal(value));
+  const predicate = value
+    ? or(fields.flatMap(field => value ? fn(transform(field), query) : []))
+    : null;
+  const meta: MatchMetadata = { type: 'match', method };
+  return { meta, source, clients, value, predicate };
+}
+
+/**
+ * Generate a selection clause for a single selected point value in a list.
+ * @param field The table column or expression to select, which must be a list.
+ * @param value The selected value.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns The generated selection clause.
+ */
+export function clauseList(
+  field: ExprValue,
+  value: unknown,
+  {
+    source,
+    clients = isMosaicClient(source) ? new Set([source]) : undefined,
+    listMatch = 'any'
+  }: {
+    source: ClauseSource;
+    clients?: Set<MosaicClient>;
+    listMatch?: 'any' | 'all';
+  }
+): SelectionClause {
+  const listFn = listMatch === 'all' ? listHasAll : listHasAny;
+  const predicate = value !== undefined ? listFn(field, literal(value)) : null;
+  return { source, clients, value, predicate };
+}

package/src/connectors/Connector.ts

@@ -1,23 +1,23 @@
 import type { Table } from '@uwdata/flechette';
 
-export interface QueryRequest {
+export interface ConnectorQueryRequest {
   /** The query type. */
   type?: string;
   /** A SQL query string. */
   sql: string;
 }
 
-export interface ArrowQueryRequest extends QueryRequest {
+export interface ArrowQueryRequest extends ConnectorQueryRequest {
   /** The query type. */
   type?: 'arrow';
 }
 
-export interface ExecQueryRequest extends QueryRequest {
+export interface ExecQueryRequest extends ConnectorQueryRequest {
   /** The query type. */
   type: 'exec';
 }
 
-export interface JSONQueryRequest extends QueryRequest {
+export interface JSONQueryRequest extends ConnectorQueryRequest {
   /** The query type. */
   type: 'json';
 }
@@ -26,5 +26,5 @@ export interface Connector {
   /** Issue a query and return the result. */
   query(query: ArrowQueryRequest): Promise<Table>;
   query(query: ExecQueryRequest): Promise<void>;
-  query(query: JSONQueryRequest): Promise<Record<string, any>[]>;
-}
+  query(query: JSONQueryRequest): Promise<Record<string, unknown>[]>;
+}

package/src/connectors/rest.ts

@@ -0,0 +1,56 @@
+import type { ExtractionOptions, Table } from '@uwdata/flechette';
+import type { ArrowQueryRequest, Connector, ExecQueryRequest, JSONQueryRequest, ConnectorQueryRequest } from './Connector.js';
+import { decodeIPC } from '../util/decode-ipc.js';
+
+interface RestOptions {
+  uri?: string;
+  ipc?: ExtractionOptions;
+}
+
+/**
+ * Connect to a DuckDB server over an HTTP REST interface.
+ * @param options Connector options.
+ * @param options.uri The URI for the DuckDB REST server.
+ * @param options.ipc Arrow IPC extraction options.
+ * @returns A connector instance.
+ */
+export function restConnector(options?: RestOptions) {
+  return new RestConnector(options);
+}
+
+export class RestConnector implements Connector {
+  private _uri: string;
+  private _ipc?: ExtractionOptions;
+
+  constructor({
+    uri = 'http://localhost:3000/',
+    ipc = undefined
+  }: RestOptions = {}) {
+    this._uri = uri;
+    this._ipc = ipc;
+  }
+
+  async query(query: ArrowQueryRequest): Promise<Table>;
+  async query(query: ExecQueryRequest): Promise<void>;
+  async query(query: JSONQueryRequest): Promise<Record<string, unknown>[]>;
+  async query(query: ConnectorQueryRequest): Promise<unknown> {
+    const req = fetch(this._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(), this._ipc)
+      : res.json();
+  }
+}

package/src/connectors/{socket.js → socket.ts}

@@ -1,38 +1,56 @@
-/** @import { ExtractionOptions, Table } from '@uwdata/flechette' */
-/** @import { ArrowQueryRequest, Connector, ExecQueryRequest, JSONQueryRequest } from './Connector.js' */
+import type { ExtractionOptions, Table } from '@uwdata/flechette';
+import type { ArrowQueryRequest, Connector, ExecQueryRequest, JSONQueryRequest, ConnectorQueryRequest } from './Connector.js';
 import { decodeIPC } from '../util/decode-ipc.js';
 
+interface SocketOptions {
+  uri?: string;
+  ipc?: ExtractionOptions;
+}
+
+interface QueueItem<T = unknown> {
+  query: ConnectorQueryRequest;
+  resolve: (value?: T) => void;
+  reject: (reason?: unknown) => void;
+}
+
 /**
  * Connect to a DuckDB server over a WebSocket 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 {SocketConnector} A connector instance.
+ * @param options Connector options.
+ * @param options.uri The URI for the DuckDB REST server.
+ * @param options.ipc Arrow IPC extraction options.
+ * @returns A connector instance.
  */
-export function socketConnector(options) {
+export function socketConnector(options?: SocketOptions) {
   return new SocketConnector(options);
 }
 
 /**
  * DuckDB socket connector.
- * @implements {Connector}
  */
-export class SocketConnector {
+export class SocketConnector implements Connector {
+  private _uri: string;
+  private _queue: QueueItem[];
+  private _connected: boolean;
+  private _request: QueueItem | null;
+  private _ws: WebSocket | null;
+  private _events: Record<string, (event?: unknown) => void>;
+
   /**
-   * @param {object} [options] Connector options.
-   * @param {string} [options.uri] The URI for the DuckDB REST server.
-   * @param {ExtractionOptions} [options.ipc] Arrow IPC extraction options.
+   * @param options Connector options.
+   * @param options.uri The URI for the DuckDB REST server.
+   * @param options.ipc Arrow IPC extraction options.
    */
   constructor({
     uri = 'ws://localhost:3000/',
     ipc = undefined,
-  } = {}) {
+  }: SocketOptions = {}) {
     this._uri = uri;
     this._queue = [];
     this._connected = false;
     this._request = null;
     this._ws = null;
 
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     const c = this;
     this._events = {
       open() {
@@ -45,11 +63,11 @@ export class SocketConnector {
         c._request = null;
         c._ws = null;
         while (c._queue.length) {
-          c._queue.shift().reject('Socket closed');
+          c._queue.shift()!.reject('Socket closed');
         }
       },
 
-      error(event) {
+      error(event: unknown) {
         if (c._request) {
           const { reject } = c._request;
           c._request = null;
@@ -60,7 +78,8 @@ export class SocketConnector {
         }
       },
 
-      message({ data }) {
+      message(msg: unknown) {
+        const { data } = msg as { data: unknown };
         if (c._request) {
           const { query, resolve, reject } = c._request;
 
@@ -71,11 +90,12 @@ export class SocketConnector {
           // process result
           if (typeof data === 'string') {
             const json = JSON.parse(data);
+            // eslint-disable-next-line @typescript-eslint/no-unused-expressions
             json.error ? reject(json.error) : resolve(json);
           } else if (query.type === 'exec') {
             resolve();
           } else if (query.type === 'arrow') {
-            resolve(decodeIPC(data, ipc));
+            resolve(decodeIPC(data as Uint8Array, ipc));
           } else {
             throw new Error(`Unexpected socket data: ${data}`);
           }
@@ -83,14 +103,14 @@ export class SocketConnector {
           console.log('WebSocket message: ', data);
         }
       }
-    }
+    };
   }
 
-  get connected() {
+  get connected(): boolean {
     return this._connected;
   }
 
-  init() {
+  init(): void {
     this._ws = new WebSocket(this._uri);
     this._ws.binaryType = 'arraybuffer';
     for (const type in this._events) {
@@ -98,38 +118,29 @@ export class SocketConnector {
     }
   }
 
-  enqueue(query, resolve, reject) {
+  enqueue(
+    query: ConnectorQueryRequest,
+    resolve: (value?: unknown) => void,
+    reject: (reason?: unknown) => void
+  ): void {
     if (this._ws == null) this.init();
     this._queue.push({ query, resolve, reject });
     if (this._connected && !this._request) this.next();
   }
 
-  next() {
+  next(): void {
     if (this._queue.length) {
-      this._request = this._queue.shift();
-      this._ws.send(JSON.stringify(this._request.query));
+      this._request = this._queue.shift()!;
+      this._ws!.send(JSON.stringify(this._request.query));
     }
   }
 
-  /**
-   * @overload
-   * @param {ArrowQueryRequest} query
-   * @returns {Promise<Table>}
-   *
-   * @overload
-   * @param {ExecQueryRequest} query
-   * @returns {Promise<void>}
-   *
-   * @overload
-   * @param {JSONQueryRequest} query
-   * @returns {Promise<Record<string, any>[]>}
-   *
-   * @param {ArrowQueryRequest | ExecQueryRequest | JSONQueryRequest} query
-   * @returns {Promise<Table | void | Record<string, any>[]>}}
-   */
-  query(query) {
+  query(query: ArrowQueryRequest): Promise<Table>;
+  query(query: ExecQueryRequest): Promise<void>;
+  query(query: JSONQueryRequest): Promise<Record<string, unknown>[]>;
+  query(query: ConnectorQueryRequest): Promise<unknown> {
     return new Promise(
       (resolve, reject) => this.enqueue(query, resolve, reject)
     );
   }
-}
+}