grafeo-ogm 2.1.1 → 2.3.0

package/dist/cjs/compilers/where.compiler.d.ts

@@ -1,6 +1,7 @@
 import type { OGMLogger } from '../execution/executor';
-import type { PolicyContextBundle } from '../policy/types';
+import type { Operation, PermissivePolicy, PolicyContextBundle, RestrictivePolicy } from '../policy/types';
 import { NodeDefinition, SchemaMetadata } from '../schema/types';
+import { CypherFieldScope } from '../utils/cypher-field-projection';
 export interface WhereResult {
     cypher: string;
     params: Record<string, unknown>;
@@ -17,6 +18,43 @@ export interface WhereResult {
      */
     preludes?: string[];
 }
+/**
+ * One resolved policy's compiled contribution to the policy clause.
+ * `parts` are its boolean fragments in emission order (the `when` part,
+ * then the `cypher` part) — exactly what `composePolicyClause` joins.
+ * Empty `parts` → the policy emitted no predicate: it abstained, or (for
+ * restrictives) it is write-side or gated off by `appliesWhen`.
+ */
+export interface CompiledPolicy {
+    readonly policy: PermissivePolicy | RestrictivePolicy;
+    readonly parts: ReadonlyArray<string>;
+}
+/**
+ * Per-policy compilation of one (typeName, op) frame. Positionally
+ * aligned with the bundle's `resolved.permissives` /
+ * `resolved.restrictives` — one entry per policy, in order.
+ */
+export interface CompiledPolicyFragments {
+    readonly permissives: ReadonlyArray<CompiledPolicy>;
+    readonly restrictives: ReadonlyArray<CompiledPolicy>;
+}
+/** Result of `WhereCompiler.compileForExplain` (explain path). */
+export interface ExplainWhereResult {
+    /** User where body only — the candidate filter. `''` when absent. */
+    userCypher: string;
+    /** User-where params followed by policy params (same as `compile()`). */
+    params: Record<string, unknown>;
+    /** Top-level `@cypher` preludes for BOTH the user where and policies. */
+    preludes: string[];
+    /**
+     * Root policy clause, or `null` when none applies (override fired).
+     * `clause` is byte-identical to what `compile()` AND-stitches.
+     */
+    policy: {
+        fragments: CompiledPolicyFragments;
+        clause: string;
+    } | null;
+}
 type OperatorSuffix = string;
 export interface WhereCompilerOptions {
     /** Set of operator suffixes to reject at runtime (e.g. `new Set(['_MATCHES'])`) */
@@ -73,17 +111,93 @@ export declare class WhereCompiler {
          * responsible for rejecting BEFORE compile — see `Model`.
          */
         policyContext?: PolicyContextBundle;
+        /**
+         * Caller-owned `@cypher` prelude scope (v2.3.0). When given, preludes
+         * register into it and are NOT returned — the caller emits the scope
+         * once, so several compiles against the same variable (a connection's
+         * node filter and its target policy) share one `CALL`/`WITH` chain.
+         * `preserveVars` is ignored (the scope already carries its own).
+         */
+        scope?: CypherFieldScope;
     }): WhereResult;
     /**
-     * Compile the policy clause for a single (typeName, op) frame. AND-
-     * stitches into the user's body via `stitchUserAndPolicy`. Shares the
-     * same `paramCounter` and `scope` as the user where so that nothing
-     * collides downstream.
+     * Explain-path twin of `compile()`, used by `Model.explainPolicies`.
+     * Compiles the user `where` EXACTLY as `compile()` does — same order,
+     * same `paramCounter`, same `@cypher` prelude scope, same policy-aware
+     * relationship traversal — but returns the root policy clause
+     * separately instead of AND-stitching it: as per-policy fragments AND
+     * as the composed string `compile()` would have stitched. Both come
+     * from one compilation, so an explanation cannot drift from
+     * enforcement.
+     *
+     * `policy` is `null` when no root policy clause applies (an override
+     * fired).
+     *
+     * @internal
+     */
+    compileForExplain(where: Record<string, unknown> | undefined | null, nodeVar: string, nodeDef: NodeDefinition, paramCounter: {
+        count: number;
+    }, policyContext: PolicyContextBundle): ExplainWhereResult;
+    /**
+     * The policy clause guarding a node of a possibly ABSTRACT type for one
+     * operation (v2.3.0) — the single construction behind every target-
+     * policy consumer (nested selection, traversal filters, nested writes)
+     * and `InterfaceModel`'s root clause:
+     *
+     *   - concrete type → its own composed clause for `op` (byte-identical
+     *     to compiling it directly); `null` when it has no policy for `op`
+     *     or an override fires.
+     *   - interface / union →
+     *       `(CASE WHEN v:M1 THEN <M1 clause> WHEN v:M2 THEN … ELSE false END)`
+     *     over the concrete members, each branch being exactly that member's
+     *     own clause (`resolveForType(M, op)` already folds in M's interface
+     *     policies). A member without a policy for `op`, or whose override
+     *     fires, is `true`; when EVERY member is `true` the result is `null`
+     *     (unconstrained, like a concrete type without policies). `ELSE false`
+     *     excludes a node carrying no known member label (defense in depth).
+     *
+     * Pre-2.3.0 abstract targets resolved the ABSTRACT type's name, so the
+     * implementers' own policies were never applied through relationships.
+     *
+     * `fallbackOp`: resolve it for a type with NO policy for `op` — the
+     * `aggregate` → `read` fallback `Model.aggregate` applies at the root.
+     *
+     * `preludes` (for `@cypher` fields referenced by a policy) are returned
+     * to the caller; nested contexts reject them.
+     *
+     * @internal
+     */
+    compileTargetPolicyClause(typeName: string, varName: string, op: Operation, policyContext: PolicyContextBundle, paramCounter: {
+        count: number;
+    }, fallbackOp?: Operation): {
+        cypher: string | null;
+        params: Record<string, unknown>;
+        preludes: string[];
+    };
+    private compileConcreteTargetClause;
+    /** Concrete members of an interface / union; `null` for any other type. */
+    private abstractMembers;
+    /**
+     * Shared body of `compile()` / `compileForExplain()`: compiles the user
+     * where, then the policy fragments, sharing one `paramCounter` and one
+     * top-level `@cypher` scope. Returns `null` when there is nothing to
+     * compile (no user where and no active policy).
+     */
+    private compileUserAndPolicy;
+    /**
+     * Compile each resolved policy of a single (typeName, op) frame into
+     * its boolean fragments ("parts"), WITHOUT combining them —
+     * `composePolicyClause` does that. Shares the same `paramCounter` and
+     * `scope` as the user where so that nothing collides downstream.
+     *
+     * The result is positionally aligned with `resolved.permissives` /
+     * `resolved.restrictives`: one entry per policy, in order, even when a
+     * policy contributes no part.
      *
      * Permissive `cypher.params` keys are namespaced with `policy_p<n>_`
      * to guarantee no collision with `param0..N`.
      */
-    private compilePolicyClause;
+    private compilePolicyFragments;
     /**
      * Build a `PolicyContextBundle` for a target type when crossing a
      * node-type boundary inside a relationship traversal (`_SOME` /
@@ -99,6 +213,36 @@ export declare class WhereCompiler {
      * nesting (target → target's relationship → ...) keeps cascading.
      */
     private buildTargetBundle;
+    /**
+     * Compile a traversal's filter against its target node with the
+     * caller's filter (`user`) and the target's `read` policy (`policy`)
+     * kept SEPARATE, so each quantifier composes them correctly — the
+     * policy must never sit inside a negation (v2.3.0). Pre-2.3.0 the policy
+     * was compiled INTO the filter, so `_ALL` (`NOT (user AND policy)`) was
+     * falsified by hidden related nodes (an existence oracle), and a
+     * connection `node_NOT` was SATISFIED by them.
+     *
+     *   - no policy context → plain compile.
+     *   - concrete target → one `compileUserAndPolicy` pass (shared `@cypher`
+     *     prelude scope); the bundle cascades as `NO_ROOT_POLICY` at any depth.
+     *   - interface target → filter via a `NO_ROOT_POLICY` traversal bundle,
+     *     policy via `compileTargetPolicyClause` (CASE over the members'
+     *     own clauses — pre-2.3.0 only the interface's own policies ran).
+     *
+     * `''` for an absent part. With `scope`, concrete-target preludes
+     * register into it (caller emits); otherwise they are returned.
+     * Shared with `SelectionCompiler`'s nested-projection filters.
+     *
+     * @internal
+     */
+    compileTargetBody(where: Record<string, unknown> | undefined | null, targetVar: string, targetDef: NodeDefinition, counter: {
+        count: number;
+    }, policyContext: PolicyContextBundle | undefined, scope?: CypherFieldScope): {
+        user: string;
+        policy: string;
+        params: Record<string, unknown>;
+        preludes: string[];
+    };
     private compileConditions;
     /**
      * Resolve the Cypher reference for a where-clause field. For stored
@@ -129,6 +273,37 @@ export declare class WhereCompiler {
      * Multiple members are combined with OR.
      */
     private compileUnionRelationship;
+    /**
+     * Compile `<key>: null` on a node (v2.3.0). The operator suffix is split
+     * off FIRST: pre-2.3.0 the whole key was treated as a property name, so
+     * the common "is not null" idiom `{ deletedAt_NOT: null }` compiled to
+     * `n.deletedAt_NOT IS NULL` — always true, silently matching every row
+     * (and silently restricting nothing when used in a restrictive policy).
+     *
+     *   field: null          → field IS NULL
+     *   field_NOT: null      → field IS NOT NULL
+     *   rel: null            → NOT EXISTS { MATCH (n)-[:REL]->(…) }
+     *   rel_NOT: null        → EXISTS { MATCH (n)-[:REL]->(…) }
+     *   any other operator   → OGMError (null has no meaning there)
+     *   undeclared field     → OGMError regardless of `strictWhere` — a null
+     *                          filter on an undeclared field matches every
+     *                          row (fail OPEN), unlike a non-null one
+     *
+     * A field literally named `key` always wins over suffix parsing.
+     */
+    private compileNullCondition;
+    /**
+     * Scalar half of the null semantics above, shared by node properties and
+     * relationship-edge properties: `IS NULL` / `IS NOT NULL`, or an
+     * `OGMError` for any other operator and for undeclared fields.
+     */
+    private compileNullScalar;
+    /**
+     * `NOT EXISTS` (no related node) / `EXISTS` (at least one) for a
+     * relationship null filter. Byte-identical to the pre-2.3.0 `rel: null`
+     * emission for the `NOT EXISTS` case.
+     */
+    private compileRelationshipExistence;
     private compileEdgeConditions;
     /**
      * Compile a scalar where-condition. If `fieldName` resolves to a
@@ -139,5 +314,30 @@ export declare class WhereCompiler {
      */
     private compileScalarCondition;
 }
+/**
+ * Stitch a user where-body and a policy clause into a single Cypher
+ * fragment. Both come from `compileConditions` so each is already a
+ * valid boolean expression. Empty user bodies skip the AND wrap.
+ */
+export declare function stitchUserAndPolicy(userBody: string, policyClause: string): string;
+/**
+ * The bundle a traversal's USER filter compiles under (v2.3.0): no clause
+ * for the target itself (its policy is composed separately by the caller),
+ * but `resolveForType` stays live so deeper traversals keep enforcing.
+ *
+ * @internal
+ */
+export declare function traversalBundle(policyContext: PolicyContextBundle): PolicyContextBundle;
+/**
+ * The boolean value ONE compiled policy contributes to
+ * `composePolicyClause`, as a standalone expression (explain path): a
+ * permissive's parts are OR-ed — they join the permissive disjunction —
+ * and a restrictive's parts are AND-ed — they join the restrictive
+ * conjunction. OR/AND are associative in Cypher's three-valued logic,
+ * so grouping per policy preserves the composed clause's truth value.
+ *
+ * Returns `null` when the policy has no parts (it abstained).
+ */
+export declare function policyValueExpression(kind: 'permissive' | 'restrictive', parts: ReadonlyArray<string>): string | null;
 export {};
 //# sourceMappingURL=where.compiler.d.ts.map

package/dist/cjs/compilers/where.compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"where.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/where.compiler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EACL,cAAc,EAGd,cAAc,EACf,MAAM,iBAAiB,CAAC;AAiBzB,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAqDD,KAAK,cAAc,GAAG,MAAM,CAAC;AA4B7B,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACxC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,MAAM,CAAC,CAAY;gBAGjB,MAAM,EAAE,cAAc,EAC9B,OAAO,CAAC,EAAE,oBAAoB;IAOhC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CACL,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EACjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,YAAY,GAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAiB,EAC9C,OAAO,CAAC,EAAE;QACR;;;;;WAKG;QACH,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QACrC;;;;;;;;;;WAUG;QACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;KACrC,GACA,WAAW;IAoDd;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IA6K3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,iBAAiB;IAsNzB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,oBAAoB;IA0I5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,2BAA2B;IAsKnC,OAAO,CAAC,sBAAsB;IAsK9B;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAyKhC,OAAO,CAAC,qBAAqB;IA8B7B;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;CA0G/B"}
+{"version":3,"file":"where.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/where.compiler.ts"],"names":[],"mappings":"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"}