@inixiative/json-rules 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -223,15 +223,27 @@ type FieldMapEntry = {
     fromFields?: string[];
     toFields?: string[];
     relationName?: string;
+    /**
+     * Per-field allowed values, primarily for enum fields. Takes precedence over
+     * `FieldMap.enums[type]` if both are set. Pass-through from codegen
+     * (e.g. prisma-map's `EnumField.values`). Consumed by `checkRuleAgainstLens`.
+     */
+    values?: readonly string[];
+};
+type ModelEntry = {
+    dbName?: string | null;
+    fields: Record<string, FieldMapEntry>;
+};
+/**
+ * A schema map: models keyed by name, plus an optional enum registry scoped to
+ * this source. In multi-source setups (Prisma + Salesforce + CRM) each FieldMap
+ * carries its own enums so namespaces don't collide across sources.
+ */
+type FieldMap = {
+    models: Record<string, ModelEntry>;
+    /** Enum name → allowed values, e.g. `{ UserRole: ['ADMIN', 'USER'] }`. */
+    enums?: Record<string, readonly string[]>;
 };
-interface FieldMap {
-    [modelName: string]: {
-        dbName?: string | null;
-        fields: {
-            [fieldName: string]: FieldMapEntry;
-        };
-    };
-}
 type StepRef = {
     __step: number;
 };
@@ -266,6 +278,21 @@ type BridgeEndpoint = {
     on: string;
 };
 type BridgeCardinality = 'oneToOne' | 'oneToMany';
+/**
+ * A cross-source edge between two endpoints.
+ *
+ * Endpoint ordering convention for `oneToMany`:
+ *   - `endpoints[0]` is the "one" side — its `on` field must be unique per row
+ *     (typically a primary key).
+ *   - `endpoints[1]` is the "many" side — its `on` field may repeat across rows
+ *     (typically a foreign key).
+ *
+ * Mis-ordering produces wrong `isList` flags during stitching and silent
+ * row-dedup when building bridge dictionaries. `buildBridgeDictionary` throws
+ * at runtime if endpoint[0]'s data has duplicate `on` values to catch this.
+ *
+ * For `oneToOne`, both `on` fields must be unique; endpoint order is symmetric.
+ */
 type Bridge = {
     endpoints: [BridgeEndpoint, BridgeEndpoint];
     cardinality: BridgeCardinality;
@@ -290,21 +317,56 @@ type Lens = FieldMapSet & {
     mapName: string;
     model: string;
 };
-type ModelNarrowing = {
+/**
+ * Narrowing applied wherever a model appears (intrinsic to the model).
+ * Has no `relations` because relations are path-specific by definition.
+ *
+ * Two kinds of narrowing live here:
+ * - SCHEMA narrowing (picks/omits/enumPicks/enumOmits): controls what's visible
+ *   in the type surface. AI/SDK consumers can't see narrowed-away fields.
+ * - DATA narrowing (where): controls which ROWS are in scope. Filter-first
+ *   semantic, anchored to the model. Under arrayOperator: 'all', applied via
+ *   implication (negate) to preserve filter-first meaning — see applyLens.
+ */
+type ModelDefaultNarrowing = {
     picks?: string[];
     omits?: string[];
+    enumPicks?: Record<string, readonly string[]>;
+    enumOmits?: Record<string, readonly string[]>;
+    /**
+     * Row-level filter anchored to this model — "from what you can see, this is true."
+     * Composes via filter-first semantic at every visit of this model.
+     */
+    where?: Condition;
+};
+/** Narrowing for a model at a specific traversal path. Adds relations to the default shape. */
+type ModelNarrowing = ModelDefaultNarrowing & {
     relations?: Record<string, ModelNarrowing>;
 };
+/** Narrowing for an enum type (applies anywhere the enum is referenced). */
+type EnumNarrowing = {
+    picks?: readonly string[];
+    omits?: readonly string[];
+};
+/** Applies-everywhere narrowings — per-model (no relations) + per-enum-type. */
+type NarrowingDefaults = {
+    models?: Record<string, ModelDefaultNarrowing>;
+    enums?: Record<string, EnumNarrowing>;
+};
 type MapNarrowing = {
+    /** Path-specific narrowings, root + relations tree. */
     models: Record<string, ModelNarrowing>;
+    /** Applies-everywhere narrowings, intersect with path-specific. */
+    defaults?: NarrowingDefaults;
 };
 type LensNarrowing = {
     parent: Lens | LensNarrowing;
     maps: Record<string, MapNarrowing>;
-    constrains?: Condition;
+    /** Lens-level row filter, anchored to the root model. ANDs into the root rule. */
+    where?: Condition;
 };
 
-declare const applyLens: (rule: Condition, narrowing: Lens | LensNarrowing) => Condition;
+declare const applyLens: (rule: Condition, lensOrNarrowing: Lens | LensNarrowing) => Condition;
 
 type RuleLensViolation = {
     path: string;
@@ -475,4 +537,4 @@ declare const assertValidRule: (condition: unknown, options?: {
     target?: RuleTarget;
 }) => asserts condition is Condition;
 
-export { AGGREGATE_OPERATORS, ALL_KINDS, ARRAY_OPERATOR_CATALOG, type AggregateMode, type AggregateRule, type All, type Any, type ArrayCatalogEntry, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, type BuildOptions, type CatalogEntry, type CheckOptions, type Condition, type CreateLensInput, DATE_OPERATOR_CATALOG, type DateInputValue, DateOperator, type DateRule, type DateRuleValue, EQUATABLE_KINDS, FIELD_OPERATOR_CATALOG, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type GroupByStep, type IfThenElse, type Lens, type LensNarrowing, type MapNarrowing, type ModelNarrowing, NUMERIC_KINDS, ORDERABLE_KINDS, Operator, type OrderedRuleValue, type PrismaStep, type PrismaWhere, type Rule, type RuleLensCheck, type RuleLensViolation, type RuleScalar, RuleTarget, type RuleValue, STRINGY_KINDS, type SqlResult, type StepRef, 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 ToPrismaResult, type ValidationIssue, type ValidationResult, ValueShape, type WhereStep, applyLens, assertValidRule, buildBridgeDictionary, check, checkRuleAgainstLens, createLens, executePrismaQueryPlan, getArrayOperators, getOperatorsForKind, getValueShape, isAggregateRangeOperator, isAggregateSingleOperator, isOperatorSupportedForTarget, projectNarrowing, stitchFieldMaps, toPrisma, toSql, validateFieldMap, validateFieldMapSet, validateNarrowing, validateRule };
+export { AGGREGATE_OPERATORS, ALL_KINDS, ARRAY_OPERATOR_CATALOG, type AggregateMode, type AggregateRule, type All, type Any, type ArrayCatalogEntry, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, type BuildOptions, type CatalogEntry, type CheckOptions, type Condition, type CreateLensInput, DATE_OPERATOR_CATALOG, type DateInputValue, DateOperator, type DateRule, type DateRuleValue, EQUATABLE_KINDS, type EnumNarrowing, FIELD_OPERATOR_CATALOG, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type GroupByStep, type IfThenElse, type Lens, type LensNarrowing, type MapNarrowing, type ModelDefaultNarrowing, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, ORDERABLE_KINDS, Operator, type OrderedRuleValue, type PrismaStep, type PrismaWhere, type Rule, type RuleLensCheck, type RuleLensViolation, type RuleScalar, RuleTarget, type RuleValue, STRINGY_KINDS, type SqlResult, type StepRef, 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 ToPrismaResult, type ValidationIssue, type ValidationResult, ValueShape, type WhereStep, applyLens, assertValidRule, buildBridgeDictionary, check, checkRuleAgainstLens, createLens, executePrismaQueryPlan, getArrayOperators, getOperatorsForKind, getValueShape, isAggregateRangeOperator, isAggregateSingleOperator, isOperatorSupportedForTarget, projectNarrowing, stitchFieldMaps, toPrisma, toSql, validateFieldMap, validateFieldMapSet, validateNarrowing, validateRule };

package/dist/index.d.ts

@@ -223,15 +223,27 @@ type FieldMapEntry = {
     fromFields?: string[];
     toFields?: string[];
     relationName?: string;
+    /**
+     * Per-field allowed values, primarily for enum fields. Takes precedence over
+     * `FieldMap.enums[type]` if both are set. Pass-through from codegen
+     * (e.g. prisma-map's `EnumField.values`). Consumed by `checkRuleAgainstLens`.
+     */
+    values?: readonly string[];
+};
+type ModelEntry = {
+    dbName?: string | null;
+    fields: Record<string, FieldMapEntry>;
+};
+/**
+ * A schema map: models keyed by name, plus an optional enum registry scoped to
+ * this source. In multi-source setups (Prisma + Salesforce + CRM) each FieldMap
+ * carries its own enums so namespaces don't collide across sources.
+ */
+type FieldMap = {
+    models: Record<string, ModelEntry>;
+    /** Enum name → allowed values, e.g. `{ UserRole: ['ADMIN', 'USER'] }`. */
+    enums?: Record<string, readonly string[]>;
 };
-interface FieldMap {
-    [modelName: string]: {
-        dbName?: string | null;
-        fields: {
-            [fieldName: string]: FieldMapEntry;
-        };
-    };
-}
 type StepRef = {
     __step: number;
 };
@@ -266,6 +278,21 @@ type BridgeEndpoint = {
     on: string;
 };
 type BridgeCardinality = 'oneToOne' | 'oneToMany';
+/**
+ * A cross-source edge between two endpoints.
+ *
+ * Endpoint ordering convention for `oneToMany`:
+ *   - `endpoints[0]` is the "one" side — its `on` field must be unique per row
+ *     (typically a primary key).
+ *   - `endpoints[1]` is the "many" side — its `on` field may repeat across rows
+ *     (typically a foreign key).
+ *
+ * Mis-ordering produces wrong `isList` flags during stitching and silent
+ * row-dedup when building bridge dictionaries. `buildBridgeDictionary` throws
+ * at runtime if endpoint[0]'s data has duplicate `on` values to catch this.
+ *
+ * For `oneToOne`, both `on` fields must be unique; endpoint order is symmetric.
+ */
 type Bridge = {
     endpoints: [BridgeEndpoint, BridgeEndpoint];
     cardinality: BridgeCardinality;
@@ -290,21 +317,56 @@ type Lens = FieldMapSet & {
     mapName: string;
     model: string;
 };
-type ModelNarrowing = {
+/**
+ * Narrowing applied wherever a model appears (intrinsic to the model).
+ * Has no `relations` because relations are path-specific by definition.
+ *
+ * Two kinds of narrowing live here:
+ * - SCHEMA narrowing (picks/omits/enumPicks/enumOmits): controls what's visible
+ *   in the type surface. AI/SDK consumers can't see narrowed-away fields.
+ * - DATA narrowing (where): controls which ROWS are in scope. Filter-first
+ *   semantic, anchored to the model. Under arrayOperator: 'all', applied via
+ *   implication (negate) to preserve filter-first meaning — see applyLens.
+ */
+type ModelDefaultNarrowing = {
     picks?: string[];
     omits?: string[];
+    enumPicks?: Record<string, readonly string[]>;
+    enumOmits?: Record<string, readonly string[]>;
+    /**
+     * Row-level filter anchored to this model — "from what you can see, this is true."
+     * Composes via filter-first semantic at every visit of this model.
+     */
+    where?: Condition;
+};
+/** Narrowing for a model at a specific traversal path. Adds relations to the default shape. */
+type ModelNarrowing = ModelDefaultNarrowing & {
     relations?: Record<string, ModelNarrowing>;
 };
+/** Narrowing for an enum type (applies anywhere the enum is referenced). */
+type EnumNarrowing = {
+    picks?: readonly string[];
+    omits?: readonly string[];
+};
+/** Applies-everywhere narrowings — per-model (no relations) + per-enum-type. */
+type NarrowingDefaults = {
+    models?: Record<string, ModelDefaultNarrowing>;
+    enums?: Record<string, EnumNarrowing>;
+};
 type MapNarrowing = {
+    /** Path-specific narrowings, root + relations tree. */
     models: Record<string, ModelNarrowing>;
+    /** Applies-everywhere narrowings, intersect with path-specific. */
+    defaults?: NarrowingDefaults;
 };
 type LensNarrowing = {
     parent: Lens | LensNarrowing;
     maps: Record<string, MapNarrowing>;
-    constrains?: Condition;
+    /** Lens-level row filter, anchored to the root model. ANDs into the root rule. */
+    where?: Condition;
 };
 
-declare const applyLens: (rule: Condition, narrowing: Lens | LensNarrowing) => Condition;
+declare const applyLens: (rule: Condition, lensOrNarrowing: Lens | LensNarrowing) => Condition;
 
 type RuleLensViolation = {
     path: string;
@@ -475,4 +537,4 @@ declare const assertValidRule: (condition: unknown, options?: {
     target?: RuleTarget;
 }) => asserts condition is Condition;
 
-export { AGGREGATE_OPERATORS, ALL_KINDS, ARRAY_OPERATOR_CATALOG, type AggregateMode, type AggregateRule, type All, type Any, type ArrayCatalogEntry, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, type BuildOptions, type CatalogEntry, type CheckOptions, type Condition, type CreateLensInput, DATE_OPERATOR_CATALOG, type DateInputValue, DateOperator, type DateRule, type DateRuleValue, EQUATABLE_KINDS, FIELD_OPERATOR_CATALOG, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type GroupByStep, type IfThenElse, type Lens, type LensNarrowing, type MapNarrowing, type ModelNarrowing, NUMERIC_KINDS, ORDERABLE_KINDS, Operator, type OrderedRuleValue, type PrismaStep, type PrismaWhere, type Rule, type RuleLensCheck, type RuleLensViolation, type RuleScalar, RuleTarget, type RuleValue, STRINGY_KINDS, type SqlResult, type StepRef, 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 ToPrismaResult, type ValidationIssue, type ValidationResult, ValueShape, type WhereStep, applyLens, assertValidRule, buildBridgeDictionary, check, checkRuleAgainstLens, createLens, executePrismaQueryPlan, getArrayOperators, getOperatorsForKind, getValueShape, isAggregateRangeOperator, isAggregateSingleOperator, isOperatorSupportedForTarget, projectNarrowing, stitchFieldMaps, toPrisma, toSql, validateFieldMap, validateFieldMapSet, validateNarrowing, validateRule };
+export { AGGREGATE_OPERATORS, ALL_KINDS, ARRAY_OPERATOR_CATALOG, type AggregateMode, type AggregateRule, type All, type Any, type ArrayCatalogEntry, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, type BuildOptions, type CatalogEntry, type CheckOptions, type Condition, type CreateLensInput, DATE_OPERATOR_CATALOG, type DateInputValue, DateOperator, type DateRule, type DateRuleValue, EQUATABLE_KINDS, type EnumNarrowing, FIELD_OPERATOR_CATALOG, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type GroupByStep, type IfThenElse, type Lens, type LensNarrowing, type MapNarrowing, type ModelDefaultNarrowing, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, ORDERABLE_KINDS, Operator, type OrderedRuleValue, type PrismaStep, type PrismaWhere, type Rule, type RuleLensCheck, type RuleLensViolation, type RuleScalar, RuleTarget, type RuleValue, STRINGY_KINDS, type SqlResult, type StepRef, 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 ToPrismaResult, type ValidationIssue, type ValidationResult, ValueShape, type WhereStep, applyLens, assertValidRule, buildBridgeDictionary, check, checkRuleAgainstLens, createLens, executePrismaQueryPlan, getArrayOperators, getOperatorsForKind, getValueShape, isAggregateRangeOperator, isAggregateSingleOperator, isOperatorSupportedForTarget, projectNarrowing, stitchFieldMaps, toPrisma, toSql, validateFieldMap, validateFieldMapSet, validateNarrowing, validateRule };