@deephaven-enterprise/query-utils 2026.1.26-- → 2026.1.28--

package/dist/CorePlusManager.d.ts

@@ -0,0 +1,47 @@
+import type { EnterpriseClient, WorkerKind } from '@deephaven-enterprise/jsapi-types';
+import type { dh as DhType } from '@deephaven/jsapi-types';
+/**
+ * Interface defining a connection manager for fetching APIs from and creating connections to CorePlus workers. Implementation may cache values.
+ */
+export interface CorePlusManager {
+    /** The DHE JS API client */
+    get dheClient(): EnterpriseClient;
+    /** Whether this has been disposed. */
+    get isDisposed(): boolean;
+    /** Dispose resources. */
+    dispose(): Promise<void>;
+    /**
+     * Get the API for the specified worker kind.
+     * @param engine The engine to get the API for
+     * @param jsApiUrl The URL to load the API from
+     * @return The API for the specified worker kind
+     */
+    getApi(engine: string, jsApiUrl: string): Promise<typeof DhType>;
+    /**
+     * Get the CoreClient for the specified worker.
+     * @param dh The Core API to create the CoreClient with.
+     * @param grpcUrl The gRPC URL
+     * @param envoyPrefix The envoy prefix
+     * @return The CoreClient for the specified worker kind
+     */
+    getClient(dh: typeof DhType, grpcUrl: string, envoyPrefix?: string | null): Promise<DhType.CoreClient>;
+    /**
+     * Get the IDE connection for the specified worker.
+     * @param dh The Core API to create the CoreClient with.
+     * @param grpcUrl The gRPC URL
+     * @param envoyPrefix The envoy prefix
+     * @return The IDE connection for the specified worker kind
+     */
+    getConnection(dh: typeof DhType, grpcUrl: string, envoyPrefix?: string | null): Promise<DhType.IdeConnection>;
+    /**
+     * Get the worker kind or null for the specified engine.
+     * @param engine The engine to get the worker kind for
+     */
+    getEngineWorkerKind(engine: string): WorkerKind | null;
+    /**
+     * Check if an engine is a community worker kind.
+     * @param engine The engine name to check
+     */
+    isCommunityWorkerKind(engine: string | null): boolean;
+}
+export default CorePlusManager;

package/dist/CorePlusManager.js

@@ -0,0 +1 @@
+export {};

package/dist/QueryStatus.d.ts

@@ -0,0 +1,19 @@
+export declare class QueryStatus {
+    static getDisplayString(status?: string | null): string;
+    static getClassName(status?: string | null): string;
+    static uninitialized: string;
+    static connecting: string;
+    static authenticating: string;
+    static acquiringWorker: string;
+    static initializing: string;
+    static running: string;
+    static failed: string;
+    static error: string;
+    static disconnected: string;
+    static stopping: string;
+    static stopped: string;
+    static completed: string;
+    static executing: string;
+    static none: string;
+}
+export default QueryStatus;

package/dist/QueryStatus.js

@@ -0,0 +1,31 @@
+const NULL_STATUS_STRING = 'None';
+export class QueryStatus {
+    // returns a humanized name from status
+    static getDisplayString(status) {
+        return status != null && status !== QueryStatus.none
+            ? status.replace(/([a-z])([A-Z])/g, '$1 $2')
+            : NULL_STATUS_STRING;
+    }
+    static getClassName(status) {
+        return (status != null && status !== QueryStatus.none
+            ? status.replace(/([a-z])([A-Z])/g, '$1-$2')
+            : NULL_STATUS_STRING).toLowerCase();
+    }
+}
+QueryStatus.uninitialized = 'Uninitialized';
+QueryStatus.connecting = 'Connecting';
+QueryStatus.authenticating = 'Authenticating';
+QueryStatus.acquiringWorker = 'AcquiringWorker';
+QueryStatus.initializing = 'Initializing';
+QueryStatus.running = 'Running';
+QueryStatus.failed = 'Failed';
+QueryStatus.error = 'Error';
+QueryStatus.disconnected = 'Disconnected';
+QueryStatus.stopping = 'Stopping';
+QueryStatus.stopped = 'Stopped';
+QueryStatus.completed = 'Completed';
+QueryStatus.executing = 'Executing';
+// Some queries have a null status which is translated to an empty string for JS
+// This is not an official status but is listed here for clarity
+QueryStatus.none = '';
+export default QueryStatus;

package/dist/QueryUtils.d.ts

@@ -0,0 +1,277 @@
+import type { dh } from '@deephaven/jsapi-types';
+import type { UriVariableDescriptor } from '@deephaven/jsapi-bootstrap';
+import type { EnterpriseClient, EnterpriseDhType, QueryInfo, QueryVariableDescriptor, ReplicaStatus, UserInfo } from '@deephaven-enterprise/jsapi-types';
+import { type Brand } from '@deephaven/utils';
+import DraftQuery, { type DraftQueryConstructorObject } from './DraftQuery';
+import type { CorePlusManager } from './CorePlusManager';
+export type ConsoleType = 'groovy' | 'python';
+export type QuerySerial = Brand<'QuerySerial', string>;
+export declare const DEFAULT_TEMPORARY_QUERY_AUTO_DELETE_TIMEOUT_MS: 600000;
+export declare const DEFAULT_TEMPORARY_QUERY_TIMEOUT_MS: 60000;
+export declare const INTERACTIVE_CONSOLE_TEMPORARY_QUEUE_NAME: "InteractiveConsoleTemporaryQueue";
+export declare const QUERY_TIMEOUT: 10000;
+export declare const MESSAGE_TIMEOUT: 10000;
+/** Configuration type for the Core+ WebClientData query */
+export declare const WEB_CLIENT_DATA_CORE_CONFIG_TYPE: "WebClientData";
+export declare const WEB_CLIENT_DATA_CORE_QUERY: "WebClientData";
+export declare const WEB_CLIENT_TABLE_FACTORY_TYPE: "WebClientTableFactoryService";
+export declare const WEB_CLIENT_TABLE_FACTORY_NAME: "WebClientTableFactory";
+export declare const WEB_CLIENT_REVERT_TABLE_TYPE: "RevertTableProviderService";
+export declare const WEB_CLIENT_REVERT_TABLE_NAME: "RevertTableProvider";
+export declare const WEB_CLIENT_WRITE_OBJECT_NAME: "WorkspaceDataWriter";
+export declare const WEB_CLIENT_WRITE_OBJECT_TYPE: "WorkspaceDataWriterService";
+export declare const QUERY_CONFIG_TABLE: "QueryInfo";
+export declare const SCOPE_CONFIG_TABLE: "ScopeNamesAndType";
+export declare const CATALOG_TABLE: "catalog";
+export declare const FACTORY_SERVICE_TABLES: Set<"QueryInfo" | "ScopeNamesAndType" | "catalog">;
+export type TemporaryDraftQueryConfig = Omit<DraftQueryConstructorObject, 'scheduling' | 'workerKind' | 'type'> & {
+    type: string;
+    engine: string;
+    isCommunityWorker?: boolean;
+};
+export type WebClientData2Response = {
+    id: string;
+    error: string | null;
+};
+export type WebClientData2WriteResponse = WebClientData2Response & {
+    uuids: string[];
+};
+/**
+ * Creates a temporary draft query with auto-delete enabled.
+ *
+ * Temporary queries are automatically scheduled on the InteractiveConsoleTemporaryQueue
+ * and will be deleted when they complete or timeout. This is useful for queries that
+ * should only run once and be cleaned up automatically.
+ *
+ * @param config Configuration object for the temporary draft query
+ * @param config.additionalMemory Additional memory in MB to allocate beyond the heap size (default: 0)
+ * @param config.engine The engine/worker kind to use for the query
+ * @param config.heapSize JVM heap size multiplier (default: 0.5)
+ * @param config.isClientSide Whether this is a client-side query (default: true)
+ * @param config.isCommunityWorker Whether this is a Community (Core+) worker (default: false)
+ * @param config.initializationThreads Number of threads for initialization (Core+ only)
+ * @param config.updateThreads Number of threads for updates (Core+ only)
+ * @param config.timeout Timeout in milliseconds before auto-deletion (default: 60000)
+ * @returns A configured DraftQuery instance ready to be created
+ */
+export declare function createTemporaryDraftQuery({ additionalMemory, engine, heapSize, isClientSide, isCommunityWorker, initializationThreads, updateThreads, timeout, ...config }: TemporaryDraftQueryConfig): DraftQuery;
+/**
+ * Gets the Core+ connection for a given query.
+ *
+ * @param params Function parameters
+ * @param params.query Query to get the connection for
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @returns the Core+ connection for the query
+ * @throws Error if the query is not running or not on a Core+ worker
+ */
+export declare function getCoreConnection({ query, corePlusManager, }: {
+    query: QueryInfo;
+    corePlusManager: CorePlusManager;
+}): Promise<dh.IdeConnection>;
+/**
+ * Get QueryInfo for a string which may be the query name or its serial.
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryNameOrSerial String representing either the query name or serial, but we don't know which it is.
+ * @returns QueryInfo for the specified query
+ * @throws Error if the query is not found
+ */
+export declare function getQueryInfoForNameOrSerial({ client, dh, queryNameOrSerial, }: {
+    client: EnterpriseClient;
+    dh: EnterpriseDhType;
+    queryNameOrSerial: string;
+}): Promise<QueryInfo>;
+/**
+ * Get ObjectDefinition from a query by object name
+ * @param query Query
+ * @param name The name of the object to fetch
+ * @returns Resolves to the object definition
+ */
+export declare function getQueryObjectDefinitionByName(query: QueryInfo, name: string): dh.ide.VariableDefinition;
+/**
+ * Get replica or spare worker for a given slot. If slot is null, returns the designated worker.
+ * @param query Query to get the worker from
+ * @param slot The slot to get the worker for
+ * @returns Resolves to the ReplicaStatus
+ */
+export declare function getWorkerForSlot(query: QueryInfo, slot?: number | null): ReplicaStatus | undefined;
+/**
+ * Indicates that a table should be fetched from the WebClientTableFactoryService rather than the query scope.
+ *
+ * @param tableName the name of the table
+ * @returns true if the table is a factory service table, false otherwise
+ */
+export declare function isFactoryServiceTable(tableName: string): boolean;
+/**
+ * Turns a URI into a QueryVariableDescriptor
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.dh Deephaven Enterprise API
+ * @param params.uri The URI to convert to a descriptor
+ * @returns A promise that resolves to the query variable descriptor
+ * @throws Error if the URI is invalid, not found, or an unsupported protocol
+ */
+export declare function makeDescriptorFromUri({ client, dh, uri, }: {
+    client: EnterpriseClient;
+    dh: EnterpriseDhType;
+    uri: UriVariableDescriptor;
+}): Promise<QueryVariableDescriptor>;
+/**
+ * Get a table from the WebClientData Core+ WebClientTableFactoryService
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.userInfo User information
+ * @param params.tableName Table name to get
+ * @returns Promise for the table
+ */
+export declare function makeFactoryServiceTablePromise({ client, corePlusManager, dh, userInfo, tableName, }: {
+    client: EnterpriseClient;
+    corePlusManager: CorePlusManager;
+    dh: EnterpriseDhType;
+    userInfo: UserInfo;
+    tableName?: string;
+}): Promise<dh.Table>;
+/**
+ * Creates PQ Query Promise
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryName Query name
+ * @param params.querySerial Serial to check - if present, will use this instead of name to match
+ * @returns A promise for the query
+ */
+export declare function makeQueryPromise({ client, dh, queryName, querySerial, }: {
+    client: EnterpriseClient;
+    dh: EnterpriseDhType;
+    queryName: string | undefined;
+    querySerial?: string | null;
+}): Promise<QueryInfo>;
+/**
+ * Creates PQ Query Object Promise
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryName Query name to fetch
+ * @param params.querySerial Serial to check - if present, will use this instead of name to match
+ * @param params.objectDescriptor The descriptor of the object to fetch
+ * @param params.replicaSlot The replica slot to use, if null will use the designated worker
+ * @returns Resolves to the object fetched
+ */
+export declare function makeQueryObjectPromise<T = unknown>({ client, corePlusManager, dh, queryName, querySerial, objectDescriptor, replicaSlot, }: {
+    client: EnterpriseClient;
+    corePlusManager: CorePlusManager;
+    dh: EnterpriseDhType;
+    queryName: string | null | undefined;
+    querySerial: string | null | undefined;
+    objectDescriptor: dh.ide.VariableDescriptor;
+    replicaSlot?: number;
+}): Promise<T>;
+/**
+ * Creates PQ Table Promise
+ * Should use makeQueryObjectPromise when possible instead.
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryName Query name
+ * @param params.querySerial Query serial
+ * @param params.tableName Table name
+ * @returns A promise for the table or tree table
+ */
+export declare function makeQueryTablePromise({ client, corePlusManager, dh, queryName, querySerial, tableName, }: {
+    client: EnterpriseClient;
+    corePlusManager: CorePlusManager;
+    dh: EnterpriseDhType;
+    queryName: string;
+    querySerial: string | null | undefined;
+    tableName: string;
+}): Promise<dh.Table | dh.TreeTable>;
+/**
+ * Retrieves a table with the revision history for a given query.
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.serial Serial of the query to get the revision history for.
+ * @returns A promise for the revision history table.
+ */
+export declare function makeRevertTablePromise({ client, corePlusManager, dh, serial, }: {
+    client: EnterpriseClient;
+    corePlusManager: CorePlusManager;
+    dh: EnterpriseDhType;
+    serial: string;
+}): Promise<dh.Table>;
+/**
+ * Sends a message to a WebClientData2 widget and returns a promise that resolves to the event detail.
+ *
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.messageId the ID of the message to send
+ * @param params.message the message to send
+ * @param params.type the type of the widget to send the message to
+ * @param params.name the name of the widget to send the message to
+ * @returns the event detail from the response
+ */
+export declare function sendWebClientData2Message<T extends WebClientData2Response>({ client, corePlusManager, dh, messageId, message, type, name, }: {
+    client: EnterpriseClient;
+    corePlusManager: CorePlusManager;
+    dh: EnterpriseDhType;
+    messageId: string;
+    message: string;
+    type: string;
+    name: string;
+}): Promise<[T, dh.WidgetMessageDetails]>;
+/**
+ * Sends a message to a widget on a Core+ query. Will call the provided callback with the event.
+ * It is the responsibility of the calling code to determine if the message is correct and to clean up the event listener.
+ * This method will time out after a set period if the message is not received.
+ *
+ * TODO: DH-20345: There are a number of issues with this function not properly
+ * handling Promise rejections and timeouts. Since it returns `void`, there is
+ * no way for an upstream caller to handle errors or even know about them.
+ *
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.message the message to send
+ * @param params.onEventCallback the callback to handle the event when the message is received
+ * @param params.queryName the name of the query to send the message to, null if using serial
+ * @param params.querySerial the serial of the query to send the message to, null if using name
+ * @param params.objectDefinition the definition of the widget to send the message to
+ * @param params.replicaSlot the replica slot to send the message to, if null will use the designated worker
+ */
+export declare function sendWidgetMessage({ client, corePlusManager, dh, message, onEventCallback, queryName, querySerial, objectDefinition, replicaSlot, }: {
+    client: EnterpriseClient;
+    corePlusManager: CorePlusManager;
+    dh: EnterpriseDhType;
+    message: string;
+    onEventCallback: (event: dh.Event<dh.WidgetMessageDetails>, cleanupFn: () => void) => void;
+    queryName: string | null | undefined;
+    querySerial: string | null | undefined;
+    objectDefinition: dh.ide.VariableDescriptor;
+    replicaSlot?: number;
+}): void;
+/**
+ * Starts a query and returns a promise that resolves when the query starts running.
+ *
+ * This function:
+ * - Creates the query on the server
+ * - Listens for status updates
+ * - Auto-starts temporary queries (which don't start automatically)
+ * - Resolves when the query reaches running status
+ * - Rejects if the query fails to start
+ *
+ * @param dh Deephaven Enterprise API
+ * @param client Enterprise client to create the query with
+ * @param draftQuery Draft query configuration to start
+ * @returns Promise that resolves to the QueryInfo when the query starts running
+ * @throws Error if the query fails to start or encounters an error
+ */
+export declare function startQuery(dh: EnterpriseDhType, client: EnterpriseClient, draftQuery: DraftQuery): Promise<QueryInfo>;

package/dist/QueryUtils.js

@@ -0,0 +1,553 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { InvalidMetadataError } from '@deephaven/utils';
+import Log from '@deephaven/log';
+import { nanoid } from 'nanoid';
+import QueryScheduler from './QueryScheduler';
+import DraftQuery from './DraftQuery';
+import { WorkerThreadUtils } from './WorkerThreadUtils';
+import { QueryStatus } from './QueryStatus';
+const log = Log.module('QueryUtils');
+// 600 seconds is based on default `auto_delete_timeout` in
+// `ControllerClient.make_temporary_config`
+export const DEFAULT_TEMPORARY_QUERY_AUTO_DELETE_TIMEOUT_MS = 600000;
+export const DEFAULT_TEMPORARY_QUERY_TIMEOUT_MS = 60000;
+export const INTERACTIVE_CONSOLE_TEMPORARY_QUEUE_NAME = 'InteractiveConsoleTemporaryQueue';
+// Query interaction constants
+export const QUERY_TIMEOUT = 10000;
+export const MESSAGE_TIMEOUT = 10000;
+/** Configuration type for the Core+ WebClientData query */
+export const WEB_CLIENT_DATA_CORE_CONFIG_TYPE = 'WebClientData';
+// Name of the Core+ WebClientData query. Used for reading and writing workspace data.
+export const WEB_CLIENT_DATA_CORE_QUERY = 'WebClientData';
+export const WEB_CLIENT_TABLE_FACTORY_TYPE = 'WebClientTableFactoryService';
+export const WEB_CLIENT_TABLE_FACTORY_NAME = 'WebClientTableFactory';
+export const WEB_CLIENT_REVERT_TABLE_TYPE = 'RevertTableProviderService';
+export const WEB_CLIENT_REVERT_TABLE_NAME = 'RevertTableProvider';
+export const WEB_CLIENT_WRITE_OBJECT_NAME = 'WorkspaceDataWriter';
+export const WEB_CLIENT_WRITE_OBJECT_TYPE = 'WorkspaceDataWriterService';
+export const QUERY_CONFIG_TABLE = 'QueryInfo';
+export const SCOPE_CONFIG_TABLE = 'ScopeNamesAndType';
+export const CATALOG_TABLE = 'catalog';
+export const FACTORY_SERVICE_TABLES = new Set([
+    QUERY_CONFIG_TABLE,
+    SCOPE_CONFIG_TABLE,
+    CATALOG_TABLE,
+]);
+/**
+ * Creates a temporary draft query with auto-delete enabled.
+ *
+ * Temporary queries are automatically scheduled on the InteractiveConsoleTemporaryQueue
+ * and will be deleted when they complete or timeout. This is useful for queries that
+ * should only run once and be cleaned up automatically.
+ *
+ * @param config Configuration object for the temporary draft query
+ * @param config.additionalMemory Additional memory in MB to allocate beyond the heap size (default: 0)
+ * @param config.engine The engine/worker kind to use for the query
+ * @param config.heapSize JVM heap size multiplier (default: 0.5)
+ * @param config.isClientSide Whether this is a client-side query (default: true)
+ * @param config.isCommunityWorker Whether this is a Community (Core+) worker (default: false)
+ * @param config.initializationThreads Number of threads for initialization (Core+ only)
+ * @param config.updateThreads Number of threads for updates (Core+ only)
+ * @param config.timeout Timeout in milliseconds before auto-deletion (default: 60000)
+ * @returns A configured DraftQuery instance ready to be created
+ */
+export function createTemporaryDraftQuery(_a) {
+    var { additionalMemory = 0, engine, heapSize = 0.5, isClientSide = true, isCommunityWorker = false, initializationThreads, updateThreads, timeout = DEFAULT_TEMPORARY_QUERY_TIMEOUT_MS } = _a, config = __rest(_a, ["additionalMemory", "engine", "heapSize", "isClientSide", "isCommunityWorker", "initializationThreads", "updateThreads", "timeout"]);
+    const scheduling = QueryScheduler.makeTemporaryScheduling({
+        autoDelete: true,
+        queueName: INTERACTIVE_CONSOLE_TEMPORARY_QUEUE_NAME,
+    });
+    const draftQuery = new DraftQuery(Object.assign(Object.assign({}, config), { additionalMemory,
+        heapSize,
+        isClientSide,
+        scheduling,
+        timeout, workerKind: engine, 
+        // TODO: DH-22081: createTemporaryDraftQuery converts initializationThreads/
+        // updateThreads with WorkerThreadUtils.getValue(...) before storing them on
+        // the DraftQuery. DraftQuery later calls WorkerThreadUtils.addArgs, which
+        // expects display strings
+        initializationThreads: isCommunityWorker && initializationThreads != null
+            ? WorkerThreadUtils.getValue(initializationThreads)
+            : undefined, updateThreads: isCommunityWorker && updateThreads != null
+            ? WorkerThreadUtils.getValue(updateThreads)
+            : undefined }));
+    draftQuery.addThreadCountToJVMArgs();
+    draftQuery.updateSchedule();
+    return draftQuery;
+}
+/**
+ * Gets the Core+ connection for a given query.
+ *
+ * @param params Function parameters
+ * @param params.query Query to get the connection for
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @returns the Core+ connection for the query
+ * @throws Error if the query is not running or not on a Core+ worker
+ */
+export function getCoreConnection({ query, corePlusManager, }) {
+    const designated = getWorkerForSlot(query);
+    if (designated == null || designated.status !== QueryStatus.running) {
+        throw new Error(`Query ${query.name} is not running.`);
+    }
+    // Sending a message to a widget requires a Core+ worker
+    if (!corePlusManager.isCommunityWorkerKind(query.workerKind)) {
+        throw new Error(`Query ${query.name} is not running on a Core+ worker.`);
+    }
+    const { grpcUrl, envoyPrefix, jsApiUrl } = designated;
+    return corePlusManager
+        .getApi(query.workerKind, jsApiUrl)
+        .then(api => corePlusManager.getConnection(api, grpcUrl, envoyPrefix));
+}
+/**
+ * Get QueryInfo for a string which may be the query name or its serial.
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryNameOrSerial String representing either the query name or serial, but we don't know which it is.
+ * @returns QueryInfo for the specified query
+ * @throws Error if the query is not found
+ */
+export async function getQueryInfoForNameOrSerial({ client, dh, queryNameOrSerial, }) {
+    try {
+        return await makeQueryPromise({
+            client,
+            dh,
+            queryName: undefined,
+            querySerial: queryNameOrSerial,
+        });
+    }
+    catch (error) {
+        log.debug(`${queryNameOrSerial} not found as a serial. Trying as a name.`);
+    }
+    return makeQueryPromise({
+        client,
+        dh,
+        queryName: queryNameOrSerial,
+        querySerial: undefined,
+    });
+}
+/**
+ * Get ObjectDefinition from a query by object name
+ * @param query Query
+ * @param name The name of the object to fetch
+ * @returns Resolves to the object definition
+ */
+export function getQueryObjectDefinitionByName(query, name) {
+    var _a;
+    // Non-running queries don't list the objects
+    if (((_a = query.designated) === null || _a === void 0 ? void 0 : _a.status) !== QueryStatus.running) {
+        throw new Error(`Query ${query.name} isn't running.`);
+    }
+    const objectDefinition = query.designated.objects.find(o => o.title === name);
+    if (objectDefinition == null) {
+        throw new Error(`Object ${name} not found in query ${query.name}.`);
+    }
+    return objectDefinition;
+}
+/**
+ * Get replica or spare worker for a given slot. If slot is null, returns the designated worker.
+ * @param query Query to get the worker from
+ * @param slot The slot to get the worker for
+ * @returns Resolves to the ReplicaStatus
+ */
+export function getWorkerForSlot(query, slot) {
+    if (slot == null) {
+        return query.designated;
+    }
+    if (slot < 0) {
+        return query.spares[-slot - 1];
+    }
+    return query.replicas[slot];
+}
+/**
+ * Indicates that a table should be fetched from the WebClientTableFactoryService rather than the query scope.
+ *
+ * @param tableName the name of the table
+ * @returns true if the table is a factory service table, false otherwise
+ */
+export function isFactoryServiceTable(tableName) {
+    return FACTORY_SERVICE_TABLES.has(tableName);
+}
+/**
+ * Turns a URI into a QueryVariableDescriptor
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.dh Deephaven Enterprise API
+ * @param params.uri The URI to convert to a descriptor
+ * @returns A promise that resolves to the query variable descriptor
+ * @throws Error if the URI is invalid, not found, or an unsupported protocol
+ */
+export async function makeDescriptorFromUri({ client, dh, uri, }) {
+    var _a;
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch (e) {
+        throw new Error(`Invalid URI: ${uri}. Did you forget to URI encode it?`);
+    }
+    const protocol = url.protocol.slice(0, -1); // Remove the trailing ':'
+    const querySerialOrName = decodeURIComponent(url.hostname);
+    const pathName = decodeURIComponent(url.pathname);
+    const widgetName = pathName.replace(/^\/scope\//, '');
+    if (protocol !== 'pq') {
+        throw new Error(`Unsupported URI protocol: ${protocol}`);
+    }
+    if (!pathName.startsWith('/scope/')) {
+        throw new Error(`Expected PQ URI path to start with /scope/. Got ${pathName}`);
+    }
+    const queryInfo = await getQueryInfoForNameOrSerial({
+        client,
+        dh,
+        queryNameOrSerial: querySerialOrName,
+    });
+    const variableDefinition = (_a = queryInfo.designated) === null || _a === void 0 ? void 0 : _a.objects.find(obj => obj.name === widgetName);
+    if (!variableDefinition) {
+        throw new Error(`Query ${querySerialOrName} (Serial: ${queryInfo.serial}) does not have widget named ${widgetName}`);
+    }
+    return {
+        querySerial: queryInfo.serial,
+        query: queryInfo.name,
+        name: widgetName,
+        type: variableDefinition.type,
+    };
+}
+/**
+ * Get a table from the WebClientData Core+ WebClientTableFactoryService
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.userInfo User information
+ * @param params.tableName Table name to get
+ * @returns Promise for the table
+ */
+export async function makeFactoryServiceTablePromise({ client, corePlusManager, dh, userInfo, tableName = QUERY_CONFIG_TABLE, }) {
+    // This message id is used to correlate the message sent to the workspace widget
+    const messageId = nanoid();
+    const message = JSON.stringify({
+        id: messageId,
+        user: userInfo.operateAs,
+        tableNames: [tableName],
+    });
+    const [, eventDetail] = await sendWebClientData2Message({
+        client,
+        corePlusManager,
+        dh,
+        messageId,
+        message,
+        type: WEB_CLIENT_TABLE_FACTORY_TYPE,
+        name: WEB_CLIENT_TABLE_FACTORY_NAME,
+    });
+    if (eventDetail.exportedObjects.length < 1) {
+        throw new Error('No objects exported from the widget');
+    }
+    const table = await eventDetail.exportedObjects[0].fetch();
+    return table;
+}
+/**
+ * Creates PQ Query Promise
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryName Query name
+ * @param params.querySerial Serial to check - if present, will use this instead of name to match
+ * @returns A promise for the query
+ */
+export async function makeQueryPromise({ client, dh, queryName, querySerial, }) {
+    function getMatchingQuery(queries) {
+        return querySerial !== undefined
+            ? queries.find(query => query.serial === querySerial)
+            : queries.find(query => query.name === queryName);
+    }
+    function waitForAddedQuery() {
+        return new Promise((resolve, reject) => {
+            let removeListener;
+            const timeout = setTimeout(() => {
+                reject(new Error(`Query ${querySerial !== null && querySerial !== void 0 ? querySerial : queryName} not found or you do not have access.`));
+                removeListener === null || removeListener === void 0 ? void 0 : removeListener();
+            }, QUERY_TIMEOUT);
+            function handleConfigAdded(event) {
+                const addedQueries = [event === null || event === void 0 ? void 0 : event.detail];
+                const matchingQuery = getMatchingQuery(addedQueries);
+                if (matchingQuery) {
+                    resolve(matchingQuery);
+                    clearTimeout(timeout);
+                    removeListener === null || removeListener === void 0 ? void 0 : removeListener();
+                }
+            }
+            removeListener = client.addEventListener(dh.Client.EVENT_CONFIG_ADDED, handleConfigAdded);
+        });
+    }
+    if (querySerial == null && queryName == null) {
+        throw new InvalidMetadataError('Invalid query');
+    }
+    // Get the query from the known configs,
+    const matchingQuery = getMatchingQuery(client.getKnownConfigs());
+    if (matchingQuery) {
+        return matchingQuery;
+    }
+    if (queryName === WEB_CLIENT_DATA_CORE_QUERY) {
+        // WebClientData is a special case - try and wait for it to become available
+        return waitForAddedQuery();
+    }
+    throw new Error(`Query ${querySerial !== null && querySerial !== void 0 ? querySerial : queryName} not found or you do not have access.`);
+}
+/**
+ * Creates PQ Query Object Promise
+ * @param params Function parameters
+ * @param params.client Enterprise client to use
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryName Query name to fetch
+ * @param params.querySerial Serial to check - if present, will use this instead of name to match
+ * @param params.objectDescriptor The descriptor of the object to fetch
+ * @param params.replicaSlot The replica slot to use, if null will use the designated worker
+ * @returns Resolves to the object fetched
+ */
+export async function makeQueryObjectPromise({ client, corePlusManager, dh, queryName, querySerial, objectDescriptor, replicaSlot, }) {
+    const query = await makeQueryPromise({
+        client,
+        dh,
+        queryName: queryName !== null && queryName !== void 0 ? queryName : undefined,
+        querySerial: querySerial !== null && querySerial !== void 0 ? querySerial : undefined,
+    });
+    const designated = getWorkerForSlot(query, replicaSlot);
+    if (designated == null || designated.status !== QueryStatus.running) {
+        throw new Error(`Query ${query.name} is not running.`);
+    }
+    if (corePlusManager.isCommunityWorkerKind(query.workerKind)) {
+        const { grpcUrl, envoyPrefix, jsApiUrl } = designated;
+        const api = await corePlusManager.getApi(query.workerKind, jsApiUrl);
+        const coreConnection = await corePlusManager.getConnection(api, grpcUrl, envoyPrefix);
+        // DH-20545: We shouldn't pass the object definition we got from the Enterprise QueryInfo object directly to Core connection.getObject, as they may be incompatible.
+        return coreConnection.getObject({
+            name: objectDescriptor.name,
+            type: objectDescriptor.type,
+        });
+    }
+    return designated.getObject(objectDescriptor);
+}
+/**
+ * Creates PQ Table Promise
+ * Should use makeQueryObjectPromise when possible instead.
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.queryName Query name
+ * @param params.querySerial Query serial
+ * @param params.tableName Table name
+ * @returns A promise for the table or tree table
+ */
+export async function makeQueryTablePromise({ client, corePlusManager, dh, queryName, querySerial, tableName, }) {
+    var _a;
+    const query = await makeQueryPromise({
+        client,
+        dh,
+        queryName,
+        querySerial: querySerial !== null && querySerial !== void 0 ? querySerial : undefined,
+    });
+    if (query.designated == null ||
+        query.designated.status !== QueryStatus.running) {
+        throw new Error(`Query ${queryName} is not running.`);
+    }
+    const isTreeTable = ((_a = query.designated.objects.find(({ name }) => name === tableName)) === null || _a === void 0 ? void 0 : _a.type) ===
+        dh.VariableType.TREETABLE;
+    const { designated } = query;
+    if (corePlusManager.isCommunityWorkerKind(query.workerKind)) {
+        const { grpcUrl, envoyPrefix, jsApiUrl } = designated;
+        const api = await corePlusManager.getApi(query.workerKind, jsApiUrl);
+        const coreConnection = await corePlusManager.getConnection(api, grpcUrl, envoyPrefix);
+        return coreConnection.getObject({
+            type: isTreeTable ? dh.VariableType.TREETABLE : dh.VariableType.TABLE,
+            name: tableName,
+        });
+    }
+    return isTreeTable
+        ? designated.getTreeTable(tableName)
+        : designated.getTable(tableName);
+}
+/**
+ * Retrieves a table with the revision history for a given query.
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.serial Serial of the query to get the revision history for.
+ * @returns A promise for the revision history table.
+ */
+export async function makeRevertTablePromise({ client, corePlusManager, dh, serial, }) {
+    const messageId = nanoid();
+    const message = JSON.stringify({
+        id: messageId,
+        serial,
+    });
+    const [, eventDetail] = await sendWebClientData2Message({
+        client,
+        corePlusManager,
+        dh,
+        messageId,
+        message,
+        type: WEB_CLIENT_REVERT_TABLE_TYPE,
+        name: WEB_CLIENT_REVERT_TABLE_NAME,
+    });
+    if (eventDetail.exportedObjects.length < 1) {
+        throw new Error('No objects exported from the widget');
+    }
+    const table = await eventDetail.exportedObjects[0].fetch();
+    return table;
+}
+/**
+ * Sends a message to a WebClientData2 widget and returns a promise that resolves to the event detail.
+ *
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.messageId the ID of the message to send
+ * @param params.message the message to send
+ * @param params.type the type of the widget to send the message to
+ * @param params.name the name of the widget to send the message to
+ * @returns the event detail from the response
+ */
+export function sendWebClientData2Message({ client, corePlusManager, dh, messageId, message, type, name, }) {
+    return new Promise((resolve, reject) => {
+        // Handle message events from the workspace widget
+        const handleMessageEvent = (event, cleanupFn) => {
+            const eventDetail = JSON.parse(event.detail.getDataAsString());
+            // Only handle the message if the ID matches
+            if (eventDetail.id === messageId) {
+                // We're handling the message, so we can clean up
+                cleanupFn();
+                if (eventDetail.error != null) {
+                    log.error(`Error returned from ${name}:`, eventDetail.error);
+                    reject(new Error(eventDetail.error));
+                    return;
+                }
+                resolve([eventDetail, event.detail]);
+            }
+        };
+        sendWidgetMessage({
+            client,
+            corePlusManager,
+            dh,
+            message,
+            onEventCallback: handleMessageEvent,
+            queryName: WEB_CLIENT_DATA_CORE_QUERY,
+            querySerial: null,
+            objectDefinition: {
+                type,
+                name,
+            },
+        });
+    });
+}
+/**
+ * Sends a message to a widget on a Core+ query. Will call the provided callback with the event.
+ * It is the responsibility of the calling code to determine if the message is correct and to clean up the event listener.
+ * This method will time out after a set period if the message is not received.
+ *
+ * TODO: DH-20345: There are a number of issues with this function not properly
+ * handling Promise rejections and timeouts. Since it returns `void`, there is
+ * no way for an upstream caller to handle errors or even know about them.
+ *
+ * @param params Function parameters
+ * @param params.client Enterprise client
+ * @param params.corePlusManager CorePlus manager for worker connections
+ * @param params.dh Deephaven Enterprise API
+ * @param params.message the message to send
+ * @param params.onEventCallback the callback to handle the event when the message is received
+ * @param params.queryName the name of the query to send the message to, null if using serial
+ * @param params.querySerial the serial of the query to send the message to, null if using name
+ * @param params.objectDefinition the definition of the widget to send the message to
+ * @param params.replicaSlot the replica slot to send the message to, if null will use the designated worker
+ */
+export function sendWidgetMessage({ client, corePlusManager, dh, message, onEventCallback, queryName, querySerial, objectDefinition, replicaSlot, }) {
+    makeQueryPromise({
+        client,
+        dh,
+        queryName: queryName !== null && queryName !== void 0 ? queryName : undefined,
+        querySerial: querySerial !== null && querySerial !== void 0 ? querySerial : undefined,
+    }).then(async (query) => {
+        const designated = getWorkerForSlot(query, replicaSlot);
+        if (designated == null || designated.status !== QueryStatus.running) {
+            throw new Error(`Query ${query.name} is not running.`);
+        }
+        // Sending a message to a widget requires a Core+ worker
+        if (!corePlusManager.isCommunityWorkerKind(query.workerKind)) {
+            throw new Error(`Query ${query.name} is not running on a Core+ worker.`);
+        }
+        const { grpcUrl, envoyPrefix, jsApiUrl } = designated;
+        const api = await corePlusManager.getApi(query.workerKind, jsApiUrl);
+        const coreConnection = await corePlusManager.getConnection(api, grpcUrl, envoyPrefix);
+        const widget = (await coreConnection.getObject(objectDefinition));
+        // Set a timeout for the message to be received
+        // TODO: DH-20345: This timeout doesn't properly cleanup or surface an error
+        // to the caller.
+        const timeoutId = setTimeout(() => {
+            // This logs a warning rather than throwing an error because the message may still be received later and to avoid breaking the UI
+            log.warn(`No response from the server after ${MESSAGE_TIMEOUT}ms for message: ${message}`);
+        }, MESSAGE_TIMEOUT);
+        // Messages may come out of order, so the calling code is responsible for determining if the message is correct and clean up
+        const removeListener = widget.addEventListener(api.Widget.EVENT_MESSAGE, event => onEventCallback(event, () => {
+            clearTimeout(timeoutId);
+            removeListener();
+            widget.close();
+        }));
+        widget.sendMessage(message);
+    });
+}
+/**
+ * Starts a query and returns a promise that resolves when the query starts running.
+ *
+ * This function:
+ * - Creates the query on the server
+ * - Listens for status updates
+ * - Auto-starts temporary queries (which don't start automatically)
+ * - Resolves when the query reaches running status
+ * - Rejects if the query fails to start
+ *
+ * @param dh Deephaven Enterprise API
+ * @param client Enterprise client to create the query with
+ * @param draftQuery Draft query configuration to start
+ * @returns Promise that resolves to the QueryInfo when the query starts running
+ * @throws Error if the query fails to start or encounters an error
+ */
+export async function startQuery(dh, client, draftQuery) {
+    const serial = await client.createQuery(draftQuery);
+    const queryInfoPromise = new Promise((resolve, reject) => {
+        const removeEventListener = client.addEventListener(dh.Client.EVENT_CONFIG_UPDATED, ({ detail }) => {
+            var _a, _b, _c, _d;
+            if (detail.serial !== serial) {
+                return;
+            }
+            if (((_a = detail.designated) === null || _a === void 0 ? void 0 : _a.status) === QueryStatus.running) {
+                removeEventListener();
+                resolve(detail);
+            }
+            if (((_b = detail.designated) === null || _b === void 0 ? void 0 : _b.status) === QueryStatus.error ||
+                ((_c = detail.designated) === null || _c === void 0 ? void 0 : _c.status) === QueryStatus.failed) {
+                removeEventListener();
+                reject(new Error('Query failed to start', {
+                    cause: (_d = detail.designated) === null || _d === void 0 ? void 0 : _d.shortCauses,
+                }));
+            }
+        });
+    });
+    // Temporary queries don't auto start, so we need to start it manually.
+    if (draftQuery.scheduler.type === QueryScheduler.TYPES.TEMPORARY) {
+        client.restartQueries([serial]);
+    }
+    return queryInfoPromise;
+}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
+export * from './CorePlusManager';
 export * from './DraftQuery';
 export * from './QueryColumns';
 export * from './QueryDisplayType';
 export * from './QueryScheduler';
 export * from './QuerySchedulerValidation';
+export * from './QueryStatus';
 export * from './QueryType';
+export * from './QueryUtils';
 export * from './WorkerThreadUtils';

package/dist/index.js

@@ -1,7 +1,10 @@
+export * from './CorePlusManager';
 export * from './DraftQuery';
 export * from './QueryColumns';
 export * from './QueryDisplayType';
 export * from './QueryScheduler';
 export * from './QuerySchedulerValidation';
+export * from './QueryStatus';
 export * from './QueryType';
+export * from './QueryUtils';
 export * from './WorkerThreadUtils';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deephaven-enterprise/query-utils",
-  "version": "2026.1.26--",
+  "version": "2026.1.28--",
   "description": "Deephaven Enterprise Query Utils",
   "author": "Deephaven Data Labs LLC",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@deephaven/jsapi-types": "^1.0.0-dev0.36.1",
+    "@deephaven-enterprise/jsapi-types": "file:../jsapi-types",
     "@deephaven/log": "^0.97.0",
     "@deephaven/utils": "^0.97.0",
     "@internationalized/date": "^3.5.5",