@cerbos/orm-prisma 4.1.0 → 5.0.0

package/src/hierarchy.ts

@@ -0,0 +1,405 @@
+// The hierarchy operators: `overlaps`, `ancestorOf`, `descendentOf` over `hierarchy(...)`
+// operands, lowered to equality, IN-lists of strict prefixes, and a prefix match on a column.
+
+import type { PlanExpressionOperand } from "@cerbos/core";
+
+import {
+  assertStringField,
+  buildFieldFilter,
+  buildImpossibleFilter,
+  buildPrefixFilter,
+} from "./fields";
+import type { PrismaFilter } from "./index";
+import { isResolvedValue, resolveFieldReference } from "./mapping";
+import type { ResolvedFieldReference, TranslationContext } from "./mapping";
+import {
+  assertDefined,
+  isNamedOperand,
+  isOperatorOperand,
+  isValueOperand,
+} from "./plan";
+import type { OperatorOperand } from "./plan";
+import { resolveOperand } from "./translate";
+import { UnsupportedQueryPlanError } from "./errors";
+
+type ConstantSegment = { type: "constant"; value: string };
+
+type FieldSegment = { type: "field"; fieldRef: ResolvedFieldReference };
+
+type HierarchySegment = ConstantSegment | FieldSegment;
+
+type ConstantHierarchy = {
+  type: "constant";
+  segments: string[];
+};
+
+type FieldHierarchy = {
+  type: "field";
+  fieldRef: ResolvedFieldReference;
+  delimiter: string;
+};
+
+type SegmentedHierarchy = {
+  type: "segmented";
+  segments: HierarchySegment[];
+};
+
+type ResolvedHierarchy = ConstantHierarchy | FieldHierarchy | SegmentedHierarchy;
+
+function resolveHierarchy(
+  expr: OperatorOperand,
+  context: TranslationContext
+): ResolvedHierarchy {
+  const operands = expr.operands;
+
+  if (operands.length === 2) {
+    const strOperand = assertDefined(operands[0], "hierarchy requires operands");
+
+    const delimOperand = assertDefined(
+      operands[1],
+      "hierarchy requires a delimiter"
+    );
+
+    if (!isValueOperand(delimOperand)) {
+      throw new UnsupportedQueryPlanError("hierarchy delimiter must be a value");
+    }
+
+    const delimiter = String(delimOperand.value);
+
+    if (isValueOperand(strOperand)) {
+      return {
+        type: "constant",
+        segments: splitPath(String(strOperand.value), delimiter),
+      };
+    }
+
+    if (isNamedOperand(strOperand)) {
+      return {
+        type: "field",
+        fieldRef: resolveFieldReference(strOperand.name, context),
+        delimiter,
+      };
+    }
+
+    throw new UnsupportedQueryPlanError("hierarchy(string, delimiter) requires a value or field operand");
+  }
+
+  if (operands.length === 1) {
+    const inner = assertDefined(operands[0], "hierarchy requires an operand");
+
+    if (isValueOperand(inner)) {
+      return { type: "constant", segments: String(inner.value).split(".") };
+    }
+
+    if (isNamedOperand(inner)) {
+      return {
+        type: "field",
+        fieldRef: resolveFieldReference(inner.name, context),
+        delimiter: ".",
+      };
+    }
+
+    if (isOperatorOperand(inner) && inner.operator === "list") {
+      const segments = inner.operands.map((op): HierarchySegment => {
+        const resolved = resolveOperand(op, context);
+
+        if (isResolvedValue(resolved)) {
+          return { type: "constant", value: String(resolved.value) };
+        }
+
+        return { type: "field", fieldRef: resolved };
+      });
+
+      return { type: "segmented", segments };
+    }
+
+    throw new UnsupportedQueryPlanError("hierarchy requires a value, field, or list operand");
+  }
+
+  throw new UnsupportedQueryPlanError("hierarchy requires 1 or 2 operands");
+}
+
+/**
+ * Cerbos splits a path with Go's `strings.Split`: an empty delimiter yields one segment per code
+ * point, and an empty path then has no segments at all.
+ */
+function splitPath(path: string, delimiter: string): string[] {
+  return delimiter === "" ? Array.from(path) : path.split(delimiter);
+}
+
+function toSegments(resolved: ResolvedHierarchy): HierarchySegment[] {
+  switch (resolved.type) {
+    case "constant":
+      return resolved.segments.map((s) => ({ type: "constant" as const, value: s }));
+    case "segmented":
+      return resolved.segments;
+    case "field":
+      throw new UnsupportedQueryPlanError(
+        "Cannot get segments from a field-reference hierarchy"
+      );
+  }
+}
+
+/** A segmented hierarchy whose segments are all constants is a constant hierarchy. */
+function normalizeHierarchy(h: ResolvedHierarchy): ResolvedHierarchy {
+  if (h.type !== "segmented") return h;
+  const constants: string[] = [];
+
+  for (const segment of h.segments) {
+    if (segment.type !== "constant") return h;
+    constants.push(segment.value);
+  }
+
+  return { type: "constant", segments: constants };
+}
+
+function checkPrefixConditions(
+  shorter: HierarchySegment[],
+  longer: HierarchySegment[]
+): PrismaFilter | null {
+  if (shorter.length > longer.length) return null;
+
+  const conditions: PrismaFilter[] = [];
+
+  for (let i = 0; i < shorter.length; i++) {
+    const s = shorter[i]!;
+    const l = longer[i]!;
+
+    if (s.type === "constant" && l.type === "constant") {
+      if (s.value !== l.value) return null;
+    } else if (s.type === "field" && l.type === "constant") {
+      conditions.push(buildFieldFilter(s.fieldRef, "equals", l.value));
+    } else if (s.type === "constant" && l.type === "field") {
+      conditions.push(buildFieldFilter(l.fieldRef, "equals", s.value));
+    } else {
+      throw new UnsupportedQueryPlanError(
+        "Cannot compare two field references in hierarchy overlap"
+      );
+    }
+  }
+
+  if (conditions.length === 0) return {};
+
+  if (conditions.length === 1) return conditions[0]!;
+
+  return { AND: conditions };
+}
+
+export function handleOverlapsOperator(
+  operands: PlanExpressionOperand[],
+  context: TranslationContext,
+): PrismaFilter {
+  const [left, right] = extractHierarchyOperands("overlaps", operands, context);
+
+  if (left.type === "field" || right.type === "field") {
+    return handleFieldOverlaps(left, right);
+  }
+
+  const leftSegs = toSegments(left);
+  const rightSegs = toSegments(right);
+
+  const leftPrefixOfRight = checkPrefixConditions(leftSegs, rightSegs);
+  const rightPrefixOfLeft = checkPrefixConditions(rightSegs, leftSegs);
+
+  const validConditions = [leftPrefixOfRight, rightPrefixOfLeft].filter(
+    (c): c is PrismaFilter => c !== null
+  );
+
+  // Hierarchy construction evaluates every segment, including a trailing segment that
+  // neither prefix comparison needs. Preserve its SQL UNKNOWN under outer negation too.
+  const fields = [...leftSegs, ...rightSegs]
+    .filter((segment): segment is FieldSegment => segment.type === "field")
+    .filter((segment) => segment.fieldRef.nullable !== false);
+
+  const pairs = fields.map(({ fieldRef }) => ({
+    equal: buildFieldFilter(fieldRef, "equals", ""),
+    unequal: buildFieldFilter(fieldRef, "not", ""),
+  }));
+
+  const presence = pairs.map(({ equal, unequal }) => ({
+    OR: [equal, unequal],
+  }));
+
+  const unknown = pairs.map(({ equal, unequal }) => ({
+    AND: [equal, unequal],
+  }));
+
+  if (validConditions.length === 0) {
+    if (unknown.length > 0) return { OR: unknown };
+
+    const field = [...leftSegs, ...rightSegs].find(
+      (segment): segment is FieldSegment => segment.type === "field",
+    );
+
+    if (field) return buildImpossibleFilter(field.fieldRef);
+    throw new UnsupportedQueryPlanError("Cannot determine overlap: no field references found");
+  }
+
+  if (
+    validConditions.some((condition) => Object.keys(condition).length === 0)
+  ) {
+    return presence.length === 0 ? {} : { AND: presence };
+  }
+
+  // Equal-length comparisons are identical in either direction. A contradiction is
+  // FALSE for a present field and UNKNOWN for NULL, restoring errors even if the
+  // prefix comparison is FALSE (FALSE AND NULL alone would lose that error).
+  const condition = validConditions[0]!;
+
+  return presence.length === 0
+    ? condition
+    : {
+        OR: [{ AND: [condition, ...presence] }, ...unknown],
+      };
+}
+
+function handleFieldOverlaps(
+  left: ResolvedHierarchy,
+  right: ResolvedHierarchy
+): PrismaFilter {
+  if (left.type === "field" && right.type === "field") {
+    throw new UnsupportedQueryPlanError("overlaps: cannot compare two field-reference hierarchies");
+  }
+
+  // The caller routes here only when at least one side is a field hierarchy.
+  const field = left.type === "field" ? left : right.type === "field" ? right : undefined;
+
+  if (field === undefined) {
+    throw new UnsupportedQueryPlanError("overlaps: neither side is a field-reference hierarchy");
+  }
+
+  const other = field === left ? right : left;
+
+  if (other.type !== "constant") {
+    throw new UnsupportedQueryPlanError("overlaps: segmented hierarchies with field hierarchies are not supported");
+  }
+
+  const delimiter = field.delimiter;
+  const otherRaw = other.segments.join(delimiter);
+  const strictPrefixes = getStrictPrefixes(other.segments, delimiter);
+
+  const conditions: PrismaFilter[] = [];
+
+  if (strictPrefixes.length > 0) {
+    conditions.push(buildFieldFilter(field.fieldRef, "in", strictPrefixes));
+  }
+
+  conditions.push(buildFieldFilter(field.fieldRef, "equals", otherRaw));
+  conditions.push(buildPrefixFilter(field.fieldRef, otherRaw + delimiter));
+
+  return { OR: conditions };
+}
+
+function extractHierarchyOperands(
+  operatorName: string,
+  operands: PlanExpressionOperand[],
+  context: TranslationContext
+): [ResolvedHierarchy, ResolvedHierarchy] {
+  if (operands.length !== 2) {
+    throw new UnsupportedQueryPlanError(`${operatorName} requires exactly two operands`);
+  }
+
+  const leftOp = assertDefined(operands[0], `${operatorName} requires a left operand`);
+  const rightOp = assertDefined(operands[1], `${operatorName} requires a right operand`);
+
+  if (
+    !isOperatorOperand(leftOp) || leftOp.operator !== "hierarchy" ||
+    !isOperatorOperand(rightOp) || rightOp.operator !== "hierarchy"
+  ) {
+    throw new UnsupportedQueryPlanError(`${operatorName} requires two hierarchy operands`);
+  }
+
+  return [
+    normalizeHierarchy(resolveHierarchy(leftOp, context)),
+    normalizeHierarchy(resolveHierarchy(rightOp, context)),
+  ];
+}
+
+function getStrictPrefixes(segments: string[], delimiter: string): string[] {
+  if (delimiter === "") {
+    // Per code point, the empty path is itself a (zero-segment) strict prefix.
+    return segments.map((_, length) => segments.slice(0, length).join(""));
+  }
+
+  if (segments.length <= 1) return [];
+  const prefixes: string[] = [];
+  let current = segments[0]!;
+  prefixes.push(current);
+
+  for (let i = 1; i < segments.length - 1; i++) {
+    current = current + delimiter + segments[i]!;
+    prefixes.push(current);
+  }
+
+  return prefixes;
+}
+
+export function handleAncestorDescendantOperator(
+  operands: PlanExpressionOperand[],
+  context: TranslationContext,
+  direction: "ancestor" | "descendant",
+): PrismaFilter {
+  const operatorName = direction === "ancestor" ? "ancestorOf" : "descendentOf";
+  const [left, right] = extractHierarchyOperands(operatorName, operands, context);
+
+  // ancestorOf(A, B) = A is strict prefix of B
+  // descendentOf(A, B) = B is strict prefix of A
+  const ancestor = direction === "ancestor" ? left : right;
+  const descendant = direction === "ancestor" ? right : left;
+
+  if (ancestor.type === "field")
+    assertStringField(ancestor.fieldRef, operatorName);
+
+  if (descendant.type === "field")
+    assertStringField(descendant.fieldRef, operatorName);
+
+  if (ancestor.type === "constant" && descendant.type === "field") {
+    if (descendant.delimiter === "") {
+      // Per code point, a descendant is the ancestor followed by at least one more character.
+      return buildPrefixFilter(descendant.fieldRef, ancestor.segments.join(""), true);
+    }
+
+    return buildPrefixFilter(
+      descendant.fieldRef,
+      ancestor.segments.join(descendant.delimiter) + descendant.delimiter
+    );
+  }
+
+  if (ancestor.type === "field" && descendant.type === "constant") {
+    const delimiter = ancestor.delimiter;
+    const prefixes = getStrictPrefixes(descendant.segments, delimiter);
+
+    if (prefixes.length === 0) {
+      if (ancestor.fieldRef.nullable === false) return buildImpossibleFilter(ancestor.fieldRef);
+
+      return {
+        AND: [
+          buildFieldFilter(ancestor.fieldRef, "equals", ""),
+          buildFieldFilter(ancestor.fieldRef, "not", ""),
+        ],
+      };
+    }
+
+    if (prefixes.length === 1) {
+      return buildFieldFilter(ancestor.fieldRef, "equals", prefixes[0]!);
+    }
+
+    return buildFieldFilter(ancestor.fieldRef, "in", prefixes);
+  }
+
+  if (ancestor.type === "constant" && descendant.type === "constant") {
+    const ancestorSegs = ancestor.segments;
+    const descendantSegs = descendant.segments;
+
+    if (
+      descendantSegs.length > ancestorSegs.length &&
+      ancestorSegs.every((seg, i) => seg === descendantSegs[i])
+    ) {
+      return {};
+    }
+
+    throw new UnsupportedQueryPlanError(`${operatorName}: constants do not satisfy ${direction} relationship`);
+  }
+
+  throw new UnsupportedQueryPlanError(`${operatorName}: unsupported hierarchy type combination`);
+}