@uwdata/mosaic-core 0.16.2 → 0.18.0

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

@@ -1,109 +1,93 @@
-/** @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 * as duckdb from '@duckdb/duckdb-wasm';
 import { decodeIPC } from '../util/decode-ipc.js';
 
-/**
- * @typedef {object} DuckDBWASMOptions
- * @property {boolean} [log] Flag to enable logging.
- */
+interface DuckDBWASMOptions {
+  /** Flag to enable logging. */
+  log?: boolean;
+}
 
-/**
- * @typedef {object} DuckDBWASMConnectorOptions
- * @property {boolean} [log] Flag to enable logging.
- * @property {ExtractionOptions} [ipc]
- *  Arrow IPC extraction options.
- * @property {duckdb.AsyncDuckDB} [duckdb]
- *  Optional pre-existing DuckDB-WASM instance.
- * @property {duckdb.AsyncDuckDBConnection} [connection]
- *  Optional pre-existing DuckDB-WASM connection.
- */
+interface DuckDBWASMConnectorOptions extends DuckDBWASMOptions {
+  /** Arrow IPC extraction options. */
+  ipc?: ExtractionOptions;
+  /** Optional pre-existing DuckDB-WASM instance. */
+  duckdb?: duckdb.AsyncDuckDB;
+  /** Optional pre-existing DuckDB-WASM connection. */
+  connection?: duckdb.AsyncDuckDBConnection;
+}
 
 /**
  * Connect to a DuckDB-WASM instance.
- * @param {DuckDBWASMConnectorOptions} [options] Connector options.
- * @returns {DuckDBWASMConnector} A connector instance.
+ * @param options Connector options.
+ * @returns A connector instance.
  */
-export function wasmConnector(options = {}) {
+export function wasmConnector(options: DuckDBWASMConnectorOptions = {}): DuckDBWASMConnector {
   return new DuckDBWASMConnector(options);
 }
 
 /**
  * DuckDB-WASM connector.
- * @implements {Connector}
  */
-export class DuckDBWASMConnector {
+export class DuckDBWASMConnector implements Connector {
+  private _ipc?: ExtractionOptions;
+  public _options: DuckDBWASMOptions;
+  public _db?: duckdb.AsyncDuckDB;
+  public _con?: duckdb.AsyncDuckDBConnection;
+  public _loadPromise?: Promise<unknown>;
+
   /**
    * Create a new DuckDB-WASM connector instance.
-   * @param {DuckDBWASMConnectorOptions} [options]
+   * @param options Connector options.
    */
-  constructor(options = {}) {
+  constructor(options: DuckDBWASMConnectorOptions = {}) {
     const { ipc, duckdb, connection, ...opts } = options;
-    /** @type {ExtractionOptions} */
     this._ipc = ipc;
-    /** @type {DuckDBWASMOptions} */
     this._options = opts;
-    /** @type {duckdb.AsyncDuckDB} */
     this._db = duckdb;
-    /** @type {duckdb.AsyncDuckDBConnection} */
     this._con = connection;
-    /** @type {Promise<unknown>} */
-    this._loadPromise;
   }
 
   /**
    * Get the backing DuckDB-WASM instance.
    * Lazily initializes DuckDB-WASM if not already loaded.
-   * @returns {Promise<duckdb.AsyncDuckDB>} The DuckDB-WASM instance.
+   * @returns The DuckDB-WASM instance.
    */
-  async getDuckDB() {
+  async getDuckDB(): Promise<duckdb.AsyncDuckDB> {
     if (!this._db) await connect(this);
-    return this._db;
+    return this._db!;
   }
 
   /**
    * Get the backing DuckDB-WASM connection.
    * Lazily initializes DuckDB-WASM if not already loaded.
-   * @returns {Promise<duckdb.AsyncDuckDBConnection>} The DuckDB-WASM connection.
+   * @returns The DuckDB-WASM connection.
    */
-  async getConnection() {
+  async getConnection(): Promise<duckdb.AsyncDuckDBConnection> {
     if (!this._con) await connect(this);
-    return this._con;
+    return this._con!;
   }
 
-  /**
-   * @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>[]>}}
-   */
-  async query(query) {
+  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 { type, sql } = query;
     const con = await this.getConnection();
     const result = await getArrowIPC(con, sql);
     return type === 'exec' ? undefined
       : type === 'arrow' ? decodeIPC(result, this._ipc)
       : decodeIPC(result).toArray();
-  };
+  }
 }
 
 /**
  * Bypass duckdb-wasm query method to get Arrow IPC bytes directly.
  * https://github.com/duckdb/duckdb-wasm/issues/267#issuecomment-2252749509
- * @param {duckdb.AsyncDuckDBConnection} con The DuckDB-WASM connection.
- * @param {string} query The SQL query to run.
+ * @param con The DuckDB-WASM connection.
+ * @param query The SQL query to run.
  */
-function getArrowIPC(con, query) {
+function getArrowIPC(con: duckdb.AsyncDuckDBConnection, query: string): Promise<ArrayBuffer> {
   return new Promise((resolve, reject) => {
     con.useUnsafe(async (bindings, conn) => {
       try {
@@ -118,10 +102,10 @@ function getArrowIPC(con, query) {
 
 /**
  * Establish a new database connection for the given connector.
- * @param {DuckDBWASMConnector} c The connector.
- * @returns {Promise<unknown>}
+ * @param c The connector.
+ * @returns Connection promise.
  */
-function connect(c) {
+function connect(c: DuckDBWASMConnector): Promise<unknown> {
   if (!c._loadPromise) {
     // use a loading promise to avoid race conditions
     // synchronizes multiple callees on the same load
@@ -137,11 +121,11 @@ function connect(c) {
 
 /**
  * Initialize a new DuckDB-WASM instance.
- * @param {DuckDBWASMOptions} options
+ * @param options Database initialization options.
  */
 async function initDatabase({
   log = false
-} = {}) {
+}: DuckDBWASMOptions = {}): Promise<duckdb.AsyncDuckDB> {
   const JSDELIVR_BUNDLES = duckdb.getJsDelivrBundles();
 
   // Select a bundle based on browser checks
@@ -159,4 +143,4 @@ async function initDatabase({
   URL.revokeObjectURL(worker_url);
 
   return db;
-}
+}

package/src/{index.js → index.ts}

@@ -5,10 +5,15 @@ export { Selection, isSelection } from './Selection.js';
 export { Param, isParam } from './Param.js';
 export { Priority } from './QueryManager.js';
 
+// deprecated in favor of constructors
 export { restConnector } from './connectors/rest.js';
 export { socketConnector } from './connectors/socket.js';
 export { wasmConnector } from './connectors/wasm.js';
 
+export { RestConnector } from './connectors/rest.js';
+export { SocketConnector } from './connectors/socket.js';
+export { DuckDBWASMConnector } from './connectors/wasm.js';
+
 export {
   clauseInterval,
   clauseIntervals,
@@ -20,9 +25,16 @@ export {
 export { decodeIPC } from './util/decode-ipc.js';
 export { distinct } from './util/distinct.js';
 export { isArrowTable } from './util/is-arrow-table.js';
-export { synchronizer } from './util/synchronizer.js';
+export { Synchronizer } from './util/synchronizer.js';
 export { throttle } from './util/throttle.js';
 export { toDataColumns } from './util/to-data-columns.js';
 export { queryFieldInfo } from './util/field-info.js';
 export { jsType } from './util/js-type.js';
 export { isActivatable } from './util/is-activatable.js';
+export type { QueryResult } from './util/query-result.js';
+
+export * from './types.js';
+
+export type * from './connectors/Connector.js';
+export type * from './Selection.js';
+export type * from './SelectionClause.js';

package/src/make-client.ts

@@ -0,0 +1,93 @@
+import type { Coordinator } from './Coordinator.js';
+import type { Selection } from './Selection.js';
+import type { FilterExpr } from '@uwdata/mosaic-sql';
+import { type ClientQuery, MosaicClient } from './MosaicClient.js';
+import { coordinator as defaultCoordinator } from './Coordinator.js';
+
+export interface MakeClientOptions {
+  /** Mosaic coordinator. Defaults to the global coordinator. */
+  coordinator?: Coordinator;
+  /** A selection whose predicates are fed into the query function to produce the SQL query. */
+  selection?: Selection;
+  /** A flag (default `true`) indicating if the client should initially be enabled or not. */
+  enabled?: boolean;
+  /** A flag (default `true`) indicating 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. */
+  filterStable?: boolean;
+  /** An async function to prepare the client before running queries. */
+  prepare?: () => Promise<void>;
+  /** A function that returns a query from a list of selection predicates. */
+  query?: (filter: FilterExpr) => ClientQuery;
+  /** Called by the coordinator to return a query result. */
+  queryResult?: (data: unknown) => void;
+  /** Called by the coordinator to inform the client that a query is pending. */
+  queryPending?: () => void;
+  /** Called by the coordinator to report a query execution error. */
+  queryError?: (error: Error) => void;
+}
+
+/**
+ * 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.
+ */
+export function makeClient(options: MakeClientOptions): MosaicClient & { destroy: () => void } {
+  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 {
+  private readonly _methods: Omit<MakeClientOptions, 'coordinator' | 'selection' | 'enabled' | 'filterStable'>;
+  private readonly _filterStable: boolean;
+
+  /**
+   * @param options The options for making the client.
+   */
+  constructor({
+    selection = undefined,
+    enabled = true,
+    filterStable = true,
+    ...methods
+  }: Omit<MakeClientOptions, 'coordinator'>) {
+    super(selection);
+    this.enabled = enabled;
+    this._methods = methods;
+    this._filterStable = filterStable;
+  }
+
+  get filterStable(): boolean {
+    return this._filterStable;
+  }
+
+  async prepare(): Promise<void> {
+    await this._methods.prepare?.();
+  }
+
+  query(filter: FilterExpr): ClientQuery {
+    return this._methods.query?.(filter) ?? null;
+  }
+
+  queryResult(data: unknown): this {
+    this._methods.queryResult?.(data);
+    return this;
+  }
+
+  queryPending(): this {
+    this._methods.queryPending?.();
+    return this;
+  }
+
+  queryError(error: Error): this {
+    this._methods.queryError?.(error);
+    return this;
+  }
+}