grafeo-ogm 2.2.0 → 2.3.0

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

@@ -1,6 +1,7 @@
 import type { OGMLogger } from '../execution/executor';
-import type { PermissivePolicy, PolicyContextBundle, RestrictivePolicy } 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>;
@@ -110,6 +111,14 @@ 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;
     /**
      * Explain-path twin of `compile()`, used by `Model.explainPolicies`.
@@ -129,6 +138,45 @@ export declare class WhereCompiler {
     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
@@ -165,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
@@ -195,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
@@ -205,6 +314,20 @@ 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

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":"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"}
+{"version":3,"file":"where.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/where.compiler.ts"],"names":[],"mappings":"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"}