@uwdata/mosaic-core 0.18.0 → 0.19.1

package/src/SelectionClause.ts

@@ -1,6 +1,5 @@
-
 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 } from '@uwdata/mosaic-sql';
+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.
@@ -26,7 +25,7 @@ export interface PointMetadata extends ClauseMetadata {
  * Selection clause metadata indicating text search matching.
  */
 export interface MatchMetadata extends ClauseMetadata {
-  type: MatchMethod;
+  type: 'match';
   /** The text search matching method used. */
   method?: 'contains' | 'prefix' | 'suffix' | 'regexp' | (string & {});
 }
@@ -59,9 +58,7 @@ export interface IntervalMetadata extends ClauseMetadata {
   bin?: BinMethod
 }
 
-export interface ClauseSource {
-  reset?: () => void;
-}
+export type ClauseSource = object & { reset?: () => void; };
 
 /**
  * A selection clause representing filtering criteria
@@ -98,6 +95,11 @@ export interface SelectionClause {
   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.
@@ -109,13 +111,13 @@ export interface SelectionClause {
  *  cross-filtering contexts.
  * @returns The generated selection clause.
  */
-export function clausePoint(field: ExprValue, value: unknown, {
-  source,
-  clients = isMosaicClient(source) ? new Set([source]) : undefined
-}: {
-  source: ClauseSource;
-  clients?: Set<MosaicClient>;
-}): SelectionClause {
+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;
@@ -140,15 +142,16 @@ export function clausePoint(field: ExprValue, value: unknown, {
  *  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
-}: {
-  source: ClauseSource;
-  clients?: Set<MosaicClient>;
-}): SelectionClause {
+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) {
+  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(_)))));
@@ -165,6 +168,14 @@ export function clausePoints(fields: ExprValue[], value: unknown[][] | null | un
   };
 }
 
+/** 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.
@@ -179,19 +190,17 @@ export function clausePoints(fields: ExprValue[], value: unknown[][] | null | un
  * @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
-}: {
-  source: ClauseSource;
-  clients?: Set<MosaicClient>;
-  scale?: ScaleOptions;
-  bin?: BinMethod;
-  pixelSize?: number;
-}): SelectionClause {
+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',
@@ -217,19 +226,17 @@ export function clauseInterval(field: ExprValue, value: ScaleDomain | null | und
  * @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
-}: {
-  source: ClauseSource;
-  clients?: Set<MosaicClient>;
-  scales?: ScaleOptions[];
-  bin?: BinMethod;
-  pixelSize?: number;
-}): SelectionClause {
+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;
@@ -242,34 +249,109 @@ export function clauseIntervals(fields: ExprValue[], value: ScaleDomain[] | null
   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 | (string & {});
+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.
- * @param field The table column or expression to select.
+ * 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 The 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. Defaults to `'contains'`.
+ * @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: ExprValue, value: string | null | undefined, {
-  source,
-  clients = undefined,
-  method = 'contains'
-}: {
-  source: ClauseSource;
-  clients?: Set<MosaicClient>;
-  method?: MatchMethod;
-}): SelectionClause {
+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 predicate: ExprNode | null = value ? fn(field, literal(value)) : null;
+  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/wasm.ts

@@ -15,6 +15,8 @@ interface DuckDBWASMConnectorOptions extends DuckDBWASMOptions {
   duckdb?: duckdb.AsyncDuckDB;
   /** Optional pre-existing DuckDB-WASM connection. */
   connection?: duckdb.AsyncDuckDBConnection;
+  /** Optional database config. */
+  config?: duckdb.DuckDBConfig;
 }
 
 /**
@@ -34,6 +36,7 @@ export class DuckDBWASMConnector implements Connector {
   public _options: DuckDBWASMOptions;
   public _db?: duckdb.AsyncDuckDB;
   public _con?: duckdb.AsyncDuckDBConnection;
+  public _config?: duckdb.DuckDBConfig;
   public _loadPromise?: Promise<unknown>;
 
   /**
@@ -41,11 +44,12 @@ export class DuckDBWASMConnector implements Connector {
    * @param options Connector options.
    */
   constructor(options: DuckDBWASMConnectorOptions = {}) {
-    const { ipc, duckdb, connection, ...opts } = options;
+    const { ipc, duckdb, connection, config, ...opts } = options;
     this._ipc = ipc;
     this._options = opts;
     this._db = duckdb;
     this._con = connection;
+    this._config = config;
   }
 
   /**
@@ -87,7 +91,7 @@ export class DuckDBWASMConnector implements Connector {
  * @param con The DuckDB-WASM connection.
  * @param query The SQL query to run.
  */
-function getArrowIPC(con: duckdb.AsyncDuckDBConnection, query: string): Promise<ArrayBuffer> {
+function getArrowIPC(con: duckdb.AsyncDuckDBConnection, query: string): Promise<Uint8Array> {
   return new Promise((resolve, reject) => {
     con.useUnsafe(async (bindings, conn) => {
       try {
@@ -113,6 +117,7 @@ function connect(c: DuckDBWASMConnector): Promise<unknown> {
       c._db
         ? Promise.resolve(c._db)
         : initDatabase(c._options).then(result => c._db = result))
+      .then(db => c._config != undefined ? db.open(c._config).then(() => db) : db)
       .then(db => db.connect())
       .then(result => c._con = result);
   }
@@ -135,7 +140,7 @@ async function initDatabase({
     new Blob([`importScripts("${bundle.mainWorker}");`], {type: 'text/javascript'})
   );
 
-  // Instantiate the asynchronus version of DuckDB-wasm
+  // Instantiate the asynchronous version of DuckDB-wasm
   const worker = new Worker(worker_url);
   const logger = log ? new duckdb.ConsoleLogger() : new duckdb.VoidLogger();
   const db = new duckdb.AsyncDuckDB(logger, worker);
@@ -143,4 +148,4 @@ async function initDatabase({
   URL.revokeObjectURL(worker_url);
 
   return db;
-}
+}

package/src/index.ts

@@ -17,9 +17,11 @@ export { DuckDBWASMConnector } from './connectors/wasm.js';
 export {
   clauseInterval,
   clauseIntervals,
+  clauseList,
   clausePoint,
   clausePoints,
-  clauseMatch
+  clauseMatch,
+  clauseMatchAny
 } from './SelectionClause.js';
 
 export { decodeIPC } from './util/decode-ipc.js';

package/src/make-client.ts

@@ -30,9 +30,9 @@ export interface MakeClientOptions {
  * Make a new client with the given options, and connect the client to the
  * provided coordinator.
  * @param options The options for making the client.
- * @returns The resulting client, along with a method to destroy the client when no longer needed.
+ * @returns The resulting client.
  */
-export function makeClient(options: MakeClientOptions): MosaicClient & { destroy: () => void } {
+export function makeClient(options: MakeClientOptions): MosaicClient {
   const {
     coordinator = defaultCoordinator(),
     ...clientOptions

package/src/util/decode-ipc.ts

@@ -10,6 +10,9 @@ import { tableFromIPC } from '@uwdata/flechette';
  *  values to JS Date objects.
  * @returns A table instance.
  */
-export function decodeIPC(data: ArrayBuffer | Uint8Array, options: ExtractionOptions = { useDate: true }): Table {
+export function decodeIPC(
+  data: ArrayBufferLike | Uint8Array,
+  options: ExtractionOptions = { useDate: true }
+): Table {
   return tableFromIPC(data, options);
 }

package/src/util/field-info.ts

@@ -66,7 +66,7 @@ async function getFieldInfo(mc: Coordinator, { table, column, stats }: FieldInfo
     .groupby(isNode(column) && isAggregateExpression(column) ? sql`ALL` : []);
 
   const [desc] = Array.from(
-    await mc.query(Query.describe(q)) as Table
+    await mc.query(Query.describe(q))
   ) as ColumnDescription[];
   const info: FieldInfo = {
     table,
@@ -83,7 +83,7 @@ async function getFieldInfo(mc: Coordinator, { table, column, stats }: FieldInfo
   const [result] = await mc.query(
     summarize({ table, column, stats }),
     { persist: true }
-  ) as Table;
+  );
 
   // extract summary stats, copy to field info, and return
   return Object.assign(info, result);
@@ -97,7 +97,7 @@ async function getFieldInfo(mc: Coordinator, { table, column, stats }: FieldInfo
  */
 async function getTableInfo(mc: Coordinator, table: string): Promise<FieldInfo[]> {
   const result = Array.from(
-    await mc.query(`DESCRIBE ${asTableRef(table)}`) as Table
+    await mc.query(`DESCRIBE ${asTableRef(table)}`)
   ) as ColumnDescription[];
   return result.map(desc => ({
     table,