@inixiative/json-rules 3.18.0 → 3.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -298,6 +298,8 @@ declare const getOperatorsForKind: (kind: FieldKind, target?: RuleTarget) => {
298
298
  };
299
299
  /** The array operators, narrowed to one target when given. */
300
300
  declare const getArrayOperators: (target?: RuleTarget) => ArrayOperator[];
301
+ /** Every mode a value expression's aggregate takes. */
302
+ declare const VALUE_AGGREGATE_MODES: readonly ValueAggregateMode[];
301
303
  /** The comparisons an aggregate rule takes; every target compiles all of them. */
302
304
  declare const getAggregateOperators: () => readonly Operator[];
303
305
  /** The steps a clock-relative date moves by, finest first. */
@@ -363,6 +365,9 @@ type ArrayOperatorValues = typeof ArrayOperator;
363
365
  type DateOperatorValues = typeof DateOperator;
364
366
  type RuleScalar = string | number | boolean | null | undefined;
365
367
  type AggregateMode = 'sum' | 'avg';
368
+ /** What a value expression's aggregate computes: an aggregate rule's modes, plus `count` and the
369
+ * least / greatest item value. */
370
+ type ValueAggregateMode = AggregateMode | 'count' | 'min' | 'max' | 'distinct';
366
371
  type RuleValue = RuleScalar | Date | RegExp | RuleValue[] | {
367
372
  [key: string]: RuleValue;
368
373
  };
@@ -588,6 +593,52 @@ type CompileOptions = {
588
593
  } & DateConfig;
589
594
  /** What check() evaluates: one row, or a root array of them. */
590
595
  type CheckData = Row | unknown[];
596
+ /** An aggregate rule's shape without `operator` and value: the aggregate is the value. */
597
+ type AggregateValue<TRuleValue = RuleValue, TDateValue = DateRuleValue> = WindowFields & {
598
+ field: string;
599
+ aggregate: {
600
+ mode: ValueAggregateMode;
601
+ field?: string;
602
+ };
603
+ condition?: Condition<TRuleValue, TDateValue>;
604
+ /** `distinct` / `min` / `max`: read each value as this kind first (`'10'` as 10, an ISO string
605
+ * as a date, `Decimal('1')` as 1). Without it values compare as stored, kind by kind. */
606
+ coerceType?: FieldKind;
607
+ /** `distinct` over strings: `'Acme'` and `'acme'` are one value (the first seen is kept).
608
+ * Defaults to the engine's `string.caseInsensitive`. */
609
+ caseInsensitive?: boolean;
610
+ operator?: never;
611
+ value?: never;
612
+ path?: never;
613
+ bind?: never;
614
+ };
615
+ /** First match as if / else: `then` when `if` holds, else `else` — null when there is none (in a
616
+ * list, nothing). */
617
+ type IfThenElseValue = {
618
+ if: Condition;
619
+ then: ValueExpression;
620
+ else?: ValueExpression;
621
+ };
622
+ /** Experimental. A list of values, each item evaluated in turn; an `if` with no `else` that does not
623
+ * hold adds nothing — match-all, for a multiselect. Items are single values, not lists. A bare
624
+ * array keeps every item; `{ list, distinct: true }` keeps the first of equal items. */
625
+ type ListValue = ValueExpression[] | {
626
+ list: ValueExpression[];
627
+ distinct?: boolean;
628
+ };
629
+ /** A scalar written as itself, as a stored value is: `5`, `'gold'`, `true`, `null`, a Date. */
630
+ type BareLiteral = string | number | boolean | bigint | Date | null;
631
+ /** A value computed from a row: a literal (bare, or `{ value }` — an object literal needs the
632
+ * wrapper), a path read (`{ path }`), a binding (`{ bind }`), an aggregate over a relation's rows,
633
+ * if / then / else, or a list. */
634
+ type ValueExpression = BareLiteral | ValueSourceOf<RuleValue> | AggregateValue | IfThenElseValue | ListValue;
635
+ /** What a value expression returns: its kind (null when it can only be null), whether it is a
636
+ * list, and whether it can be null. */
637
+ type ValueType = {
638
+ kind: FieldKind | null;
639
+ isList: boolean;
640
+ nullable: boolean;
641
+ };
591
642
 
592
643
  /** `required`: leave out the names an optional bind (`bindOptional`) may go unsupplied. */
593
644
  type ListBindingsOptions = {
@@ -613,6 +664,24 @@ declare const listFields: (condition: Condition) => string[];
613
664
  */
614
665
  declare const bindRule: (condition: Condition, bindings: Record<string, RuleValue>) => Condition;
615
666
 
667
+ type ScopeRef = {
668
+ depth: number;
669
+ path: string;
670
+ };
671
+ /** A `$`-prefixed ref's depth (one per `$`) and the path after it; `null` for a bare ref. */
672
+ declare const parseScopeRef: (ref: string) => ScopeRef | null;
673
+ type ScopedRef<S> = {
674
+ scope: S;
675
+ path: string;
676
+ };
677
+ type ScopeOutOfBounds = {
678
+ outOfBounds: string;
679
+ };
680
+ /** The scope a ref names in a stack (innermost last) and the path left to read in it: a bare
681
+ * ref and `$.` read the innermost, `$$.` the one above it, … A ref deeper than the stack comes
682
+ * back as `{ outOfBounds }` with its message; it never throws. */
683
+ declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<S> | ScopeOutOfBounds;
684
+
616
685
  /** `bindings`: the caller's values, read by `{ bind }`. The rest is the clock and zone. */
617
686
  type CheckOptions = {
618
687
  bindings?: Record<string, RuleValue>;
@@ -1252,24 +1321,6 @@ declare const validateRuleInLens: (rule: Condition, lensOrNarrowing: Lens | Lens
1252
1321
  */
1253
1322
  declare const walkLensPath: (lensOrNarrowing: Lens | LensNarrowing, path: string) => LensPathResolution;
1254
1323
 
1255
- type ScopeRef = {
1256
- depth: number;
1257
- path: string;
1258
- };
1259
- /** A `$`-prefixed ref's depth (one per `$`) and the path after it; `null` for a bare ref. */
1260
- declare const parseScopeRef: (ref: string) => ScopeRef | null;
1261
- type ScopedRef<S> = {
1262
- scope: S;
1263
- path: string;
1264
- };
1265
- type ScopeOutOfBounds = {
1266
- outOfBounds: string;
1267
- };
1268
- /** The scope a ref names in a stack (innermost last) and the path left to read in it: a bare
1269
- * ref and `$.` read the innermost, `$$.` the one above it, … A ref deeper than the stack comes
1270
- * back as `{ outOfBounds }` with its message; it never throws. */
1271
- declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<S> | ScopeOutOfBounds;
1272
-
1273
1324
  /**
1274
1325
  * Execute a Prisma query plan produced by toPrisma().
1275
1326
  *
@@ -1402,6 +1453,57 @@ type ConditionShapeKeys = {
1402
1453
  /** The keys a node of one shape takes: those it must have and those it may. */
1403
1454
  declare const getConditionShapeKeys: (shape: ConditionShape) => ConditionShapeKeys;
1404
1455
 
1456
+ /** A value expression under a lens: its type, the dotted paths it reads from the row (a relation's
1457
+ * rows under the relation: `fanMissions.status`), its clock unit, and every problem the
1458
+ * validator, the lens gate and type inference find. Never throws on a bad expression. */
1459
+ type ValueDescription = {
1460
+ type: ValueType | null;
1461
+ paths: string[];
1462
+ clockUnit: ClockUnit | null;
1463
+ errors: ValidationIssue[];
1464
+ };
1465
+ declare const describeValue: (expression: ValueExpression, lensOrNarrowing: Lens | LensNarrowing) => ValueDescription;
1466
+
1467
+ /**
1468
+ * The value an expression computes from a row, in memory, with what check() takes (`bindings`,
1469
+ * `now`, `timeZone`, `weekStart`, `absent`): a literal (bare or `{ value }`), a path read (null when absent), a bound
1470
+ * value, an aggregate over a relation's rows (`count`, `sum`, `avg`, `min`, `max`, through its
1471
+ * window and condition; `avg` and `min` / `max` over no values are null), the branch an `if` picks,
1472
+ * or a list (`distinct: true` drops repeats). Throws on a malformed expression,
1473
+ * as check() throws on a malformed rule; `validateValue` reports every problem without data.
1474
+ */
1475
+ declare const evaluateValue: (expression: ValueExpression, data: Row, options?: CheckOptions) => unknown;
1476
+
1477
+ /**
1478
+ * The type a value expression returns, worked out without data — for a consumer to check against
1479
+ * the type it stores before saving the expression. A literal, bare or `{ value }`, has its value's
1480
+ * kind (a whole number `Int`, any other `Float`); a path its column's kind through the lens
1481
+ * (nullable unless the map declares it required); `count` an `Int`; `sum` its column's numeric
1482
+ * kind, never null (0 over no rows); `avg` a `Float` (`Decimal` stays `Decimal`), null over no
1483
+ * rows; `min` / `max` their column's kind, nullable (no rows). An `if`'s branches and a list's
1484
+ * items must agree (two numeric kinds read as `Decimal` when either is, else `Float`; a missing
1485
+ * `else` is null). `lens` is needed wherever a path's kind is read. Throws on
1486
+ * an expression that has no type: a path that does not resolve, reads through a to-many relation
1487
+ * or names rows, an aggregate over something that isn't a list, branches that disagree, a binding,
1488
+ * `distinct` over Json.
1489
+ */
1490
+ declare const inferValueType: (expression: ValueExpression, lens?: Lens | LensNarrowing) => ValueType;
1491
+
1492
+ /** A value expression's shape checked without data: each node exactly one kind, every key known,
1493
+ * aggregate modes from VALUE_AGGREGATE_MODES, and each condition it holds (`if`, an aggregate's
1494
+ * `filter` / `condition` / window) valid as `validateRule` sees it. */
1495
+ declare const validateValue: (expression: unknown) => ValidationResult;
1496
+ /** validateValue's throwing form. */
1497
+ declare const assertValidValue: (expression: unknown) => void;
1498
+
1499
+ /**
1500
+ * The finest clock unit a value expression's answer can change by while its data stays the same —
1501
+ * `clockUnit` over every condition it holds (an `if`, an aggregate's `filter` / `condition`), so
1502
+ * an aggregate over the last 90 days reads `day`. Null when it reads no clock. Throws, as
1503
+ * `clockUnit` does, on a unit finer than `clock.finestUnit`.
1504
+ */
1505
+ declare const valueClockUnit: (expression: ValueExpression) => ClockUnit | null;
1506
+
1405
1507
  /**
1406
1508
  * Records sorted by an `OrderBy`, the way every rail orders a window: each key in turn, read as an
1407
1509
  * own-property path, `dir` order, a NULL (or absent) value last in either direction; ties keep their
@@ -1409,4 +1511,4 @@ declare const getConditionShapeKeys: (shape: ConditionShape) => ConditionShapeKe
1409
1511
  */
1410
1512
  declare const orderRecords: <T>(items: readonly T[], orderBy: OrderBy) => T[];
1411
1513
 
1412
- export { ALL_KINDS, type Absent, type AggregateMode, type AggregateRule, type All, type Any, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, CLOCK_UNITS, type CheckData, type CheckOptions, type ClockUnit, type CompileOptions, type Condition, ConditionShape, type ConditionShapeKeys, type DateConfig, type DateExpr, type DateInputOrExpr, type DateInputValue, type DateOffset, DateOperator, type DateRule, type DateRuleValue, type EdgeExpr, type EngineGlobalDefaults, type EngineGlobalPath, type EngineGlobalValues, type EngineGlobalsState, type EnumNarrowing, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type FuzzyConfig, type GroupByStep, type IfThenElse, type Lens, type LensClamps, type LensNarrowing, type LensPathHop, type LensPathResolution, LensRefusal, type LensRelationSelect, type LensSelect, type LensSelectOptions, type LensValue, type LensWhereSql, type LensWhereSqlOptions, type ListBindingsOptions, type Magnitude, type MaterializeSourceQueryOptions, type ModelDefaultNarrowing, type ModelEntry, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, type NumberOffset, Operator, type OperatorFamily, type OrderBy, type OrderedRuleValue, type PathProjection, type PeriodExpr, type PeriodUnit, type PrismaProvider, type PrismaStep, type PrismaWhere, type ProjectLensOptions, type ProjectRowsOptions, type ProjectedVisit, type RelativeUnit, type RelativeUnits, type RollingExpr, type Row, type Rule, type RuleDescription, type RuleScalar, type RuleSourceDescription, RuleTarget, type RuleValue, type ScopeOutOfBounds, type ScopeRef, type ScopedRef, type SortDir, type SourceEntry, type SourceOption, SourceOptionOrder, type SourcePrismaQuery, type SourceQuery, type SourceRowShape, type SourceSelect, type SourceSpec, type SourceSqlQuery, type SourceValues, SqlDialect, type StepRef, type StoredLens, type StrictAggregateRule, type StrictAll, type StrictAny, type StrictArrayCountRule, type StrictArrayPredicateRule, type StrictArrayPresenceRule, type StrictArrayRule, type StrictCondition, type StrictContainsRule, type StrictDateComparisonRule, type StrictDateDayRule, type StrictDateRangeRule, type StrictDateRule, type StrictEqualityRule, type StrictIfThenElse, type StrictMembershipRule, type StrictOrderedComparisonRule, type StrictPatternRule, type StrictPresenceRule, type StrictRangeRule, type StrictRule, type StrictStringBoundaryRule, type TimeZoneConfig, type ToPrismaOptions, type ToPrismaResult, type ToSqlOptions, type ToSqlResult, UsageError, type ValidateRuleOptions, type ValidationIssue, type ValidationResult, ValueShape, type ValueSourceFields, type ValueSourceOf, type WeekStart, type WhereSqlOptions, type WhereStep, type WindowFields, andWhere, assertValidFieldMaps, assertValidNarrowing, assertValidRule, bindLens, bindRule, check, clampLens, clockUnit, coerceRule, composeLens, createLens, describeRule, describeRuleSources, engineGlobals, executePrismaPlan, getAggregateOperators, getArrayOperators, getConditionShapeKeys, getLensRoot, getOperatorsForKind, getValueShape, indexBridges, lensVisit, listBindings, listFields, listLensBindings, matchAll, matchNothing, materializeSourceQuery, materializeSources, narrowRule, orWhere, orderRecords, parseScopeRef, prefixConditionFields, projectLens, projectRows, readLensValue, readScopeRef, registerEngineGlobals, stitchFieldMaps, storeLens, toLensSelect, toLensWhereSql, toPrisma, toSourceQueries, toSql, toWhereSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };
1514
+ export { ALL_KINDS, type Absent, type AggregateMode, type AggregateRule, type AggregateValue, type All, type Any, ArrayOperator, type ArrayRule, type BareLiteral, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, CLOCK_UNITS, type CheckData, type CheckOptions, type ClockUnit, type CompileOptions, type Condition, ConditionShape, type ConditionShapeKeys, type DateConfig, type DateExpr, type DateInputOrExpr, type DateInputValue, type DateOffset, DateOperator, type DateRule, type DateRuleValue, type EdgeExpr, type EngineGlobalDefaults, type EngineGlobalPath, type EngineGlobalValues, type EngineGlobalsState, type EnumNarrowing, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type FuzzyConfig, type GroupByStep, type IfThenElse, type IfThenElseValue, type Lens, type LensClamps, type LensNarrowing, type LensPathHop, type LensPathResolution, LensRefusal, type LensRelationSelect, type LensSelect, type LensSelectOptions, type LensValue, type LensWhereSql, type LensWhereSqlOptions, type ListBindingsOptions, type ListValue, type Magnitude, type MaterializeSourceQueryOptions, type ModelDefaultNarrowing, type ModelEntry, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, type NumberOffset, Operator, type OperatorFamily, type OrderBy, type OrderedRuleValue, type PathProjection, type PeriodExpr, type PeriodUnit, type PrismaProvider, type PrismaStep, type PrismaWhere, type ProjectLensOptions, type ProjectRowsOptions, type ProjectedVisit, type RelativeUnit, type RelativeUnits, type RollingExpr, type Row, type Rule, type RuleDescription, type RuleScalar, type RuleSourceDescription, RuleTarget, type RuleValue, type ScopeOutOfBounds, type ScopeRef, type ScopedRef, type SortDir, type SourceEntry, type SourceOption, SourceOptionOrder, type SourcePrismaQuery, type SourceQuery, type SourceRowShape, type SourceSelect, type SourceSpec, type SourceSqlQuery, type SourceValues, SqlDialect, type StepRef, type StoredLens, type StrictAggregateRule, type StrictAll, type StrictAny, type StrictArrayCountRule, type StrictArrayPredicateRule, type StrictArrayPresenceRule, type StrictArrayRule, type StrictCondition, type StrictContainsRule, type StrictDateComparisonRule, type StrictDateDayRule, type StrictDateRangeRule, type StrictDateRule, type StrictEqualityRule, type StrictIfThenElse, type StrictMembershipRule, type StrictOrderedComparisonRule, type StrictPatternRule, type StrictPresenceRule, type StrictRangeRule, type StrictRule, type StrictStringBoundaryRule, type TimeZoneConfig, type ToPrismaOptions, type ToPrismaResult, type ToSqlOptions, type ToSqlResult, UsageError, VALUE_AGGREGATE_MODES, type ValidateRuleOptions, type ValidationIssue, type ValidationResult, type ValueAggregateMode, type ValueDescription, type ValueExpression, ValueShape, type ValueSourceFields, type ValueSourceOf, type ValueType, type WeekStart, type WhereSqlOptions, type WhereStep, type WindowFields, andWhere, assertValidFieldMaps, assertValidNarrowing, assertValidRule, assertValidValue, bindLens, bindRule, check, clampLens, clockUnit, coerceRule, composeLens, createLens, describeRule, describeRuleSources, describeValue, engineGlobals, evaluateValue, executePrismaPlan, getAggregateOperators, getArrayOperators, getConditionShapeKeys, getLensRoot, getOperatorsForKind, getValueShape, indexBridges, inferValueType, lensVisit, listBindings, listFields, listLensBindings, matchAll, matchNothing, materializeSourceQuery, materializeSources, narrowRule, orWhere, orderRecords, parseScopeRef, prefixConditionFields, projectLens, projectRows, readLensValue, readScopeRef, registerEngineGlobals, stitchFieldMaps, storeLens, toLensSelect, toLensWhereSql, toPrisma, toSourceQueries, toSql, toWhereSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, validateValue, valueClockUnit, walkLensPath };
package/dist/index.d.ts CHANGED
@@ -298,6 +298,8 @@ declare const getOperatorsForKind: (kind: FieldKind, target?: RuleTarget) => {
298
298
  };
299
299
  /** The array operators, narrowed to one target when given. */
300
300
  declare const getArrayOperators: (target?: RuleTarget) => ArrayOperator[];
301
+ /** Every mode a value expression's aggregate takes. */
302
+ declare const VALUE_AGGREGATE_MODES: readonly ValueAggregateMode[];
301
303
  /** The comparisons an aggregate rule takes; every target compiles all of them. */
302
304
  declare const getAggregateOperators: () => readonly Operator[];
303
305
  /** The steps a clock-relative date moves by, finest first. */
@@ -363,6 +365,9 @@ type ArrayOperatorValues = typeof ArrayOperator;
363
365
  type DateOperatorValues = typeof DateOperator;
364
366
  type RuleScalar = string | number | boolean | null | undefined;
365
367
  type AggregateMode = 'sum' | 'avg';
368
+ /** What a value expression's aggregate computes: an aggregate rule's modes, plus `count` and the
369
+ * least / greatest item value. */
370
+ type ValueAggregateMode = AggregateMode | 'count' | 'min' | 'max' | 'distinct';
366
371
  type RuleValue = RuleScalar | Date | RegExp | RuleValue[] | {
367
372
  [key: string]: RuleValue;
368
373
  };
@@ -588,6 +593,52 @@ type CompileOptions = {
588
593
  } & DateConfig;
589
594
  /** What check() evaluates: one row, or a root array of them. */
590
595
  type CheckData = Row | unknown[];
596
+ /** An aggregate rule's shape without `operator` and value: the aggregate is the value. */
597
+ type AggregateValue<TRuleValue = RuleValue, TDateValue = DateRuleValue> = WindowFields & {
598
+ field: string;
599
+ aggregate: {
600
+ mode: ValueAggregateMode;
601
+ field?: string;
602
+ };
603
+ condition?: Condition<TRuleValue, TDateValue>;
604
+ /** `distinct` / `min` / `max`: read each value as this kind first (`'10'` as 10, an ISO string
605
+ * as a date, `Decimal('1')` as 1). Without it values compare as stored, kind by kind. */
606
+ coerceType?: FieldKind;
607
+ /** `distinct` over strings: `'Acme'` and `'acme'` are one value (the first seen is kept).
608
+ * Defaults to the engine's `string.caseInsensitive`. */
609
+ caseInsensitive?: boolean;
610
+ operator?: never;
611
+ value?: never;
612
+ path?: never;
613
+ bind?: never;
614
+ };
615
+ /** First match as if / else: `then` when `if` holds, else `else` — null when there is none (in a
616
+ * list, nothing). */
617
+ type IfThenElseValue = {
618
+ if: Condition;
619
+ then: ValueExpression;
620
+ else?: ValueExpression;
621
+ };
622
+ /** Experimental. A list of values, each item evaluated in turn; an `if` with no `else` that does not
623
+ * hold adds nothing — match-all, for a multiselect. Items are single values, not lists. A bare
624
+ * array keeps every item; `{ list, distinct: true }` keeps the first of equal items. */
625
+ type ListValue = ValueExpression[] | {
626
+ list: ValueExpression[];
627
+ distinct?: boolean;
628
+ };
629
+ /** A scalar written as itself, as a stored value is: `5`, `'gold'`, `true`, `null`, a Date. */
630
+ type BareLiteral = string | number | boolean | bigint | Date | null;
631
+ /** A value computed from a row: a literal (bare, or `{ value }` — an object literal needs the
632
+ * wrapper), a path read (`{ path }`), a binding (`{ bind }`), an aggregate over a relation's rows,
633
+ * if / then / else, or a list. */
634
+ type ValueExpression = BareLiteral | ValueSourceOf<RuleValue> | AggregateValue | IfThenElseValue | ListValue;
635
+ /** What a value expression returns: its kind (null when it can only be null), whether it is a
636
+ * list, and whether it can be null. */
637
+ type ValueType = {
638
+ kind: FieldKind | null;
639
+ isList: boolean;
640
+ nullable: boolean;
641
+ };
591
642
 
592
643
  /** `required`: leave out the names an optional bind (`bindOptional`) may go unsupplied. */
593
644
  type ListBindingsOptions = {
@@ -613,6 +664,24 @@ declare const listFields: (condition: Condition) => string[];
613
664
  */
614
665
  declare const bindRule: (condition: Condition, bindings: Record<string, RuleValue>) => Condition;
615
666
 
667
+ type ScopeRef = {
668
+ depth: number;
669
+ path: string;
670
+ };
671
+ /** A `$`-prefixed ref's depth (one per `$`) and the path after it; `null` for a bare ref. */
672
+ declare const parseScopeRef: (ref: string) => ScopeRef | null;
673
+ type ScopedRef<S> = {
674
+ scope: S;
675
+ path: string;
676
+ };
677
+ type ScopeOutOfBounds = {
678
+ outOfBounds: string;
679
+ };
680
+ /** The scope a ref names in a stack (innermost last) and the path left to read in it: a bare
681
+ * ref and `$.` read the innermost, `$$.` the one above it, … A ref deeper than the stack comes
682
+ * back as `{ outOfBounds }` with its message; it never throws. */
683
+ declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<S> | ScopeOutOfBounds;
684
+
616
685
  /** `bindings`: the caller's values, read by `{ bind }`. The rest is the clock and zone. */
617
686
  type CheckOptions = {
618
687
  bindings?: Record<string, RuleValue>;
@@ -1252,24 +1321,6 @@ declare const validateRuleInLens: (rule: Condition, lensOrNarrowing: Lens | Lens
1252
1321
  */
1253
1322
  declare const walkLensPath: (lensOrNarrowing: Lens | LensNarrowing, path: string) => LensPathResolution;
1254
1323
 
1255
- type ScopeRef = {
1256
- depth: number;
1257
- path: string;
1258
- };
1259
- /** A `$`-prefixed ref's depth (one per `$`) and the path after it; `null` for a bare ref. */
1260
- declare const parseScopeRef: (ref: string) => ScopeRef | null;
1261
- type ScopedRef<S> = {
1262
- scope: S;
1263
- path: string;
1264
- };
1265
- type ScopeOutOfBounds = {
1266
- outOfBounds: string;
1267
- };
1268
- /** The scope a ref names in a stack (innermost last) and the path left to read in it: a bare
1269
- * ref and `$.` read the innermost, `$$.` the one above it, … A ref deeper than the stack comes
1270
- * back as `{ outOfBounds }` with its message; it never throws. */
1271
- declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<S> | ScopeOutOfBounds;
1272
-
1273
1324
  /**
1274
1325
  * Execute a Prisma query plan produced by toPrisma().
1275
1326
  *
@@ -1402,6 +1453,57 @@ type ConditionShapeKeys = {
1402
1453
  /** The keys a node of one shape takes: those it must have and those it may. */
1403
1454
  declare const getConditionShapeKeys: (shape: ConditionShape) => ConditionShapeKeys;
1404
1455
 
1456
+ /** A value expression under a lens: its type, the dotted paths it reads from the row (a relation's
1457
+ * rows under the relation: `fanMissions.status`), its clock unit, and every problem the
1458
+ * validator, the lens gate and type inference find. Never throws on a bad expression. */
1459
+ type ValueDescription = {
1460
+ type: ValueType | null;
1461
+ paths: string[];
1462
+ clockUnit: ClockUnit | null;
1463
+ errors: ValidationIssue[];
1464
+ };
1465
+ declare const describeValue: (expression: ValueExpression, lensOrNarrowing: Lens | LensNarrowing) => ValueDescription;
1466
+
1467
+ /**
1468
+ * The value an expression computes from a row, in memory, with what check() takes (`bindings`,
1469
+ * `now`, `timeZone`, `weekStart`, `absent`): a literal (bare or `{ value }`), a path read (null when absent), a bound
1470
+ * value, an aggregate over a relation's rows (`count`, `sum`, `avg`, `min`, `max`, through its
1471
+ * window and condition; `avg` and `min` / `max` over no values are null), the branch an `if` picks,
1472
+ * or a list (`distinct: true` drops repeats). Throws on a malformed expression,
1473
+ * as check() throws on a malformed rule; `validateValue` reports every problem without data.
1474
+ */
1475
+ declare const evaluateValue: (expression: ValueExpression, data: Row, options?: CheckOptions) => unknown;
1476
+
1477
+ /**
1478
+ * The type a value expression returns, worked out without data — for a consumer to check against
1479
+ * the type it stores before saving the expression. A literal, bare or `{ value }`, has its value's
1480
+ * kind (a whole number `Int`, any other `Float`); a path its column's kind through the lens
1481
+ * (nullable unless the map declares it required); `count` an `Int`; `sum` its column's numeric
1482
+ * kind, never null (0 over no rows); `avg` a `Float` (`Decimal` stays `Decimal`), null over no
1483
+ * rows; `min` / `max` their column's kind, nullable (no rows). An `if`'s branches and a list's
1484
+ * items must agree (two numeric kinds read as `Decimal` when either is, else `Float`; a missing
1485
+ * `else` is null). `lens` is needed wherever a path's kind is read. Throws on
1486
+ * an expression that has no type: a path that does not resolve, reads through a to-many relation
1487
+ * or names rows, an aggregate over something that isn't a list, branches that disagree, a binding,
1488
+ * `distinct` over Json.
1489
+ */
1490
+ declare const inferValueType: (expression: ValueExpression, lens?: Lens | LensNarrowing) => ValueType;
1491
+
1492
+ /** A value expression's shape checked without data: each node exactly one kind, every key known,
1493
+ * aggregate modes from VALUE_AGGREGATE_MODES, and each condition it holds (`if`, an aggregate's
1494
+ * `filter` / `condition` / window) valid as `validateRule` sees it. */
1495
+ declare const validateValue: (expression: unknown) => ValidationResult;
1496
+ /** validateValue's throwing form. */
1497
+ declare const assertValidValue: (expression: unknown) => void;
1498
+
1499
+ /**
1500
+ * The finest clock unit a value expression's answer can change by while its data stays the same —
1501
+ * `clockUnit` over every condition it holds (an `if`, an aggregate's `filter` / `condition`), so
1502
+ * an aggregate over the last 90 days reads `day`. Null when it reads no clock. Throws, as
1503
+ * `clockUnit` does, on a unit finer than `clock.finestUnit`.
1504
+ */
1505
+ declare const valueClockUnit: (expression: ValueExpression) => ClockUnit | null;
1506
+
1405
1507
  /**
1406
1508
  * Records sorted by an `OrderBy`, the way every rail orders a window: each key in turn, read as an
1407
1509
  * own-property path, `dir` order, a NULL (or absent) value last in either direction; ties keep their
@@ -1409,4 +1511,4 @@ declare const getConditionShapeKeys: (shape: ConditionShape) => ConditionShapeKe
1409
1511
  */
1410
1512
  declare const orderRecords: <T>(items: readonly T[], orderBy: OrderBy) => T[];
1411
1513
 
1412
- export { ALL_KINDS, type Absent, type AggregateMode, type AggregateRule, type All, type Any, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, CLOCK_UNITS, type CheckData, type CheckOptions, type ClockUnit, type CompileOptions, type Condition, ConditionShape, type ConditionShapeKeys, type DateConfig, type DateExpr, type DateInputOrExpr, type DateInputValue, type DateOffset, DateOperator, type DateRule, type DateRuleValue, type EdgeExpr, type EngineGlobalDefaults, type EngineGlobalPath, type EngineGlobalValues, type EngineGlobalsState, type EnumNarrowing, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type FuzzyConfig, type GroupByStep, type IfThenElse, type Lens, type LensClamps, type LensNarrowing, type LensPathHop, type LensPathResolution, LensRefusal, type LensRelationSelect, type LensSelect, type LensSelectOptions, type LensValue, type LensWhereSql, type LensWhereSqlOptions, type ListBindingsOptions, type Magnitude, type MaterializeSourceQueryOptions, type ModelDefaultNarrowing, type ModelEntry, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, type NumberOffset, Operator, type OperatorFamily, type OrderBy, type OrderedRuleValue, type PathProjection, type PeriodExpr, type PeriodUnit, type PrismaProvider, type PrismaStep, type PrismaWhere, type ProjectLensOptions, type ProjectRowsOptions, type ProjectedVisit, type RelativeUnit, type RelativeUnits, type RollingExpr, type Row, type Rule, type RuleDescription, type RuleScalar, type RuleSourceDescription, RuleTarget, type RuleValue, type ScopeOutOfBounds, type ScopeRef, type ScopedRef, type SortDir, type SourceEntry, type SourceOption, SourceOptionOrder, type SourcePrismaQuery, type SourceQuery, type SourceRowShape, type SourceSelect, type SourceSpec, type SourceSqlQuery, type SourceValues, SqlDialect, type StepRef, type StoredLens, type StrictAggregateRule, type StrictAll, type StrictAny, type StrictArrayCountRule, type StrictArrayPredicateRule, type StrictArrayPresenceRule, type StrictArrayRule, type StrictCondition, type StrictContainsRule, type StrictDateComparisonRule, type StrictDateDayRule, type StrictDateRangeRule, type StrictDateRule, type StrictEqualityRule, type StrictIfThenElse, type StrictMembershipRule, type StrictOrderedComparisonRule, type StrictPatternRule, type StrictPresenceRule, type StrictRangeRule, type StrictRule, type StrictStringBoundaryRule, type TimeZoneConfig, type ToPrismaOptions, type ToPrismaResult, type ToSqlOptions, type ToSqlResult, UsageError, type ValidateRuleOptions, type ValidationIssue, type ValidationResult, ValueShape, type ValueSourceFields, type ValueSourceOf, type WeekStart, type WhereSqlOptions, type WhereStep, type WindowFields, andWhere, assertValidFieldMaps, assertValidNarrowing, assertValidRule, bindLens, bindRule, check, clampLens, clockUnit, coerceRule, composeLens, createLens, describeRule, describeRuleSources, engineGlobals, executePrismaPlan, getAggregateOperators, getArrayOperators, getConditionShapeKeys, getLensRoot, getOperatorsForKind, getValueShape, indexBridges, lensVisit, listBindings, listFields, listLensBindings, matchAll, matchNothing, materializeSourceQuery, materializeSources, narrowRule, orWhere, orderRecords, parseScopeRef, prefixConditionFields, projectLens, projectRows, readLensValue, readScopeRef, registerEngineGlobals, stitchFieldMaps, storeLens, toLensSelect, toLensWhereSql, toPrisma, toSourceQueries, toSql, toWhereSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };
1514
+ export { ALL_KINDS, type Absent, type AggregateMode, type AggregateRule, type AggregateValue, type All, type Any, ArrayOperator, type ArrayRule, type BareLiteral, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, CLOCK_UNITS, type CheckData, type CheckOptions, type ClockUnit, type CompileOptions, type Condition, ConditionShape, type ConditionShapeKeys, type DateConfig, type DateExpr, type DateInputOrExpr, type DateInputValue, type DateOffset, DateOperator, type DateRule, type DateRuleValue, type EdgeExpr, type EngineGlobalDefaults, type EngineGlobalPath, type EngineGlobalValues, type EngineGlobalsState, type EnumNarrowing, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type FuzzyConfig, type GroupByStep, type IfThenElse, type IfThenElseValue, type Lens, type LensClamps, type LensNarrowing, type LensPathHop, type LensPathResolution, LensRefusal, type LensRelationSelect, type LensSelect, type LensSelectOptions, type LensValue, type LensWhereSql, type LensWhereSqlOptions, type ListBindingsOptions, type ListValue, type Magnitude, type MaterializeSourceQueryOptions, type ModelDefaultNarrowing, type ModelEntry, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, type NumberOffset, Operator, type OperatorFamily, type OrderBy, type OrderedRuleValue, type PathProjection, type PeriodExpr, type PeriodUnit, type PrismaProvider, type PrismaStep, type PrismaWhere, type ProjectLensOptions, type ProjectRowsOptions, type ProjectedVisit, type RelativeUnit, type RelativeUnits, type RollingExpr, type Row, type Rule, type RuleDescription, type RuleScalar, type RuleSourceDescription, RuleTarget, type RuleValue, type ScopeOutOfBounds, type ScopeRef, type ScopedRef, type SortDir, type SourceEntry, type SourceOption, SourceOptionOrder, type SourcePrismaQuery, type SourceQuery, type SourceRowShape, type SourceSelect, type SourceSpec, type SourceSqlQuery, type SourceValues, SqlDialect, type StepRef, type StoredLens, type StrictAggregateRule, type StrictAll, type StrictAny, type StrictArrayCountRule, type StrictArrayPredicateRule, type StrictArrayPresenceRule, type StrictArrayRule, type StrictCondition, type StrictContainsRule, type StrictDateComparisonRule, type StrictDateDayRule, type StrictDateRangeRule, type StrictDateRule, type StrictEqualityRule, type StrictIfThenElse, type StrictMembershipRule, type StrictOrderedComparisonRule, type StrictPatternRule, type StrictPresenceRule, type StrictRangeRule, type StrictRule, type StrictStringBoundaryRule, type TimeZoneConfig, type ToPrismaOptions, type ToPrismaResult, type ToSqlOptions, type ToSqlResult, UsageError, VALUE_AGGREGATE_MODES, type ValidateRuleOptions, type ValidationIssue, type ValidationResult, type ValueAggregateMode, type ValueDescription, type ValueExpression, ValueShape, type ValueSourceFields, type ValueSourceOf, type ValueType, type WeekStart, type WhereSqlOptions, type WhereStep, type WindowFields, andWhere, assertValidFieldMaps, assertValidNarrowing, assertValidRule, assertValidValue, bindLens, bindRule, check, clampLens, clockUnit, coerceRule, composeLens, createLens, describeRule, describeRuleSources, describeValue, engineGlobals, evaluateValue, executePrismaPlan, getAggregateOperators, getArrayOperators, getConditionShapeKeys, getLensRoot, getOperatorsForKind, getValueShape, indexBridges, inferValueType, lensVisit, listBindings, listFields, listLensBindings, matchAll, matchNothing, materializeSourceQuery, materializeSources, narrowRule, orWhere, orderRecords, parseScopeRef, prefixConditionFields, projectLens, projectRows, readLensValue, readScopeRef, registerEngineGlobals, stitchFieldMaps, storeLens, toLensSelect, toLensWhereSql, toPrisma, toSourceQueries, toSql, toWhereSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, validateValue, valueClockUnit, walkLensPath };