@malloydata/malloy 0.0.390 → 0.0.392

package/dist/lang/lib/Malloy/MalloyParserListener.d.ts

@@ -22,6 +22,7 @@ import { FilterString_stubContext } from "./MalloyParser";
 import { ExprNowContext } from "./MalloyParser";
 import { NestDefContext } from "./MalloyParser";
 import { ExprFieldPathContext } from "./MalloyParser";
+import { ExprGivenRefContext } from "./MalloyParser";
 import { ExprLiteralContext } from "./MalloyParser";
 import { ExprArrayLiteralContext } from "./MalloyParser";
 import { ExprLiteralRecordContext } from "./MalloyParser";
@@ -100,6 +101,11 @@ import { UserTypeShapeContext } from "./MalloyParser";
 import { UserTypeFieldContext } from "./MalloyParser";
 import { UserTypeFieldTypeContext } from "./MalloyParser";
 import { DefineQueryContext } from "./MalloyParser";
+import { DefineGivenStatementContext } from "./MalloyParser";
+import { GivenDefListContext } from "./MalloyParser";
+import { GivenDefContext } from "./MalloyParser";
+import { GivenNameDefContext } from "./MalloyParser";
+import { GivenTypeContext } from "./MalloyParser";
 import { TopLevelAnonQueryDefContext } from "./MalloyParser";
 import { AnnotationContext } from "./MalloyParser";
 import { TagsContext } from "./MalloyParser";
@@ -546,6 +552,18 @@ export interface MalloyParserListener extends ParseTreeListener {
      * @param ctx the parse tree
      */
     exitExprFieldPath?: (ctx: ExprFieldPathContext) => void;
+    /**
+     * Enter a parse tree produced by the `exprGivenRef`
+     * labeled alternative in `MalloyParser.fieldExpr`.
+     * @param ctx the parse tree
+     */
+    enterExprGivenRef?: (ctx: ExprGivenRefContext) => void;
+    /**
+     * Exit a parse tree produced by the `exprGivenRef`
+     * labeled alternative in `MalloyParser.fieldExpr`.
+     * @param ctx the parse tree
+     */
+    exitExprGivenRef?: (ctx: ExprGivenRefContext) => void;
     /**
      * Enter a parse tree produced by the `exprLiteral`
      * labeled alternative in `MalloyParser.fieldExpr`.
@@ -1458,6 +1476,56 @@ export interface MalloyParserListener extends ParseTreeListener {
      * @param ctx the parse tree
      */
     exitDefineQuery?: (ctx: DefineQueryContext) => void;
+    /**
+     * Enter a parse tree produced by `MalloyParser.defineGivenStatement`.
+     * @param ctx the parse tree
+     */
+    enterDefineGivenStatement?: (ctx: DefineGivenStatementContext) => void;
+    /**
+     * Exit a parse tree produced by `MalloyParser.defineGivenStatement`.
+     * @param ctx the parse tree
+     */
+    exitDefineGivenStatement?: (ctx: DefineGivenStatementContext) => void;
+    /**
+     * Enter a parse tree produced by `MalloyParser.givenDefList`.
+     * @param ctx the parse tree
+     */
+    enterGivenDefList?: (ctx: GivenDefListContext) => void;
+    /**
+     * Exit a parse tree produced by `MalloyParser.givenDefList`.
+     * @param ctx the parse tree
+     */
+    exitGivenDefList?: (ctx: GivenDefListContext) => void;
+    /**
+     * Enter a parse tree produced by `MalloyParser.givenDef`.
+     * @param ctx the parse tree
+     */
+    enterGivenDef?: (ctx: GivenDefContext) => void;
+    /**
+     * Exit a parse tree produced by `MalloyParser.givenDef`.
+     * @param ctx the parse tree
+     */
+    exitGivenDef?: (ctx: GivenDefContext) => void;
+    /**
+     * Enter a parse tree produced by `MalloyParser.givenNameDef`.
+     * @param ctx the parse tree
+     */
+    enterGivenNameDef?: (ctx: GivenNameDefContext) => void;
+    /**
+     * Exit a parse tree produced by `MalloyParser.givenNameDef`.
+     * @param ctx the parse tree
+     */
+    exitGivenNameDef?: (ctx: GivenNameDefContext) => void;
+    /**
+     * Enter a parse tree produced by `MalloyParser.givenType`.
+     * @param ctx the parse tree
+     */
+    enterGivenType?: (ctx: GivenTypeContext) => void;
+    /**
+     * Exit a parse tree produced by `MalloyParser.givenType`.
+     * @param ctx the parse tree
+     */
+    exitGivenType?: (ctx: GivenTypeContext) => void;
     /**
      * Enter a parse tree produced by `MalloyParser.topLevelAnonQueryDef`.
      * @param ctx the parse tree

package/dist/lang/lib/Malloy/MalloyParserVisitor.d.ts

@@ -22,6 +22,7 @@ import { FilterString_stubContext } from "./MalloyParser";
 import { ExprNowContext } from "./MalloyParser";
 import { NestDefContext } from "./MalloyParser";
 import { ExprFieldPathContext } from "./MalloyParser";
+import { ExprGivenRefContext } from "./MalloyParser";
 import { ExprLiteralContext } from "./MalloyParser";
 import { ExprArrayLiteralContext } from "./MalloyParser";
 import { ExprLiteralRecordContext } from "./MalloyParser";
@@ -100,6 +101,11 @@ import { UserTypeShapeContext } from "./MalloyParser";
 import { UserTypeFieldContext } from "./MalloyParser";
 import { UserTypeFieldTypeContext } from "./MalloyParser";
 import { DefineQueryContext } from "./MalloyParser";
+import { DefineGivenStatementContext } from "./MalloyParser";
+import { GivenDefListContext } from "./MalloyParser";
+import { GivenDefContext } from "./MalloyParser";
+import { GivenNameDefContext } from "./MalloyParser";
+import { GivenTypeContext } from "./MalloyParser";
 import { TopLevelAnonQueryDefContext } from "./MalloyParser";
 import { AnnotationContext } from "./MalloyParser";
 import { TagsContext } from "./MalloyParser";
@@ -434,6 +440,13 @@ export interface MalloyParserVisitor<Result> extends ParseTreeVisitor<Result> {
      * @return the visitor result
      */
     visitExprFieldPath?: (ctx: ExprFieldPathContext) => Result;
+    /**
+     * Visit a parse tree produced by the `exprGivenRef`
+     * labeled alternative in `MalloyParser.fieldExpr`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitExprGivenRef?: (ctx: ExprGivenRefContext) => Result;
     /**
      * Visit a parse tree produced by the `exprLiteral`
      * labeled alternative in `MalloyParser.fieldExpr`.
@@ -968,6 +981,36 @@ export interface MalloyParserVisitor<Result> extends ParseTreeVisitor<Result> {
      * @return the visitor result
      */
     visitDefineQuery?: (ctx: DefineQueryContext) => Result;
+    /**
+     * Visit a parse tree produced by `MalloyParser.defineGivenStatement`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitDefineGivenStatement?: (ctx: DefineGivenStatementContext) => Result;
+    /**
+     * Visit a parse tree produced by `MalloyParser.givenDefList`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitGivenDefList?: (ctx: GivenDefListContext) => Result;
+    /**
+     * Visit a parse tree produced by `MalloyParser.givenDef`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitGivenDef?: (ctx: GivenDefContext) => Result;
+    /**
+     * Visit a parse tree produced by `MalloyParser.givenNameDef`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitGivenNameDef?: (ctx: GivenNameDefContext) => Result;
+    /**
+     * Visit a parse tree produced by `MalloyParser.givenType`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitGivenType?: (ctx: GivenTypeContext) => Result;
     /**
      * Visit a parse tree produced by `MalloyParser.topLevelAnonQueryDef`.
      * @param ctx the parse tree

package/dist/lang/malloy-to-ast.d.ts

@@ -8,7 +8,7 @@ import type { LogMessageOptions, MessageCode, MessageLogger, MessageParameterTyp
 import type { MalloyParseInfo } from './malloy-parse-info';
 import type { FieldDeclarationConstructor } from './ast';
 import type { HasString, HasID } from './parse-utils';
-import type { AccessModifierLabel, AtomicTypeDef, BasicAtomicTypeDef, DocumentLocation, DocumentRange, Note } from '../model/malloy_types';
+import type { AccessModifierLabel, AtomicTypeDef, BasicAtomicTypeDef, DocumentLocation, DocumentRange, FilterExprType, GivenTypeDef, Note } from '../model/malloy_types';
 import type { Tag } from '@malloydata/malloy-tag';
 import type * as Malloy from '@malloydata/malloy-interfaces';
 import { Timer } from '../timing';
@@ -89,6 +89,17 @@ export declare class MalloyToAST extends AbstractParseTreeVisitor<ast.MalloyElem
     protected getIsNotes(cx: parse.IsDefineContext): Note[];
     visitMalloyDocument(pcx: parse.MalloyDocumentContext): ast.Document;
     visitDefineSourceStatement(pcx: parse.DefineSourceStatementContext): ast.DefineSourceList;
+    visitDefineGivenStatement(pcx: parse.DefineGivenStatementContext): ast.DefineGivens;
+    visitGivenDef(pcx: parse.GivenDefContext): ast.GivenDeclaration;
+    /**
+     * Parse the TYPE inside `filter<TYPE>`. Returns the filter type on
+     * success; logs `illegal-filter-type` and returns undefined when TYPE
+     * is not a filterable type. `getBasicMalloyType` already logs for
+     * invalid basic types, so on its `'error'` path we stay silent and
+     * return undefined.
+     */
+    protected getFilterType(basicCx: parse.MalloyBasicTypeContext): FilterExprType | undefined;
+    getGivenType(pcx: parse.GivenTypeContext): GivenTypeDef;
     visitDefineUserTypeStatement(pcx: parse.DefineUserTypeStatementContext): ast.DefineUserTypeList;
     visitUserTypeDefinition(pcx: parse.UserTypeDefinitionContext): ast.DefineUserType;
     getUserTypeShapeExpr(cx: parse.UserTypeExprContext): ast.UserTypeShape;
@@ -185,6 +196,7 @@ export declare class MalloyToAST extends AbstractParseTreeVisitor<ast.MalloyElem
     visitExprNow(_pcx: parse.ExprNowContext): ast.ExprNow;
     visitExprNumber(pcx: parse.ExprNumberContext): ast.ExprNumber;
     visitExprFieldPath(pcx: parse.ExprFieldPathContext): ast.ExprIdReference;
+    visitExprGivenRef(pcx: parse.ExprGivenRefContext): ast.GivenReference;
     visitExprNULL(_pcx: parse.ExprNULLContext): ast.ExprNULL;
     visitExprExpr(pcx: parse.ExprExprContext): ast.ExprParens;
     visitExprMinus(pcx: parse.ExprMinusContext): ast.ExprMinus;

package/dist/lang/malloy-to-ast.js

@@ -86,6 +86,7 @@ function isIndirectUserType(t) {
     return 'namedUserType' in t;
 }
 const DEFAULT_COMPILER_FLAGS = [];
+const LEGAL_FILTER_TYPES = 'string, number, boolean, date, timestamp, timestamptz';
 /**
  * ANTLR visitor pattern parse tree traversal. Generates a Malloy
  * AST from an ANTLR parse tree.
@@ -286,6 +287,79 @@ class MalloyToAST extends AbstractParseTreeVisitor_1.AbstractParseTreeVisitor {
         defList.extendNote({ blockNotes });
         return defList;
     }
+    visitDefineGivenStatement(pcx) {
+        this.inExperiment('givens', pcx);
+        const defsCx = pcx.givenDefList().givenDef();
+        const givens = defsCx.map(dcx => this.visitGivenDef(dcx));
+        const blockNotes = this.getNotes(pcx.tags());
+        const block = new ast.DefineGivens(givens);
+        for (const g of givens) {
+            g.extendNote({ blockNotes });
+        }
+        return this.astAt(block, pcx);
+    }
+    visitGivenDef(pcx) {
+        const name = (0, parse_utils_1.getId)(pcx.givenNameDef());
+        const typeDef = this.getGivenType(pcx.givenType());
+        const defaultCx = pcx.fieldExpr();
+        let defVal;
+        if (defaultCx) {
+            defVal = this.astAt(new ast.ConstantExpression(this.getFieldExpr(defaultCx)), defaultCx);
+        }
+        const isCx = pcx.isDefine();
+        if (isCx) {
+            // We accept the `tags IS tags` shape syntactically so we can give a
+            // targeted error here instead of a confusing parse-level one. Tags
+            // belong above the declaration; nothing should sit between `is` and
+            // the default expression.
+            const afterIs = isCx._afterIs;
+            if (afterIs && afterIs.annotation().length > 0) {
+                this.contextError(afterIs, 'given-no-tags-after-is', 'Annotations are not allowed between `is` and the default value of a given; place them above the declaration');
+            }
+        }
+        const decl = new ast.GivenDeclaration(name, typeDef, defVal);
+        decl.extendNote({ notes: this.getNotes(pcx.tags()) });
+        return this.astAt(decl, pcx);
+    }
+    /**
+     * Parse the TYPE inside `filter<TYPE>`. Returns the filter type on
+     * success; logs `illegal-filter-type` and returns undefined when TYPE
+     * is not a filterable type. `getBasicMalloyType` already logs for
+     * invalid basic types, so on its `'error'` path we stay silent and
+     * return undefined.
+     */
+    getFilterType(basicCx) {
+        const inner = this.getBasicMalloyType(basicCx);
+        if (inner.type === 'error')
+            return undefined;
+        if ((0, malloy_filter_1.isFilterable)(inner.type)) {
+            return inner.type;
+        }
+        this.contextError(basicCx, 'illegal-filter-type', `\`filter<${basicCx.text}>\` is not allowed; filtering is only supported for ${LEGAL_FILTER_TYPES}`);
+        return undefined;
+    }
+    getGivenType(pcx) {
+        if (pcx.FILTER()) {
+            const basicCx = pcx.malloyBasicType();
+            if (basicCx) {
+                const filterType = this.getFilterType(basicCx);
+                if (filterType)
+                    return { type: 'filter expression', filterType };
+            }
+            return { type: 'error' };
+        }
+        const mtcx = pcx.malloyType();
+        if (mtcx) {
+            return this.getMalloyType(mtcx);
+        }
+        // Unreachable from valid grammar input: `givenType` is exactly
+        // `malloyType | FILTER LT malloyBasicType GT`, so one of the branches
+        // above must have matched. Surfacing a real error here (rather than
+        // throwing) keeps the translator running and gives any AI or human
+        // reading the log a hint that the parser and AST builder have drifted.
+        this.contextError(pcx, 'unexpected-malloy-type', `\`${pcx.text}\` was not recognized as a legal type. This is likely a compiler bug — the grammar admits cases the translator doesn't handle.`);
+        return { type: 'error' };
+    }
     visitDefineUserTypeStatement(pcx) {
         this.inExperiment('virtual_source', pcx);
         const defsCx = pcx.userTypePropertyList().userTypeDefinition();
@@ -385,21 +459,20 @@ class MalloyToAST extends AbstractParseTreeVisitor_1.AbstractParseTreeVisitor {
         let pType;
         const typeCx = pcx.legalParamType();
         if (typeCx) {
-            const typeDef = this.getBasicMalloyType(typeCx.malloyBasicType());
-            const t = typeDef.type;
             if (typeCx.FILTER()) {
-                if ((0, malloy_filter_1.isFilterable)(t)) {
-                    pType = { type: 'filter expression', filterType: t };
-                }
-                else {
-                    this.contextError(typeCx, 'parameter-illegal-default-type', `Unknown filter type ${t}`);
+                const filterType = this.getFilterType(typeCx.malloyBasicType());
+                if (filterType) {
+                    pType = { type: 'filter expression', filterType };
                 }
             }
-            else if (!(0, malloy_types_1.isParameterType)(t)) {
-                this.contextError(typeCx, 'parameter-illegal-default-type', `Unknown parameter type ${t}`);
-            }
             else {
-                pType = { type: t };
+                const t = this.getBasicMalloyType(typeCx.malloyBasicType()).type;
+                if (!(0, malloy_types_1.isParameterType)(t)) {
+                    this.contextError(typeCx, 'parameter-illegal-default-type', `Unknown parameter type ${t}`);
+                }
+                else {
+                    pType = { type: t };
+                }
             }
         }
         const defaultCx = pcx.fieldExpr();
@@ -1048,6 +1121,12 @@ class MalloyToAST extends AbstractParseTreeVisitor_1.AbstractParseTreeVisitor {
         const idRef = new ast.ExprIdReference(this.getFieldPath(pcx.fieldPath(), ast.ExpressionFieldReference));
         return this.astAt(idRef, pcx);
     }
+    visitExprGivenRef(pcx) {
+        this.inExperiment('givens', pcx);
+        // GIVEN_REF token text is `$NAME`; strip the leading `$`.
+        const name = pcx.GIVEN_REF().text.slice(1);
+        return this.astAt(new ast.GivenReference(name), pcx);
+    }
     visitExprNULL(_pcx) {
         return new ast.ExprNULL();
     }

package/dist/lang/parse-log.d.ts

@@ -265,6 +265,7 @@ type MessageParameterTypes = {
     'query-definition-from-non-query': string;
     'source-definition-name-conflict': string;
     'user-type-definition-name-conflict': string;
+    'given-definition-name-conflict': string;
     'virtual-source-not-yet-implemented': string;
     'virtual-source-missing-user-type-refs': string;
     'virtual-source-unknown-dialect': string;
@@ -279,6 +280,8 @@ type MessageParameterTypes = {
     'selective-import-not-found': string;
     'name-conflict-on-indiscriminate-import': string;
     'failed-import': string;
+    'unsatisfied-given-in-query': string;
+    'given-alias-collision': string;
     'failed-to-compute-output-schema': string;
     'invalid-timeframe-for-time-offset': string;
     'time-comparison-type-mismatch': string;
@@ -286,6 +289,11 @@ type MessageParameterTypes = {
     'time-offset-type-mismatch': string;
     'unexpected-binary-operator': string;
     'illegal-reference-in-parameter-default': string;
+    'given-reference-not-implemented': string;
+    'given-not-found': string;
+    'given-no-tags-after-is': string;
+    'illegal-filter-type': string;
+    'invalid-source-from-given': string;
     'aggregate-analytic-in-select': string;
     'refinement-of-raw-query': string;
     'illegal-multistage-refinement-operation': string;

package/dist/lang/prettify/filter-type.d.ts

@@ -0,0 +1,3 @@
+import type * as parser from '../lib/Malloy/MalloyParser';
+import type { Formatter } from './formatter';
+export declare function formatFilterTypeOrFallback(f: Formatter, ctx: parser.GivenTypeContext | parser.LegalParamTypeContext): void;

package/dist/lang/prettify/filter-type.js

@@ -0,0 +1,38 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ *
+ * RULE: FILTER TYPE — `filter<T>`
+ *
+ * `givenType` and `legalParamType` both have a `FILTER LT malloyBasicType GT`
+ * alternative. The default leaf walker treats LT/GT as binary operators
+ * (spaces both sides), which renders this as `filter < string >`. This rule
+ * intercepts the two contexts and emits the four-token sequence as a glued
+ * unit.
+ *
+ * Falls through to default child recursion when the context is the non-FILTER
+ * alternative (a plain malloy type), so the type's own formatting still runs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFilterTypeOrFallback = formatFilterTypeOrFallback;
+const tokens_1 = require("./tokens");
+const leaf_1 = require("./leaf");
+function formatFilterTypeOrFallback(f, ctx) {
+    const filterTok = ctx.FILTER();
+    if (!filterTok) {
+        for (let i = 0; i < ctx.childCount; i++)
+            f.format(ctx.getChild(i));
+        return;
+    }
+    const action = (0, tokens_1.leadingAction)(f.lastEmittedType, tokens_1.L.FILTER);
+    if (action === 'glue')
+        f.o.trimTrailingSpace();
+    else if (action === 'space')
+        f.o.space();
+    const typeCtx = ctx.malloyBasicType();
+    f.o.text(`filter<${typeCtx.text}>`);
+    const gtTok = ctx.GT().symbol;
+    (0, leaf_1.note)(f, tokens_1.L.GT, gtTok.tokenIndex, gtTok);
+}
+//# sourceMappingURL=filter-type.js.map

package/dist/lang/prettify/formatter.js

@@ -61,6 +61,7 @@ const field_properties_1 = require("./field-properties");
 const pick_case_1 = require("./pick-case");
 const binary_chain_1 = require("./binary-chain");
 const import_select_1 = require("./import-select");
+const filter_type_1 = require("./filter-type");
 class Formatter {
     constructor(src, tokens) {
         this.src = src;
@@ -128,6 +129,11 @@ class Formatter {
         if (node instanceof parser.ImportSelectContext) {
             return (0, import_select_1.formatImportSelect)(this, node);
         }
+        // RULE: FILTER TYPE — `filter<T>` rendered glued, not as `filter < T >`.
+        if (node instanceof parser.GivenTypeContext ||
+            node instanceof parser.LegalParamTypeContext) {
+            return (0, filter_type_1.formatFilterTypeOrFallback)(this, node);
+        }
         // RULE: PICK / CASE / BINARY CHAIN.
         if (node instanceof parser.PickStatementContext)
             return (0, pick_case_1.formatPickStatement)(this, node);

package/dist/lang/prettify/inline-renderer.js

@@ -30,6 +30,10 @@ function renderItemInline(f, ctx) {
     var _a;
     let buf = '';
     let lastType = null;
+    // True between the LT and matching GT of a `filter<T>` window (LT
+    // immediately follows FILTER). All four tokens render glued; mirrors
+    // formatFilterTypeOrFallback in the leaf walker.
+    let inFilterType = false;
     // Coalescing space: skip if buffer is empty or last char already provides
     // separation. Mirrors Out.space() (./out) minus the newline check, since
     // this renderer never emits a newline.
@@ -83,6 +87,22 @@ function renderItemInline(f, ctx) {
             lastType = t.type;
             continue;
         }
+        // filter<T>: glue all four tokens.
+        if (t.type === tokens_1.L.LT && lastType === tokens_1.L.FILTER) {
+            trim();
+            buf += '<';
+            inFilterType = true;
+            lastType = t.type;
+            continue;
+        }
+        if (inFilterType) {
+            trim();
+            buf += text;
+            if (t.type === tokens_1.L.GT)
+                inFilterType = false;
+            lastType = t.type;
+            continue;
+        }
         // Everything else: classifier-driven leading separator + text + (if a
         // binary op) trailing space. Same shape as the leaf walker's default.
         const action = (0, tokens_1.leadingAction)(lastType, t.type);

package/dist/lang/prettify/rules.d.ts

@@ -1,5 +1,5 @@
 import type { ParserRuleContext } from 'antlr4ts';
-export type ItemKind = 'fieldEntry' | 'nestEntry' | 'fieldDef' | 'fieldName' | 'collectionMember' | 'orderBySpec' | 'fieldExpr' | 'joinDef' | 'includeField' | 'indexElement';
+export type ItemKind = 'fieldEntry' | 'nestEntry' | 'fieldDef' | 'fieldName' | 'collectionMember' | 'orderBySpec' | 'fieldExpr' | 'joinDef' | 'includeField' | 'indexElement' | 'givenDef';
 export interface SectionRule {
     ctxClass: new (...args: never[]) => ParserRuleContext;
     keywordTypes: number[];

package/dist/lang/prettify/rules.js

@@ -87,6 +87,7 @@ exports.SECTION_STATEMENT_RULES = [
     // findKeyword in ./sections handles that nested case.
     rule(parser.IncludeItemContext, [tokens_1.L.PUBLIC, tokens_1.L.PRIVATE, tokens_1.L.INTERNAL], c => c.includeList(), 'includeField'),
     rule(parser.IndexStatementContext, [tokens_1.L.INDEX], c => c.indexFields(), 'indexElement'),
+    rule(parser.DefineGivenStatementContext, [tokens_1.L.GIVEN], c => c.givenDefList(), 'givenDef'),
 ];
 // Coarse statement-kind labels for the same-kind-no-blank rule in block
 // bodies. Different kinds preserve a single user-supplied blank line.

package/dist/lang/prettify/sections.js

@@ -156,6 +156,8 @@ function listItems(listCtx, itemKind) {
                 return c instanceof parser.IncludeFieldContext;
             case 'indexElement':
                 return c instanceof parser.IndexElementContext;
+            case 'givenDef':
+                return c instanceof parser.GivenDefContext;
         }
     };
     const out = [];

package/dist/lang/prettify/tokens.js

@@ -67,6 +67,8 @@ exports.TOP_LEVEL_STARTERS = new Set([
     exports.L.QUERY,
     exports.L.RUN,
     exports.L.IMPORT,
+    exports.L.GIVEN,
+    exports.L.TYPE,
 ]);
 // Token types after which an immediately following `(` or `[` is a call /
 // subscript and should hug (no leading space). Anything else (binary ops,

package/dist/lang/test/expr-to-str.js

@@ -28,6 +28,8 @@ function exprToStr(e, symbols) {
         }
         case 'parameter':
             return `{parameter ${e.path}}`;
+        case 'given':
+            return `{$${e.refName}}`;
         case '()':
             return `(${subExpr(e.e)})`;
         case 'numberLiteral':

package/dist/lang/test/parse-expects.d.ts

@@ -48,6 +48,7 @@ declare global {
             compilesTo(exprString: string): R;
             toBeExpr(exprString: string): R;
             hasFieldUsage(paths: string[][]): R;
+            hasExpandedFieldUsage(paths: string[][]): R;
         }
     }
 }

package/dist/lang/test/parse-expects.js

@@ -1,5 +1,4 @@
 "use strict";
-/* eslint-disable no-console */
 /*
  * Copyright 2023 Google LLC
  *
@@ -241,18 +240,36 @@ expect.extend({
         if (!badRefs.pass) {
             return badRefs;
         }
-        const actual = bx.generated().fieldUsage;
+        const actual = (0, model_1.fieldUsageFrom)(bx.generated().refSummary);
         const actualPaths = actual.filter(u => (0, model_1.bareFieldUsage)(u)).map(u => u.path);
-        // there is no guarantee of the order of field usage data, so we sort the two lists
-        // so i need to compare sorted versions of the two lists... we can sort on path.join('.)
-        // maybe make a lambda for that and pass it to sort
-        const pass = this.equals(actualPaths.sort((a, b) => a.join('.').localeCompare(b.join('.'))), paths.sort((a, b) => a.join('.').localeCompare(b.join('.'))));
-        const msg = pass
-            ? `Matched: ${actual}`
-            : this.utils.diff(paths, actualPaths);
-        return { pass, message: () => `${msg}` };
+        return comparePathSets(this, actualPaths, paths);
+    },
+    hasExpandedFieldUsage: function (segment, paths) {
+        var _a;
+        if (!(0, model_1.isQuerySegment)(segment) && !(0, model_1.isIndexSegment)(segment)) {
+            return {
+                pass: false,
+                message: () => 'hasExpandedFieldUsage: receiver is not a query or index segment',
+            };
+        }
+        const actualPaths = ((_a = segment.expandedFieldUsage) !== null && _a !== void 0 ? _a : [])
+            .filter(u => (0, model_1.bareFieldUsage)(u))
+            .map(u => u.path);
+        return comparePathSets(this, actualPaths, paths);
     },
 });
+// Field-usage entries have no order or duplication guarantee. Compare as
+// sets of `path.join('.')` strings so equality is purely set membership.
+function comparePathSets(ctx, actualPaths, expectedPaths) {
+    const toKey = (p) => p.join('.');
+    const actualSet = new Set(actualPaths.map(toKey));
+    const expectedSet = new Set(expectedPaths.map(toKey));
+    const pass = ctx.equals(actualSet, expectedSet);
+    const msg = pass
+        ? `Matched: ${[...actualSet].sort().join(', ')}`
+        : ctx.utils.diff([...expectedSet].sort(), [...actualSet].sort());
+    return { pass, message: () => `${msg}` };
+}
 function problemSpecSummary(s) {
     return `${s.severity} '${'message' in s ? s.message : s.code}' ${s.data !== undefined ? (0, test_translator_1.pretty)(s.data) : ''}`;
 }

package/dist/model/constant_expression_compiler.js

@@ -87,6 +87,7 @@ class ConstantQueryStruct extends query_node_1.QueryStruct {
         // Create minimal model with empty structs map
         const minimalModel = {
             structs: new Map(),
+            givens: {},
         };
         // Create minimal prepare result options with eventStream
         const minimalPrepareOptions = { eventStream };

package/dist/model/expression_compiler.d.ts

@@ -1,4 +1,4 @@
-import type { Expr, FunctionCallNode, FunctionOverloadDef, FunctionOrderBy, FieldnameNode, OutputFieldNode, GenericSQLExpr, FilteredExpr, UngroupNode, ParameterNode, AggregateExpr, SourceReferenceNode, CaseExpr } from './malloy_types';
+import type { Expr, FunctionCallNode, FunctionOverloadDef, FunctionOrderBy, GivenRefNode, FieldnameNode, OutputFieldNode, GenericSQLExpr, FilteredExpr, UngroupNode, ParameterNode, AggregateExpr, SourceReferenceNode, CaseExpr } from './malloy_types';
 import { type FieldInstanceResult } from './field_instance';
 import { GenerateState } from './utils';
 import type { QueryStruct } from './query_node';
@@ -11,6 +11,7 @@ export declare function generateFunctionCallExpression(resultSet: FieldInstanceR
 export declare function generateFieldFragment(resultSet: FieldInstanceResult, context: QueryStruct, expr: FieldnameNode, state: GenerateState): string;
 export declare function generateOutputFieldFragment(resultSet: FieldInstanceResult, _context: QueryStruct, frag: OutputFieldNode, _state: GenerateState): string;
 export declare function generateParameterFragment(resultSet: FieldInstanceResult, context: QueryStruct, expr: ParameterNode, state: GenerateState): string;
+export declare function generateGivenFragment(resultSet: FieldInstanceResult, context: QueryStruct, expr: GivenRefNode, state: GenerateState): string;
 export declare function generateFilterFragment(resultSet: FieldInstanceResult, context: QueryStruct, expr: FilteredExpr, state: GenerateState): string;
 export declare function generateDimFragment(resultSet: FieldInstanceResult, context: QueryStruct, expr: Expr, state: GenerateState): string;
 export declare function generateUngroupedFragment(resultSet: FieldInstanceResult, context: QueryStruct, expr: UngroupNode, state: GenerateState): string;