@inixiative/json-rules 1.1.2 → 1.2.0

package/dist/index.d.cts

@@ -1,119 +1,350 @@
-declare enum Operator {
-    equals = "equals",
-    notEquals = "notEquals",
-    lessThan = "lessThan",
-    lessThanEquals = "lessThanEquals",
-    greaterThan = "greaterThan",
-    greaterThanEquals = "greaterThanEquals",
-    contains = "contains",
-    notContains = "notContains",
-    in = "in",
-    notIn = "notIn",
-    matches = "matches",
-    notMatches = "notMatches",
-    between = "between",
-    notBetween = "notBetween",
-    isEmpty = "isEmpty",
-    notEmpty = "notEmpty",
-    exists = "exists",
-    notExists = "notExists",
-    startsWith = "startsWith",
-    endsWith = "endsWith"
-}
-declare enum ArrayOperator {
-    all = "all",
-    any = "any",
-    none = "none",
-    atLeast = "atLeast",
-    atMost = "atMost",
-    exactly = "exactly",
-    empty = "empty",
-    notEmpty = "notEmpty"
-}
-declare enum DateOperator {
-    before = "before",
-    after = "after",
-    onOrBefore = "onOrBefore",
-    onOrAfter = "onOrAfter",
-    between = "between",
-    notBetween = "notBetween",
-    dayIn = "dayIn",// e.g., ['monday', 'tuesday', 'friday']
-    dayNotIn = "dayNotIn"
-}
+declare const Operator: {
+    readonly equals: "equals";
+    readonly notEquals: "notEquals";
+    readonly lessThan: "lessThan";
+    readonly lessThanEquals: "lessThanEquals";
+    readonly greaterThan: "greaterThan";
+    readonly greaterThanEquals: "greaterThanEquals";
+    readonly contains: "contains";
+    readonly notContains: "notContains";
+    readonly in: "in";
+    readonly notIn: "notIn";
+    readonly matches: "matches";
+    readonly notMatches: "notMatches";
+    readonly between: "between";
+    readonly notBetween: "notBetween";
+    readonly isEmpty: "isEmpty";
+    readonly notEmpty: "notEmpty";
+    readonly exists: "exists";
+    readonly notExists: "notExists";
+    readonly startsWith: "startsWith";
+    readonly endsWith: "endsWith";
+};
+type Operator = (typeof Operator)[keyof typeof Operator];
+declare const ArrayOperator: {
+    readonly all: "all";
+    readonly any: "any";
+    readonly none: "none";
+    readonly atLeast: "atLeast";
+    readonly atMost: "atMost";
+    readonly exactly: "exactly";
+    readonly empty: "empty";
+    readonly notEmpty: "notEmpty";
+};
+type ArrayOperator = (typeof ArrayOperator)[keyof typeof ArrayOperator];
+declare const DateOperator: {
+    readonly before: "before";
+    readonly after: "after";
+    readonly onOrBefore: "onOrBefore";
+    readonly onOrAfter: "onOrAfter";
+    readonly between: "between";
+    readonly notBetween: "notBetween";
+    readonly dayIn: "dayIn";
+    readonly dayNotIn: "dayNotIn";
+};
+type DateOperator = (typeof DateOperator)[keyof typeof DateOperator];
 
-type Rule = {
+type OperatorValues = typeof Operator;
+type ArrayOperatorValues = typeof ArrayOperator;
+type DateOperatorValues = typeof DateOperator;
+type RuleScalar = string | number | boolean | null | undefined;
+type RuleValue = RuleScalar | Date | RegExp | RuleValue[] | {
+    [key: string]: RuleValue;
+};
+type OrderedRuleValue = string | number | Date;
+type DateInputValue = string | number | Date;
+type DateRuleValue = DateInputValue | [DateInputValue, DateInputValue] | string[];
+type ValueSource<TValue> = {
+    value: TValue;
+    path?: never;
+} | {
+    path: string;
+    value?: never;
+};
+type NoValueSource = {
+    value?: never;
+    path?: never;
+};
+type RuleBase<TOperator extends Operator> = {
+    field: string;
+    operator: TOperator;
+    error?: string;
+};
+type DateRuleBase<TOperator extends DateOperator> = {
+    field: string;
+    dateOperator: TOperator;
+    error?: string;
+};
+type StrictEqualityRule<TValue = RuleValue> = (RuleBase<OperatorValues['equals']> & ValueSource<TValue>) | (RuleBase<OperatorValues['notEquals']> & ValueSource<TValue>);
+type StrictOrderedComparisonRule = (RuleBase<OperatorValues['lessThan']> & ValueSource<OrderedRuleValue>) | (RuleBase<OperatorValues['lessThanEquals']> & ValueSource<OrderedRuleValue>) | (RuleBase<OperatorValues['greaterThan']> & ValueSource<OrderedRuleValue>) | (RuleBase<OperatorValues['greaterThanEquals']> & ValueSource<OrderedRuleValue>);
+type StrictMembershipRule<TValue = RuleValue> = (RuleBase<OperatorValues['in']> & ValueSource<TValue[]>) | (RuleBase<OperatorValues['notIn']> & ValueSource<TValue[]>);
+type StrictContainsRule<TValue = RuleValue> = (RuleBase<OperatorValues['contains']> & ValueSource<TValue>) | (RuleBase<OperatorValues['notContains']> & ValueSource<TValue>);
+type StrictPatternRule = (RuleBase<OperatorValues['matches']> & ValueSource<RegExp | string>) | (RuleBase<OperatorValues['notMatches']> & ValueSource<RegExp | string>);
+type StrictStringBoundaryRule = (RuleBase<OperatorValues['startsWith']> & ValueSource<string>) | (RuleBase<OperatorValues['endsWith']> & ValueSource<string>);
+type StrictRangeRule = (RuleBase<OperatorValues['between']> & ValueSource<[OrderedRuleValue, OrderedRuleValue]>) | (RuleBase<OperatorValues['notBetween']> & ValueSource<[OrderedRuleValue, OrderedRuleValue]>);
+type StrictPresenceRule = (RuleBase<OperatorValues['isEmpty']> & NoValueSource) | (RuleBase<OperatorValues['notEmpty']> & NoValueSource) | (RuleBase<OperatorValues['exists']> & NoValueSource) | (RuleBase<OperatorValues['notExists']> & NoValueSource);
+type StrictRule<TValue = RuleValue> = StrictEqualityRule<TValue> | StrictOrderedComparisonRule | StrictMembershipRule<TValue> | StrictContainsRule<TValue> | StrictPatternRule | StrictStringBoundaryRule | StrictRangeRule | StrictPresenceRule;
+type ArrayType = 'jsonb' | 'native';
+type ArrayRuleBase<TOperator extends ArrayOperator> = {
+    field: string;
+    arrayOperator: TOperator;
+    arrayType?: ArrayType;
+    error?: string;
+};
+type StrictArrayPredicateRule<TRuleValue = RuleValue, TDateValue = DateRuleValue> = (ArrayRuleBase<ArrayOperatorValues['all']> & {
+    condition: StrictCondition<TRuleValue, TDateValue>;
+    count?: never;
+}) | (ArrayRuleBase<ArrayOperatorValues['any']> & {
+    condition: StrictCondition<TRuleValue, TDateValue>;
+    count?: never;
+}) | (ArrayRuleBase<ArrayOperatorValues['none']> & {
+    condition: StrictCondition<TRuleValue, TDateValue>;
+    count?: never;
+});
+type StrictArrayCountRule<TRuleValue = RuleValue, TDateValue = DateRuleValue> = (ArrayRuleBase<ArrayOperatorValues['atLeast']> & {
+    condition?: StrictCondition<TRuleValue, TDateValue>;
+    count?: number;
+}) | (ArrayRuleBase<ArrayOperatorValues['atMost']> & {
+    condition?: StrictCondition<TRuleValue, TDateValue>;
+    count?: number;
+}) | (ArrayRuleBase<ArrayOperatorValues['exactly']> & {
+    condition?: StrictCondition<TRuleValue, TDateValue>;
+    count?: number;
+});
+type StrictArrayPresenceRule = (ArrayRuleBase<ArrayOperatorValues['empty']> & {
+    condition?: never;
+    count?: never;
+}) | (ArrayRuleBase<ArrayOperatorValues['notEmpty']> & {
+    condition?: never;
+    count?: never;
+});
+type StrictArrayRule<TRuleValue = RuleValue, TDateValue = DateRuleValue> = StrictArrayPredicateRule<TRuleValue, TDateValue> | StrictArrayCountRule<TRuleValue, TDateValue> | StrictArrayPresenceRule;
+type StrictDateComparisonRule = (DateRuleBase<DateOperatorValues['before']> & ValueSource<DateInputValue>) | (DateRuleBase<DateOperatorValues['after']> & ValueSource<DateInputValue>) | (DateRuleBase<DateOperatorValues['onOrBefore']> & ValueSource<DateInputValue>) | (DateRuleBase<DateOperatorValues['onOrAfter']> & ValueSource<DateInputValue>);
+type StrictDateRangeRule = (DateRuleBase<DateOperatorValues['between']> & ValueSource<[DateInputValue, DateInputValue]>) | (DateRuleBase<DateOperatorValues['notBetween']> & ValueSource<[DateInputValue, DateInputValue]>);
+type StrictDateDayRule = (DateRuleBase<DateOperatorValues['dayIn']> & {
+    value: string[];
+    path?: never;
+}) | (DateRuleBase<DateOperatorValues['dayNotIn']> & {
+    value: string[];
+    path?: never;
+});
+type StrictDateRule = StrictDateComparisonRule | StrictDateRangeRule | StrictDateDayRule;
+type Rule<TValue = RuleValue> = {
     field: string;
     operator: Operator;
-    value?: any;
+    value?: TValue;
     path?: string;
     error?: string;
 };
-type ArrayType = 'jsonb' | 'native';
-type ArrayRule = {
+type ArrayRule<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
     field: string;
     arrayOperator: ArrayOperator;
     arrayType?: ArrayType;
-    condition?: Condition;
+    condition?: Condition<TRuleValue, TDateValue>;
     count?: number;
     error?: string;
 };
-type DateRule = {
+type DateRule<TValue = DateRuleValue> = {
     field: string;
     dateOperator: DateOperator;
-    value?: any;
+    value?: TValue;
     path?: string;
     error?: string;
 };
-type All = {
-    all: Condition[];
+type All<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
+    all: Condition<TRuleValue, TDateValue>[];
+    error?: string;
+};
+type Any<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
+    any: Condition<TRuleValue, TDateValue>[];
+    error?: string;
+};
+type IfThenElse<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
+    if: Condition<TRuleValue, TDateValue>;
+    then: Condition<TRuleValue, TDateValue>;
+    else?: Condition<TRuleValue, TDateValue>;
+    error?: string;
+};
+type Condition<TRuleValue = RuleValue, TDateValue = DateRuleValue> = Rule<TRuleValue> | ArrayRule<TRuleValue, TDateValue> | DateRule<TDateValue> | All<TRuleValue, TDateValue> | Any<TRuleValue, TDateValue> | IfThenElse<TRuleValue, TDateValue> | boolean;
+type StrictAll<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
+    all: StrictCondition<TRuleValue, TDateValue>[];
     error?: string;
 };
-type Any = {
-    any: Condition[];
+type StrictAny<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
+    any: StrictCondition<TRuleValue, TDateValue>[];
     error?: string;
 };
-type IfThenElse = {
-    if: Condition;
-    then: Condition;
-    else?: Condition;
+type StrictIfThenElse<TRuleValue = RuleValue, TDateValue = DateRuleValue> = {
+    if: StrictCondition<TRuleValue, TDateValue>;
+    then: StrictCondition<TRuleValue, TDateValue>;
+    else?: StrictCondition<TRuleValue, TDateValue>;
     error?: string;
 };
-type Condition = Rule | ArrayRule | DateRule | All | Any | IfThenElse | boolean;
+type StrictCondition<TRuleValue = RuleValue, TDateValue = DateRuleValue> = StrictRule<TRuleValue> | StrictArrayRule<TRuleValue, TDateValue> | StrictDateRule | StrictAll<TRuleValue, TDateValue> | StrictAny<TRuleValue, TDateValue> | StrictIfThenElse<TRuleValue, TDateValue> | boolean;
+
+declare const check: <TData extends Record<string, unknown>>(conditions: Condition, data: TData, context?: TData) => boolean | string;
+
+type PrismaWhere = Record<string, unknown>;
+type FieldMapEntry = {
+    kind: 'scalar' | 'object' | 'enum';
+    type: string;
+    isList?: boolean;
+    fromFields?: string[];
+    toFields?: string[];
+    relationName?: string;
+};
+interface FieldMap {
+    [modelName: string]: {
+        dbName?: string | null;
+        fields: {
+            [fieldName: string]: FieldMapEntry;
+        };
+    };
+}
+type StepRef = {
+    __step: number;
+};
+type GroupByStep = {
+    operation: 'groupBy';
+    model: string;
+    args: {
+        by: string[];
+        where: Record<string, unknown>;
+        having: Record<string, unknown>;
+    };
+    extract: string;
+};
+type WhereStep = {
+    operation: 'where';
+    where: Record<string, unknown>;
+};
+type PrismaStep = GroupByStep | WhereStep;
+type ToPrismaResult = {
+    steps: PrismaStep[];
+};
+type BuildOptions = {
+    map?: FieldMap;
+    model?: string;
+    context?: Record<string, unknown>;
+};
 
-declare const check: (conditions: Condition, data: any, context?: any) => boolean | string;
+/**
+ * Execute a Prisma query plan produced by toPrisma().
+ *
+ * The plan is a flat list of steps where all but the last are `groupBy` steps
+ * that feed results (via { __step: N } sentinels) into subsequent steps.
+ * The final step is always a `where` step whose resolved WHERE clause is returned.
+ *
+ * @param result         - Result from toPrisma()
+ * @param prismaDelegate - Map of camelCase model name → Prisma delegate
+ *                         e.g. { post: prisma.post, user: prisma.user }
+ * @returns The resolved WHERE clause (ready for findMany/count/etc.)
+ *
+ * @example
+ * const plan = toPrisma(condition, { map, model: 'User' });
+ * const where = await executePrismaQueryPlan(plan, { post: prisma.post });
+ * await prisma.user.findMany({ where });
+ */
+declare const executePrismaQueryPlan: (result: ToPrismaResult, prismaDelegate: Record<string, Record<string, (...args: unknown[]) => unknown>>) => Promise<Record<string, unknown>>;
+
+/**
+ * Convert a json-rules Condition to a Prisma query plan.
+ *
+ * Returns a `ToPrismaResult` with:
+ * - `where` – the Prisma WHERE clause
+ * - `steps` – optional array of groupBy steps for count-based relation filters
+ *   (only present when `atLeast`/`atMost`/`exactly` operators are used with a map)
+ *
+ * When `steps` is present, pass the result to `executePrismaQueryPlan` to
+ * resolve step refs before using `where` in a Prisma query.
+ *
+ * @param condition - The rule condition to convert
+ * @param options   - Optional map, model, and context
+ *
+ * @example
+ * ```typescript
+ * // Simple scalar
+ * toPrisma({ field: 'status', operator: Operator.equals, value: 'active' })
+ * // → { where: { status: { equals: 'active' } } }
+ *
+ * // JSON field detection (map required)
+ * toPrisma({ field: 'metadata.theme', operator: Operator.equals, value: 'dark' }, { map, model: 'User' })
+ * // → { where: { metadata: { path: ['theme'], equals: 'dark' } } }
+ *
+ * // Context path ref
+ * toPrisma({ field: 'userId', operator: Operator.equals, path: 'currentUser.id' }, { context: { currentUser: { id: '123' } } })
+ * // → { where: { userId: { equals: '123' } } }
+ *
+ * // Multi-step (map required)
+ * const plan = toPrisma({ field: 'posts', arrayOperator: 'atLeast', count: 3, condition: {...} }, { map, model: 'User' });
+ * const where = await executePrismaQueryPlan(plan, { post: prisma.post });
+ * await prisma.user.findMany({ where });
+ * ```
+ */
+declare const toPrisma: (condition: Condition, options?: BuildOptions) => ToPrismaResult;
 
 type SqlResult = {
     sql: string;
     params: unknown[];
+    joins: string[];
 };
 
+type SqlBuildOptions = {
+    map?: FieldMap;
+    model?: string;
+    alias?: string;
+    context?: Record<string, unknown>;
+};
 /**
  * Convert a json-rules Condition to a PostgreSQL WHERE clause.
  *
  * @param condition - The rule condition to convert
- * @returns Object with `sql` (WHERE clause fragment) and `params` array
+ * @param options   - Optional map/model/alias for JOIN generation; context for path refs
+ * @returns Object with `sql`, `params`, and `joins` (LEFT JOIN clauses)
  *
  * @example
  * ```typescript
- * import { toSql, Operator } from '@inixiative/json-rules';
- *
- * const rule = { field: 'status', operator: Operator.equals, value: 'active' };
- * const { sql, params } = toSql(rule);
+ * // Simple field
+ * const { sql, params } = toSql({ field: 'status', operator: Operator.equals, value: 'active' });
  * // sql: '"status" = $1'
- * // params: ['active']
  *
- * // Complex rule
- * const rule2 = {
- *   all: [
- *     { field: 'deletedAt', operator: Operator.equals, value: null },
- *     { field: 'status', operator: Operator.in, value: ['active', 'pending'] }
- *   ]
- * };
- * const { sql: sql2, params: params2 } = toSql(rule2);
- * // sql: '("deletedAt" IS NULL AND "status" = ANY($1))'
- * // params: [['active', 'pending']]
+ * // Relation traversal with JOINs (map required)
+ * const { sql, params, joins } = toSql(
+ *   { field: 'author.email', operator: Operator.equals, value: 'a@b.com' },
+ *   { map, model: 'Post', alias: 't0' }
+ * );
+ * // sql:  '"t1"."email" = $1'
+ * // joins: ['LEFT JOIN "User" AS "t1" ON "t1"."id" = "t0"."authorId"']
+ *
+ * // Same-record field comparison ($.field)
+ * const { sql: sql2 } = toSql({ field: 'endDate', operator: Operator.greaterThan, path: '$.startDate' });
+ * // sql2: '"endDate" > "startDate"'
+ *
+ * // External context ref
+ * const { sql: sql3 } = toSql(
+ *   { field: 'userId', operator: Operator.equals, path: 'currentUser.id' },
+ *   { context: { currentUser: { id: '123' } } }
+ * );
+ * // sql3: '"userId" = $1'  params: ['123']
  * ```
  */
-declare const toSql: (condition: Condition) => SqlResult;
+declare const toSql: (condition: Condition, options?: SqlBuildOptions) => SqlResult;
+
+type RuleValidationTarget = 'check' | 'toPrisma' | 'toSql';
+type ValidationIssue = {
+    path: string;
+    message: string;
+    code: string;
+};
+type ValidationResult = {
+    ok: boolean;
+    errors: ValidationIssue[];
+};
+declare const validateRule: (condition: unknown, options?: {
+    target?: RuleValidationTarget;
+}) => ValidationResult;
+declare const assertValidRule: (condition: unknown, options?: {
+    target?: RuleValidationTarget;
+}) => asserts condition is Condition;
 
-export { type All, type Any, ArrayOperator, type ArrayRule, type ArrayType, type Condition, DateOperator, type DateRule, type IfThenElse, Operator, type Rule, type SqlResult, check, toSql };
+export { type All, type Any, ArrayOperator, type ArrayRule, type ArrayType, type BuildOptions, type Condition, type DateInputValue, DateOperator, type DateRule, type DateRuleValue, type FieldMap, type FieldMapEntry, type GroupByStep, type IfThenElse, Operator, type OrderedRuleValue, type PrismaStep, type PrismaWhere, type Rule, type RuleScalar, type RuleValidationTarget, type RuleValue, type SqlResult, type StepRef, 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, type WhereStep, assertValidRule, check, executePrismaQueryPlan, toPrisma, toSql, validateRule };