@byline/core 1.3.0 → 1.4.0

package/dist/query/parse-where.d.ts

@@ -75,6 +75,13 @@ declare const DOCUMENT_SORT_COLUMNS: Record<string, string>;
  * are resolved into `RelationFilter` entries; otherwise only
  * direct/operator predicates against the relation's own
  * `target_document_id` are emitted.
+ *
+ * Reserved-key rules inside a nested sub-clause: `status` and `path`
+ * downshift to `DocumentColumnFilter` entries against the target
+ * version's `document_versions` columns (the adapter wires these to
+ * `td${depth}.status` / `td${depth}.path` via the inner relation scope);
+ * `query` is dropped with a debug log because text search has no
+ * sensible composition through a relation hop.
  */
 export declare function parseWhere(where: WhereClause | undefined, definition: CollectionDefinition, ctx?: ParseContext): Promise<ParsedWhere>;
 /**

package/dist/query/parse-where.js

@@ -31,6 +31,13 @@ const DOCUMENT_SORT_COLUMNS = {
  * are resolved into `RelationFilter` entries; otherwise only
  * direct/operator predicates against the relation's own
  * `target_document_id` are emitted.
+ *
+ * Reserved-key rules inside a nested sub-clause: `status` and `path`
+ * downshift to `DocumentColumnFilter` entries against the target
+ * version's `document_versions` columns (the adapter wires these to
+ * `td${depth}.status` / `td${depth}.path` via the inner relation scope);
+ * `query` is dropped with a debug log because text search has no
+ * sensible composition through a relation hop.
  */
 export async function parseWhere(where, definition, ctx) {
     return parseWhereInternal(where, definition, ctx, { isNested: false, inCombinator: false });
@@ -57,10 +64,15 @@ export function mergePredicates(hookPredicate, userWhere) {
     return { $and: [hookPredicate, userWhere] };
 }
 /**
- * Recursion entry point. `isNested: true` disables the top-level reserved
- * keys (`status`, `query`, `path`) so that on a nested sub-where, those
- * names resolve as ordinary fields on the target collection (where `path`
- * and `status` are typically real text fields).
+ * Recursion entry point. `isNested: true` rewires the document-level
+ * reserved keys: `status` / `path` downshift to `DocumentColumnFilter`
+ * entries against the target version's columns (the adapter resolves
+ * those via the inner relation scope, e.g. `td${depth}.status`); `query`
+ * is dropped with a debug log because text search has no sensible
+ * composition through a relation hop. Reserved keys still take precedence
+ * over field lookups — a target collection that happens to declare a
+ * `path` or `status` field will not see those clauses resolve as field
+ * filters; rename the offending field if that conflict matters.
  */
 async function parseWhereInternal(where, definition, ctx, { isNested, inCombinator }) {
     const result = { filters: [] };
@@ -134,65 +146,82 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
             continue;
         }
         // --- Document-level reserved keys --------------------------------------
-        // At the top level (not nested in a relation, not inside a combinator)
-        // these keys map to direct adapter scalar parameters
-        // (`ParsedWhere.status` / `query` / `pathFilter`) which compile to the
-        // outermost WHERE clause. Inside a combinator that mapping no longer
-        // composes — the predicate needs to OR with siblings, which the scalar
-        // parameter form cannot express — so `status` / `path` downshift to a
-        // `DocumentColumnFilter` and `query` is dropped (text search has no
-        // sensible OR-composing form here).
-        if (!isNested) {
-            if (key === 'status') {
-                if (inCombinator) {
-                    const parsed = normaliseToOperator(rawValue);
-                    if (parsed) {
-                        result.filters.push({
-                            kind: 'docColumn',
-                            column: 'status',
-                            operator: parsed.operator,
-                            value: parsed.value === null ? null : String(parsed.value),
-                        });
-                    }
-                    continue;
-                }
-                if (typeof rawValue === 'string') {
-                    result.status = rawValue;
+        // `status` / `path` / `query` are reserved on every collection — they
+        // never resolve to a field of the same name (no field-shadow exception),
+        // mirroring the consumer-intuitive rule that these names refer to the
+        // document version's metadata columns.
+        //
+        // Where they compile depends on scope:
+        //
+        //   • Top level (not nested in a relation, not inside a combinator):
+        //     map to direct adapter scalar parameters
+        //     (`ParsedWhere.status` / `query` / `pathFilter`) which compile to
+        //     the outermost WHERE clause.
+        //
+        //   • Inside a combinator, OR inside a relation sub-clause: the scalar-
+        //     parameter mapping no longer composes (the predicate needs to OR
+        //     with siblings, or anchor against the *target's* doc version), so
+        //     `status` / `path` downshift to a `DocumentColumnFilter`. The SQL
+        //     compiler reads `outerScope.status` / `outerScope.path`, which the
+        //     adapter rewires per-scope (`d.path` at the top level,
+        //     `td${depth}.path` inside a relation hop).
+        //
+        //   • `query` is dropped with a debug log in both downshift cases —
+        //     text search has no sensible OR-composing form, and a per-target
+        //     EXISTS over `store_text` is intentionally deferred.
+        if (key === 'status') {
+            if (isNested || inCombinator) {
+                const parsed = normaliseToOperator(rawValue);
+                if (parsed) {
+                    result.filters.push({
+                        kind: 'docColumn',
+                        column: 'status',
+                        operator: parsed.operator,
+                        value: parsed.value === null ? null : String(parsed.value),
+                    });
                 }
                 continue;
             }
-            if (key === 'query') {
-                if (inCombinator) {
-                    ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a combinator — text search does not compose with OR/AND');
-                    continue;
-                }
-                if (typeof rawValue === 'string') {
-                    result.query = rawValue;
-                }
+            if (typeof rawValue === 'string') {
+                result.status = rawValue;
+            }
+            continue;
+        }
+        if (key === 'query') {
+            if (isNested) {
+                ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a relation sub-clause — text search does not compose through a relation hop');
                 continue;
             }
-            if (key === 'path') {
-                if (inCombinator) {
-                    const parsed = normaliseToOperator(rawValue);
-                    if (parsed) {
-                        result.filters.push({
-                            kind: 'docColumn',
-                            column: 'path',
-                            operator: parsed.operator,
-                            value: parsed.value === null ? null : String(parsed.value),
-                        });
-                    }
-                    continue;
-                }
+            if (inCombinator) {
+                ctx?.logger?.debug({ collection: definition.path }, 'parse-where: dropping `query` inside a combinator — text search does not compose with OR/AND');
+                continue;
+            }
+            if (typeof rawValue === 'string') {
+                result.query = rawValue;
+            }
+            continue;
+        }
+        if (key === 'path') {
+            if (isNested || inCombinator) {
                 const parsed = normaliseToOperator(rawValue);
                 if (parsed) {
-                    result.pathFilter = {
+                    result.filters.push({
+                        kind: 'docColumn',
+                        column: 'path',
                         operator: parsed.operator,
-                        value: String(parsed.value),
-                    };
+                        value: parsed.value === null ? null : String(parsed.value),
+                    });
                 }
                 continue;
             }
+            const parsed = normaliseToOperator(rawValue);
+            if (parsed) {
+                result.pathFilter = {
+                    operator: parsed.operator,
+                    value: String(parsed.value),
+                };
+            }
+            continue;
         }
         // --- Field-level keys --------------------------------------------------
         const field = definition.fields.find((f) => f.name === key);
@@ -226,11 +255,11 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                 isNested: true,
                 inCombinator: false,
             });
-            // Flatten nested: only field-level / relation-level conditions make
-            // sense inside a relation subclause. Document-level keys (status,
-            // path, query) on the target are deliberately out of scope for this
-            // first phase — they can be added later by promoting them into
-            // the nested filter list here.
+            // Splice nested filters straight in. The nested parse runs with
+            // `isNested: true`, which promotes `status` / `path` into
+            // `DocumentColumnFilter` entries the adapter resolves against the
+            // target version's columns (`td${depth}.status` / `td${depth}.path`)
+            // via the inner relation scope. `query` is dropped one level up.
             result.filters.push({
                 kind: 'relation',
                 fieldName: key,

package/dist/query/parse-where.test.node.js

@@ -40,7 +40,11 @@ const categoriesCollection = defineCollection({
     }),
     fields: [
         { name: 'name', type: 'text', label: 'Name', localized: true },
-        { name: 'path', type: 'text', label: 'Path' },
+        // `slug`, not `path` — `path` is a reserved key that resolves to the
+        // target version's `document_versions.path` column inside a nested
+        // sub-clause (same precedence as the top level), so a real `path`
+        // field would be unreachable through the where clause.
+        { name: 'slug', type: 'text', label: 'Slug' },
         {
             name: 'parent',
             type: 'relation',
@@ -220,8 +224,8 @@ describe('parseWhere', () => {
             value: ['cat-a', 'cat-b'],
         });
     });
-    it('should emit a RelationFilter for a nested plain-object sub-where', async () => {
-        const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
+    it('should emit a RelationFilter for a nested plain-object sub-where (field key)', async () => {
+        const result = await parseWhere({ category: { slug: 'news' } }, testCollection, ctx);
         expect(result.filters).toHaveLength(1);
         expect(result.filters[0]).toEqual({
             kind: 'relation',
@@ -230,7 +234,7 @@ describe('parseWhere', () => {
             nested: [
                 {
                     kind: 'field',
-                    fieldName: 'path',
+                    fieldName: 'slug',
                     storeType: 'text',
                     valueColumn: 'value',
                     operator: '$eq',
@@ -239,6 +243,55 @@ describe('parseWhere', () => {
             ],
         });
     });
+    it('promotes `path` inside a nested sub-where to a DocumentColumnFilter', async () => {
+        // Reserved-key precedence: `path` inside a relation sub-clause maps to
+        // the target version's `document_versions.path` column, never to a
+        // field of the same name. The adapter wires it to `td${depth}.path`
+        // via the inner relation scope.
+        const result = await parseWhere({ category: { path: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'category',
+            targetCollectionId: 'id-test-categories',
+            nested: [
+                {
+                    kind: 'docColumn',
+                    column: 'path',
+                    operator: '$eq',
+                    value: 'news',
+                },
+            ],
+        });
+    });
+    it('promotes `status` inside a nested sub-where to a DocumentColumnFilter', async () => {
+        const result = await parseWhere({ category: { status: 'draft' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toEqual({
+            kind: 'relation',
+            fieldName: 'category',
+            targetCollectionId: 'id-test-categories',
+            nested: [
+                {
+                    kind: 'docColumn',
+                    column: 'status',
+                    operator: '$eq',
+                    value: 'draft',
+                },
+            ],
+        });
+    });
+    it('drops `query` inside a nested sub-where (no nested filter emitted)', async () => {
+        // Same rationale as `query` inside a combinator: text search has no
+        // sensible composition through a relation hop.
+        const result = await parseWhere({ category: { query: 'news' } }, testCollection, ctx);
+        expect(result.filters).toHaveLength(1);
+        const relation = result.filters[0];
+        expect(relation?.kind).toBe('relation');
+        if (relation?.kind !== 'relation')
+            return;
+        expect(relation.nested).toEqual([]);
+    });
     it('should support operator objects inside a nested sub-where', async () => {
         const result = await parseWhere({ category: { name: { $contains: 'news' } } }, testCollection, ctx);
         const relation = result.filters[0];
@@ -257,7 +310,7 @@ describe('parseWhere', () => {
         ]);
     });
     it('should recurse into multi-hop relation sub-wheres', async () => {
-        const result = await parseWhere({ category: { parent: { path: 'news' } } }, testCollection, ctx);
+        const result = await parseWhere({ category: { parent: { slug: 'news' } } }, testCollection, ctx);
         const top = result.filters[0];
         expect(top?.kind).toBe('relation');
         if (top?.kind !== 'relation')
@@ -274,7 +327,7 @@ describe('parseWhere', () => {
         expect(inner.nested).toEqual([
             {
                 kind: 'field',
-                fieldName: 'path',
+                fieldName: 'slug',
                 storeType: 'text',
                 valueColumn: 'value',
                 operator: '$eq',
@@ -282,6 +335,26 @@ describe('parseWhere', () => {
             },
         ]);
     });
+    it('recurses multi-hop with the doc-column form (target.path at depth 2)', async () => {
+        const result = await parseWhere({ category: { parent: { path: 'news' } } }, testCollection, ctx);
+        const top = result.filters[0];
+        expect(top?.kind).toBe('relation');
+        if (top?.kind !== 'relation')
+            return;
+        expect(top.nested).toHaveLength(1);
+        const inner = top.nested[0];
+        expect(inner?.kind).toBe('relation');
+        if (inner?.kind !== 'relation')
+            return;
+        expect(inner.nested).toEqual([
+            {
+                kind: 'docColumn',
+                column: 'path',
+                operator: '$eq',
+                value: 'news',
+            },
+        ]);
+    });
     it('should skip nested sub-where when ctx is not provided', async () => {
         const result = await parseWhere({ category: { path: 'news' } }, testCollection);
         expect(result.filters).toEqual([]);
@@ -526,6 +599,11 @@ describe('parseWhere — combinators', () => {
         expect(result.filters).toEqual([]);
     });
     it('parses combinators inside a nested relation sub-where', async () => {
+        // Inside the nested sub-where: `name` is a real field on the target
+        // (resolves to a FieldFilter) and `path` is a reserved key that
+        // downshifts to a `DocumentColumnFilter` against the target version's
+        // path column. Inside an `$or` either side composes — the OR is
+        // emitted as a CombinatorFilter wrapping both children.
         const result = await parseWhere({
             category: {
                 $or: [{ name: 'News' }, { path: 'announcements' }],
@@ -541,7 +619,7 @@ describe('parseWhere — combinators', () => {
             kind: 'or',
             children: [
                 { kind: 'field', fieldName: 'name' },
-                { kind: 'field', fieldName: 'path' },
+                { kind: 'docColumn', column: 'path', operator: '$eq', value: 'announcements' },
             ],
         });
     });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=20.9.0"
   },