@open-aih/payload-ddb 3.1.0 → 4.1.0

package/dist/utilities/backfillUniqueGuards.d.ts

@@ -0,0 +1,42 @@
+import type { Payload } from 'payload';
+/**
+ * One-shot pass that creates unique-field guard rows for documents written
+ * before the adapter enforced `unique: true`.
+ *
+ * Guards are created as documents are written, so a document that hasn't
+ * been touched since upgrading holds its unique values without a guard — a
+ * new document could still take the same value. Running this once closes
+ * that gap: it walks every collection that declares unique fields and claims
+ * a guard for each value each document holds.
+ *
+ * Safe to re-run; claiming a guard the document already owns is a no-op.
+ *
+ * Existing duplicates can't both be guarded. The first document reached
+ * keeps the value and the others are listed under `conflicts` — fix those by
+ * hand (change or clear the duplicated value) and run the pass again.
+ *
+ * @example
+ *   import { getPayload } from 'payload'
+ *   import config from './payload.config'
+ *   import { backfillUniqueGuards } from '@aih-software/payload-ddb'
+ *
+ *   const payload = await getPayload({ config })
+ *   const report = await backfillUniqueGuards(payload)
+ *   console.log(JSON.stringify(report, null, 2))
+ *   await payload.destroy()
+ */
+export interface UniqueBackfillReport {
+    collections: Record<string, {
+        /** Values another document already holds a guard for. */
+        conflicts: {
+            heldBy: string;
+            id: unknown;
+            path: string;
+        }[];
+        /** Guards this pass created or confirmed. */
+        guarded: number;
+        scanned: number;
+    }>;
+}
+export declare function backfillUniqueGuards(payload: Payload): Promise<UniqueBackfillReport>;
+//# sourceMappingURL=backfillUniqueGuards.d.ts.map

package/dist/utilities/backfillUniqueGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfillUniqueGuards.d.ts","sourceRoot":"","sources":["../../src/utilities/backfillUniqueGuards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAStC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CACjB,MAAM,EACN;QACE,yDAAyD;QACzD,SAAS,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;QAC1D,6CAA6C;QAC7C,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;KAChB,CACF,CAAA;CACF;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA+B1F"}

package/dist/utilities/backfillUniqueGuards.js

@@ -0,0 +1,39 @@
+import { mapWithConcurrency } from './mapWithConcurrency.js';
+import { queryMatching } from './queryMatching.js';
+import { hasUniqueFields, uniqueGuardsFor } from './uniqueGuards.js';
+import { claimGuard, WRITE_CONCURRENCY } from './writeItems.js';
+export async function backfillUniqueGuards(payload) {
+    const adapter = payload.db;
+    if (!adapter.docClient) {
+        throw new Error('payload-ddb: backfillUniqueGuards requires a connected adapter.');
+    }
+    const report = {
+        collections: {}
+    };
+    for (const slug of Object.keys(adapter.payload?.collections ?? {})){
+        if (!hasUniqueFields(adapter, slug)) continue;
+        const partition = adapter.resolvePartition(slug);
+        const entry = {
+            conflicts: [],
+            guarded: 0,
+            scanned: 0
+        };
+        report.collections[slug] = entry;
+        const rows = await queryMatching(adapter, partition, undefined);
+        await mapWithConcurrency(rows, WRITE_CONCURRENCY, async (row)=>{
+            entry.scanned++;
+            for (const guard of uniqueGuardsFor(adapter, slug, partition, row)){
+                const heldBy = await claimGuard(adapter, guard, String(row['id']));
+                if (heldBy === null) entry.guarded++;
+                else entry.conflicts.push({
+                    heldBy,
+                    id: row['id'],
+                    path: guard.path
+                });
+            }
+        });
+    }
+    return report;
+}
+
+//# sourceMappingURL=backfillUniqueGuards.js.map

package/dist/utilities/backfillUniqueGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utilities/backfillUniqueGuards.ts"],"sourcesContent":["import type { Payload } from 'payload'\n\nimport type { DynamoAdapter } from '../types.js'\n\nimport { mapWithConcurrency } from './mapWithConcurrency.js'\nimport { queryMatching } from './queryMatching.js'\nimport { hasUniqueFields, uniqueGuardsFor } from './uniqueGuards.js'\nimport { claimGuard, WRITE_CONCURRENCY } from './writeItems.js'\n\n/**\n * One-shot pass that creates unique-field guard rows for documents written\n * before the adapter enforced `unique: true`.\n *\n * Guards are created as documents are written, so a document that hasn't\n * been touched since upgrading holds its unique values without a guard — a\n * new document could still take the same value. Running this once closes\n * that gap: it walks every collection that declares unique fields and claims\n * a guard for each value each document holds.\n *\n * Safe to re-run; claiming a guard the document already owns is a no-op.\n *\n * Existing duplicates can't both be guarded. The first document reached\n * keeps the value and the others are listed under `conflicts` — fix those by\n * hand (change or clear the duplicated value) and run the pass again.\n *\n * @example\n *   import { getPayload } from 'payload'\n *   import config from './payload.config'\n *   import { backfillUniqueGuards } from '@aih-software/payload-ddb'\n *\n *   const payload = await getPayload({ config })\n *   const report = await backfillUniqueGuards(payload)\n *   console.log(JSON.stringify(report, null, 2))\n *   await payload.destroy()\n */\nexport interface UniqueBackfillReport {\n  collections: Record<\n    string,\n    {\n      /** Values another document already holds a guard for. */\n      conflicts: { heldBy: string; id: unknown; path: string }[]\n      /** Guards this pass created or confirmed. */\n      guarded: number\n      scanned: number\n    }\n  >\n}\n\nexport async function backfillUniqueGuards(payload: Payload): Promise<UniqueBackfillReport> {\n  const adapter = payload.db as DynamoAdapter\n  if (!adapter.docClient) {\n    throw new Error('payload-ddb: backfillUniqueGuards requires a connected adapter.')\n  }\n\n  const report: UniqueBackfillReport = { collections: {} }\n\n  for (const slug of Object.keys(adapter.payload?.collections ?? {})) {\n    if (!hasUniqueFields(adapter, slug)) continue\n\n    const partition = adapter.resolvePartition(slug)\n    const entry: UniqueBackfillReport['collections'][string] = {\n      conflicts: [],\n      guarded: 0,\n      scanned: 0,\n    }\n    report.collections[slug] = entry\n\n    const rows = await queryMatching(adapter, partition, undefined)\n    await mapWithConcurrency(rows, WRITE_CONCURRENCY, async (row) => {\n      entry.scanned++\n      for (const guard of uniqueGuardsFor(adapter, slug, partition, row)) {\n        const heldBy = await claimGuard(adapter, guard, String(row['id']))\n        if (heldBy === null) entry.guarded++\n        else entry.conflicts.push({ heldBy, id: row['id'], path: guard.path })\n      }\n    })\n  }\n\n  return report\n}\n"],"names":["mapWithConcurrency","queryMatching","hasUniqueFields","uniqueGuardsFor","claimGuard","WRITE_CONCURRENCY","backfillUniqueGuards","payload","adapter","db","docClient","Error","report","collections","slug","Object","keys","partition","resolvePartition","entry","conflicts","guarded","scanned","rows","undefined","row","guard","heldBy","String","push","id","path"],"mappings":"AAIA,SAASA,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,aAAa,QAAQ,qBAAoB;AAClD,SAASC,eAAe,EAAEC,eAAe,QAAQ,oBAAmB;AACpE,SAASC,UAAU,EAAEC,iBAAiB,QAAQ,kBAAiB;AAyC/D,OAAO,eAAeC,qBAAqBC,OAAgB;IACzD,MAAMC,UAAUD,QAAQE,EAAE;IAC1B,IAAI,CAACD,QAAQE,SAAS,EAAE;QACtB,MAAM,IAAIC,MAAM;IAClB;IAEA,MAAMC,SAA+B;QAAEC,aAAa,CAAC;IAAE;IAEvD,KAAK,MAAMC,QAAQC,OAAOC,IAAI,CAACR,QAAQD,OAAO,EAAEM,eAAe,CAAC,GAAI;QAClE,IAAI,CAACX,gBAAgBM,SAASM,OAAO;QAErC,MAAMG,YAAYT,QAAQU,gBAAgB,CAACJ;QAC3C,MAAMK,QAAqD;YACzDC,WAAW,EAAE;YACbC,SAAS;YACTC,SAAS;QACX;QACAV,OAAOC,WAAW,CAACC,KAAK,GAAGK;QAE3B,MAAMI,OAAO,MAAMtB,cAAcO,SAASS,WAAWO;QACrD,MAAMxB,mBAAmBuB,MAAMlB,mBAAmB,OAAOoB;YACvDN,MAAMG,OAAO;YACb,KAAK,MAAMI,SAASvB,gBAAgBK,SAASM,MAAMG,WAAWQ,KAAM;gBAClE,MAAME,SAAS,MAAMvB,WAAWI,SAASkB,OAAOE,OAAOH,GAAG,CAAC,KAAK;gBAChE,IAAIE,WAAW,MAAMR,MAAME,OAAO;qBAC7BF,MAAMC,SAAS,CAACS,IAAI,CAAC;oBAAEF;oBAAQG,IAAIL,GAAG,CAAC,KAAK;oBAAEM,MAAML,MAAMK,IAAI;gBAAC;YACtE;QACF;IACF;IAEA,OAAOnB;AACT"}

package/dist/utilities/buildFilterExpression.d.ts

@@ -3,16 +3,23 @@ import type { Where } from 'payload';
  * Compile a Payload `Where` into a DynamoDB `FilterExpression` plus its
  * companion `ExpressionAttributeNames` / `ExpressionAttributeValues` maps.
  *
- * Return contract:
- *  - `undefined` — no filter to apply (empty/missing `where`, or only no-op
- *    clauses like `and: []`). Callers should query without a filter.
- *  - `null` — the predicate is structurally always-false (e.g. an empty
- *    `id: { in: [] }`). Callers should short-circuit and return zero rows
- *    without ever hitting DynamoDB. Payload uses empty `in` as a "match
- *    nothing" sentinel (typically from access control resolving to no IDs);
- *    surfacing it as a filter would mean throwing or constructing an
- *    invalid `IN ()` clause.
- *  - `FilterExpression` — actual predicate to push down.
+ * The result is a *prefilter*: it never rejects a row the `where` accepts,
+ * but it may let through rows the `where` rejects. `exact` says which:
+ *
+ *  - `exact: true` — the filter (or its absence) is the whole `where`; rows
+ *    DynamoDB returns need no further checking.
+ *  - `exact: false` — some clause couldn't be expressed (a JS-only operator
+ *    such as `like`, or a path `castWhere` marked as running through an
+ *    array). That clause is left out, so callers must re-check every
+ *    returned row with `matchesWhere`. Everything that *could* be expressed
+ *    still narrows the read server-side.
+ *
+ * `never: true` means the predicate is structurally always-false (e.g. an
+ * empty `id: { in: [] }`). Callers should short-circuit and return zero rows
+ * without ever hitting DynamoDB. Payload uses empty `in` as a "match
+ * nothing" sentinel (typically from access control resolving to no IDs);
+ * surfacing it as a filter would mean throwing or constructing an invalid
+ * `IN ()` clause.
  *
  * Throws on any operator outside `operators.ts`'s supported set, identical
  * to `matchesWhere` — coverage is enforced from one source so the in-JS
@@ -27,9 +34,12 @@ import type { Where } from 'payload';
  *    keeps the expression readable.
  *  - Dotted paths in `where` keys are split on `.` so DynamoDB document-path
  *    syntax (`#a.#b`) is produced for nested fields.
- *  - `in: []` propagates a NEVER sentinel through the AND/OR algebra:
- *    AND with NEVER → NEVER (whole result `null`); OR with NEVER drops the
- *    NEVER branch; an OR whose every branch is NEVER itself becomes NEVER.
+ *  - A clause compiles to an expression string, to `''` (always true — no
+ *    constraint), or to the NEVER sentinel (always false). AND drops `''`
+ *    and collapses to NEVER if any part is NEVER; OR drops NEVER branches
+ *    and collapses to `''` if any branch is `''`. An inexpressible clause
+ *    compiles to `''` and clears `exact`, which keeps the result a superset
+ *    under both AND and OR.
  *  - `not_in: []` is treated as no constraint (the complement of an empty
  *    set is everything, so omitting it from the expression matches semantics).
  */
@@ -38,5 +48,10 @@ export type FilterExpression = {
     names: Record<string, string>;
     values: Record<string, unknown>;
 };
-export declare function buildFilterExpression(where: undefined | Where): FilterExpression | null | undefined;
+export type CompiledFilter = {
+    exact: boolean;
+    filter?: FilterExpression;
+    never: boolean;
+};
+export declare function buildFilterExpression(where: undefined | Where): CompiledFilter;
 //# sourceMappingURL=buildFilterExpression.d.ts.map

package/dist/utilities/buildFilterExpression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildFilterExpression.d.ts","sourceRoot":"","sources":["../../src/utilities/buildFilterExpression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAKpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC,CAAA;AAaD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,GAAG,KAAK,GACvB,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAoBrC"}
+{"version":3,"file":"buildFilterExpression.d.ts","sourceRoot":"","sources":["../../src/utilities/buildFilterExpression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAUpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,gBAAgB,CAAA;IACzB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAcD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,GAAG,cAAc,CAyB9E"}

package/dist/utilities/buildFilterExpression.js

@@ -1,9 +1,13 @@
 import { normalizeForDynamo } from './normalizeForDynamo.js';
-import { SUPPORTED_OPERATORS, unsupportedOperatorError } from './operators.js';
+import { JS_ONLY_MARKER, JS_ONLY_OPERATORS, SUPPORTED_OPERATORS, unsupportedOperatorError } from './operators.js';
 const NEVER = Symbol('payload-ddb-filter-never');
 export function buildFilterExpression(where) {
-    if (!where) return undefined;
+    if (!where) return {
+        exact: true,
+        never: false
+    };
     const ctx = {
+        exact: true,
         nameByPlaceholder: {},
         nameCounter: 0,
         placeholderBySegment: new Map(),
@@ -11,14 +15,38 @@ export function buildFilterExpression(where) {
         values: {}
     };
     const expression = compile(where, ctx);
-    if (expression === NEVER) return null;
-    if (!expression) return undefined;
+    if (expression === NEVER) return {
+        exact: true,
+        never: true
+    };
+    if (!expression) return {
+        exact: ctx.exact,
+        never: false
+    };
     return {
-        expression,
-        names: ctx.nameByPlaceholder,
-        values: ctx.values
+        exact: ctx.exact,
+        filter: {
+            expression,
+            names: onlyReferenced(ctx.nameByPlaceholder, expression, /#n\d+/g),
+            values: onlyReferenced(ctx.values, expression, /:v\d+/g)
+        },
+        never: false
     };
 }
+/**
+ * DynamoDB rejects a request that declares an expression name or value the
+ * expression never uses. Placeholders get registered as clauses compile, but
+ * a clause can still end up contributing nothing (a skipped JS-only
+ * operator, `not_in: []`, a branch dropped from an OR), so keep only what
+ * the final expression references.
+ */ function onlyReferenced(registered, expression, pattern) {
+    const used = new Set(expression.match(pattern) ?? []);
+    const out = {};
+    for (const [placeholder, value] of Object.entries(registered)){
+        if (used.has(placeholder)) out[placeholder] = value;
+    }
+    return out;
+}
 function compile(where, ctx) {
     const parts = [];
     for (const [key, raw] of Object.entries(where)){
@@ -35,12 +63,20 @@ function compile(where, ctx) {
             continue;
         }
         if (!raw || typeof raw !== 'object') continue;
-        const path = pathRef(ctx, key);
         const operators = raw;
+        // `castWhere` marks clauses whose path can't be a DynamoDB document path
+        // (it runs through an array). Leave the whole clause to `matchesWhere`.
+        const pathIsJsOnly = JS_ONLY_MARKER in operators;
+        const path = pathIsJsOnly ? '' : pathRef(ctx, key);
         for (const [operator, expected] of Object.entries(operators)){
+            if (operator === JS_ONLY_MARKER) continue;
             if (!SUPPORTED_OPERATORS.has(operator)) {
                 throw unsupportedOperatorError(operator, key);
             }
+            if (pathIsJsOnly || JS_ONLY_OPERATORS.has(operator)) {
+                ctx.exact = false;
+                continue;
+            }
             const expr = operatorToExpression(operator, path, expected, ctx);
             if (expr === NEVER) return NEVER;
             if (expr) parts.push(expr);
@@ -64,6 +100,9 @@ function compileGroup(raw, ctx, joiner) {
             neverCount++;
             continue;
         }
+        // An unconstrained branch makes the whole OR unconstrained. (Dropping it
+        // and keeping the others would narrow the result.)
+        if (!expr && joiner === 'OR') return '';
         if (expr) subs.push(expr);
     }
     // OR over branches that all collapsed to NEVER is NEVER itself.
@@ -109,12 +148,14 @@ function operatorToExpression(operator, path, expected, ctx) {
         case 'less_than_equal':
             return `${path} <= ${valueRef(ctx, expected)}`;
         case 'exists':
-            return expected ? `attribute_exists(${path})` : `attribute_not_exists(${path})`;
-        case 'like':
-            // JS-only: `whereHasJsOnlyOperator` should have steered the helpers
-            // away from compiling this `where` server-side. Returning '' is a
-            // belt-and-braces no-op in case a caller compiles directly.
-            return '';
+            {
+                // "Exists" means "holds a non-null value", same as `matchesWhere`.
+                // Payload writes `null` when a field is cleared and DynamoDB stores
+                // that as a real attribute of type NULL, so `attribute_exists` alone
+                // would report a cleared field as present.
+                const nullType = valueRef(ctx, 'NULL');
+                return expected ? `(attribute_exists(${path}) AND NOT attribute_type(${path}, ${nullType}))` : `(attribute_not_exists(${path}) OR attribute_type(${path}, ${nullType}))`;
+            }
         case 'in':
             {
                 if (!Array.isArray(expected)) return '';

package/dist/utilities/buildFilterExpression.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utilities/buildFilterExpression.ts"],"sourcesContent":["import type { Where } from 'payload'\n\nimport { normalizeForDynamo } from './normalizeForDynamo.js'\nimport { SUPPORTED_OPERATORS, unsupportedOperatorError } from './operators.js'\n\n/**\n * Compile a Payload `Where` into a DynamoDB `FilterExpression` plus its\n * companion `ExpressionAttributeNames` / `ExpressionAttributeValues` maps.\n *\n * Return contract:\n *  - `undefined` — no filter to apply (empty/missing `where`, or only no-op\n *    clauses like `and: []`). Callers should query without a filter.\n *  - `null` — the predicate is structurally always-false (e.g. an empty\n *    `id: { in: [] }`). Callers should short-circuit and return zero rows\n *    without ever hitting DynamoDB. Payload uses empty `in` as a \"match\n *    nothing\" sentinel (typically from access control resolving to no IDs);\n *    surfacing it as a filter would mean throwing or constructing an\n *    invalid `IN ()` clause.\n *  - `FilterExpression` — actual predicate to push down.\n *\n * Throws on any operator outside `operators.ts`'s supported set, identical\n * to `matchesWhere` — coverage is enforced from one source so the in-JS\n * path and the pushdown path can never disagree.\n *\n * Implementation notes:\n *  - Every field path segment becomes an `#nN` placeholder, sidestepping\n *    DynamoDB's reserved-word list entirely. Segments are deduped per-call so\n *    repeated fields produce one `#name` entry rather than many.\n *  - Every value becomes a `:vN` placeholder. We don't dedupe values because\n *    array members and repeated literals are cheap and the placeholder count\n *    keeps the expression readable.\n *  - Dotted paths in `where` keys are split on `.` so DynamoDB document-path\n *    syntax (`#a.#b`) is produced for nested fields.\n *  - `in: []` propagates a NEVER sentinel through the AND/OR algebra:\n *    AND with NEVER → NEVER (whole result `null`); OR with NEVER drops the\n *    NEVER branch; an OR whose every branch is NEVER itself becomes NEVER.\n *  - `not_in: []` is treated as no constraint (the complement of an empty\n *    set is everything, so omitting it from the expression matches semantics).\n */\nexport type FilterExpression = {\n  expression: string\n  names: Record<string, string>\n  values: Record<string, unknown>\n}\n\nconst NEVER = Symbol('payload-ddb-filter-never')\ntype Compiled = string | typeof NEVER\n\ntype Ctx = {\n  nameByPlaceholder: Record<string, string>\n  nameCounter: number\n  placeholderBySegment: Map<string, string>\n  valueCounter: number\n  values: Record<string, unknown>\n}\n\nexport function buildFilterExpression(\n  where: undefined | Where,\n): FilterExpression | null | undefined {\n  if (!where) return undefined\n\n  const ctx: Ctx = {\n    nameByPlaceholder: {},\n    nameCounter: 0,\n    placeholderBySegment: new Map(),\n    valueCounter: 0,\n    values: {},\n  }\n\n  const expression = compile(where, ctx)\n  if (expression === NEVER) return null\n  if (!expression) return undefined\n\n  return {\n    expression,\n    names: ctx.nameByPlaceholder,\n    values: ctx.values,\n  }\n}\n\nfunction compile(where: Where, ctx: Ctx): Compiled {\n  const parts: string[] = []\n\n  for (const [key, raw] of Object.entries(where)) {\n    if (key === 'and') {\n      const inner = compileGroup(raw, ctx, 'AND')\n      if (inner === NEVER) return NEVER\n      if (inner) parts.push(inner)\n      continue\n    }\n    if (key === 'or') {\n      const inner = compileGroup(raw, ctx, 'OR')\n      if (inner === NEVER) return NEVER\n      if (inner) parts.push(inner)\n      continue\n    }\n\n    if (!raw || typeof raw !== 'object') continue\n\n    const path = pathRef(ctx, key)\n    const operators = raw as Record<string, unknown>\n\n    for (const [operator, expected] of Object.entries(operators)) {\n      if (!SUPPORTED_OPERATORS.has(operator)) {\n        throw unsupportedOperatorError(operator, key)\n      }\n      const expr = operatorToExpression(operator, path, expected, ctx)\n      if (expr === NEVER) return NEVER\n      if (expr) parts.push(expr)\n    }\n  }\n\n  if (parts.length === 0) return ''\n  if (parts.length === 1) return parts[0]!\n  return parts.join(' AND ')\n}\n\nfunction compileGroup(raw: unknown, ctx: Ctx, joiner: 'AND' | 'OR'): Compiled {\n  if (!Array.isArray(raw)) return ''\n  const subs: string[] = []\n  let neverCount = 0\n  let consideredCount = 0\n  for (const sub of raw) {\n    if (!sub || typeof sub !== 'object') continue\n    consideredCount++\n    const expr = compile(sub as Where, ctx)\n    if (expr === NEVER) {\n      if (joiner === 'AND') return NEVER\n      neverCount++\n      continue\n    }\n    if (expr) subs.push(expr)\n  }\n  // OR over branches that all collapsed to NEVER is NEVER itself.\n  if (joiner === 'OR' && consideredCount > 0 && neverCount === consideredCount) {\n    return NEVER\n  }\n  if (subs.length === 0) return ''\n  if (subs.length === 1) return subs[0]!\n  return `(${subs.join(` ${joiner} `)})`\n}\n\nfunction pathRef(ctx: Ctx, path: string): string {\n  return path\n    .split('.')\n    .map((segment) => segmentRef(ctx, segment))\n    .join('.')\n}\n\nfunction segmentRef(ctx: Ctx, segment: string): string {\n  const cached = ctx.placeholderBySegment.get(segment)\n  if (cached) return cached\n  const placeholder = `#n${ctx.nameCounter++}`\n  ctx.nameByPlaceholder[placeholder] = segment\n  ctx.placeholderBySegment.set(segment, placeholder)\n  return placeholder\n}\n\nfunction valueRef(ctx: Ctx, value: unknown): string {\n  const placeholder = `:v${ctx.valueCounter++}`\n  // Normalize so Date literals in `where` compare against the ISO strings we\n  // actually stored. Without this, `{ updatedAt: { greater_than: new Date() } }`\n  // would push an empty map literal into the filter and DynamoDB would reject\n  // the comparison.\n  ctx.values[placeholder] = normalizeForDynamo(value)\n  return placeholder\n}\n\nfunction operatorToExpression(\n  operator: string,\n  path: string,\n  expected: unknown,\n  ctx: Ctx,\n): Compiled {\n  switch (operator) {\n    case 'equals':\n      return `${path} = ${valueRef(ctx, expected)}`\n    case 'not_equals':\n      return `${path} <> ${valueRef(ctx, expected)}`\n    case 'greater_than':\n      return `${path} > ${valueRef(ctx, expected)}`\n    case 'greater_than_equal':\n      return `${path} >= ${valueRef(ctx, expected)}`\n    case 'less_than':\n      return `${path} < ${valueRef(ctx, expected)}`\n    case 'less_than_equal':\n      return `${path} <= ${valueRef(ctx, expected)}`\n    case 'exists':\n      return expected ? `attribute_exists(${path})` : `attribute_not_exists(${path})`\n    case 'like':\n      // JS-only: `whereHasJsOnlyOperator` should have steered the helpers\n      // away from compiling this `where` server-side. Returning '' is a\n      // belt-and-braces no-op in case a caller compiles directly.\n      return ''\n    case 'in': {\n      if (!Array.isArray(expected)) return ''\n      if (expected.length === 0) return NEVER\n      const refs = expected.map((v) => valueRef(ctx, v))\n      return `${path} IN (${refs.join(', ')})`\n    }\n    case 'not_in': {\n      if (!Array.isArray(expected) || expected.length === 0) return ''\n      const refs = expected.map((v) => valueRef(ctx, v))\n      return `NOT (${path} IN (${refs.join(', ')}))`\n    }\n    default:\n      // Unreachable — gated by SUPPORTED_OPERATORS check above. Belt-and-braces.\n      throw unsupportedOperatorError(operator, path)\n  }\n}\n"],"names":["normalizeForDynamo","SUPPORTED_OPERATORS","unsupportedOperatorError","NEVER","Symbol","buildFilterExpression","where","undefined","ctx","nameByPlaceholder","nameCounter","placeholderBySegment","Map","valueCounter","values","expression","compile","names","parts","key","raw","Object","entries","inner","compileGroup","push","path","pathRef","operators","operator","expected","has","expr","operatorToExpression","length","join","joiner","Array","isArray","subs","neverCount","consideredCount","sub","split","map","segment","segmentRef","cached","get","placeholder","set","valueRef","value","refs","v"],"mappings":"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"}
+{"version":3,"sources":["../../src/utilities/buildFilterExpression.ts"],"sourcesContent":["import type { Where } from 'payload'\n\nimport { normalizeForDynamo } from './normalizeForDynamo.js'\nimport {\n  JS_ONLY_MARKER,\n  JS_ONLY_OPERATORS,\n  SUPPORTED_OPERATORS,\n  unsupportedOperatorError,\n} from './operators.js'\n\n/**\n * Compile a Payload `Where` into a DynamoDB `FilterExpression` plus its\n * companion `ExpressionAttributeNames` / `ExpressionAttributeValues` maps.\n *\n * The result is a *prefilter*: it never rejects a row the `where` accepts,\n * but it may let through rows the `where` rejects. `exact` says which:\n *\n *  - `exact: true` — the filter (or its absence) is the whole `where`; rows\n *    DynamoDB returns need no further checking.\n *  - `exact: false` — some clause couldn't be expressed (a JS-only operator\n *    such as `like`, or a path `castWhere` marked as running through an\n *    array). That clause is left out, so callers must re-check every\n *    returned row with `matchesWhere`. Everything that *could* be expressed\n *    still narrows the read server-side.\n *\n * `never: true` means the predicate is structurally always-false (e.g. an\n * empty `id: { in: [] }`). Callers should short-circuit and return zero rows\n * without ever hitting DynamoDB. Payload uses empty `in` as a \"match\n * nothing\" sentinel (typically from access control resolving to no IDs);\n * surfacing it as a filter would mean throwing or constructing an invalid\n * `IN ()` clause.\n *\n * Throws on any operator outside `operators.ts`'s supported set, identical\n * to `matchesWhere` — coverage is enforced from one source so the in-JS\n * path and the pushdown path can never disagree.\n *\n * Implementation notes:\n *  - Every field path segment becomes an `#nN` placeholder, sidestepping\n *    DynamoDB's reserved-word list entirely. Segments are deduped per-call so\n *    repeated fields produce one `#name` entry rather than many.\n *  - Every value becomes a `:vN` placeholder. We don't dedupe values because\n *    array members and repeated literals are cheap and the placeholder count\n *    keeps the expression readable.\n *  - Dotted paths in `where` keys are split on `.` so DynamoDB document-path\n *    syntax (`#a.#b`) is produced for nested fields.\n *  - A clause compiles to an expression string, to `''` (always true — no\n *    constraint), or to the NEVER sentinel (always false). AND drops `''`\n *    and collapses to NEVER if any part is NEVER; OR drops NEVER branches\n *    and collapses to `''` if any branch is `''`. An inexpressible clause\n *    compiles to `''` and clears `exact`, which keeps the result a superset\n *    under both AND and OR.\n *  - `not_in: []` is treated as no constraint (the complement of an empty\n *    set is everything, so omitting it from the expression matches semantics).\n */\nexport type FilterExpression = {\n  expression: string\n  names: Record<string, string>\n  values: Record<string, unknown>\n}\n\nexport type CompiledFilter = {\n  exact: boolean\n  filter?: FilterExpression\n  never: boolean\n}\n\nconst NEVER = Symbol('payload-ddb-filter-never')\ntype Compiled = string | typeof NEVER\n\ntype Ctx = {\n  exact: boolean\n  nameByPlaceholder: Record<string, string>\n  nameCounter: number\n  placeholderBySegment: Map<string, string>\n  valueCounter: number\n  values: Record<string, unknown>\n}\n\nexport function buildFilterExpression(where: undefined | Where): CompiledFilter {\n  if (!where) return { exact: true, never: false }\n\n  const ctx: Ctx = {\n    exact: true,\n    nameByPlaceholder: {},\n    nameCounter: 0,\n    placeholderBySegment: new Map(),\n    valueCounter: 0,\n    values: {},\n  }\n\n  const expression = compile(where, ctx)\n  if (expression === NEVER) return { exact: true, never: true }\n  if (!expression) return { exact: ctx.exact, never: false }\n\n  return {\n    exact: ctx.exact,\n    filter: {\n      expression,\n      names: onlyReferenced(ctx.nameByPlaceholder, expression, /#n\\d+/g),\n      values: onlyReferenced(ctx.values, expression, /:v\\d+/g),\n    },\n    never: false,\n  }\n}\n\n/**\n * DynamoDB rejects a request that declares an expression name or value the\n * expression never uses. Placeholders get registered as clauses compile, but\n * a clause can still end up contributing nothing (a skipped JS-only\n * operator, `not_in: []`, a branch dropped from an OR), so keep only what\n * the final expression references.\n */\nfunction onlyReferenced<T>(\n  registered: Record<string, T>,\n  expression: string,\n  pattern: RegExp,\n): Record<string, T> {\n  const used = new Set(expression.match(pattern) ?? [])\n  const out: Record<string, T> = {}\n  for (const [placeholder, value] of Object.entries(registered)) {\n    if (used.has(placeholder)) out[placeholder] = value\n  }\n  return out\n}\n\nfunction compile(where: Where, ctx: Ctx): Compiled {\n  const parts: string[] = []\n\n  for (const [key, raw] of Object.entries(where)) {\n    if (key === 'and') {\n      const inner = compileGroup(raw, ctx, 'AND')\n      if (inner === NEVER) return NEVER\n      if (inner) parts.push(inner)\n      continue\n    }\n    if (key === 'or') {\n      const inner = compileGroup(raw, ctx, 'OR')\n      if (inner === NEVER) return NEVER\n      if (inner) parts.push(inner)\n      continue\n    }\n\n    if (!raw || typeof raw !== 'object') continue\n\n    const operators = raw as Record<string, unknown>\n    // `castWhere` marks clauses whose path can't be a DynamoDB document path\n    // (it runs through an array). Leave the whole clause to `matchesWhere`.\n    const pathIsJsOnly = JS_ONLY_MARKER in operators\n    const path = pathIsJsOnly ? '' : pathRef(ctx, key)\n\n    for (const [operator, expected] of Object.entries(operators)) {\n      if (operator === JS_ONLY_MARKER) continue\n      if (!SUPPORTED_OPERATORS.has(operator)) {\n        throw unsupportedOperatorError(operator, key)\n      }\n      if (pathIsJsOnly || JS_ONLY_OPERATORS.has(operator)) {\n        ctx.exact = false\n        continue\n      }\n      const expr = operatorToExpression(operator, path, expected, ctx)\n      if (expr === NEVER) return NEVER\n      if (expr) parts.push(expr)\n    }\n  }\n\n  if (parts.length === 0) return ''\n  if (parts.length === 1) return parts[0]!\n  return parts.join(' AND ')\n}\n\nfunction compileGroup(raw: unknown, ctx: Ctx, joiner: 'AND' | 'OR'): Compiled {\n  if (!Array.isArray(raw)) return ''\n  const subs: string[] = []\n  let neverCount = 0\n  let consideredCount = 0\n  for (const sub of raw) {\n    if (!sub || typeof sub !== 'object') continue\n    consideredCount++\n    const expr = compile(sub as Where, ctx)\n    if (expr === NEVER) {\n      if (joiner === 'AND') return NEVER\n      neverCount++\n      continue\n    }\n    // An unconstrained branch makes the whole OR unconstrained. (Dropping it\n    // and keeping the others would narrow the result.)\n    if (!expr && joiner === 'OR') return ''\n    if (expr) subs.push(expr)\n  }\n  // OR over branches that all collapsed to NEVER is NEVER itself.\n  if (joiner === 'OR' && consideredCount > 0 && neverCount === consideredCount) {\n    return NEVER\n  }\n  if (subs.length === 0) return ''\n  if (subs.length === 1) return subs[0]!\n  return `(${subs.join(` ${joiner} `)})`\n}\n\nfunction pathRef(ctx: Ctx, path: string): string {\n  return path\n    .split('.')\n    .map((segment) => segmentRef(ctx, segment))\n    .join('.')\n}\n\nfunction segmentRef(ctx: Ctx, segment: string): string {\n  const cached = ctx.placeholderBySegment.get(segment)\n  if (cached) return cached\n  const placeholder = `#n${ctx.nameCounter++}`\n  ctx.nameByPlaceholder[placeholder] = segment\n  ctx.placeholderBySegment.set(segment, placeholder)\n  return placeholder\n}\n\nfunction valueRef(ctx: Ctx, value: unknown): string {\n  const placeholder = `:v${ctx.valueCounter++}`\n  // Normalize so Date literals in `where` compare against the ISO strings we\n  // actually stored. Without this, `{ updatedAt: { greater_than: new Date() } }`\n  // would push an empty map literal into the filter and DynamoDB would reject\n  // the comparison.\n  ctx.values[placeholder] = normalizeForDynamo(value)\n  return placeholder\n}\n\nfunction operatorToExpression(\n  operator: string,\n  path: string,\n  expected: unknown,\n  ctx: Ctx,\n): Compiled {\n  switch (operator) {\n    case 'equals':\n      return `${path} = ${valueRef(ctx, expected)}`\n    case 'not_equals':\n      return `${path} <> ${valueRef(ctx, expected)}`\n    case 'greater_than':\n      return `${path} > ${valueRef(ctx, expected)}`\n    case 'greater_than_equal':\n      return `${path} >= ${valueRef(ctx, expected)}`\n    case 'less_than':\n      return `${path} < ${valueRef(ctx, expected)}`\n    case 'less_than_equal':\n      return `${path} <= ${valueRef(ctx, expected)}`\n    case 'exists': {\n      // \"Exists\" means \"holds a non-null value\", same as `matchesWhere`.\n      // Payload writes `null` when a field is cleared and DynamoDB stores\n      // that as a real attribute of type NULL, so `attribute_exists` alone\n      // would report a cleared field as present.\n      const nullType = valueRef(ctx, 'NULL')\n      return expected\n        ? `(attribute_exists(${path}) AND NOT attribute_type(${path}, ${nullType}))`\n        : `(attribute_not_exists(${path}) OR attribute_type(${path}, ${nullType}))`\n    }\n    case 'in': {\n      if (!Array.isArray(expected)) return ''\n      if (expected.length === 0) return NEVER\n      const refs = expected.map((v) => valueRef(ctx, v))\n      return `${path} IN (${refs.join(', ')})`\n    }\n    case 'not_in': {\n      if (!Array.isArray(expected) || expected.length === 0) return ''\n      const refs = expected.map((v) => valueRef(ctx, v))\n      return `NOT (${path} IN (${refs.join(', ')}))`\n    }\n    default:\n      // Unreachable — gated by SUPPORTED_OPERATORS check above. Belt-and-braces.\n      throw unsupportedOperatorError(operator, path)\n  }\n}\n"],"names":["normalizeForDynamo","JS_ONLY_MARKER","JS_ONLY_OPERATORS","SUPPORTED_OPERATORS","unsupportedOperatorError","NEVER","Symbol","buildFilterExpression","where","exact","never","ctx","nameByPlaceholder","nameCounter","placeholderBySegment","Map","valueCounter","values","expression","compile","filter","names","onlyReferenced","registered","pattern","used","Set","match","out","placeholder","value","Object","entries","has","parts","key","raw","inner","compileGroup","push","operators","pathIsJsOnly","path","pathRef","operator","expected","expr","operatorToExpression","length","join","joiner","Array","isArray","subs","neverCount","consideredCount","sub","split","map","segment","segmentRef","cached","get","set","valueRef","nullType","refs","v"],"mappings":"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"}

package/dist/utilities/castWhere.d.ts

@@ -0,0 +1,84 @@
+import type { FlattenedField, Where } from 'payload';
+/**
+ * Rewrite a Payload `Where` into the terms the stored rows are in, before
+ * either evaluator (`buildFilterExpression` or `matchesWhere`) sees it. Three
+ * things happen per clause, all driven by the field the path points at:
+ *
+ * **Operands are cast** to the type the field stores. They routinely arrive
+ * as strings: the REST API parses `?where[price][greater_than]=10` with
+ * `qs`, which yields `"10"`, and the admin list filters go the same way.
+ * Mongoose and SQL drivers quietly coerce those against their schema.
+ * DynamoDB has no schema and compares strictly by type — `"10"` never equals
+ * or orders against the number `10` — so without this such a filter matches
+ * nothing and reports no error. The rules follow Payload's Mongo and
+ * Postgres adapters (`sanitizeQueryValue`), minus their database quirks:
+ *
+ *  - `checkbox`: `'true'` / `'false'` (any case) → boolean.
+ *  - `number`: numeric strings → number.
+ *  - `date`: parseable strings, epoch-ms numbers and `Date`s → the full ISO
+ *    string we store. `'2026-01-01'` must become `'2026-01-01T00:00:00.000Z'`
+ *    or it would compare as a mere prefix of the stored value.
+ *  - `relationship` / `upload`: `'null'` → `null`; ids → number when the
+ *    related collection has numeric ids, including inside a polymorphic
+ *    `{ relationTo, value }` operand.
+ *  - `id`: → number when this collection has numeric ids.
+ *  - `in` / `not_in` / `all`: a comma-delimited string → array, each member
+ *    cast.
+ *  - `exists`: operand → boolean (`'false'` is a truthy string otherwise),
+ *    and for fields that can hold text, an empty string counts as absent —
+ *    that's what the admin UI leaves behind when a text input is cleared.
+ *  - `contains` on a `hasMany` select or a relationship means "has this
+ *    value", so it becomes `equals` / `in`.
+ *
+ * **Localized paths get their locale key.** A localized field is stored as
+ * `{ en: …, es: … }`, so `title` becomes `title.en` for the request's locale
+ * (unless the caller already wrote a locale into the path).
+ *
+ * **Paths DynamoDB can't address are marked** with `JS_ONLY_MARKER`: any that
+ * run through an `array` / `blocks` field or a `hasMany` value, or into a
+ * field whose inner shape the schema doesn't describe (`json`, rich text).
+ * The pushdown skips those clauses; `matchesWhere` evaluates them with
+ * any-element semantics.
+ *
+ * Anything it can't confidently cast is left exactly as given: an unknown
+ * path, a path that continues past a leaf field, an unparseable value.
+ *
+ * Returns a new `Where`; the caller's object is never mutated.
+ */
+export type IdType = 'number' | 'text';
+export type Localization = {
+    /** Locale to address when a path doesn't name one. */
+    locale: string;
+    localeCodes: string[];
+};
+export type CastContext = {
+    /** Flattened fields of the entity the `where` targets. */
+    fields: FlattenedField[];
+    /** Type of the entity's own `id` when it isn't declared as a field. */
+    idType: IdType;
+    /** Id type of another collection, for relationship operands. */
+    idTypeOf: (collectionSlug: string) => IdType;
+    /** Set only when the Payload config has localization enabled. */
+    localization?: Localization;
+};
+export declare function castWhere(where: undefined | Where, ctx: CastContext): undefined | Where;
+export type ResolvedPath = {
+    /** The field the path ends on, when the schema describes it. */
+    field: FlattenedField | null;
+    /** True when DynamoDB can't address the path as one value. */
+    multi: boolean;
+    /** The path as stored: locale keys inserted after localized segments. */
+    path: string;
+};
+/**
+ * Walk a dotted path through groups, named tabs, arrays and blocks to the
+ * field it names, noting on the way whether it crosses anything list-shaped
+ * and where locale keys belong.
+ *
+ * `field` is `null` when the path leaves the declared schema — an unknown
+ * name, or a path that continues past a field with no sub-fields (a
+ * polymorphic relationship's `.value`, a key inside `json`), where guessing
+ * a type would be wrong.
+ */
+export declare function resolvePath(fields: FlattenedField[], path: string, localization?: Localization): ResolvedPath;
+//# sourceMappingURL=castWhere.d.ts.map

package/dist/utilities/castWhere.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"castWhere.d.ts","sourceRoot":"","sources":["../../src/utilities/castWhere.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAOpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEtC,MAAM,MAAM,YAAY,GAAG;IACzB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,0DAA0D;IAC1D,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAA;IAC5C,iEAAiE;IACjE,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAaD,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,KAAK,CAoFvF;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,gEAAgE;IAChE,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;IAC5B,8DAA8D;IAC9D,KAAK,EAAE,OAAO,CAAA;IACd,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EAAE,EACxB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,YAAY,GAC1B,YAAY,CAwDd"}