@malloydata/malloy 0.0.335 → 0.0.337

package/dist/api/foundation/runtime.d.ts

@@ -0,0 +1,361 @@
+import type { Connection, LookupConnection } from '../../connection/types';
+import type { URLReader, EventStream } from '../../runtime_types';
+import type { ModelDef, Query as InternalQuery, SearchIndexResult, SearchValueMapResult, QueryRunStats } from '../../model';
+import type { Dialect } from '../../dialect';
+import type { RunSQLOptions } from '../../run_sql_options';
+import type { CacheManager } from './cache';
+import type { ParseOptions, CompileOptions, CompileQueryOptions } from './types';
+import type { PreparedResult, Explore } from './core';
+import { Model, PreparedQuery } from './core';
+import type { DataRecord, Result } from './result';
+type ModelURL = URL;
+type ModelString = string;
+type QueryURL = URL;
+type QueryString = string;
+type Connectionable = {
+    connection: Connection;
+    connections?: undefined;
+} | {
+    connections: LookupConnection<Connection>;
+    connection?: undefined;
+};
+declare class FluentState<T> {
+    protected runtime: Runtime;
+    private readonly _materialize;
+    private materialized;
+    constructor(runtime: Runtime, materialize: () => Promise<T>);
+    protected materialize(): Promise<T>;
+    protected rematerialize(): Promise<T>;
+    protected makeQueryMaterializer(materialize: () => Promise<PreparedQuery>, options?: CompileQueryOptions): QueryMaterializer;
+    protected makeExploreMaterializer(materialize: () => Promise<Explore>, options?: CompileQueryOptions): ExploreMaterializer;
+    protected makePreparedResultMaterializer(materialize: () => Promise<PreparedResult>): PreparedResultMaterializer;
+}
+/**
+ * An environment for compiling and running Malloy queries.
+ */
+export declare class Runtime {
+    isTestRuntime: boolean;
+    private _urlReader;
+    private _connections;
+    private _eventStream;
+    private _cacheManager;
+    constructor({ urlReader, connections, connection, eventStream, cacheManager, }: {
+        urlReader?: URLReader;
+        eventStream?: EventStream;
+        cacheManager?: CacheManager;
+    } & Connectionable);
+    /**
+     * @return The `CacheManager` for this runtime instance.
+     */
+    get cacheManager(): CacheManager | undefined;
+    /**
+     * @return The `URLReader` for this runtime instance.
+     */
+    get urlReader(): URLReader;
+    /**
+     * @return The `LookupConnection<Connection>` for this runtime instance.
+     */
+    get connections(): LookupConnection<Connection>;
+    /**
+     * @return The `EventStream` for this runtime instance.
+     */
+    get eventStream(): EventStream | undefined;
+    /**
+     * Load a Malloy model by URL or contents.
+     *
+     * @param source The model URL or contents to load and (eventually) compile.
+     * @return A `ModelMaterializer` capable of materializing the requested model,
+     * or loading further related objects.
+     */
+    loadModel(source: ModelURL | ModelString, options?: ParseOptions & CompileOptions & CompileQueryOptions): ModelMaterializer;
+    _loadModelFromModelDef(modelDef: ModelDef, options?: CompileQueryOptions): ModelMaterializer;
+    /**
+     * Load a Malloy query by URL or contents.
+     *
+     * @param query The query URL or contents to load and (eventually) compile.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQuery(query: QueryURL | QueryString, options?: ParseOptions & CompileOptions & CompileQueryOptions): QueryMaterializer;
+    /**
+     * Load a Malloy query by the URL or contents of a Malloy model document
+     * and the index of an unnamed query contained in the model.
+     *
+     * @param model The model URL or contents to load and (eventually) compile to retrieve the requested query.
+     * @param index The index of the query to use within the model.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQueryByIndex(model: ModelURL | ModelString, index: number, options?: ParseOptions & CompileOptions & CompileQueryOptions): QueryMaterializer;
+    /**
+     * Load a Malloy query by the URL or contents of a Malloy model document
+     * and the name of a query contained in the model.
+     *
+     * @param model The model URL or contents to load and (eventually) compile to retrieve the requested query.
+     * @param name The name of the query to use within the model.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQueryByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions & CompileQueryOptions): QueryMaterializer;
+    /**
+     * Compile a Malloy model by URL or contents.
+     *
+     * @param source The URL or contents of a Malloy model document to compile.
+     * @return A promise of a compiled `Model`.
+     */
+    getModel(source: ModelURL | ModelString, options?: ParseOptions & CompileOptions): Promise<Model>;
+    /**
+     * Compile a Malloy query by URL or contents.
+     *
+     * @param query The URL or contents of a Malloy query document to compile.
+     * @return A promise of a compiled `PreparedQuery`.
+     */
+    getQuery(query: QueryURL | QueryString, options?: ParseOptions & CompileOptions): Promise<PreparedQuery>;
+    /**
+     * Compile a Malloy query by the URL or contents of a model document
+     * and the index of an unnamed query contained within the model.
+     *
+     * @param model The URL or contents of a Malloy model document to compile.
+     * @param index The index of an unnamed query contained within the model.
+     * @return A promise of a compiled `PreparedQuery`.
+     */
+    getQueryByIndex(model: ModelURL | ModelString, index: number, options?: ParseOptions & CompileOptions): Promise<PreparedQuery>;
+    /**
+     * Compile a Malloy query by the URL or contents of a model document
+     * and the name of a query contained within the model.
+     *
+     * @param model The URL or contents of a Malloy model document to compile.
+     * @param name The name of a query contained within the model.
+     * @return A promise of a compiled `PreparedQuery`.
+     */
+    getQueryByName(model: ModelURL | ModelString, name: string, options?: ParseOptions & CompileOptions): Promise<PreparedQuery>;
+}
+export declare class ConnectionRuntime extends Runtime {
+    readonly rawConnections: Connection[];
+    constructor({ urlReader, connections, }: {
+        urlReader?: URLReader;
+        connections: Connection[];
+    });
+}
+export declare class SingleConnectionRuntime<T extends Connection = Connection> extends Runtime {
+    readonly connection: T;
+    constructor({ urlReader, connection, eventStream, cacheManager, }: {
+        urlReader?: URLReader;
+        eventStream?: EventStream;
+        cacheManager?: CacheManager;
+        connection: T;
+    });
+    get supportsNesting(): boolean;
+    quote(column: string): string;
+    get dialect(): Dialect;
+    getQuoter(): (arg: TemplateStringsArray) => string;
+}
+/**
+ * An object representing the task of loading a `Model`, capable of
+ * materializing that model (via `getModel()`) or extending the task to load
+ * queries or explores (via e.g. `loadFinalQuery()`, `loadQuery`, `loadExploreByName`, etc.).
+ */
+export declare class ModelMaterializer extends FluentState<Model> {
+    protected runtime: Runtime;
+    private readonly compileQueryOptions;
+    constructor(runtime: Runtime, materialize: () => Promise<Model>, options?: CompileQueryOptions);
+    /**
+     * Load the final (unnamed) Malloy query contained within this loaded `Model`.
+     *
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadFinalQuery(options?: CompileQueryOptions): QueryMaterializer;
+    /**
+     * Load an unnamed query contained within this loaded `Model` by index.
+     *
+     * @param index The index of the query to load.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQueryByIndex(index: number, options?: CompileQueryOptions): QueryMaterializer;
+    /**
+     * Load a query contained within this loaded `Model` by its name.
+     *
+     * @param name The name of the query to load.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQueryByName(name: string, options?: CompileQueryOptions): QueryMaterializer;
+    /**
+     * Load a query against this loaded `Model` by its URL or contents.
+     *
+     * @param query The URL or contents of the query to load and (eventually) compile.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQuery(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions & CompileQueryOptions): QueryMaterializer;
+    /**
+     * Extend a Malloy model by URL or contents.
+     *
+     * @param source The model URL or contents to load and (eventually) compile.
+     * @return A `ModelMaterializer` capable of materializing the requested model,
+     * or loading further related objects.
+     */
+    extendModel(query: QueryString | QueryURL, options?: ParseOptions & CompileOptions & CompileQueryOptions): ModelMaterializer;
+    search(sourceName: string, searchTerm: string, limit?: number, searchField?: string | undefined): Promise<SearchIndexResult[] | undefined>;
+    searchValueMap(sourceName: string, limit?: number, options?: ParseOptions): Promise<SearchValueMapResult[] | undefined>;
+    /**
+     * Materialize the final query contained within this loaded `Model`.
+     *
+     * @return A promise to a prepared query.
+     */
+    getFinalQuery(): Promise<PreparedQuery>;
+    /**
+     * Materialize an unnamed query contained within this loaded `Model` by index.
+     *
+     * @param index The index of the query contained within this loaded `Model`.
+     * @return A promise to a prepared query.
+     */
+    getQueryByIndex(index: number): Promise<PreparedQuery>;
+    /**
+     * Materialize a query contained within this loaded `Model` by name.
+     *
+     * @param name The name of the query contained within this loaded `Model`.
+     * @return A promise to a prepared query.
+     */
+    getQueryByName(name: string): Promise<PreparedQuery>;
+    /**
+     * Materialize a query against this loaded `Model` by its URL or contents.
+     *
+     * @param query The URL or contents of a query document to compile.
+     * @return A promise to a prepared query.
+     */
+    getQuery(query: QueryString | QueryURL, options?: ParseOptions): Promise<PreparedQuery>;
+    _loadQueryFromQueryDef(query: InternalQuery, options?: CompileQueryOptions): QueryMaterializer;
+    /**
+     * Load an explore contained within this loaded `Model` by name.
+     *
+     * @param name The name of the explore contained within this loaded `Model`.
+     * @return An `ExploreMaterializer` capable of materializing the requested explore,
+     * or loading further related objects.
+     */
+    loadExploreByName(name: string): ExploreMaterializer;
+    /**
+     * Materialize an explore contained within this loaded `Model` by its name.
+     *
+     * @param query The name of an explore within this loaded `Model`.
+     * @return A promise to an explore.
+     */
+    getExploreByName(name: string): Promise<Explore>;
+    /**
+     * Compile and materialize this loaded `Model`.
+     *
+     * @return A promise to the compiled model that is loaded.
+     */
+    getModel(): Promise<Model>;
+}
+/**
+ * An object representing the task of loading a `Query`, capable of
+ * materializing the query (via `getPreparedQuery()`) or extending the task to load
+ * prepared results or run the query (via e.g. `loadPreparedResult()` or `run()`).
+ */
+export declare class QueryMaterializer extends FluentState<PreparedQuery> {
+    protected runtime: Runtime;
+    private readonly compileQueryOptions;
+    constructor(runtime: Runtime, materialize: () => Promise<PreparedQuery>, options?: CompileQueryOptions);
+    /**
+     * Run this loaded `Query`.
+     *
+     * @return The query results from running this loaded query.
+     */
+    run(options?: RunSQLOptions & CompileQueryOptions): Promise<Result>;
+    runStream(options?: RunSQLOptions & CompileQueryOptions): AsyncIterableIterator<DataRecord>;
+    /**
+     * Load the prepared result of this loaded query.
+     *
+     * @return A `PreparedResultMaterializer` capable of materializing the requested
+     * prepared query or running it.
+     */
+    loadPreparedResult(options?: CompileQueryOptions): PreparedResultMaterializer;
+    /**
+     * Materialize the prepared result of this loaded query.
+     *
+     * @return A promise of the prepared result of this loaded query.
+     */
+    getPreparedResult(options?: CompileQueryOptions): Promise<PreparedResult>;
+    /**
+     * Materialize the SQL of this loaded query.
+     *
+     * @return A promise of the SQL string.
+     */
+    getSQL(options?: CompileQueryOptions): Promise<string>;
+    /**
+     * Materialize this loaded query.
+     *
+     * @return A promise of the `PreparedQuery`.
+     */
+    getPreparedQuery(): Promise<PreparedQuery>;
+    /**
+     * Estimates the cost of this loaded `Query`.
+     *
+     * @return The estimated cost of running this loaded query.
+     */
+    estimateQueryCost(options?: CompileQueryOptions): Promise<QueryRunStats>;
+    get eventStream(): EventStream | undefined;
+}
+/**
+ * An object representing the task of loading a `PreparedResult`, capable of
+ * materializing the prepared result (via `getPreparedResult()`) or extending the task run
+ * the query.
+ */
+export declare class PreparedResultMaterializer extends FluentState<PreparedResult> {
+    /**
+     * Run this prepared result.
+     *
+     * @return A promise to the query result data.
+     */
+    run(options?: RunSQLOptions): Promise<Result>;
+    runStream(options?: {
+        rowLimit?: number;
+    }): AsyncIterableIterator<DataRecord>;
+    /**
+     * Materialize this loaded prepared result.
+     *
+     * @return A promise of a prepared result.
+     */
+    getPreparedResult(): Promise<PreparedResult>;
+    /**
+     * Materialize the SQL of this loaded prepared result.
+     *
+     * @return A promise to the SQL string.
+     */
+    getSQL(): Promise<string>;
+}
+/**
+ * An object representing the task of loading an `Explore`, capable of
+ * materializing the explore (via `getExplore()`) or extending the task to produce
+ * related queries.
+ */
+export declare class ExploreMaterializer extends FluentState<Explore> {
+    protected runtime: Runtime;
+    private readonly compileQueryOptions;
+    constructor(runtime: Runtime, materialize: () => Promise<Explore>, options?: CompileQueryOptions);
+    /**
+     * Load a query contained within this loaded explore.
+     *
+     * @param name The name of the query to load.
+     * @return A `QueryMaterializer` capable of materializing the requested query, running it,
+     * or loading further related objects.
+     */
+    loadQueryByName(name: string, options?: CompileQueryOptions): QueryMaterializer;
+    /**
+     * Materialize a query contained within this loaded explore.
+     *
+     * @param name The name of the query to materialize.
+     * @return A promise to the requested prepared query.
+     */
+    getQueryByName(name: string): Promise<PreparedQuery>;
+    /**
+     * Materialize this loaded explore.
+     *
+     * @return A promise to the compiled `Explore`.
+     */
+    getExplore(): Promise<Explore>;
+}
+export {};