@uwdata/mosaic-core 0.16.2 → 0.18.0

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

@@ -1,5 +1,5 @@
-/** @import { Connector } from './connectors/Connector.js' */
-/** @import { Cache, Logger } from './types.js' */
+import type { Connector } from './connectors/Connector.js';
+import type { Cache, Logger, QueryEntry, QueryRequest } from './types.js';
 import { consolidator } from './QueryConsolidator.js';
 import { lruCache, voidCache } from './util/cache.js';
 import { PriorityQueue } from './util/priority-queue.js';
@@ -9,38 +9,38 @@ import { voidLogger } from './util/void-logger.js';
 export const Priority = Object.freeze({ High: 0, Normal: 1, Low: 2 });
 
 export class QueryManager {
-  constructor(
-    maxConcurrentRequests = 32
-  ) {
-    /** @type {PriorityQueue} */
+  private queue: PriorityQueue<QueryEntry>;
+  private db: Connector | null;
+  private clientCache: Cache | null;
+  private _logger: Logger;
+  private _logQueries: boolean;
+  private _consolidate: ReturnType<typeof consolidator> | null;
+  /** Requests pending with the query manager. */
+  public pendingResults: QueryResult[];
+  private maxConcurrentRequests: number;
+  private pendingExec: boolean;
+
+  constructor(maxConcurrentRequests: number = 32) {
     this.queue = new PriorityQueue(3);
-    /** @type {Connector} */
     this.db = null;
-    /** @type {Cache} */
     this.clientCache = null;
-    /** @type {Logger} */
     this._logger = voidLogger();
-    /** @type {boolean} */
     this._logQueries = false;
-    /** @type {ReturnType<typeof consolidator> | null} */
     this._consolidate = null;
-    /**
-     * Requests pending with the query manager.
-     * @type {QueryResult[]}
-     */
     this.pendingResults = [];
-    /** @type {number} */
     this.maxConcurrentRequests = maxConcurrentRequests;
-    /** @type {boolean} */
     this.pendingExec = false;
   }
 
-  next() {
+  next(): void {
     if (this.queue.isEmpty() || this.pendingResults.length > this.maxConcurrentRequests || this.pendingExec) {
       return;
     }
 
-    const { request, result } = this.queue.next();
+    const entry = this.queue.next();
+    if (!entry) return;
+
+    const { request, result } = entry;
 
     this.pendingResults.push(result);
     if (request.type === 'exec') this.pendingExec = true;
@@ -48,7 +48,7 @@ export class QueryManager {
     this.submit(request, result).finally(() => {
       // return from the queue all requests that are ready
       while (this.pendingResults.length && this.pendingResults[0].state !== QueryState.pending) {
-        const result = this.pendingResults.shift();
+        const result = this.pendingResults.shift()!;
         if (result.state === QueryState.ready) {
           result.fulfill();
         } else if (result.state === QueryState.done) {
@@ -62,29 +62,27 @@ export class QueryManager {
 
   /**
    * Add an entry to the query queue with a priority.
-   * @param {object} entry The entry to add.
-   * @param {*} [entry.request] The query request.
-   * @param {QueryResult} [entry.result] The query result.
-   * @param {number} priority The query priority, defaults to `Priority.Normal`.
+   * @param entry The entry to add.
+   * @param priority The query priority, defaults to `Priority.Normal`.
    */
-  enqueue(entry, priority = Priority.Normal) {
+  enqueue(entry: QueryEntry, priority: number = Priority.Normal): void {
     this.queue.insert(entry, priority);
     this.next();
   }
 
   /**
    * Submit the query to the connector.
-   * @param {*} request The request.
-   * @param {QueryResult} result The query result.
+   * @param request The request.
+   * @param result The query result.
    */
-  async submit(request, result) {
+  async submit(request: QueryRequest, result: QueryResult): Promise<void> {
     try {
       const { query, type, cache = false, options } = request;
       const sql = query ? `${query}` : null;
 
       // check query cache
       if (cache) {
-        const cached = this.clientCache.get(sql);
+        const cached = this.clientCache!.get(sql!);
         if (cached) {
           const data = await cached;
           this._logger.debug('Cache');
@@ -99,12 +97,13 @@ export class QueryManager {
         this._logger.debug('Query', { type, sql, ...options });
       }
 
-      const promise = this.db.query({ type, sql, ...options });
-      if (cache) this.clientCache.set(sql, promise);
+      // @ts-expect-error type may be exec | json | arrow
+      const promise = this.db!.query({ type, sql: sql!, ...options });
+      if (cache) this.clientCache!.set(sql!, promise);
 
       const data = await promise;
 
-      if (cache) this.clientCache.set(sql, data);
+      if (cache) this.clientCache!.set(sql!, data);
 
       this._logger.debug(`Request: ${(performance.now() - t0).toFixed(1)}`);
       result.ready(type === 'exec' ? null : data);
@@ -115,10 +114,12 @@ export class QueryManager {
 
   /**
    * Get or set the current query cache.
-   * @param {Cache | boolean} [value]
-   * @returns {Cache}
+   * @param value Cache value to set
+   * @returns Current cache
    */
-  cache(value) {
+  cache(): Cache | null;
+  cache(value: Cache | boolean): Cache;
+  cache(value?: Cache | boolean): Cache | null {
     return value !== undefined
       ? (this.clientCache = value === true ? lruCache() : (value || voidCache()))
       : this.clientCache;
@@ -126,38 +127,44 @@ export class QueryManager {
 
   /**
    * Get or set the current logger.
-   * @param {Logger} [value]
-   * @returns {Logger}
+   * @param value Logger to set
+   * @returns Current logger
    */
-  logger(value) {
+  logger(): Logger;
+  logger(value: Logger): Logger;
+  logger(value?: Logger): Logger {
     return value ? (this._logger = value) : this._logger;
   }
 
   /**
    * Get or set if queries should be logged.
-   * @param {boolean} [value]
-   * @returns {boolean}
+   * @param value Whether to log queries
+   * @returns Current logging state
    */
-  logQueries(value) {
+  logQueries(): boolean;
+  logQueries(value: boolean): boolean;
+  logQueries(value?: boolean): boolean {
     return value !== undefined ? this._logQueries = !!value : this._logQueries;
   }
 
   /**
    * Get or set the database connector.
-   * @param {Connector} [connector]
-   * @returns {Connector}
+   * @param connector Connector to set
+   * @returns Current connector
    */
-  connector(connector) {
+  connector(): Connector | null;
+  connector(connector: Connector): Connector;
+  connector(connector?: Connector): Connector | null {
     return connector ? (this.db = connector) : this.db;
   }
 
   /**
    * Indicate if query consolidation should be performed.
-   * @param {boolean} flag
+   * @param flag Whether to enable consolidation
    */
-  consolidate(flag) {
+  consolidate(flag: boolean): void {
     if (flag && !this._consolidate) {
-      this._consolidate = consolidator(this.enqueue.bind(this), this.clientCache);
+      this._consolidate = consolidator(this.enqueue.bind(this), this.clientCache!);
     } else if (!flag && this._consolidate) {
       this._consolidate = null;
     }
@@ -165,11 +172,11 @@ export class QueryManager {
 
   /**
    * Request a query result.
-   * @param {*} request The request.
-   * @param {number} priority The query priority, defaults to `Priority.Normal`.
-   * @returns {QueryResult} A query result promise.
+   * @param request The request.
+   * @param priority The query priority, defaults to `Priority.Normal`.
+   * @returns A query result promise.
    */
-  request(request, priority = Priority.Normal) {
+  request(request: QueryRequest, priority: number = Priority.Normal): QueryResult {
     const result = new QueryResult();
     const entry = { request, result };
     if (this._consolidate) {
@@ -180,7 +187,7 @@ export class QueryManager {
     return result;
   }
 
-  cancel(requests) {
+  cancel(requests: QueryResult[]): void {
     const set = new Set(requests);
     if (set.size) {
       this.queue.remove(({ result }) => {
@@ -199,7 +206,7 @@ export class QueryManager {
     }
   }
 
-  clear() {
+  clear(): void {
     this.queue.remove(({ result }) => {
       result.reject('Cleared');
       return true;
@@ -210,4 +217,4 @@ export class QueryManager {
     }
     this.pendingResults = [];
   }
-}
+}

package/src/Selection.ts

@@ -0,0 +1,388 @@
+import { type MosaicClient } from './MosaicClient.js';
+import { type ExprNode, FilterExpr, literal, MaybeArray, or } from '@uwdata/mosaic-sql';
+import { Param } from './Param.js';
+import { ClauseSource, SelectionClause } from './SelectionClause.js';
+
+export interface SelectionOptions {
+  /** Boolean flag indicating cross-filtered resolution. If true, selection clauses will not be applied to the clients they are associated with. */
+  cross?: boolean;
+  /** Boolean flag indicating if a lack of clauses should correspond to an empty selection with no records. This setting determines the default selection state. */
+  empty?: boolean;
+  /** Upstream selections whose clauses should be included as part of the new selection. Any clauses published to upstream selections will be relayed to the new selection. */
+  include?: Selection | Selection[];
+}
+
+export interface SelectionResolverOptions extends Pick<SelectionOptions, "empty" | "cross"> {
+  /** Boolean flag to indicate a union strategy. If false, an intersection strategy is used. */
+  union?: boolean;
+    /** Boolean flag to indicate single clauses only. */
+  single?: boolean;
+}
+
+/**
+ * Test if a value is a Selection instance.
+ * @param x The value to test.
+ * @returns True if the input is a Selection, false otherwise.
+ */
+export function isSelection(x: unknown): x is Selection {
+  return x instanceof Selection;
+}
+
+function create(options: SelectionResolverOptions, include?: Selection | Selection[]): Selection {
+  return new Selection(
+    new SelectionResolver(options),
+    include ? [include].flat() : undefined
+  );
+}
+
+type SelectionClauseArray = SelectionClause[] & { active?: SelectionClause };
+type ResolvedPredicate = MaybeArray<string | boolean | ExprNode> | undefined;
+
+/**
+ * Represents a dynamic set of query filter predicates.
+ */
+export class Selection extends Param<SelectionClauseArray> {
+  _resolved: SelectionClauseArray;
+  _resolver: SelectionResolver;
+  _relay: Set<Selection>;
+
+  /**
+   * Create a new Selection instance with an
+   * intersect (conjunction) resolution strategy.
+   * @param options The selection options.
+   * @returns The new Selection instance.
+   */
+  static intersect({ cross = false, empty = false, include = [] }: SelectionOptions = {}): Selection {
+    return create({ cross, empty }, include);
+  }
+
+  /**
+   * Create a new Selection instance with a
+   * union (disjunction) resolution strategy.
+   * @param options The selection options.
+   * @returns The new Selection instance.
+   */
+  static union({ cross = false, empty = false, include = [] }: SelectionOptions = {}): Selection {
+    return create({ cross, empty, union: true }, include);
+  }
+
+  /**
+   * Create a new Selection instance with a singular resolution strategy
+   * that keeps only the most recent selection clause.
+   * @param options The selection options.
+   * @returns The new Selection instance.
+   */
+  static single({ cross = false, empty = false, include = [] }: SelectionOptions = {}): Selection {
+    return create({ cross, empty, single: true }, include);
+  }
+
+  /**
+   * Create a new Selection instance with a
+   * cross-filtered intersect resolution strategy.
+   * @param options The selection options.
+   * @returns The new Selection instance.
+   */
+  static crossfilter({ empty = false, include = [] }: Omit<SelectionOptions, 'cross'> = {}): Selection {
+    return create({ cross: true, empty }, include);
+  }
+
+  /**
+   * Create a new Selection instance.
+   * @param resolver The selection resolution
+   *  strategy to apply.
+   * @param include Upstream selections whose clauses
+   * should be included as part of this selection. Any clauses published
+   * to these upstream selections will be relayed to this selection.
+   */
+  constructor(resolver = new SelectionResolver(), include: Selection[] = []) {
+    super([]);
+    this._resolved = this._value!;
+    this._resolver = resolver;
+    this._relay = new Set();
+    if (Array.isArray(include)) {
+      for (const sel of include) {
+        sel._relay.add(this);
+      }
+    }
+  }
+
+  /**
+   * Create a cloned copy of this Selection instance.
+   * @returns A clone of this selection.
+   */
+  clone(): Selection {
+    const s = new Selection(this._resolver);
+    s._value = s._resolved = this._value!;
+    return s;
+  }
+
+  /**
+   * Create a clone of this Selection with clauses corresponding
+   * to the provided source removed.
+   * @param source The clause source to remove.
+   * @returns A cloned and updated Selection.
+   */
+  remove(source: ClauseSource): Selection {
+    const s = this.clone();
+    s._value = s._resolved = s._resolver.resolve(
+      this._resolved,
+      { source } as SelectionClause
+    );
+    s._value.active = { source } as SelectionClause;
+    return s;
+  }
+
+  /**
+   * The selection clause resolver.
+   */
+  get resolver(): SelectionResolver {
+    return this._resolver;
+  }
+
+  /**
+   * Indicate if this selection has a single resolution strategy.
+   */
+  get single(): boolean {
+    return this._resolver.single;
+  }
+
+  /**
+   * The current array of selection clauses.
+   */
+  get clauses(): SelectionClauseArray {
+    return super.value!;
+  }
+
+  /**
+   * The current active (most recently updated) selection clause.
+   */
+  get active(): SelectionClause {
+    return this.clauses.active!;
+  }
+
+  /**
+   * The value corresponding to the current active selection clause.
+   * This method ensures compatibility where a normal Param is expected.
+   */
+  // @ts-expect-error return type differs from Param parent class
+  get value(): unknown {
+    return this.active?.value;
+  }
+
+  /**
+   * The value corresponding to a given source. Returns undefined if
+   * this selection does not include a clause from this source.
+   * @param source The clause source to look up the value for.
+   */
+  valueFor(source: unknown): unknown {
+    return this.clauses.find(c => c.source === source)?.value;
+  }
+
+  /**
+   * Emit an activate event with the given selection clause.
+   * @param clause The clause representing the potential activation.
+   */
+  activate(clause: SelectionClause): void {
+    // @ts-expect-error selection operates differently than scalar param
+    this.emit('activate', clause);
+    this._relay.forEach(sel => sel.activate(clause));
+  }
+
+  /**
+   * Update the selection with a new selection clause.
+   * @param clause The selection clause to add.
+   * @returns This Selection instance.
+   */
+  // @ts-expect-error selection and param use differing value types
+  update(clause: SelectionClause): this {
+    // we maintain an up-to-date list of all resolved clauses
+    // this ensures consistent clause state across unemitted event values
+    this._resolved = this._resolver.resolve(this._resolved, clause, true);
+    this._resolved.active = clause;
+    this._relay.forEach(sel => sel.update(clause));
+    return super.update(this._resolved);
+  }
+
+  /**
+   * Reset the selection state by removing all provided clauses. If no clause
+   * array is provided as an argument, all current clauses are removed. The
+   * reset method (if defined) is invoked on all corresponding clause sources.
+   * The reset is relayed to downstream selections that include this selection.
+   * @param clauses The clauses to remove. If unspecified, all current clauses are removed.
+   * @returns This selection instance.
+   */
+  reset(clauses?: SelectionClause[]): this {
+    clauses ??= this._resolved;
+    clauses.forEach(c => c.source?.reset?.());
+    this._resolved = this._resolved.filter(c => clauses!.includes(c));
+    this._relay.forEach(sel => sel.reset(clauses));
+    return super.update(this._resolved = []);
+  }
+
+  /**
+   * Upon value-typed updates, sets the current clause list to the
+   * input value and returns the active clause value.
+   * @param type The event type.
+   * @param value The input event value.
+   * @returns For value-typed events, returns the active clause
+   *  values. Otherwise returns the input event value as-is.
+   */
+  // @ts-expect-error selection and param use differing value types
+  willEmit(type: string, value: unknown): unknown {
+    if (type === 'value') {
+      this._value = value as SelectionClauseArray;
+      return this.value;
+    }
+    return value;
+  }
+
+  /**
+   * Upon value-typed updates, returns a dispatch queue filter function.
+   * The return value depends on the selection resolution strategy.
+   * @param type The event type.
+   * @param value The new event value that will be enqueued.
+   * @returns A dispatch queue filter function. For non-value events,
+   *  returns a function that always returns null (no filtering).
+   */
+  // @ts-expect-error selection and param use differing value types
+  emitQueueFilter(
+    type: string,
+    value: SelectionClauseArray
+  ): ((value: SelectionClauseArray) => boolean) | null {
+    return type === 'value'
+      ? this._resolver.queueFilter(value)
+      : null;
+  }
+
+  /**
+   * Indicates if a selection clause should not be applied to a given client.
+   * The return value depends on the selection resolution strategy.
+   * @param client The client to test.
+   * @param clause The selection clause.
+   * @returns True if the client should be skipped, false otherwise.
+   */
+  skip(client: MosaicClient, clause: SelectionClause): boolean {
+    return this._resolver.skip(client, clause);
+  }
+
+  /**
+   * Return a selection query predicate for the given client.
+   * @param client The client whose data may be filtered.
+   * @param noSkip Disable skipping of active
+   *  cross-filtered sources. If set true, the source of the active
+   *  clause in a cross-filtered selection will not be skipped.
+   * @returns The query predicate for filtering client data,
+   *  based on the current state of this selection.
+   */
+  predicate(client: MosaicClient, noSkip: boolean = false): ResolvedPredicate {
+    const { clauses } = this;
+    const active = noSkip ? null : clauses.active;
+    return this._resolver.predicate(clauses, active!, client);
+  }
+}
+
+/**
+ * Implements selection clause resolution strategies.
+ */
+export class SelectionResolver {
+  union: boolean;
+  cross: boolean;
+  single: boolean;
+  empty: boolean;
+
+  /**
+   * Create a new selection resolved instance.
+   * @param options The resolution strategy options.
+   * @param options.union Boolean flag to indicate a union strategy.
+   *  If false, an intersection strategy is used.
+   * @param options.cross Boolean flag to indicate cross-filtering.
+   * @param options.single Boolean flag to indicate single clauses only.
+   * @param options.empty Boolean flag indicating if a lack
+   *  of clauses should correspond to an empty selection with no records. This
+   *  setting determines the default selection state.
+   */
+  constructor({ union, cross, single, empty }: SelectionResolverOptions = {}) {
+    this.union = !!union;
+    this.cross = !!cross;
+    this.single = !!single;
+    this.empty = !!empty;
+  }
+
+  /**
+   * Resolve a list of selection clauses according to the resolution strategy.
+   * @param clauseList An array of selection clauses.
+   * @param clause A new selection clause to add.
+   * @returns An updated array of selection clauses.
+   */
+  resolve(
+    clauseList: SelectionClause[],
+    clause: SelectionClause,
+    reset: boolean = false
+  ): SelectionClause[] {
+    const { source, predicate } = clause;
+    const filtered = clauseList.filter(c => source !== c.source);
+    const clauses = this.single ? [] : filtered;
+    if (this.single && reset) filtered.forEach(c => c.source?.reset?.());
+    if (predicate) clauses.push(clause);
+    return clauses;
+  }
+
+  /**
+   * Indicates if a selection clause should not be applied to a given client.
+   * The return value depends on the resolution strategy.
+   * @param client The selection clause.
+   * @param clause The client to test.
+   * @returns True if the client should be skipped, false otherwise.
+   */
+  skip(client: MosaicClient, clause: SelectionClause): boolean {
+    return Boolean(this.cross && clause?.clients?.has(client));
+  }
+
+  /**
+   * Return a selection query predicate for the given client.
+   * @param clauseList An array of selection clauses.
+   * @param active The current active selection clause.
+   * @param client The client whose data may be filtered.
+   * @returns The query predicate for filtering client data,
+   *  based on the current state of this selection.
+   */
+  predicate(
+    clauseList: SelectionClause[],
+    active: SelectionClause,
+    client: MosaicClient
+  ): ResolvedPredicate {
+    const { empty, union } = this;
+
+    if (empty && !clauseList.length) {
+      return [literal(false)];
+    }
+
+    // do nothing if cross-filtering and client is currently active
+    if (this.skip(client, active)) return undefined;
+
+    // remove client-specific predicates if cross-filtering
+    const predicates: FilterExpr = clauseList
+      .filter(clause => !this.skip(client, clause))
+      .map(clause => clause.predicate!);
+
+    // return appropriate conjunction or disjunction
+    // an array of predicates is implicitly conjunctive
+    return union && predicates.length > 1 ? or(predicates) : predicates;
+  }
+
+  /**
+   * Returns a filter function for queued selection updates.
+   * @param value The new event value that will be enqueued.
+   * @returns A dispatch queue filter
+   *  function, or null if all unemitted event values should be filtered.
+   */
+  queueFilter(
+    value: SelectionClauseArray
+  ): ((value: SelectionClauseArray) => boolean) | null {
+    if (this.cross) {
+      const source = value.active?.source;
+      return value => value.active?.source !== source;
+    }
+    return null;
+  }
+}