@true-sight/model-schema 1.2.1 → 1.3.0

package/dist/dsl/compile/compile-explore.js

@@ -5,6 +5,7 @@ require("reflect-metadata");
 const manifest_expr_types_js_1 = require("../../types/manifest-expr.types.js");
 const compile_errors_js_1 = require("../errors/compile-errors.js");
 const field_js_1 = require("../expr/field.js");
+const define_always_filter_js_1 = require("../expr/define-always-filter.js");
 const explore_registry_js_1 = require("../registry/explore-registry.js");
 const view_registry_js_1 = require("../registry/view-registry.js");
 const compile_view_js_1 = require("./compile-view.js");
@@ -53,6 +54,7 @@ function compileExplore(ExploreClass) {
     }
     const views = [...viewClasses.values()].map((ViewClass) => (0, compile_view_js_1.compileView)(ViewClass));
     const alwaysInclude = resolveAlwaysInclude(ExploreClass, exploreMeta.name, views, scopedViewNames);
+    const alwaysFilter = resolveAlwaysFilter(exploreMeta, exploreMeta.name, views, scopedViewNames);
     return {
         name: exploreMeta.name,
         label: exploreMeta.label,
@@ -60,6 +62,7 @@ function compileExplore(ExploreClass) {
         joins,
         views,
         ...(alwaysInclude ? { alwaysInclude } : {}),
+        ...(alwaysFilter ? { alwaysFilter } : {}),
     };
 }
 function resolveAlwaysInclude(ExploreClass, exploreName, views, scopedViewNames) {
@@ -106,3 +109,55 @@ function resolveAlwaysInclude(ExploreClass, exploreName, views, scopedViewNames)
     }
     return names.length > 0 ? names : undefined;
 }
+function resolveAlwaysFilter(exploreMeta, exploreName, views, scopedViewNames) {
+    const callback = exploreMeta.alwaysFilter;
+    if (!callback) {
+        return undefined;
+    }
+    const viewCtors = (0, define_always_filter_js_1.getAlwaysFilterViews)(callback);
+    if (!viewCtors) {
+        throw new compile_errors_js_1.AlwaysFilterError(exploreName, 'use defineAlwaysFilter');
+    }
+    const scope = (0, join_helpers_js_1.createJoinScope)(scopedViewNames);
+    const proxies = viewCtors.map((ViewClass) => {
+        const meta = (0, view_registry_js_1.getViewMeta)(ViewClass);
+        if (!meta) {
+            throw new compile_errors_js_1.AlwaysFilterError(exploreName, `unknown view '${ViewClass.name}'`);
+        }
+        const proxy = scope[meta.name];
+        if (!proxy) {
+            throw new compile_errors_js_1.AlwaysFilterError(exploreName, `view '${meta.name}' is not on this explore`);
+        }
+        return proxy;
+    });
+    const raw = callback(...proxies);
+    if (!Array.isArray(raw)) {
+        throw new compile_errors_js_1.AlwaysFilterError(exploreName, 'callback must return filter groups');
+    }
+    const dimensions = new Set();
+    for (const view of views) {
+        for (const dimension of view.dimensions) {
+            dimensions.add(`${view.name}.${dimension.name}`);
+        }
+    }
+    const groups = raw.map((group) => ({
+        type: group.type,
+        group: group.group.map((filter) => {
+            if (!(filter.dimension instanceof field_js_1.Field)) {
+                throw new compile_errors_js_1.AlwaysFilterError(exploreName, 'dimension must be a Field');
+            }
+            const ref = filter.dimension.ref;
+            if (!(0, manifest_expr_types_js_1.isRefString)(ref)) {
+                throw new compile_errors_js_1.AlwaysFilterError(exploreName, `invalid name "${String(ref)}"`);
+            }
+            if (!dimensions.has(ref)) {
+                throw new compile_errors_js_1.AlwaysFilterError(exploreName, `unknown dimension '${ref}'`);
+            }
+            return {
+                dimensionName: ref,
+                orStatements: filter.orStatements,
+            };
+        }),
+    }));
+    return groups.length > 0 ? groups : undefined;
+}

package/dist/dsl/errors/compile-errors.d.ts

@@ -13,3 +13,6 @@ export declare class DuplicateNameError extends Error {
 export declare class AlwaysIncludeError extends Error {
     constructor(exploreName: string, reason: string);
 }
+export declare class AlwaysFilterError extends Error {
+    constructor(exploreName: string, reason: string);
+}

package/dist/dsl/errors/compile-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlwaysIncludeError = exports.DuplicateNameError = exports.JoinScopeError = exports.InvalidMeasureError = exports.MissingMetadataError = void 0;
+exports.AlwaysFilterError = exports.AlwaysIncludeError = exports.DuplicateNameError = exports.JoinScopeError = exports.InvalidMeasureError = exports.MissingMetadataError = void 0;
 class MissingMetadataError extends Error {
     constructor(kind, className) {
         super(`${kind} metadata missing on ${className}`);
@@ -38,3 +38,10 @@ class AlwaysIncludeError extends Error {
     }
 }
 exports.AlwaysIncludeError = AlwaysIncludeError;
+class AlwaysFilterError extends Error {
+    constructor(exploreName, reason) {
+        super(`Always filter on explore '${exploreName}': ${reason}`);
+        this.name = 'AlwaysFilterError';
+    }
+}
+exports.AlwaysFilterError = AlwaysFilterError;

package/dist/dsl/expr/define-always-filter.d.ts

@@ -0,0 +1,7 @@
+import type { AlwaysFilterCallback, AlwaysFilterDraftGroup } from '../types/join-scope.types.js';
+import type { StrictViewProxy, ViewConstructor } from '../types/view-proxy.types.js';
+export declare const ALWAYS_FILTER_VIEWS: unique symbol;
+export declare function defineAlwaysFilter<const Vs extends readonly ViewConstructor[]>(views: Vs, fn: (...proxies: {
+    [I in keyof Vs]: Vs[I] extends ViewConstructor ? StrictViewProxy<Vs[I]> : never;
+}) => AlwaysFilterDraftGroup[]): AlwaysFilterCallback;
+export declare function getAlwaysFilterViews(callback: AlwaysFilterCallback): readonly ViewConstructor[] | undefined;

package/dist/dsl/expr/define-always-filter.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALWAYS_FILTER_VIEWS = void 0;
+exports.defineAlwaysFilter = defineAlwaysFilter;
+exports.getAlwaysFilterViews = getAlwaysFilterViews;
+exports.ALWAYS_FILTER_VIEWS = Symbol.for('true-sight.alwaysFilterViews');
+function defineAlwaysFilter(views, fn) {
+    const callback = fn;
+    Object.defineProperty(callback, exports.ALWAYS_FILTER_VIEWS, {
+        value: views,
+        enumerable: false,
+    });
+    return callback;
+}
+function getAlwaysFilterViews(callback) {
+    return callback[exports.ALWAYS_FILTER_VIEWS];
+}

package/dist/dsl/expr/index.d.ts

@@ -1,6 +1,7 @@
 export { Field, field } from './field.js';
 export type { VisibleField, HiddenField } from './field.js';
 export { defineAlwaysInclude } from './define-always-include.js';
+export { defineAlwaysFilter } from './define-always-filter.js';
 export { count, max, min, sum } from './aggregates.js';
 export { raw } from './raw.js';
 export { joinScope, isJoinScopeTagged } from './join-scope.js';

package/dist/dsl/expr/index.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isJoinScopeTagged = exports.joinScope = exports.raw = exports.sum = exports.min = exports.max = exports.count = exports.defineAlwaysInclude = exports.field = exports.Field = void 0;
+exports.isJoinScopeTagged = exports.joinScope = exports.raw = exports.sum = exports.min = exports.max = exports.count = exports.defineAlwaysFilter = exports.defineAlwaysInclude = exports.field = exports.Field = void 0;
 var field_js_1 = require("./field.js");
 Object.defineProperty(exports, "Field", { enumerable: true, get: function () { return field_js_1.Field; } });
 Object.defineProperty(exports, "field", { enumerable: true, get: function () { return field_js_1.field; } });
 var define_always_include_js_1 = require("./define-always-include.js");
 Object.defineProperty(exports, "defineAlwaysInclude", { enumerable: true, get: function () { return define_always_include_js_1.defineAlwaysInclude; } });
+var define_always_filter_js_1 = require("./define-always-filter.js");
+Object.defineProperty(exports, "defineAlwaysFilter", { enumerable: true, get: function () { return define_always_filter_js_1.defineAlwaysFilter; } });
 var aggregates_js_1 = require("./aggregates.js");
 Object.defineProperty(exports, "count", { enumerable: true, get: function () { return aggregates_js_1.count; } });
 Object.defineProperty(exports, "max", { enumerable: true, get: function () { return aggregates_js_1.max; } });

package/dist/dsl/registry/explore-registry.d.ts

@@ -1,11 +1,12 @@
 import type { ManifestExpr } from '../../types/manifest-expr.types.js';
 import type { JoinRelationship, JoinType } from '../../types/manifest.types.js';
-import type { AlwaysIncludeCallback } from '../types/join-scope.types.js';
+import type { AlwaysFilterCallback, AlwaysIncludeCallback } from '../types/join-scope.types.js';
 export type ViewConstructor = new (...args: unknown[]) => object;
 export type ExploreOptions = {
     name: string;
     label: string;
     from: ViewConstructor;
+    alwaysFilter?: AlwaysFilterCallback;
 };
 export type JoinScope = Record<string, unknown>;
 export type JoinOptions = {

package/dist/dsl/types/join-scope.types.d.ts

@@ -1,8 +1,17 @@
 import type { ManifestExpr } from '../../types/manifest-expr.types.js';
+import type { FilterStatement } from '../../types/manifest.types.js';
 import type { Field } from '../expr/field.js';
 import type { JoinScopeProxy } from './view-name-map.types.js';
 export type JoinScopeCallback = (...proxies: JoinScopeProxy[]) => ManifestExpr;
 export type AlwaysIncludeCallback = (...proxies: JoinScopeProxy[]) => Field<unknown>[];
+export interface AlwaysFilterDraftGroup {
+    type: 'AND' | 'OR';
+    group: Array<{
+        dimension: Field<unknown, boolean>;
+        orStatements: FilterStatement[];
+    }>;
+}
+export type AlwaysFilterCallback = (...proxies: JoinScopeProxy[]) => AlwaysFilterDraftGroup[];
 export type JoinScopeSqlOn = (scope: Record<string, unknown>) => ManifestExpr;
 export interface JoinScopeTagged {
     readonly __joinScopeBrand: symbol;

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 export { SCHEMA_VERSION } from './constants.js';
 export type { AggregateKind, AggregateExpr, ComparisonExpr, ComparisonKind, JoinOn, JoinPair, LogicExpr, LogicKind, ManifestExpr, ManifestExprObject, NotExpr, RawExpr, RefString, } from './types/manifest-expr.types.js';
 export { isJoinPair, isManifestExprObject, isRefString, REF_STRING_PATTERN, } from './types/manifest-expr.types.js';
-export type { AggregateType, DimensionDefinition, DimensionType, Explore as ManifestExplore, ExploreJoin, JoinRelationship, JoinType, MeasurementDefinition, Model as ManifestModel, ModelManifest, ViewDefinition, } from './types/manifest.types.js';
+export type { AggregateType, DimensionDefinition, DimensionType, Explore as ManifestExplore, ExploreJoin, Filter, FilterGroup, FilterOperator, FilterStatement, FilterValue, JoinRelationship, JoinType, MeasurementDefinition, Model as ManifestModel, ModelManifest, ViewDefinition, } from './types/manifest.types.js';
 export type { ManifestValidationError, ValidationResult, } from './validate/validation-result.js';
 export { validateManifest } from './validate/validate-manifest.js';
-export { Field, field, count, sum, min, max, raw, joinScope, isJoinScopeTagged, defineAlwaysInclude } from './dsl/expr/index.js';
+export { Field, field, count, sum, min, max, raw, joinScope, isJoinScopeTagged, defineAlwaysInclude, defineAlwaysFilter } from './dsl/expr/index.js';
 export type { VisibleField, HiddenField } from './dsl/expr/index.js';
-export type { JoinScopeCallback, JoinScopeSqlOn, JoinScopeTagged, AlwaysIncludeCallback } from './dsl/types/join-scope.types.js';
+export type { JoinScopeCallback, JoinScopeSqlOn, JoinScopeTagged, AlwaysIncludeCallback, AlwaysFilterCallback } from './dsl/types/join-scope.types.js';
 export { View, Dimension, Measure, Explore, Join, Model, AlwaysInclude } from './dsl/decorators/index.js';
 export type { ViewProxy, ViewConstructor, StrictViewProxy } from './dsl/types/view-proxy.types.js';
 export type { ViewNameMap, ViewProxyByName, } from './dsl/types/view-name-map.types.js';
 export { compileView, compileExplore, compileModel, compileModels } from './dsl/compile/index.js';
-export { MissingMetadataError, InvalidMeasureError, JoinScopeError, DuplicateNameError, AlwaysIncludeError, } from './dsl/errors/compile-errors.js';
+export { MissingMetadataError, InvalidMeasureError, JoinScopeError, DuplicateNameError, AlwaysIncludeError, AlwaysFilterError, } from './dsl/errors/compile-errors.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlwaysIncludeError = exports.DuplicateNameError = exports.JoinScopeError = exports.InvalidMeasureError = exports.MissingMetadataError = exports.compileModels = exports.compileModel = exports.compileExplore = exports.compileView = exports.AlwaysInclude = exports.Model = exports.Join = exports.Explore = exports.Measure = exports.Dimension = exports.View = exports.defineAlwaysInclude = exports.isJoinScopeTagged = exports.joinScope = exports.raw = exports.max = exports.min = exports.sum = exports.count = exports.field = exports.Field = exports.validateManifest = exports.REF_STRING_PATTERN = exports.isRefString = exports.isManifestExprObject = exports.isJoinPair = exports.SCHEMA_VERSION = void 0;
+exports.AlwaysFilterError = exports.AlwaysIncludeError = exports.DuplicateNameError = exports.JoinScopeError = exports.InvalidMeasureError = exports.MissingMetadataError = exports.compileModels = exports.compileModel = exports.compileExplore = exports.compileView = exports.AlwaysInclude = exports.Model = exports.Join = exports.Explore = exports.Measure = exports.Dimension = exports.View = exports.defineAlwaysFilter = exports.defineAlwaysInclude = exports.isJoinScopeTagged = exports.joinScope = exports.raw = exports.max = exports.min = exports.sum = exports.count = exports.field = exports.Field = exports.validateManifest = exports.REF_STRING_PATTERN = exports.isRefString = exports.isManifestExprObject = exports.isJoinPair = exports.SCHEMA_VERSION = void 0;
 var constants_js_1 = require("./constants.js");
 Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return constants_js_1.SCHEMA_VERSION; } });
 var manifest_expr_types_js_1 = require("./types/manifest-expr.types.js");
@@ -21,6 +21,7 @@ Object.defineProperty(exports, "raw", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "joinScope", { enumerable: true, get: function () { return index_js_1.joinScope; } });
 Object.defineProperty(exports, "isJoinScopeTagged", { enumerable: true, get: function () { return index_js_1.isJoinScopeTagged; } });
 Object.defineProperty(exports, "defineAlwaysInclude", { enumerable: true, get: function () { return index_js_1.defineAlwaysInclude; } });
+Object.defineProperty(exports, "defineAlwaysFilter", { enumerable: true, get: function () { return index_js_1.defineAlwaysFilter; } });
 var index_js_2 = require("./dsl/decorators/index.js");
 Object.defineProperty(exports, "View", { enumerable: true, get: function () { return index_js_2.View; } });
 Object.defineProperty(exports, "Dimension", { enumerable: true, get: function () { return index_js_2.Dimension; } });
@@ -40,3 +41,4 @@ Object.defineProperty(exports, "InvalidMeasureError", { enumerable: true, get: f
 Object.defineProperty(exports, "JoinScopeError", { enumerable: true, get: function () { return compile_errors_js_1.JoinScopeError; } });
 Object.defineProperty(exports, "DuplicateNameError", { enumerable: true, get: function () { return compile_errors_js_1.DuplicateNameError; } });
 Object.defineProperty(exports, "AlwaysIncludeError", { enumerable: true, get: function () { return compile_errors_js_1.AlwaysIncludeError; } });
+Object.defineProperty(exports, "AlwaysFilterError", { enumerable: true, get: function () { return compile_errors_js_1.AlwaysFilterError; } });

package/dist/types/manifest.types.d.ts

@@ -35,6 +35,20 @@ export interface ViewDefinition {
     dimensions: DimensionDefinition[];
     measurements: MeasurementDefinition[];
 }
+export type FilterOperator = 'eq' | 'neq' | 'contains' | 'not_contains' | 'gt' | 'gte' | 'lt' | 'lte' | 'is_null' | 'is_not_null';
+export type FilterValue = string | number | boolean;
+export interface FilterStatement {
+    operator: FilterOperator;
+    values: FilterValue[];
+}
+export interface Filter {
+    dimensionName: string;
+    orStatements: FilterStatement[];
+}
+export interface FilterGroup {
+    type: 'AND' | 'OR';
+    group: Filter[];
+}
 export interface Explore {
     name: string;
     label: string;
@@ -42,6 +56,7 @@ export interface Explore {
     joins: ExploreJoin[];
     views: ViewDefinition[];
     alwaysInclude?: string[];
+    alwaysFilter?: FilterGroup[];
 }
 export interface Model {
     name: string;

package/dist/validate/semantic-rules.js

@@ -76,6 +76,23 @@ function collectSemanticErrors(manifest) {
                     });
                 }
             });
+            const qualifiedDimensions = new Set();
+            for (const view of explore.views) {
+                for (const dimension of view.dimensions) {
+                    qualifiedDimensions.add(`${view.name}.${dimension.name}`);
+                }
+            }
+            (explore.alwaysFilter ?? []).forEach((filterGroup, groupIndex) => {
+                filterGroup.group.forEach((filter, filterIndex) => {
+                    const path = `${explorePath}.alwaysFilter[${groupIndex}].group[${filterIndex}].dimensionName`;
+                    if (!qualifiedDimensions.has(filter.dimensionName)) {
+                        errors.push({
+                            path,
+                            message: `alwaysFilter dimensionName "${filter.dimensionName}" is not a dimension on this explore`,
+                        });
+                    }
+                });
+            });
             explore.joins.forEach((join, joinIndex) => {
                 if (!viewNames.has(join.fromView)) {
                     errors.push({

package/manifest.schema.json

@@ -173,6 +173,50 @@
         "relationship": { "$ref": "#/definitions/JoinRelationship" }
       }
     },
+    "FilterOperator": {
+      "type": "string",
+      "enum": [
+        "eq", "neq", "contains", "not_contains",
+        "gt", "gte", "lt", "lte",
+        "is_null", "is_not_null"
+      ]
+    },
+    "FilterStatement": {
+      "type": "object",
+      "required": ["operator", "values"],
+      "additionalProperties": false,
+      "properties": {
+        "operator": { "$ref": "#/definitions/FilterOperator" },
+        "values": {
+          "type": "array",
+          "items": { "type": ["string", "number", "boolean"] }
+        }
+      }
+    },
+    "Filter": {
+      "type": "object",
+      "required": ["dimensionName", "orStatements"],
+      "additionalProperties": false,
+      "properties": {
+        "dimensionName": { "$ref": "#/definitions/RefString" },
+        "orStatements": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/FilterStatement" }
+        }
+      }
+    },
+    "FilterGroup": {
+      "type": "object",
+      "required": ["type", "group"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["AND", "OR"] },
+        "group": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/Filter" }
+        }
+      }
+    },
     "Explore": {
       "type": "object",
       "required": ["name", "label", "from", "joins", "views"],
@@ -192,6 +236,10 @@
         "alwaysInclude": {
           "type": "array",
           "items": { "$ref": "#/definitions/RefString" }
+        },
+        "alwaysFilter": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/FilterGroup" }
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@true-sight/model-schema",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [