@malloydata/malloy 0.0.391 → 0.0.393

package/dist/api/foundation/config_resolve.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prepareConfig = prepareConfig;
 const registry_1 = require("../../connection/registry");
+const config_overlays_1 = require("./config_overlays");
 /**
  * Synchronous top-level walk of a compiled config tree. Extracts the
  * non-connection sections (which only contain literals — see the section
@@ -22,9 +23,11 @@ const registry_1 = require("../../connection/registry");
  * via `includeDefaultConnections`. Property defaults are filled in at
  * lookup time alongside reference resolution.
  */
-function prepareConfig(compiled, _log) {
+function prepareConfig(compiled, overlays, log) {
     let compiledConnections = {};
     let manifestPath;
+    let givensPath;
+    let finalizeGivens;
     let virtualMap;
     let includeDefaultConnections = false;
     for (const [key, node] of Object.entries(compiled.entries)) {
@@ -36,8 +39,16 @@ function prepareConfig(compiled, _log) {
                 break;
             }
             case 'manifestPath': {
-                if (node.kind === 'value' && typeof node.value === 'string') {
-                    manifestPath = node.value;
+                manifestPath = resolveSyncStringSetting(node, overlays, log, 'manifestPath');
+                break;
+            }
+            case 'givensPath': {
+                givensPath = resolveSyncStringSetting(node, overlays, log, 'givensPath');
+                break;
+            }
+            case 'finalizeGivens': {
+                if (node.kind === 'value' && isStringArray(node.value)) {
+                    finalizeGivens = node.value;
                 }
                 break;
             }
@@ -60,7 +71,16 @@ function prepareConfig(compiled, _log) {
     if (includeDefaultConnections) {
         fabricateMissingConnections(compiledConnections);
     }
-    return { compiledConnections, manifestPath, virtualMap };
+    return {
+        compiledConnections,
+        manifestPath,
+        givensPath,
+        finalizeGivens,
+        virtualMap,
+    };
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every(x => typeof x === 'string');
 }
 /**
  * Pull each well-formed compiled connection entry out of the `connections`
@@ -105,4 +125,44 @@ function fabricateMissingConnections(compiledConnections) {
         };
     }
 }
+/**
+ * Resolve a top-level string setting that may be a literal or an overlay
+ * reference. Top-level scalars are read at construction time, so the overlay
+ * MUST resolve synchronously — same rule that applies to `configURL`. An
+ * overlay returning a Promise is a hard misuse: warn loudly and drop, so the
+ * application notices instead of silently losing the setting.
+ *
+ * Failure modes mirror connection-property resolution otherwise:
+ *   - unknown overlay source → warn + drop (case 1)
+ *   - overlay returns undefined → silent drop (case 2; falls back to default)
+ *   - non-string literal node → returns undefined (compile-time validation
+ *     already warned)
+ */
+function resolveSyncStringSetting(node, overlays, log, settingName) {
+    if (node.kind === 'value') {
+        return typeof node.value === 'string' ? node.value : undefined;
+    }
+    if (node.kind === 'reference') {
+        const overlay = overlays[node.source];
+        if (!overlay) {
+            log.push({
+                message: `unknown overlay source "${node.source}" for "${settingName}"`,
+                severity: 'warn',
+                code: 'config-overlay',
+            });
+            return undefined;
+        }
+        const v = overlay(node.path);
+        if ((0, config_overlays_1.isThenable)(v)) {
+            log.push({
+                message: `the \`${node.source}\` overlay returned a Promise for "${settingName}"; top-level string settings must resolve synchronously`,
+                severity: 'warn',
+                code: 'config-overlay',
+            });
+            return undefined;
+        }
+        return typeof v === 'string' ? v : undefined;
+    }
+    return undefined;
+}
 //# sourceMappingURL=config_resolve.js.map

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

@@ -1,5 +1,5 @@
 import type { LogMessage } from '../../lang';
-import type { BuildID, CompiledQuery, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, Annotation, NamedModelObject, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef } from '../../model';
+import type { BuildID, CompiledQuery, ConstantExpr, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Given as InternalGiven, GivenID, GivenTypeDef, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, Annotation, NamedModelObject, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef } from '../../model';
 import { QueryModel } from '../../model';
 import type { Dialect } from '../../dialect';
 import type { BuildGraph, CompileQueryOptions } from './types';
@@ -230,14 +230,41 @@ export declare class ExploreField extends Explore {
     get sourceClasses(): string[];
     get queryTimezone(): string | undefined;
 }
+/**
+ * Runtime-aware concerns layered onto a `Model` after it leaves the
+ * compiler. `Malloy.compile()` returns a `Model` with no context; a
+ * `Runtime.loadModel()` decoration attaches the runtime's context so
+ * context-sensitive views (currently `Model.givens` filtering finalized
+ * names; in future, tenant overrides / session bindings / etc.) work
+ * correctly. New runtime-aware concerns add a field here rather than a
+ * parallel constructor parameter.
+ */
+export interface RuntimeContext {
+    /** Surface names of givens locked at the runtime layer (from
+     *  `config.finalizeGivens`). Filtered out of `Model.givens` so
+     *  introspection-driven UIs don't render editors for them. */
+    readonly finalizedGivens?: ReadonlySet<string>;
+}
 export declare class Model implements Taggable {
     private modelDef;
     readonly problems: LogMessage[];
     readonly fromSources: string[];
+    /**
+     * Runtime-aware context layered onto this Model. `Malloy.compile()`
+     * leaves it undefined; `Runtime.loadModel()` paths attach the
+     * runtime's context so methods like `Model.givens` filter correctly.
+     */
+    private readonly runtimeContext?;
     private readonly references;
     private _queryModel?;
     private readonly contentsMap;
-    constructor(modelDef: ModelDef, problems: LogMessage[], fromSources: string[], existingQueryModel?: QueryModel);
+    constructor(modelDef: ModelDef, problems: LogMessage[], fromSources: string[], existingQueryModel?: QueryModel, 
+    /**
+     * Runtime-aware context layered onto this Model. `Malloy.compile()`
+     * leaves it undefined; `Runtime.loadModel()` paths attach the
+     * runtime's context so methods like `Model.givens` filter correctly.
+     */
+    runtimeContext?: RuntimeContext | undefined);
     /** Safe lookup in model contents by name. */
     getContent(name: string): NamedModelObject | undefined;
     get queryModel(): QueryModel;
@@ -247,6 +274,16 @@ export declare class Model implements Taggable {
      * the model wasn't modified (only queries were added).
      */
     getExistingQueryModel(): QueryModel | undefined;
+    /**
+     * The givens this model surfaces, keyed by caller-facing surface name.
+     * Used by whole-model parameter-editor UIs to render input widgets for
+     * every given the model can accept.
+     *
+     * Internal-only givens (declared but never surfaced into the namespace,
+     * resolved purely via defaults) are NOT in this map — the caller has no
+     * way to set them, so listing them would mislead a UI.
+     */
+    get givens(): ReadonlyMap<string, Given>;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
     /**
@@ -428,6 +465,30 @@ export declare class PersistSource implements Taggable {
      */
     get _model(): Model;
 }
+/**
+ * Foundation API wrapper for a given declaration. Parallel to Explore /
+ * PreparedQuery — exposes a stable, callerable surface over the internal
+ * `Given` IR record. Returned from `PreparedQuery.givens`.
+ */
+export declare class Given implements Taggable {
+    readonly name: string;
+    readonly id: GivenID;
+    private readonly _internal;
+    /**
+     * @param name        Caller-facing surface name in the model (post-rename
+     *                    on import). The key by which the caller passes a
+     *                    value to `.run({givens: {[name]: ...}})`.
+     * @param id          Global GivenID. Stable across imports and renames.
+     * @param _internal   The internal Given declaration record.
+     */
+    constructor(name: string, id: GivenID, _internal: InternalGiven);
+    get type(): GivenTypeDef;
+    /** `undefined` when no default — the caller must supply at run time. */
+    get default(): ConstantExpr | undefined;
+    get location(): DocumentLocation | undefined;
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    getTaglines(prefix?: RegExp): string[];
+}
 export declare class PreparedQuery implements Taggable {
     private _model;
     problems: LogMessage[];
@@ -460,6 +521,18 @@ export declare class PreparedQuery implements Taggable {
      * Get the Model this query belongs to.
      */
     get model(): Model;
+    /**
+     * The givens this specific query references, keyed by caller-facing
+     * surface name. Used by "run this query" UIs to prompt only for the
+     * givens this query actually touches, not every given declared in the
+     * model.
+     *
+     * Computed as `model.givens` filtered by `query.givenUsage` — i.e. the
+     * intersection of "what the model surfaces" with "what this query
+     * needs." Internal-only givens (referenced but never surfaced) stay
+     * invisible because they're not in `model.givens` to begin with.
+     */
+    get givens(): ReadonlyMap<string, Given>;
 }
 export declare class PreparedResult implements Taggable {
     protected modelDef: ModelDef;

package/dist/api/foundation/core.js

@@ -4,12 +4,13 @@
  * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PreparedResult = exports.PreparedQuery = exports.PersistSource = exports.Model = exports.ExploreField = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = void 0;
+exports.PreparedResult = exports.PreparedQuery = exports.Given = exports.PersistSource = exports.Model = exports.ExploreField = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = void 0;
 const model_1 = require("../../model");
 const utils_1 = require("../../model/utils");
 const dialect_1 = require("../../dialect");
 const persist_utils_1 = require("../../model/persist_utils");
 const source_def_utils_1 = require("../../model/source_def_utils");
+const given_binding_1 = require("../../model/given_binding");
 const malloy_tag_1 = require("@malloydata/malloy-tag");
 const annotation_1 = require("../../annotation");
 const to_stable_1 = require("../../to_stable");
@@ -742,15 +743,19 @@ class ExploreField extends Explore {
     }
 }
 exports.ExploreField = ExploreField;
-// =============================================================================
-// Model
-// =============================================================================
 class Model {
-    constructor(modelDef, problems, fromSources, existingQueryModel) {
+    constructor(modelDef, problems, fromSources, existingQueryModel, 
+    /**
+     * Runtime-aware context layered onto this Model. `Malloy.compile()`
+     * leaves it undefined; `Runtime.loadModel()` paths attach the
+     * runtime's context so methods like `Model.givens` filter correctly.
+     */
+    runtimeContext) {
         var _a, _b;
         this.modelDef = modelDef;
         this.problems = problems;
         this.fromSources = fromSources;
+        this.runtimeContext = runtimeContext;
         this.references = new reference_list_1.ReferenceList((_a = fromSources[0]) !== null && _a !== void 0 ? _a : '', (_b = modelDef.references) !== null && _b !== void 0 ? _b : []);
         this._queryModel = existingQueryModel;
         this.contentsMap = new Map(Object.entries(modelDef.contents));
@@ -773,6 +778,33 @@ class Model {
     getExistingQueryModel() {
         return this._queryModel;
     }
+    /**
+     * The givens this model surfaces, keyed by caller-facing surface name.
+     * Used by whole-model parameter-editor UIs to render input widgets for
+     * every given the model can accept.
+     *
+     * Internal-only givens (declared but never surfaced into the namespace,
+     * resolved purely via defaults) are NOT in this map — the caller has no
+     * way to set them, so listing them would mislead a UI.
+     */
+    get givens() {
+        var _a, _b;
+        const out = new Map();
+        const givens = this.modelDef.givens;
+        if (!givens)
+            return out;
+        for (const [surfaceName, entry] of this.contentsMap) {
+            if (entry.type !== 'given')
+                continue;
+            if ((_b = (_a = this.runtimeContext) === null || _a === void 0 ? void 0 : _a.finalizedGivens) === null || _b === void 0 ? void 0 : _b.has(surfaceName))
+                continue;
+            const decl = givens[entry.id];
+            if (!decl)
+                continue;
+            out.set(surfaceName, new Given(surfaceName, entry.id, decl));
+        }
+        return out;
+    }
     tagParse(spec) {
         return (0, annotation_1.annotationToTag)(this.modelDef.annotation, spec);
     }
@@ -1097,6 +1129,42 @@ exports.PersistSource = PersistSource;
 // =============================================================================
 // PreparedQuery
 // =============================================================================
+/**
+ * Foundation API wrapper for a given declaration. Parallel to Explore /
+ * PreparedQuery — exposes a stable, callerable surface over the internal
+ * `Given` IR record. Returned from `PreparedQuery.givens`.
+ */
+class Given {
+    /**
+     * @param name        Caller-facing surface name in the model (post-rename
+     *                    on import). The key by which the caller passes a
+     *                    value to `.run({givens: {[name]: ...}})`.
+     * @param id          Global GivenID. Stable across imports and renames.
+     * @param _internal   The internal Given declaration record.
+     */
+    constructor(name, id, _internal) {
+        this.name = name;
+        this.id = id;
+        this._internal = _internal;
+    }
+    get type() {
+        return this._internal.type;
+    }
+    /** `undefined` when no default — the caller must supply at run time. */
+    get default() {
+        return this._internal.default;
+    }
+    get location() {
+        return this._internal.location;
+    }
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this._internal.annotation, spec);
+    }
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this._internal.annotation, prefix);
+    }
+}
+exports.Given = Given;
 class PreparedQuery {
     constructor(query, _model, problems, name) {
         this._model = _model;
@@ -1129,7 +1197,13 @@ class PreparedQuery {
      */
     getPreparedResult(options) {
         const queryModel = this._model.queryModel;
-        const translatedQuery = queryModel.compileQuery(this._query, options);
+        const prepareResultOptions = {
+            ...options,
+            resolvedGivens: (options === null || options === void 0 ? void 0 : options.givens)
+                ? (0, given_binding_1.resolveSuppliedGivens)(options.givens, this._modelDef)
+                : undefined,
+        };
+        const translatedQuery = queryModel.compileQuery(this._query, prepareResultOptions);
         return new PreparedResult({
             ...translatedQuery,
             queryName: this.name || translatedQuery.queryName,
@@ -1158,6 +1232,30 @@ class PreparedQuery {
     get model() {
         return this._model;
     }
+    /**
+     * The givens this specific query references, keyed by caller-facing
+     * surface name. Used by "run this query" UIs to prompt only for the
+     * givens this query actually touches, not every given declared in the
+     * model.
+     *
+     * Computed as `model.givens` filtered by `query.givenUsage` — i.e. the
+     * intersection of "what the model surfaces" with "what this query
+     * needs." Internal-only givens (referenced but never surfaced) stay
+     * invisible because they're not in `model.givens` to begin with.
+     */
+    get givens() {
+        const out = new Map();
+        const usage = this._query.givenUsage;
+        if (!usage || usage.length === 0)
+            return out;
+        const referenced = new Set(usage.map(g => g.id));
+        for (const [name, given] of this._model.givens) {
+            if (referenced.has(given.id)) {
+                out.set(name, given);
+            }
+        }
+        return out;
+    }
 }
 exports.PreparedQuery = PreparedQuery;
 // =============================================================================

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

@@ -9,7 +9,9 @@ export { type ResultJSON, type DataColumn, type DataArrayOrRecord, Result, DataA
 export { type WriteStream, DataWriter, JSONWriter, CSVWriter } from './writers';
 export { Runtime, ConnectionRuntime, SingleConnectionRuntime, ModelMaterializer, QueryMaterializer, PreparedResultMaterializer, ExploreMaterializer, } from './runtime';
 export { Manifest, MalloyConfig } from './config';
+export type { FilesystemContext, MalloyConfigOptions } from './config';
 export type { Overlay, ConfigOverlays } from './config_overlays';
+export type { RuntimeContext } from './core';
 export { envOverlay, contextOverlay, defaultConfigOverlays, } from './config_overlays';
 export { discoverConfig } from './config_discover';
 export { Malloy, MalloyError, type MalloyCompileOptions, type MalloyRunOptions, } from './compile';

package/dist/api/foundation/readers.js

@@ -26,7 +26,7 @@ async function readURL(urlReader, url) {
         contents,
         invalidationKey: isInternalURL(url.toString())
             ? null
-            : invalidationKey !== null && invalidationKey !== void 0 ? invalidationKey : hashForInvalidationKey(contents),
+            : (invalidationKey !== null && invalidationKey !== void 0 ? invalidationKey : hashForInvalidationKey(contents)),
     };
 }
 async function getInvalidationKey(urlReader, url) {

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

@@ -1,6 +1,6 @@
 import type { Connection, LookupConnection } from '../../connection/types';
 import type { URLReader, EventStream } from '../../runtime_types';
-import type { ModelDef, Query as InternalQuery, SearchIndexResult, SearchValueMapResult, QueryRunStats, BuildManifest, VirtualMap } from '../../model';
+import type { ModelDef, Query as InternalQuery, SearchIndexResult, SearchValueMapResult, QueryRunStats, BuildManifest, GivenValue, VirtualMap } from '../../model';
 import type { Dialect } from '../../dialect';
 import type { RunSQLOptions } from '../../run_sql_options';
 import type { CacheManager } from './cache';
@@ -49,12 +49,22 @@ export declare class Runtime {
     private _config;
     private _buildManifest;
     private _resolvedBuildManifestPromise;
+    private _resolvedGivensPromise;
+    private _constructorGivensMap;
+    private _finalizedGivensSet;
     private _virtualMap;
-    constructor({ urlReader, connections, connection, config, buildManifest, eventStream, cacheManager, }: {
+    constructor({ urlReader, connections, connection, config, buildManifest, eventStream, cacheManager, givens, }: {
         urlReader?: URLReader;
         buildManifest?: BuildManifest;
         eventStream?: EventStream;
         cacheManager?: CacheManager;
+        /**
+         * Per-runtime givens supplied directly by the host (multi-tenant
+         * server passing JWT-derived values; tests; scripts). Overlaid on top
+         * of `config.givensURL` per-key, then per-query supply via
+         * `.run({givens: ...})` overlays on top of both.
+         */
+        givens?: Record<string, GivenValue>;
     } & Connectionable);
     /**
      * @return The `CacheManager` for this runtime instance.
@@ -72,6 +82,35 @@ export declare class Runtime {
      * @return The `EventStream` for this runtime instance.
      */
     get eventStream(): EventStream | undefined;
+    /**
+     * Constructor-supplied givens, exposed for the materializer's per-query
+     * merge. Underscore-prefixed because it's the constructor layer only —
+     * use `getGivens()` for the full file+constructor view a caller usually
+     * wants.
+     *
+     * @internal Accessed from QueryMaterializer.
+     */
+    get _constructorGivens(): ReadonlyMap<string, GivenValue>;
+    /**
+     * The runtime's effective givens — file (from `config.givensPath`,
+     * lazily loaded) merged with the constructor `givens:` option, with
+     * the constructor winning per-key. Per-query supply via
+     * `.run({ givens: ... })` is *not* included; that's a per-call
+     * argument, not runtime state.
+     *
+     * Async because the file may not yet be loaded; subsequent calls share
+     * the cached promise.
+     */
+    getGivens(): Promise<ReadonlyMap<string, GivenValue>>;
+    /**
+     * Surface names of givens locked at the runtime layer (the resolved set
+     * the `config.finalizeGivens` directive produced). Per-query supply for
+     * these names throws; `Model.givens` and `PreparedQuery.givens` filter
+     * them out so introspection-driven UIs don't render editors for them.
+     *
+     * @internal Accessed from QueryMaterializer and Model construction.
+     */
+    get _finalizedGivens(): ReadonlySet<string>;
     /**
      * Setter — install an explicit build manifest for persist source
      * substitution. From this point on, compiled queries resolve persist
@@ -114,6 +153,23 @@ export declare class Runtime {
      * of the public API — the leading underscore + `@internal` marks intent.
      */
     _resolveBuildManifest(): Promise<BuildManifest | undefined>;
+    /**
+     * Resolve the per-runtime givens map from `config.givensURL` (the file
+     * `givensPath` points at). Lazy and cached as a Promise — first compile
+     * triggers the read, subsequent compiles share the result.
+     *
+     * Stricter error policy than `_resolveBuildManifest`: a missing file or
+     * malformed JSON throws. Per design, the per-runtime givens layer is a
+     * configured contract, not an opportunistic read; a misconfigured path
+     * should fail loudly at the first compile, not silently degrade.
+     *
+     * Returns `undefined` only when no `givensURL` is configured.
+     *
+     * @internal Accessed from QueryMaterializer.
+     */
+    _resolveGivens(): Promise<Record<string, GivenValue> | undefined>;
+    /** @internal */
+    _invalidateGivensCache(): void;
     /**
      * The virtual map for virtual source resolution.
      * When set, compiled queries automatically resolve virtual sources
@@ -157,6 +213,16 @@ export declare class Runtime {
      * or loading further related objects.
      */
     loadModel(source: ModelURL | ModelString, options?: ParseOptions & CompileOptions & CompileQueryOptions): ModelMaterializer;
+    /**
+     * Re-wrap a `Model` produced by `Malloy.compile` with this runtime's
+     * `RuntimeContext` so context-sensitive Model methods (currently
+     * `Model.givens` filtering finalized names; future runtime-aware
+     * concerns) work correctly. No-op when there's nothing in the context.
+     *
+     * @internal Accessed from `ModelMaterializer.extendModel` and Runtime
+     * loadModel paths.
+     */
+    _withRuntimeContext(m: Model): Model;
     _loadModelFromModelDef(modelDef: ModelDef, options?: CompileQueryOptions): ModelMaterializer;
     /**
      * Load a Malloy query by URL or contents.