@byline/core 2.5.1 → 2.5.2

package/dist/@types/db-types.d.ts

@@ -120,23 +120,35 @@ export interface CombinatorFilter {
     children: DocumentFilter[];
 }
 /**
- * A predicate over a document-version column (`status`, `path`). Distinct
- * from `FieldFilter` — these columns live on `document_versions` itself,
- * not on the EAV stores, so they compile to a direct outer-scope column
- * comparison rather than an `EXISTS` subquery.
+ * A predicate over a document-version column (`status`, `path`, `id`).
+ * Distinct from `FieldFilter` — these columns live on `document_versions`
+ * itself (or the current-documents view), not on the EAV stores, so they
+ * compile to a direct outer-scope column comparison rather than an `EXISTS`
+ * subquery.
  *
- * Produced by `parse-where` when `status` / `path` appear *inside* a
- * combinator (`$or` / `$and` child). At the top level the same keys are
- * intercepted as reserved keys on `ParsedWhere.status` / `ParsedWhere.pathFilter`
- * because they map to direct adapter parameters there; inside a
- * combinator that mapping no longer makes sense (you can't OR-combine
- * with the outer scalar parameter), so they downshift to this filter.
+ * Produced by `parse-where` for two reasons:
+ *
+ *   - `status` / `path` appearing *inside* a combinator (`$or` / `$and`
+ *     child) or inside a relation sub-clause. At the top level the same
+ *     keys are intercepted as `ParsedWhere.status` / `ParsedWhere.pathFilter`
+ *     because they map to direct adapter parameters there; inside a
+ *     combinator that mapping no longer makes sense (you can't OR-combine
+ *     with the outer scalar parameter), so they downshift to this filter.
+ *
+ *   - `id` at *any* scope. Unlike `status` (single equality, used in many
+ *     non-filter call sites) and `path` (needs the `pathProjection` join
+ *     against `byline_document_paths`), `id` is a plain column on the
+ *     current-documents view comparable directly at every scope. Skipping
+ *     a top-level scalar form keeps the surface area small.
+ *
+ * `value` is widened beyond `string | null` so the `$in` / `$nin` operators
+ * (the headline use case for `id`) can carry array operands.
  */
 export interface DocumentColumnFilter {
     kind: 'docColumn';
-    column: 'status' | 'path';
+    column: 'status' | 'path' | 'id';
     operator: FieldFilterOperator;
-    value: string | null;
+    value: string | number | boolean | null | Array<string | number>;
 }
 /**
  * Any filter that can appear in a `findDocuments` call — a direct field

package/dist/query/parse-where.js

@@ -10,7 +10,7 @@ import { fieldTypeToStore } from '../storage/field-store-map.js';
 // Document-level reserved keys
 // ---------------------------------------------------------------------------
 /** Where clause keys that map to document-level columns, not EAV stores. */
-const DOCUMENT_LEVEL_KEYS = new Set(['status', 'path', 'query']);
+const DOCUMENT_LEVEL_KEYS = new Set(['status', 'path', 'query', 'id']);
 // ---------------------------------------------------------------------------
 // Document-level sort columns
 // ---------------------------------------------------------------------------
@@ -225,6 +225,26 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
             }
             continue;
         }
+        // `id` always downshifts to a `DocumentColumnFilter` — no top-level
+        // scalar form. Unlike `status` (single equality, used in many non-filter
+        // call sites) and `path` (needs the `pathProjection` join), `id` is a
+        // plain column on the current-documents view comparable directly at any
+        // scope. Unifying all three scopes through the same downshift keeps the
+        // surface area small. Note: the value is passed through verbatim — we
+        // don't `String(...)` it the way status/path do, because the headline
+        // use case is `$in` / `$nin` carrying an array of document ids.
+        if (key === 'id') {
+            const parsed = normaliseToOperator(rawValue);
+            if (parsed) {
+                result.filters.push({
+                    kind: 'docColumn',
+                    column: 'id',
+                    operator: parsed.operator,
+                    value: parsed.value,
+                });
+            }
+            continue;
+        }
         // --- Field-level keys --------------------------------------------------
         const field = definition.fields.find((f) => f.name === key);
         if (!field)

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

@@ -625,6 +625,65 @@ describe('parseWhere — combinators', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// parseWhere — `id` reserved key
+// ---------------------------------------------------------------------------
+//
+// `id` is the logical document id (`document_id` on the current-documents
+// view). It is reserved at every scope and always downshifts to a
+// `DocumentColumnFilter` — no top-level scalar form like `status` /
+// `pathFilter`, because `id` is a plain column comparable directly.
+describe('parseWhere — `id` reserved key', () => {
+    it('emits a docColumn filter for a bare top-level `id` value', async () => {
+        const result = await parseWhere({ id: 'doc-123' }, testCollection);
+        expect(result.filters).toEqual([
+            { kind: 'docColumn', column: 'id', operator: '$eq', value: 'doc-123' },
+        ]);
+    });
+    it('emits a docColumn filter with array value for top-level `id: { $in }`', async () => {
+        // The headline use case — batch lookup by a list of document ids.
+        // Value passes through verbatim (no `String(...)` coercion) so the
+        // array survives to the adapter's `$in` SQL builder.
+        const ids = ['doc-1', 'doc-2', 'doc-3'];
+        const result = await parseWhere({ id: { $in: ids } }, testCollection);
+        expect(result.filters).toEqual([
+            { kind: 'docColumn', column: 'id', operator: '$in', value: ids },
+        ]);
+    });
+    it('emits a docColumn filter for `id` inside an $or combinator', async () => {
+        const result = await parseWhere({ $or: [{ id: 'doc-a' }, { id: 'doc-b' }] }, testCollection);
+        expect(result.filters).toHaveLength(1);
+        expect(result.filters[0]).toMatchObject({
+            kind: 'or',
+            children: [
+                { kind: 'docColumn', column: 'id', operator: '$eq', value: 'doc-a' },
+                { kind: 'docColumn', column: 'id', operator: '$eq', value: 'doc-b' },
+            ],
+        });
+    });
+    it('emits a docColumn filter for `id` inside a nested relation sub-where', async () => {
+        // Reserved-key precedence — same as `status` / `path`: inside a
+        // relation hop, `id` refers to the target version's document_id, not
+        // a field of the same name.
+        const result = await parseWhere({ category: { id: 'cat-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: 'id', operator: '$eq', value: 'cat-news' }],
+        });
+    });
+    it('does NOT populate any top-level scalar slot for `id`', async () => {
+        // Sanity: unlike status / pathFilter, `id` has no top-level scalar
+        // form on `ParsedWhere`. Always lives in `filters[]` as a docColumn.
+        const result = await parseWhere({ id: 'doc-x' }, testCollection);
+        expect(result.status).toBeUndefined();
+        expect(result.pathFilter).toBeUndefined();
+        expect(result.query).toBeUndefined();
+        expect(result.filters).toHaveLength(1);
+    });
+});
+// ---------------------------------------------------------------------------
 // mergePredicates
 // ---------------------------------------------------------------------------
 describe('mergePredicates', () => {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "2.5.1"
+    "@byline/auth": "2.5.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",