@true-sight/model-schema 1.0.1 → 1.1.0

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

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compileExplore = compileExplore;
 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 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");
@@ -50,11 +52,54 @@ function compileExplore(ExploreClass) {
         scopedViewNames.push(joinViewMeta.name);
     }
     const views = [...viewClasses.values()].map((ViewClass) => (0, compile_view_js_1.compileView)(ViewClass));
+    const alwaysInclude = resolveAlwaysInclude(ExploreClass, exploreMeta.name, views, scopedViewNames);
     return {
         name: exploreMeta.name,
         label: exploreMeta.label,
         from: fromViewMeta.name,
         joins,
         views,
+        ...(alwaysInclude ? { alwaysInclude } : {}),
     };
 }
+function resolveAlwaysInclude(ExploreClass, exploreName, views, scopedViewNames) {
+    const callback = (0, explore_registry_js_1.getAlwaysInclude)(ExploreClass);
+    if (!callback) {
+        return undefined;
+    }
+    const scope = (0, join_helpers_js_1.createJoinScope)(scopedViewNames);
+    const proxies = scopedViewNames.map((name) => scope[name]);
+    const raw = callback(...proxies);
+    if (!Array.isArray(raw)) {
+        throw new compile_errors_js_1.AlwaysIncludeError(exploreName, 'callback must return Field[]');
+    }
+    const known = new Set();
+    for (const view of views) {
+        for (const dimension of view.dimensions) {
+            known.add(`${view.name}.${dimension.name}`);
+        }
+        for (const measurement of view.measurements) {
+            known.add(`${view.name}.${measurement.name}`);
+        }
+    }
+    const seen = new Set();
+    const names = [];
+    for (const item of raw) {
+        if (!(item instanceof field_js_1.Field)) {
+            throw new compile_errors_js_1.AlwaysIncludeError(exploreName, 'callback must return Field[]');
+        }
+        const ref = item.ref;
+        if (!(0, manifest_expr_types_js_1.isRefString)(ref)) {
+            throw new compile_errors_js_1.AlwaysIncludeError(exploreName, `invalid name "${String(ref)}"`);
+        }
+        if (seen.has(ref)) {
+            continue;
+        }
+        seen.add(ref);
+        if (!known.has(ref)) {
+            throw new compile_errors_js_1.AlwaysIncludeError(exploreName, `unknown field '${ref}'`);
+        }
+        names.push(ref);
+    }
+    return names.length > 0 ? names : undefined;
+}

package/dist/dsl/decorators/always-include.decorator.d.ts

@@ -0,0 +1,2 @@
+import type { AlwaysIncludeCallback } from '../types/join-scope.types.js';
+export declare function AlwaysInclude(callback: AlwaysIncludeCallback): (target: new (...args: unknown[]) => object) => void;

package/dist/dsl/decorators/always-include.decorator.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlwaysInclude = AlwaysInclude;
+const explore_registry_js_1 = require("../registry/explore-registry.js");
+function AlwaysInclude(callback) {
+    return (target) => {
+        (0, explore_registry_js_1.registerAlwaysInclude)(target, callback);
+    };
+}

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

@@ -4,4 +4,5 @@ export { Measure } from './measure.decorator.js';
 export { Explore } from './explore.decorator.js';
 export { Join } from './join.decorator.js';
 export { Model } from './model.decorator.js';
+export { AlwaysInclude } from './always-include.decorator.js';
 export { joinScope, isJoinScopeTagged } from '../expr/join-scope.js';

package/dist/dsl/decorators/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isJoinScopeTagged = exports.joinScope = exports.Model = exports.Join = exports.Explore = exports.Measure = exports.Dimension = exports.View = void 0;
+exports.isJoinScopeTagged = exports.joinScope = exports.AlwaysInclude = exports.Model = exports.Join = exports.Explore = exports.Measure = exports.Dimension = exports.View = void 0;
 var view_decorator_js_1 = require("./view.decorator.js");
 Object.defineProperty(exports, "View", { enumerable: true, get: function () { return view_decorator_js_1.View; } });
 var dimension_decorator_js_1 = require("./dimension.decorator.js");
@@ -13,6 +13,8 @@ var join_decorator_js_1 = require("./join.decorator.js");
 Object.defineProperty(exports, "Join", { enumerable: true, get: function () { return join_decorator_js_1.Join; } });
 var model_decorator_js_1 = require("./model.decorator.js");
 Object.defineProperty(exports, "Model", { enumerable: true, get: function () { return model_decorator_js_1.Model; } });
+var always_include_decorator_js_1 = require("./always-include.decorator.js");
+Object.defineProperty(exports, "AlwaysInclude", { enumerable: true, get: function () { return always_include_decorator_js_1.AlwaysInclude; } });
 var join_scope_js_1 = require("../expr/join-scope.js");
 Object.defineProperty(exports, "joinScope", { enumerable: true, get: function () { return join_scope_js_1.joinScope; } });
 Object.defineProperty(exports, "isJoinScopeTagged", { enumerable: true, get: function () { return join_scope_js_1.isJoinScopeTagged; } });

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

@@ -10,3 +10,6 @@ export declare class JoinScopeError extends Error {
 export declare class DuplicateNameError extends Error {
     constructor(kind: string, name: string, context?: string);
 }
+export declare class AlwaysIncludeError 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.DuplicateNameError = exports.JoinScopeError = exports.InvalidMeasureError = exports.MissingMetadataError = void 0;
+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}`);
@@ -31,3 +31,10 @@ class DuplicateNameError extends Error {
     }
 }
 exports.DuplicateNameError = DuplicateNameError;
+class AlwaysIncludeError extends Error {
+    constructor(exploreName, reason) {
+        super(`Always include on explore '${exploreName}': ${reason}`);
+        this.name = 'AlwaysIncludeError';
+    }
+}
+exports.AlwaysIncludeError = AlwaysIncludeError;

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

@@ -1,5 +1,6 @@
 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';
 export type ViewConstructor = new (...args: unknown[]) => object;
 export type ExploreOptions = {
     name: string;
@@ -20,3 +21,5 @@ export declare function registerExplore(ctor: object, options: ExploreOptions):
 export declare function getExploreMeta(ctor: object): ExploreOptions | undefined;
 export declare function addJoin(prototype: object, entry: JoinEntry): void;
 export declare function getJoins(prototype: object): JoinEntry[];
+export declare function registerAlwaysInclude(ctor: object, callback: AlwaysIncludeCallback): void;
+export declare function getAlwaysInclude(ctor: object): AlwaysIncludeCallback | undefined;

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

@@ -4,8 +4,11 @@ exports.registerExplore = registerExplore;
 exports.getExploreMeta = getExploreMeta;
 exports.addJoin = addJoin;
 exports.getJoins = getJoins;
+exports.registerAlwaysInclude = registerAlwaysInclude;
+exports.getAlwaysInclude = getAlwaysInclude;
 const exploreMeta = new WeakMap();
 const joinMeta = new WeakMap();
+const alwaysIncludeMeta = new WeakMap();
 function registerExplore(ctor, options) {
     exploreMeta.set(ctor, options);
 }
@@ -20,3 +23,9 @@ function addJoin(prototype, entry) {
 function getJoins(prototype) {
     return joinMeta.get(prototype) ?? [];
 }
+function registerAlwaysInclude(ctor, callback) {
+    alwaysIncludeMeta.set(ctor, callback);
+}
+function getAlwaysInclude(ctor) {
+    return alwaysIncludeMeta.get(ctor);
+}

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

@@ -1,6 +1,8 @@
 import type { ManifestExpr } from '../../types/manifest-expr.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 type JoinScopeSqlOn = (scope: Record<string, unknown>) => ManifestExpr;
 export interface JoinScopeTagged {
     readonly __joinScopeBrand: symbol;

package/dist/index.d.ts

@@ -5,9 +5,9 @@ export type { AggregateType, DimensionDefinition, DimensionType, Explore as Mani
 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 } from './dsl/expr/index.js';
-export type { JoinScopeCallback, JoinScopeSqlOn, JoinScopeTagged } from './dsl/types/join-scope.types.js';
-export { View, Dimension, Measure, Explore, Join, Model } from './dsl/decorators/index.js';
+export type { JoinScopeCallback, JoinScopeSqlOn, JoinScopeTagged, AlwaysIncludeCallback } from './dsl/types/join-scope.types.js';
+export { View, Dimension, Measure, Explore, Join, Model, AlwaysInclude } from './dsl/decorators/index.js';
 export type { ViewProxy, ViewConstructor } 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, } from './dsl/errors/compile-errors.js';
+export { MissingMetadataError, InvalidMeasureError, JoinScopeError, DuplicateNameError, AlwaysIncludeError, } from './dsl/errors/compile-errors.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DuplicateNameError = exports.JoinScopeError = exports.InvalidMeasureError = exports.MissingMetadataError = exports.compileModels = exports.compileModel = exports.compileExplore = exports.compileView = exports.Model = exports.Join = exports.Explore = exports.Measure = exports.Dimension = exports.View = 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.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.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");
@@ -27,6 +27,7 @@ Object.defineProperty(exports, "Measure", { enumerable: true, get: function () {
 Object.defineProperty(exports, "Explore", { enumerable: true, get: function () { return index_js_2.Explore; } });
 Object.defineProperty(exports, "Join", { enumerable: true, get: function () { return index_js_2.Join; } });
 Object.defineProperty(exports, "Model", { enumerable: true, get: function () { return index_js_2.Model; } });
+Object.defineProperty(exports, "AlwaysInclude", { enumerable: true, get: function () { return index_js_2.AlwaysInclude; } });
 var index_js_3 = require("./dsl/compile/index.js");
 Object.defineProperty(exports, "compileView", { enumerable: true, get: function () { return index_js_3.compileView; } });
 Object.defineProperty(exports, "compileExplore", { enumerable: true, get: function () { return index_js_3.compileExplore; } });
@@ -37,3 +38,4 @@ Object.defineProperty(exports, "MissingMetadataError", { enumerable: true, get:
 Object.defineProperty(exports, "InvalidMeasureError", { enumerable: true, get: function () { return compile_errors_js_1.InvalidMeasureError; } });
 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; } });

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

@@ -39,6 +39,7 @@ export interface Explore {
     from: string;
     joins: ExploreJoin[];
     views: ViewDefinition[];
+    alwaysInclude?: string[];
 }
 export interface Model {
     name: string;

package/dist/validate/semantic-rules.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectSemanticErrors = collectSemanticErrors;
+const manifest_expr_types_js_1 = require("../types/manifest-expr.types.js");
 const expr_semantic_js_1 = require("./expr-semantic.js");
 function duplicateNameErrors(names, pathPrefix, entityLabel) {
     const seen = new Map();
@@ -43,6 +44,31 @@ function collectSemanticErrors(manifest) {
                     message: `from view "${explore.from}" is not in explore views`,
                 });
             }
+            const qualifiedFields = new Set();
+            for (const view of explore.views) {
+                for (const dimension of view.dimensions) {
+                    qualifiedFields.add(`${view.name}.${dimension.name}`);
+                }
+                for (const measurement of view.measurements) {
+                    qualifiedFields.add(`${view.name}.${measurement.name}`);
+                }
+            }
+            (explore.alwaysInclude ?? []).forEach((name, index) => {
+                const path = `${explorePath}.alwaysInclude[${index}]`;
+                if (!(0, manifest_expr_types_js_1.isRefString)(name)) {
+                    errors.push({
+                        path,
+                        message: `alwaysInclude name "${String(name)}" is not a view.field ref`,
+                    });
+                    return;
+                }
+                if (!qualifiedFields.has(name)) {
+                    errors.push({
+                        path,
+                        message: `alwaysInclude name "${name}" is not a dimension or measurement on this explore`,
+                    });
+                }
+            });
             explore.joins.forEach((join, joinIndex) => {
                 if (!viewNames.has(join.fromView)) {
                     errors.push({

package/manifest.schema.json

@@ -186,6 +186,10 @@
         "views": {
           "type": "array",
           "items": { "$ref": "#/definitions/ViewDefinition" }
+        },
+        "alwaysInclude": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/RefString" }
         }
       }
     },

package/package.json

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