@hypequery/datasets 0.7.0 → 0.9.0

package/dist/utils/relationship-fields.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Resolution helpers for relationship-qualified field names (`relationship.field`).
+ *
+ * v1 supports one hop over to-one relationships (`belongsTo`, `hasOne`) only,
+ * addressing dimensions declared on the target dataset. `hasMany` stays
+ * metadata-only to avoid fan-out corruption of aggregates. See
+ * `plans/relationship-aware-semantics-design.md`.
+ */
+import type { AnyDatasetInstance, DimensionDefinition, RelationshipDefinition } from '../types.js';
+/**
+ * Enumerates the queryable qualified field names (`<name>.<dimension>`) a
+ * relationship contributes, applying the same rules `resolveQualifiedField`
+ * enforces at query time: `hasMany` contributes nothing and SQL-backed target
+ * dimensions are excluded. Keep the two in sync — the catalog, contract, and
+ * generated input schemas all advertise exactly this list.
+ */
+export declare function listQueryableRelationshipFields(name: string, relationship: RelationshipDefinition): string[];
+export interface ParsedQualifiedField {
+    /** The relationship name (prefix before the first dot). */
+    relationship: string;
+    /** Everything after the first dot — the target field, possibly multi-hop. */
+    field: string;
+}
+/** True when a field name is relationship-qualified (contains a dot). */
+export declare function isQualifiedField(name: string): boolean;
+/**
+ * Splits a qualified name into its relationship prefix and remaining field.
+ * Returns null when `name` is not qualified (no dot), so callers can treat it
+ * as a local field.
+ */
+export declare function parseQualifiedField(name: string): ParsedQualifiedField | null;
+export interface ResolvedQualifiedField {
+    /** Relationship name, also used as the SQL table alias / qualified prefix. */
+    relationshipName: string;
+    relationship: RelationshipDefinition;
+    /** The resolved target dataset instance. */
+    target: AnyDatasetInstance;
+    /** Target dimension name (the allowlist key on the target). */
+    targetDimensionName: string;
+    targetDimension: DimensionDefinition;
+    /** Physical column backing the target dimension. */
+    targetColumn: string;
+    /** The qualified name exactly as referenced, e.g. `customer.country`. */
+    qualifiedName: string;
+}
+export type QualifiedFieldResolution = {
+    resolved: ResolvedQualifiedField;
+    error?: undefined;
+} | {
+    resolved?: undefined;
+    error: string;
+};
+/**
+ * Resolves a relationship-qualified field name against a base dataset.
+ *
+ * Returns null when `name` is not qualified (caller handles it as a local
+ * field). Otherwise returns either the resolved to-one target dimension or an
+ * actionable validation error (unknown relationship, multi-hop, `hasMany`,
+ * unknown target dimension, or SQL-backed target dimension).
+ */
+export declare function resolveQualifiedField(ds: AnyDatasetInstance, name: string): QualifiedFieldResolution | null;
+//# sourceMappingURL=relationship-fields.d.ts.map

package/dist/utils/relationship-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-fields.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,sBAAsB,GACnC,MAAM,EAAE,CAQV;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAM7E;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,sBAAsB,CAAC;IACrC,4CAA4C;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,mBAAmB,CAAC;IACrC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,wBAAwB,GAAG,IAAI,CAuDjC"}

package/dist/utils/relationship-fields.js

@@ -0,0 +1,98 @@
+/**
+ * Resolution helpers for relationship-qualified field names (`relationship.field`).
+ *
+ * v1 supports one hop over to-one relationships (`belongsTo`, `hasOne`) only,
+ * addressing dimensions declared on the target dataset. `hasMany` stays
+ * metadata-only to avoid fan-out corruption of aggregates. See
+ * `plans/relationship-aware-semantics-design.md`.
+ */
+/**
+ * Enumerates the queryable qualified field names (`<name>.<dimension>`) a
+ * relationship contributes, applying the same rules `resolveQualifiedField`
+ * enforces at query time: `hasMany` contributes nothing and SQL-backed target
+ * dimensions are excluded. Keep the two in sync — the catalog, contract, and
+ * generated input schemas all advertise exactly this list.
+ */
+export function listQueryableRelationshipFields(name, relationship) {
+    if (relationship.kind === 'hasMany') {
+        return [];
+    }
+    const target = relationship.target();
+    return Object.entries(target?.dimensions ?? {})
+        .filter(([, dimension]) => !dimension.sql)
+        .map(([field]) => `${name}.${field}`);
+}
+/** True when a field name is relationship-qualified (contains a dot). */
+export function isQualifiedField(name) {
+    return name.includes('.');
+}
+/**
+ * Splits a qualified name into its relationship prefix and remaining field.
+ * Returns null when `name` is not qualified (no dot), so callers can treat it
+ * as a local field.
+ */
+export function parseQualifiedField(name) {
+    const dot = name.indexOf('.');
+    if (dot === -1) {
+        return null;
+    }
+    return { relationship: name.slice(0, dot), field: name.slice(dot + 1) };
+}
+/**
+ * Resolves a relationship-qualified field name against a base dataset.
+ *
+ * Returns null when `name` is not qualified (caller handles it as a local
+ * field). Otherwise returns either the resolved to-one target dimension or an
+ * actionable validation error (unknown relationship, multi-hop, `hasMany`,
+ * unknown target dimension, or SQL-backed target dimension).
+ */
+export function resolveQualifiedField(ds, name) {
+    const parsed = parseQualifiedField(name);
+    if (!parsed) {
+        return null;
+    }
+    const { relationship: relationshipName, field } = parsed;
+    const relationship = ds.relationships[relationshipName];
+    if (!relationship) {
+        const available = Object.keys(ds.relationships);
+        return {
+            error: available.length > 0
+                ? `Unknown relationship "${relationshipName}" in field "${name}" on dataset "${ds.name}". Available relationships: ${available.join(', ')}.`
+                : `Unknown field "${name}": dataset "${ds.name}" declares no relationships.`,
+        };
+    }
+    if (field.includes('.')) {
+        return {
+            error: `Multi-hop relationship path "${name}" is not supported. Only a single hop is allowed (e.g. "${relationshipName}.<field>").`,
+        };
+    }
+    if (relationship.kind === 'hasMany') {
+        return {
+            error: `Relationship "${relationshipName}" on dataset "${ds.name}" is a hasMany (to-many) relationship and is not queryable, because joining it would fan out and corrupt aggregates. It remains available as metadata only.`,
+        };
+    }
+    const target = relationship.target();
+    const targetDimension = target.dimensions[field];
+    if (!targetDimension) {
+        const available = Object.keys(target.dimensions);
+        return {
+            error: `Unknown dimension "${field}" on relationship "${relationshipName}" (target dataset "${target.name}"). Available: ${available.join(', ')}.`,
+        };
+    }
+    if (targetDimension.sql) {
+        return {
+            error: `Dimension "${name}" is SQL-backed on target dataset "${target.name}"; SQL-backed dimensions are not yet queryable through relationships.`,
+        };
+    }
+    return {
+        resolved: {
+            relationshipName,
+            relationship,
+            target,
+            targetDimensionName: field,
+            targetDimension,
+            targetColumn: targetDimension.column ?? field,
+            qualifiedName: name,
+        },
+    };
+}

package/dist/utils/relationship-validation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared validation for relationship-qualified filters, used by both the
+ * dataset-query and metric-query validators.
+ */
+import type { AnyDatasetInstance, ExecutionContext, MetricFilter } from '../types.js';
+/**
+ * Validates a relationship-qualified filter (`relationship.field`). Returns an
+ * error message string, or null when the filter is valid.
+ *
+ * Enforces the same tenant rule the base dataset uses: when runtime tenancy is
+ * active and the joined target declares a `tenantKey`, an explicit filter on
+ * that column is rejected (the planner injects the tenant predicate instead).
+ */
+export declare function validateQualifiedFilter(ds: AnyDatasetInstance, filter: MetricFilter, context?: ExecutionContext): string | null;
+//# sourceMappingURL=relationship-validation.d.ts.map

package/dist/utils/relationship-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-validation.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACb,MAAM,aAAa,CAAC;AAKrB;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CAgBf"}

package/dist/utils/relationship-validation.js

@@ -0,0 +1,29 @@
+/**
+ * Shared validation for relationship-qualified filters, used by both the
+ * dataset-query and metric-query validators.
+ */
+import { validateFilterValue } from '../validation.js';
+import { getRuntimeTenantPredicate } from './tenant-runtime.js';
+import { resolveQualifiedField } from './relationship-fields.js';
+/**
+ * Validates a relationship-qualified filter (`relationship.field`). Returns an
+ * error message string, or null when the filter is valid.
+ *
+ * Enforces the same tenant rule the base dataset uses: when runtime tenancy is
+ * active and the joined target declares a `tenantKey`, an explicit filter on
+ * that column is rejected (the planner injects the tenant predicate instead).
+ */
+export function validateQualifiedFilter(ds, filter, context) {
+    const resolution = resolveQualifiedField(ds, filter.field);
+    if (!resolution) {
+        return null;
+    }
+    if (!resolution.resolved) {
+        return resolution.error;
+    }
+    const { target, targetColumn, targetDimension } = resolution.resolved;
+    if (getRuntimeTenantPredicate(context) && target.tenantKey && targetColumn === target.tenantKey) {
+        return `Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`;
+    }
+    return validateFilterValue(filter, targetDimension.fieldType);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Semantic layer for defining datasets, metrics, and semantic queries",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",