@uwdata/mosaic-core 0.16.1 → 0.17.0

package/dist/types/make-client.d.ts

@@ -1,78 +0,0 @@
-/**
- * @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: MakeClientOptions): MosaicClient & {
-    destroy: () => void;
-};
-export type 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 | null;
-    /**
-     * A flag (default `true`) indicating if the
-     * client should initially be enabled or not.
-     */
-    enabled?: boolean;
-    /**
-     * 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.
-     */
-    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?: (arg0: any) => any;
-    /**
-     * Called by the coordinator to return a query result.
-     */
-    queryResult?: (arg0: any) => void;
-    /**
-     * Called by the coordinator to report a query execution error.
-     */
-    queryPending?: () => void;
-    /**
-     * Called by the coordinator to inform the client that a query is pending.
-     */
-    queryError?: (arg0: any) => void;
-};
-import { MosaicClient } from './MosaicClient.js';
-import type { Coordinator } from './Coordinator.js';
-import type { Selection } from './Selection.js';

package/dist/types/preagg/PreAggregator.d.ts

@@ -1,180 +0,0 @@
-/**
- * @typedef {object} PreAggregateOptions
- * @property {string} [schema] Database schema (namespace) in which to write
- *  pre-aggregated materialzied views (default 'mosaic').
- * @property {boolean} [options.enabled=true] Flag to enable or disable the
- *  pre-aggregation. This flag can be updated later via the `enabled` property.
- */
-/**
- * Build and query optimized pre-aggregated materaialized views, for fast
- * computation of groupby aggregate queries over compatible client queries
- * and selections. The materialized views contains pre-aggregated data for a
- * Mosaic client, subdivided by possible query values from an active selection
- * clause. These materialized views are database tables that can be queried
- * for rapid updates.
- *
- * Compatible client queries must consist of only groupby dimensions and
- * supported aggregate functions. Compatible selections must contain an active
- * clause that exposes metadata for an interval or point value predicate.
- *
- * Materialized views are written to a dedicated schema (namespace) that
- * can be set using the *schema* constructor option. This schema acts as a
- * persistent cache, and materialized view tables may be used across sessions.
- * The `dropSchema` method issues a query to remove *all* tables within this
- * schema. This may be needed if the original tables have updated data, but
- * should be used with care.
- */
-export class PreAggregator {
-    /**
-     * Create a new manager of materialized views of pre-aggregated data.
-     * @param {Coordinator} coordinator A Mosaic coordinator.
-     * @param {PreAggregateOptions} [options] Pre-aggregation options.
-     */
-    constructor(coordinator: Coordinator, { schema, enabled }?: PreAggregateOptions);
-    /** @type {Map<MosaicClient, PreAggregateInfo | Skip | null>} */
-    entries: Map<MosaicClient, PreAggregateInfo | {
-        skip: boolean;
-        result: any;
-    } | null>;
-    active: any;
-    mc: Coordinator;
-    _schema: string;
-    _enabled: boolean;
-    /**
-     * Set the enabled state of this manager. If false, any local state is
-     * cleared and subsequent request calls will return null until re-enabled.
-     * This method has no effect on any pre-aggregated tables already in the
-     * database.
-     * @param {boolean} [state] The enabled state to set.
-     */
-    set enabled(state: boolean);
-    /**
-     * Get the enabled state of this manager.
-     * @returns {boolean} The current enabled state.
-     */
-    get enabled(): boolean;
-    /**
-     * Set the database schema used for pre-aggregated materialized view tables.
-     * Upon changes, any local state is cleared. This method does _not_ drop any
-     * existing materialized views, use `dropSchema` before changing the schema
-     * to also remove existing materalized views in the database.
-     * @param {string} [schema] The schema name to set.
-     */
-    set schema(schema: string);
-    /**
-     * Get the database schema used for pre-aggregated materialized view tables.
-     * @returns {string} The current schema name.
-     */
-    get schema(): string;
-    /**
-     * Issues a query through the coordinator to drop the current schema for
-     * pre-aggregated materialized views. *All* materialized view tables in the
-     * schema will be removed and local state is cleared. Call this method if
-     * the underlying base tables have been updated, causing materialized view
-     * to become stale and inaccurate. Use this method with care! Once dropped,
-     * the schema will be repopulated by future pre-aggregation requests.
-     * @returns A query result promise.
-     */
-    dropSchema(): import("../util/query-result.js").QueryResult;
-    /**
-     * Clear the cache of pre-aggregation entries for the current active
-     * selection clause. This method does _not_ drop any existing materialized
-     * views. Use `dropSchema` to remove existing materialized view tables from
-     * the database.
-     */
-    clear(): void;
-    /**
-     * Return pre-aggregation information for the active state of a
-     * client-selection pair, or null if the client has unstable filters.
-     * This method has multiple possible side effects, including materialized
-     * view creation and updating internal caches.
-     * @param {MosaicClient} client A Mosaic client.
-     * @param {Selection} selection A Mosaic selection to filter the client by.
-     * @param {SelectionClause} activeClause A representative active selection
-     *  clause for which to generate materialized views of pre-aggregates.
-     * @returns {PreAggregateInfo | Skip | null} Information and query generator
-     * for pre-aggregated tables, or null if the client has unstable filters.
-     */
-    request(client: MosaicClient, selection: Selection, activeClause: SelectionClause): PreAggregateInfo | {
-        skip: boolean;
-        result: any;
-    } | null;
-}
-/**
- * Metadata and query generator for materialized views of pre-aggregated data.
- * This object provides the information needed to generate and query the
- * materialized views for a client-selection pair relative to a specific
- * active clause and selection state.
- */
-export class PreAggregateInfo {
-    /**
-     * Create a new pre-aggregation information instance.
-     * @param {object} options Options object.
-     * @param {string} options.table The materialized view table name.
-     * @param {string} options.create The table creation query.
-     * @param {*} options.active Active column information.
-     * @param {SelectQuery} options.select Base query for requesting updates
-     *  using a pre-aggregated materialized view.
-     */
-    constructor({ table, create, active, select }: {
-        table: string;
-        create: string;
-        active: any;
-        select: SelectQuery;
-    });
-    /**
-     * The name of the materialized view.
-     * @type {string}
-     */
-    table: string;
-    /**
-     * The SQL query used to generate the materialized view.
-     * @type {string}
-     */
-    create: string;
-    /**
-     * A result promise returned for the materialized view creation query.
-     * @type {Promise | null}
-     */
-    result: Promise<any> | null;
-    /**
-     * Definitions and predicate function for the active columns,
-     * which are dynamically filtered by the active clause.
-     */
-    active: any;
-    /**
-     * Select query (sans where clause) for materialized views.
-     * @type {SelectQuery}
-     */
-    select: SelectQuery;
-    /**
-     * Boolean flag indicating a client that should be skipped.
-     * This value is always false for a created materialized view.
-     * @type {boolean}
-     */
-    skip: boolean;
-    /**
-     * Generate a materialized view query for the given predicate.
-     * @param {ExprNode} predicate The current active clause predicate.
-     * @returns {SelectQuery} A materialized view query.
-     */
-    query(predicate: ExprNode): SelectQuery;
-}
-export type PreAggregateOptions = {
-    /**
-     * Database schema (namespace) in which to write
-     * pre-aggregated materialzied views (default 'mosaic').
-     */
-    schema?: string;
-    /**
-     * Flag to enable or disable the
-     * pre-aggregation. This flag can be updated later via the `enabled` property.
-     */
-    enabled?: boolean;
-};
-import type { MosaicClient } from '../MosaicClient.js';
-import type { Coordinator } from '../Coordinator.js';
-import type { Selection } from '../Selection.js';
-import type { SelectionClause } from '../util/selection-types.js';
-import type { SelectQuery } from '@uwdata/mosaic-sql';
-import type { ExprNode } from '@uwdata/mosaic-sql';

package/dist/types/preagg/preagg-columns.d.ts

@@ -1,14 +0,0 @@
-/**
- * Determine pre-aggregation columns for a given Mosaic client.
- * @param {MosaicClient} client The Mosaic client.
- * @returns An object with necessary column data to generate pre-aggregated
- *  columns, or null if the client can't be optimized or the client query
- *  contains an invalid or unsupported expression.
- */
-export function preaggColumns(client: MosaicClient): {
-    group: string[];
-    preagg: Record<string, ExprNode>;
-    output: Record<string, ExprNode>;
-};
-import type { MosaicClient } from '../MosaicClient.js';
-import type { ExprNode } from '@uwdata/mosaic-sql';

package/dist/types/preagg/sufficient-statistics.d.ts

@@ -1,13 +0,0 @@
-/**
- * Determine sufficient statistics to preaggregate the given node. This
- * method populates the *preagg* and *aggrs* arguments with necessary
- * information for preaggregation optimization.
- * @param {AggregateNode} node An aggregate function.
- * @param {Record<string, ExprNode>} preagg Map of column names to
- *  expressions to include in the preaggregation table.
- * @returns {ExprNode} Output aggregate expression that uses preaggregated
- *  sufficient statistics to service updates.
- */
-export function sufficientStatistics(node: AggregateNode, preagg: Record<string, ExprNode>, avg: any): ExprNode;
-import type { AggregateNode } from '@uwdata/mosaic-sql';
-import type { ExprNode } from '@uwdata/mosaic-sql';

package/dist/types/types.d.ts

@@ -1,63 +0,0 @@
-import type { DescribeQuery, ExprNode, Query } from '@uwdata/mosaic-sql';
-/** Query type accepted by a coordinator. */
-export type QueryType = string | Query | DescribeQuery;
-/** String indicating a JavaScript data type. */
-export type JSType = 'number' | 'date' | 'boolean' | 'string' | 'array' | 'object';
-/** String indicating a requested summary statistic. */
-export type Stat = 'count' | 'nulls' | 'max' | 'min' | 'distinct';
-/** A reference to a database column or expression. */
-export type FieldRef = string | ExprNode;
-/**
- * A request for metadata information about a database column.
- */
-export interface FieldInfoRequest {
-    table: string;
-    column: FieldRef;
-    stats?: Stat[];
-}
-/**
- * A response with metadata information about a database column.
- */
-export interface FieldInfo extends Partial<Record<Stat, number>> {
-    table: string;
-    column: string;
-    sqlType: string;
-    type: JSType;
-    nullable: boolean;
-}
-/** A result row from a DESCRIBE query. */
-export interface ColumnDescription {
-    column_name: string;
-    column_type: string;
-    null: 'YES' | 'NO';
-}
-/**
- * Interface for components that perform selection activation.
- */
-export interface Activatable {
-    /**
-     * Activate the selection that this component publishes to.
-     */
-    activate(): void;
-}
-/**
- * Interface for cache implementations.
- */
-export interface Cache {
-    get(key: string): any;
-    set(key: string, value: any): any;
-    clear(): void;
-}
-/**
- * Interface for logger implementations
- */
-export interface Logger {
-    debug(...args: any[]): void;
-    info(...args: any[]): void;
-    log(...args: any[]): void;
-    warn(...args: any[]): void;
-    error(...args: any[]): void;
-    group(label?: any): void;
-    groupCollapsed(label?: any): void;
-    groupEnd(): void;
-}

package/dist/types/util/AsyncDispatch.d.ts

@@ -1,100 +0,0 @@
-/**
- * Event dispatcher supporting asynchronous updates. If an event handler
- * callback returns a Promise, the dispatcher waits for all such Promises
- * to settle before dispatching future events of the same type.
- */
-export class AsyncDispatch {
-    _callbacks: Map<any, any>;
-    /**
-     * Add an event listener callback for the provided event type.
-     * @param {string} type The event type.
-     * @param {(value: *) => void | Promise} callback The event handler
-     *  callback function to add. If the callback has already been
-     *  added for the event type, this method has no effect.
-     */
-    addEventListener(type: string, callback: (value: any) => void | Promise<any>): void;
-    /**
-     * Remove an event listener callback for the provided event type.
-     * @param {string} type The event type.
-     * @param {(value: *) => void | Promise} callback The event handler
-     *  callback function to remove.
-     */
-    removeEventListener(type: string, callback: (value: any) => void | Promise<any>): void;
-    /**
-     * Lifecycle method that returns the event value to emit.
-     * This default implementation simply returns the input value as-is.
-     * Subclasses may override this method to implement custom transformations
-     * prior to emitting an event value to all listeners.
-     * @param {string} type The event type.
-     * @param {*} value The event value.
-     * @returns The (possibly transformed) event value to emit.
-     */
-    willEmit(type: string, value: any): any;
-    /**
-     * Lifecycle method that returns a filter function for updating the
-     * queue of unemitted event values prior to enqueueing a new value.
-     * This default implementation simply returns null, indicating that
-     * any other unemitted event values should be dropped (that is, all
-     * queued events are filtered).
-     * @param {string} type The event type.
-     * @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.
-     */
-    emitQueueFilter(type: string, value: any): (value: any) => boolean | null;
-    /**
-     * Cancel all unemitted event values for the given event type.
-     * @param {string} type The event type.
-     */
-    cancel(type: string): void;
-    /**
-     * Returns a promise that resolves when any pending updates complete for
-     * the event of the given type currently being processed. The Promise will
-     * resolve immediately if the queue for the given event type is empty.
-     * @param {string} type The event type to wait for.
-     * @returns {Promise} A pending event promise.
-     */
-    pending(type: string): Promise<any>;
-    /**
-     * Emit an event value to listeners for the given event type.
-     * If a previous emit has not yet resolved, the event value
-     * will be queued to be emitted later.
-     * The actual event value given to listeners will be the result
-     * of passing the input value through the emitValue() method.
-     * @param {string} type The event type.
-     * @param {*} value The event value.
-     */
-    emit(type: string, value: any): void;
-}
-/**
- * Queue for managing unemitted event values.
- */
-export class DispatchQueue {
-    /**
-     * Clear the queue state of all event values.
-     */
-    clear(): void;
-    next: any;
-    /**
-     * Indicate if the queue is empty.
-     * @returns {boolean} True if queue is empty, false otherwise.
-     */
-    isEmpty(): boolean;
-    /**
-     * Add a new value to the queue, and optionally filter the
-     * current queue content in response.
-     * @param {*} value The value to add.
-     * @param {(value: *) => boolean} [filter] An optional filter
-     *  function to apply to existing queue content. If unspecified
-     *  or falsy, all previously queued values are removed. Otherwise,
-     *  the provided function is applied to all queue entries. The
-     *  entry is retained if the filter function returns a truthy value,
-     *  otherwise the entry is removed.
-     */
-    enqueue(value: any, filter?: (value: any) => boolean): void;
-    /**
-     * Remove and return the next queued event value.
-     * @returns {*} The next event value in the queue.
-     */
-    dequeue(): any;
-}

package/dist/types/util/cache.d.ts

@@ -1,17 +0,0 @@
-/**
- * Create a new cache that ignores all values.
- * @returns {Cache}
- */
-export function voidCache(): Cache;
-/**
- * Create a new cache that uses an LRU eviction policy.
- * @param {object} [options] Cache options.
- * @param {number} [options.max] Maximum number of cache entries.
- * @param {number} [options.ttl] Time-to-live for cache entries.
- * @returns {Cache}
- */
-export function lruCache({ max, ttl }?: {
-    max?: number;
-    ttl?: number;
-}): Cache;
-import type { Cache } from '../types.js';

package/dist/types/util/decode-ipc.d.ts

@@ -1,12 +0,0 @@
-/**
- * Decode Arrow IPC bytes to a table instance.
- * The default options map date and timestamp values to JS Date objects.
- * @param {ArrayBuffer | Uint8Array} data Arrow IPC bytes.
- * @param {ExtractionOptions} [options] Arrow IPC extraction options.
- *  If unspecified, the default options will extract date and timestamp
- *  values to JS Date objects.
- * @returns {Table} A table instance.
- */
-export function decodeIPC(data: ArrayBuffer | Uint8Array, options?: ExtractionOptions): Table;
-import type { ExtractionOptions } from '@uwdata/flechette';
-import type { Table } from '@uwdata/flechette';

package/dist/types/util/distinct.d.ts

@@ -1,2 +0,0 @@
-export function distinct(a: any, b: any): boolean;
-export function distinctArray(a: any, b: any): boolean;

package/dist/types/util/field-info.d.ts

@@ -1,23 +0,0 @@
-/**
- * Queries information about fields of a table.
- * If the `fields` array contains a single field with the column set to '*',
- * the function will retrieve and return the table information using `getTableInfo`.
- * Otherwise, it will query individual field information using `getFieldInfo`
- * for each field in the `fields` array.
- * @param {import('../Coordinator.js').Coordinator} mc A Mosaic coordinator.
- * @param {import('../types.js').FieldInfoRequest[]} fields
- * @returns {Promise<import('../types.js').FieldInfo[]>}
- */
-export function queryFieldInfo(mc: import("../Coordinator.js").Coordinator, fields: import("../types.js").FieldInfoRequest[]): Promise<import("../types.js").FieldInfo[]>;
-export const Count: "count";
-export const Nulls: "nulls";
-export const Max: "max";
-export const Min: "min";
-export const Distinct: "distinct";
-export namespace Stats {
-    export { Count };
-    export { Nulls };
-    export { Max };
-    export { Min };
-    export { Distinct };
-}

package/dist/types/util/hash.d.ts

@@ -1 +0,0 @@
-export function fnv_hash(v: any): number;

package/dist/types/util/is-activatable.d.ts

@@ -1,6 +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: any): value is import("../types.js").Activatable;

package/dist/types/util/is-arrow-table.d.ts

@@ -1,8 +0,0 @@
-/**
- * Test if a value is a Flechette Arrow table.
- * We use a "duck typing" approach and check for a getChild function.
- * @param {*} values The value to test
- * @returns {values is import('@uwdata/flechette').Table}
- *  true if the value duck types as Arrow data
- */
-export function isArrowTable(values: any): values is import("@uwdata/flechette").Table;

package/dist/types/util/js-type.d.ts

@@ -1,7 +0,0 @@
-/**
- * Maps a SQL data type to its corresponding JavaScript type.
- * @param {string} type The name of a SQL data type
- * @returns {import('../types.js').JSType} The corresponding JavaScript type name
- * @throws {Error} Throws an error if the given SQL type name is unsupported or unrecognized.
- */
-export function jsType(type: string): import("../types.js").JSType;

package/dist/types/util/priority-queue.d.ts

@@ -1,37 +0,0 @@
-export class PriorityQueue {
-    /**
-     * Create a new priority queue instance.
-     * @param {number} ranks An integer number of rank-order priority levels.
-     */
-    constructor(ranks: number);
-    queue: {
-        head: any;
-        tail: any;
-    }[];
-    /**
-     * Indicate if the queue is empty.
-     * @returns {boolean} true if empty, false otherwise.
-     */
-    isEmpty(): boolean;
-    /**
-     * Insert an item into the queue with a given priority rank.
-     * @param {*} item The item to add.
-     * @param {number} rank The integer priority rank.
-     * Priority ranks are integers starting at zero.
-     * Lower ranks indicate higher priority.
-     */
-    insert(item: any, rank: number): void;
-    /**
-     * Remove a set of items from the queue, regardless of priority rank.
-     * If a provided item is not in the queue it will be ignored.
-     * @param {(item: *) => boolean} test A predicate function to test
-     * if an item should be removed (true to drop, false to keep).
-     */
-    remove(test: (item: any) => boolean): void;
-    /**
-     * Remove and return the next highest priority item.
-     * @returns {*} The next item in the queue,
-     * or undefined if this queue is empty.
-     */
-    next(): any;
-}

package/dist/types/util/query-result.d.ts

@@ -1,44 +0,0 @@
-export const QueryState: Readonly<{
-    pending: symbol;
-    ready: symbol;
-    error: symbol;
-    done: symbol;
-}>;
-/**
- * A query result Promise that can allows external callers
- * to resolve or reject the Promise.
- */
-export class QueryResult extends Promise<any> {
-    /**
-     * Create a new query result Promise.
-     */
-    constructor();
-    _resolve: any;
-    _reject: any;
-    _state: symbol;
-    _value: any;
-    /**
-     * Resolve the result Promise with a prepared value or the provided value.
-     * This method will only succeed if either a value is provided or the promise is ready.
-     * @param {*} value The result value.
-     * @returns {this}
-     */
-    fulfill(value: any): this;
-    /**
-     * Prepare to resolve with the provided value.
-     * @param {*} value The result value.
-     * @returns {this}
-     */
-    ready(value: any): this;
-    /**
-     * Rejects the result Promise with the provided error.
-     * @param {*} error The error value.
-     * @returns {this}
-     */
-    reject(error: any): this;
-    /**
-     * Returns the state of this query result.
-     * @returns {symbol}
-     */
-    get state(): symbol;
-}