@uwdata/mosaic-core 0.17.0 → 0.18.0

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)
     );
   }
-}
+}

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;
+  }
+}