@malloydata/malloy 0.0.326 → 0.0.327

package/dist/malloy.js

@@ -25,7 +25,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryModelCache = exports.CacheManager = exports.CSVWriter = exports.JSONWriter = exports.DataWriter = exports.DataRecord = exports.DataArray = exports.Result = exports.ExploreMaterializer = exports.PreparedResultMaterializer = exports.QueryMaterializer = exports.ModelMaterializer = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.Runtime = exports.ExploreField = exports.JoinRelationship = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicField = exports.AtomicFieldType = exports.Explore = exports.SourceRelationship = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.PreparedResult = exports.DocumentCompletion = exports.DocumentSymbol = exports.DocumentPosition = exports.DocumentRange = exports.DocumentTablePath = exports.Parse = exports.PreparedQuery = exports.Model = exports.MalloyError = exports.Malloy = void 0;
 const lang_1 = require("./lang");
 const model_1 = require("./model");
-const luxon_1 = require("luxon");
 const dialect_1 = require("./dialect");
 const version_1 = require("./version");
 const uuid_1 = require("uuid");
@@ -33,6 +32,7 @@ const annotation_1 = require("./annotation");
 const sql_block_1 = require("./model/sql_block");
 const utils_1 = require("./lang/utils");
 const reference_list_1 = require("./lang/reference-list");
+const row_data_utils_1 = require("./api/row_data_utils");
 function isSourceComponent(source) {
     return (source.type === 'table' ||
         source.type === 'sql_select' ||
@@ -2122,7 +2122,15 @@ class ModelMaterializer extends FluentState {
         const result = await this.loadQuery(searchMapMalloy, options).run({
             rowLimit: 1000,
         });
-        return result._queryResult.result;
+        const rawResult = result._queryResult.result;
+        return rawResult.map(row => ({
+            ...row,
+            cardinality: (0, row_data_utils_1.rowDataToNumber)(row.cardinality),
+            values: row.values.map(v => ({
+                ...v,
+                weight: (0, row_data_utils_1.rowDataToNumber)(v.weight),
+            })),
+        }));
     }
     /**
      * Materialize the final query contained within this loaded `Model`.
@@ -2630,7 +2638,7 @@ class DataJSON extends ScalarData {
 }
 class DataNumber extends ScalarData {
     constructor(value, field, parent, parentRecord) {
-        super(value, field, parent, parentRecord);
+        super((0, row_data_utils_1.rowDataToNumber)(value), field, parent, parentRecord);
         this._field = field;
     }
     get field() {
@@ -2650,44 +2658,13 @@ class DataNumber extends ScalarData {
         return -1;
     }
 }
-function valueToDate(value) {
-    // TODO properly map the data from BQ/Postgres types
-    if (value instanceof Date) {
-        return value;
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const valAsAny = value;
-    if (valAsAny.constructor.name === 'Date') {
-        // For some reason duckdb TSTZ values come back as objects which do not
-        // pass "instance of" but do seem date like.
-        return new Date(value);
-    }
-    else if (typeof value === 'number') {
-        return new Date(value);
-    }
-    else if (typeof value !== 'string') {
-        return new Date(value.value);
-    }
-    else {
-        // Postgres timestamps end up here, and ideally we would know the system
-        // timezone of the postgres instance to correctly create a Date() object
-        // which represents the same instant in time, but we don't have the data
-        // flow to implement that. This may be a problem at some future day,
-        // so here is a comment, for that day.
-        let parsed = luxon_1.DateTime.fromISO(value, { zone: 'UTC' });
-        if (!parsed.isValid) {
-            parsed = luxon_1.DateTime.fromSQL(value, { zone: 'UTC' });
-        }
-        return parsed.toJSDate();
-    }
-}
 class DataTimestamp extends ScalarData {
     constructor(value, field, parent, parentRecord) {
         super(value, field, parent, parentRecord);
         this._field = field;
     }
     get value() {
-        return valueToDate(this._value);
+        return (0, row_data_utils_1.rowDataToDate)(this._value);
     }
     get field() {
         return this._field;
@@ -2711,7 +2688,7 @@ class DataDate extends ScalarData {
         this._field = field;
     }
     get value() {
-        return valueToDate(this._value);
+        return (0, row_data_utils_1.rowDataToDate)(this._value);
     }
     get field() {
         return this._field;
@@ -2755,6 +2732,161 @@ class DataNull extends Data {
         return '<null>';
     }
 }
+/**
+ * Safe bigint conversion - handles floats that are incorrectly typed as bigint
+ * (e.g., avg() results which should be float but Malloy marks as bigint).
+ */
+function safeRowDataToBigint(value) {
+    const strValue = (0, row_data_utils_1.rowDataToSerializedBigint)(value);
+    if (strValue.includes('.') ||
+        strValue.includes('e') ||
+        strValue.includes('E')) {
+        return (0, row_data_utils_1.rowDataToNumber)(value);
+    }
+    try {
+        return BigInt(strValue);
+    }
+    catch {
+        return (0, row_data_utils_1.rowDataToNumber)(value);
+    }
+}
+/**
+ * Safe bigint serialization - returns number for floats that should stay as numbers.
+ */
+function safeRowDataToSerializedBigint(value) {
+    const strValue = (0, row_data_utils_1.rowDataToSerializedBigint)(value);
+    if (strValue.includes('.') ||
+        strValue.includes('e') ||
+        strValue.includes('E')) {
+        return (0, row_data_utils_1.rowDataToNumber)(value);
+    }
+    return strValue;
+}
+/**
+ * Normalizers for toObject() - returns JS native types (number | bigint, Date)
+ */
+const OBJECT_NORMALIZERS = {
+    number: row_data_utils_1.rowDataToNumber,
+    bigint: safeRowDataToBigint,
+    date: row_data_utils_1.rowDataToDate,
+};
+/**
+ * Normalizers for toJSON() - returns JSON-safe types (number | string, ISO strings)
+ */
+const JSON_NORMALIZERS = {
+    number: row_data_utils_1.rowDataToNumber,
+    bigint: safeRowDataToSerializedBigint,
+    date: (value) => (0, row_data_utils_1.rowDataToDate)(value).toISOString(),
+};
+/**
+ * Walk a QueryData array and normalize values according to the given normalizers.
+ */
+function walkQueryData(data, structDef, normalizers) {
+    return data.map(row => walkQueryDataRow(row, structDef, normalizers));
+}
+/**
+ * Walk a QueryDataRow and normalize values according to the given normalizers.
+ */
+function walkQueryDataRow(row, structDef, normalizers) {
+    var _a;
+    const result = {};
+    for (const fieldDef of structDef.fields) {
+        const fieldName = (_a = fieldDef.as) !== null && _a !== void 0 ? _a : fieldDef.name;
+        const value = row[fieldName];
+        result[fieldName] = walkValue(value, fieldDef, normalizers);
+    }
+    return result;
+}
+/**
+ * Normalize a single value based on its field definition.
+ */
+function walkValue(value, fieldDef, normalizers) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    // Handle scalar types
+    if (fieldDef.type === 'number') {
+        const numberDef = fieldDef;
+        if (numberDef.numberType === 'bigint') {
+            return normalizers.bigint(value);
+        }
+        return normalizers.number(value);
+    }
+    if (fieldDef.type === 'date' ||
+        fieldDef.type === 'timestamp' ||
+        fieldDef.type === 'timestamptz') {
+        return normalizers.date(value);
+    }
+    if (fieldDef.type === 'string' ||
+        fieldDef.type === 'boolean' ||
+        fieldDef.type === 'json' ||
+        fieldDef.type === 'sql native') {
+        // Pass through as-is (or with minimal conversion for booleans from numbers)
+        if (fieldDef.type === 'boolean' && typeof value === 'number') {
+            return value !== 0;
+        }
+        return value;
+    }
+    // Handle arrays
+    if (fieldDef.type === 'array') {
+        if (!Array.isArray(value)) {
+            return value; // Unexpected, but don't crash
+        }
+        if ((0, model_1.isRepeatedRecord)(fieldDef)) {
+            // Array of records - recurse into each record
+            return value.map(item => walkQueryDataRow(item, fieldDef, normalizers));
+        }
+        else if ((0, model_1.isBasicArray)(fieldDef)) {
+            // Scalar array - normalize each element based on elementTypeDef
+            // Cast needed because QueryValue type doesn't cleanly express scalar arrays
+            const elementType = fieldDef.elementTypeDef;
+            return value.map(item => walkScalarValue(item, elementType, normalizers));
+        }
+    }
+    // Handle records (non-array)
+    if (fieldDef.type === 'record') {
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            return walkQueryDataRow(value, fieldDef, normalizers);
+        }
+    }
+    // Fallback - pass through
+    return value;
+}
+/**
+ * Normalize a scalar value (not in a row context, e.g., elements of a scalar array).
+ */
+function walkScalarValue(value, typeDef, normalizers) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeDef.type === 'number') {
+        const numberDef = typeDef;
+        if (numberDef.numberType === 'bigint') {
+            return normalizers.bigint(value);
+        }
+        return normalizers.number(value);
+    }
+    if (typeDef.type === 'date' ||
+        typeDef.type === 'timestamp' ||
+        typeDef.type === 'timestamptz') {
+        return normalizers.date(value);
+    }
+    if (typeDef.type === 'boolean' && typeof value === 'number') {
+        return value !== 0;
+    }
+    // Handle nested arrays (array of arrays)
+    if (typeDef.type === 'array' && Array.isArray(value)) {
+        if ((0, model_1.isBasicArray)(typeDef)) {
+            const elementType = typeDef.elementTypeDef;
+            return value.map(item => walkScalarValue(item, elementType, normalizers));
+        }
+        else if ((0, model_1.isRepeatedRecord)(typeDef)) {
+            return value.map(item => walkQueryDataRow(item, typeDef, normalizers));
+        }
+    }
+    // Pass through other types
+    return value;
+}
 class DataArray extends Data {
     constructor(queryData, field, parent, parentRecord) {
         super(field, parent, parentRecord);
@@ -2769,11 +2901,27 @@ class DataArray extends Data {
         return this._field;
     }
     /**
-     * @return The raw object form of the data.
+     * @return The raw query data as returned by the database driver.
+     * Values may be in various formats depending on the driver (wrapper objects, strings, etc.).
+     * Use this for passing to mapData() which handles normalization itself.
      */
-    toObject() {
+    get rawData() {
         return this.queryData;
     }
+    /**
+     * @return Normalized data with JS native types (number | bigint, Date).
+     * Use this for CSV output, tests, and general programmatic access.
+     */
+    toObject() {
+        return walkQueryData(this.queryData, this._field.structDef, OBJECT_NORMALIZERS);
+    }
+    /**
+     * @return Normalized data with JSON-safe types (numbers as number | string, dates as ISO strings).
+     * Use this for JSON serialization.
+     */
+    toJSON() {
+        return walkQueryData(this.queryData, this._field.structDef, JSON_NORMALIZERS);
+    }
     path(...path) {
         return getPath(this, path);
     }
@@ -2784,7 +2932,6 @@ class DataArray extends Data {
             this.rowCache.set(index, record);
         }
         return record;
-        return new DataRecord(this.queryData[index], index, this.field, this, this.parentRecord);
     }
     get rowCount() {
         return this.queryData.length;
@@ -2833,8 +2980,19 @@ class DataRecord extends Data {
         this._field = field;
         this.index = index;
     }
+    /**
+     * @return Normalized data with JS native types (number | bigint, Date).
+     * Use this for CSV output, tests, and general programmatic access.
+     */
     toObject() {
-        return this.queryDataRow;
+        return walkQueryDataRow(this.queryDataRow, this._field.structDef, OBJECT_NORMALIZERS);
+    }
+    /**
+     * @return Normalized data with JSON-safe types (numbers as number | string, dates as ISO strings).
+     * Use this for JSON serialization.
+     */
+    toJSON() {
+        return walkQueryDataRow(this.queryDataRow, this._field.structDef, JSON_NORMALIZERS);
     }
     path(...path) {
         return getPath(this, path);
@@ -2929,7 +3087,8 @@ class JSONWriter extends DataWriter {
             if (row.index !== undefined && row.index > 0) {
                 this.stream.write(',\n');
             }
-            const json = JSON.stringify(row.toObject(), null, 2);
+            // toJSON() returns JSON-safe values: bigints as strings, dates as ISO strings
+            const json = JSON.stringify(row.toJSON(), null, 2);
             const jsonLines = json.split('\n');
             for (let i = 0; i < jsonLines.length; i++) {
                 const line = jsonLines[i];
@@ -2991,6 +3150,10 @@ class CSVWriter extends DataWriter {
         else if (typeof value === 'boolean' || typeof value === 'number') {
             return JSON.stringify(value);
         }
+        else if (typeof value === 'bigint') {
+            // Bigints from toObject() - write as unquoted number string
+            return value.toString();
+        }
         else {
             return `${value}`;
         }

package/dist/model/malloy_types.d.ts

@@ -427,7 +427,7 @@ export interface StringTypeDef {
 export type StringFieldDef = StringTypeDef & AtomicFieldDef;
 export interface NumberTypeDef {
     type: 'number';
-    numberType?: 'integer' | 'float';
+    numberType?: 'integer' | 'float' | 'bigint';
 }
 export type NumberFieldDef = NumberTypeDef & AtomicFieldDef;
 export interface BooleanTypeDef {
@@ -923,7 +923,7 @@ export interface Note {
 export interface ModelAnnotation extends Annotation {
     id: string;
 }
-export type QueryScalar = string | boolean | number | Date | Buffer | null;
+export type QueryScalar = string | boolean | number | bigint | Date | Buffer | null;
 /** One value in one column of returned data. */
 export type QueryValue = QueryScalar | QueryData | QueryDataRow;
 /** A row of returned data. */

package/dist/model/query_model_impl.js

@@ -14,6 +14,7 @@ const stage_writer_1 = require("./stage_writer");
 const dialect_1 = require("../dialect");
 const utils_1 = require("./materialization/utils");
 const query_node_1 = require("./query_node");
+const row_data_utils_1 = require("../api/row_data_utils");
 function makeQueryModel(modelDef, eventStream) {
     return new QueryModelImpl(modelDef, eventStream);
 }
@@ -252,7 +253,10 @@ class QueryModelImpl {
         const result = await connection.runSQL(query, {
             rowLimit: 1000,
         });
-        return result.rows;
+        return result.rows.map(row => ({
+            ...row,
+            weight: (0, row_data_utils_1.rowDataToNumber)(row['weight']),
+        }));
     }
 }
 exports.QueryModelImpl = QueryModelImpl;

package/dist/test/cellsToObject.d.ts

@@ -0,0 +1,6 @@
+import type * as Malloy from '@malloydata/malloy-interfaces';
+/**
+ * Convert Malloy.Data (array of record cells) to an array of plain JS objects.
+ * This is the inverse of mapData() in util.ts.
+ */
+export declare function cellsToObjects(data: Malloy.Data, schema: Malloy.Schema): Record<string, unknown>[];

package/dist/test/cellsToObject.js

@@ -0,0 +1,111 @@
+"use strict";
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cellsToObjects = cellsToObjects;
+/**
+ * Convert a Malloy.Cell to a plain JS value.
+ * - null_cell → null
+ * - string_cell → string
+ * - number_cell → number
+ * - boolean_cell → boolean
+ * - date_cell → string (ISO date format)
+ * - timestamp_cell → string (ISO timestamp format)
+ * - json_cell → parsed JSON value
+ * - sql_native_cell → parsed JSON value
+ * - array_cell → array of converted values
+ * - record_cell → object with field names from schema
+ */
+function cellToValue(cell, fieldInfo) {
+    switch (cell.kind) {
+        case 'null_cell':
+            return null;
+        case 'string_cell':
+            return cell.string_value;
+        case 'number_cell':
+            return cell.number_value;
+        case 'big_number_cell':
+            return BigInt(cell.number_value);
+        case 'boolean_cell':
+            return cell.boolean_value;
+        case 'date_cell':
+            return cell.date_value;
+        case 'timestamp_cell':
+            return cell.timestamp_value;
+        case 'json_cell':
+            return JSON.parse(cell.json_value);
+        case 'sql_native_cell':
+            return JSON.parse(cell.sql_native_value);
+        case 'array_cell': {
+            if (fieldInfo.kind !== 'dimension') {
+                throw new Error(`Expected dimension for array, got ${fieldInfo.kind}`);
+            }
+            const type = fieldInfo.type;
+            if (type.kind !== 'array_type') {
+                throw new Error(`Expected array_type, got ${type.kind}`);
+            }
+            const elementFieldInfo = {
+                kind: 'dimension',
+                name: 'element',
+                type: type.element_type,
+            };
+            return cell.array_value.map(c => cellToValue(c, elementFieldInfo));
+        }
+        case 'record_cell': {
+            // Records can come from either a join or a dimension with record_type
+            // record_type.fields returns DimensionInfo[], schema.fields returns FieldInfo[]
+            let fields;
+            let getFieldInfo;
+            if (fieldInfo.kind === 'join') {
+                fields = fieldInfo.schema.fields;
+                getFieldInfo = i => fieldInfo.schema.fields[i];
+            }
+            else if (fieldInfo.kind === 'dimension' &&
+                fieldInfo.type.kind === 'record_type') {
+                // Capture the record type to help TypeScript narrow
+                const recordType = fieldInfo.type;
+                fields = recordType.fields;
+                // DimensionInfo needs to be wrapped as a FieldInfo
+                getFieldInfo = i => ({
+                    kind: 'dimension',
+                    name: recordType.fields[i].name,
+                    type: recordType.fields[i].type,
+                });
+            }
+            else {
+                throw new Error(`Expected join or dimension with record_type for record, got ${fieldInfo.kind}`);
+            }
+            const result = {};
+            for (let i = 0; i < fields.length; i++) {
+                result[fields[i].name] = cellToValue(cell.record_value[i], getFieldInfo(i));
+            }
+            return result;
+        }
+        default:
+            throw new Error(`Unknown cell kind: ${cell.kind}`);
+    }
+}
+/**
+ * Convert Malloy.Data (array of record cells) to an array of plain JS objects.
+ * This is the inverse of mapData() in util.ts.
+ */
+function cellsToObjects(data, schema) {
+    if (data.kind !== 'array_cell') {
+        throw new Error(`Expected array_cell at root, got ${data.kind}`);
+    }
+    const rootFieldInfo = {
+        kind: 'join',
+        name: 'root',
+        relationship: 'one',
+        schema,
+    };
+    return data.array_value.map(cell => {
+        const result = cellToValue(cell, rootFieldInfo);
+        return result;
+    });
+}
+//# sourceMappingURL=cellsToObject.js.map

package/dist/test/index.d.ts

@@ -1,3 +1,10 @@
+export { TV } from './test-values';
+export type { TypedValue } from './test-values';
+export { mkTestModel, wrapTestModel, extendTestModel } from './test-models';
+export type { TestModelSources, TestModel } from './test-models';
+export { runQuery } from './runQuery';
+export type { QueryResult } from './runQuery';
+export type { ExpectedRow, MatcherOptions } from './resultMatchers';
 /**
  * Accepts databases in env, either via comma-separated dialect list
  * (MALLOY_DATABASES=) or a single database (MALLOY_DATABASE=). returns either

package/dist/test/index.js

@@ -1,30 +1,26 @@
 "use strict";
 /*
- * Copyright 2024 Google LLC
- *
- * Permission is hereby granted, free of charge, to any person obtaining
- * a copy of this software and associated documentation files
- * (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge,
- * publish, distribute, sublicense, and/or sell copies of the Software,
- * and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be
- * included in all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
- * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
- * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
- * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
- * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runQuery = exports.extendTestModel = exports.wrapTestModel = exports.mkTestModel = exports.TV = void 0;
 exports.databasesFromEnvironmentOr = databasesFromEnvironmentOr;
 exports.describeIfDatabaseAvailable = describeIfDatabaseAvailable;
 exports.brokenIn = brokenIn;
+// Test data creation
+var test_values_1 = require("./test-values");
+Object.defineProperty(exports, "TV", { enumerable: true, get: function () { return test_values_1.TV; } });
+var test_models_1 = require("./test-models");
+Object.defineProperty(exports, "mkTestModel", { enumerable: true, get: function () { return test_models_1.mkTestModel; } });
+Object.defineProperty(exports, "wrapTestModel", { enumerable: true, get: function () { return test_models_1.wrapTestModel; } });
+Object.defineProperty(exports, "extendTestModel", { enumerable: true, get: function () { return test_models_1.extendTestModel; } });
+// Query execution
+var runQuery_1 = require("./runQuery");
+Object.defineProperty(exports, "runQuery", { enumerable: true, get: function () { return runQuery_1.runQuery; } });
+/*
+ * Legacy exports - kept for backwards compatibility
+ */
 /**
  * Accepts databases in env, either via comma-separated dialect list
  * (MALLOY_DATABASES=) or a single database (MALLOY_DATABASE=). returns either

package/dist/test/matchers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Import this module to register Jest matchers (toMatchResult, toEqualResult).
+ *
+ * Usage in jest.config.js:
+ *   setupFilesAfterEnv: ['@malloydata/malloy/test/matchers']
+ *
+ * Or import directly in a test file:
+ *   import '@malloydata/malloy/test/matchers';
+ */
+import './resultMatchers';

package/dist/test/matchers.js

@@ -0,0 +1,17 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Import this module to register Jest matchers (toMatchResult, toEqualResult).
+ *
+ * Usage in jest.config.js:
+ *   setupFilesAfterEnv: ['@malloydata/malloy/test/matchers']
+ *
+ * Or import directly in a test file:
+ *   import '@malloydata/malloy/test/matchers';
+ */
+require("./resultMatchers");
+//# sourceMappingURL=matchers.js.map

package/dist/test/resultMatchers.d.ts

@@ -0,0 +1,42 @@
+import type { TestModel } from './test-models';
+/** Expected row shape for result matching */
+export type ExpectedRow = Record<string, unknown>;
+/** Options for result matchers */
+export interface MatcherOptions {
+    debug?: boolean;
+}
+declare global {
+    namespace jest {
+        interface Matchers<R> {
+            /**
+             * Partial matching - extra fields and rows allowed.
+             *
+             * @example
+             * await expect(query).toMatchResult(tm, {name: 'alice'});
+             * await expect(query).toMatchResult(tm, {name: 'alice'}, {name: 'bob'});
+             */
+            toMatchResult(tm: TestModel, ...rowsOrOptions: (ExpectedRow | MatcherOptions)[]): Promise<R>;
+            /**
+             * Exact matching - exact fields and exact row count.
+             *
+             * @example
+             * await expect(query).toEqualResult(tm, [{name: 'alice'}]);
+             */
+            toEqualResult(tm: TestModel, rows: ExpectedRow[], options?: MatcherOptions): Promise<R>;
+            /**
+             * Partial fields but exact row count.
+             *
+             * @example
+             * await expect(query).toMatchRows(tm, [{name: 'alice'}, {name: 'bob'}]);
+             */
+            toMatchRows(tm: TestModel, rows: ExpectedRow[], options?: MatcherOptions): Promise<R>;
+            /**
+             * Check nested values via dotted paths. Takes first element at each array level.
+             *
+             * @example
+             * expect(result.data[0]).toHavePath({'by_state.state': 'TX'});
+             */
+            toHavePath(paths: Record<string, unknown>): R;
+        }
+    }
+}