@byline/core 6.9.0 → 6.10.1

package/dist/@types/query-predicate.d.ts

@@ -7,8 +7,10 @@
  */
 /**
  * Comparison operators usable on a single field-level predicate value. The
- * parser normalises a bare value (`'foo'`) to `{ $eq: 'foo' }`; an operator
- * object is taken as-is and the first declared operator wins.
+ * parser normalises a bare value (`'foo'`) to `{ $eq: 'foo' }`. Every operator
+ * in an operator object applies and the conditions are ANDed, so
+ * `{ $gte: 10, $lte: 20 }` is a closed range. An empty object or an unknown
+ * operator is a validation error.
  */
 export interface FilterOperators {
     $eq?: string | number | boolean | null;

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

@@ -167,6 +167,24 @@ export interface SearchMatching {
 }
 /** Maximum UTF-16 length accepted for one full-text query. */
 export declare const MAX_SEARCH_QUERY_LENGTH = 1024;
+/** Maximum `ceil((end - start) / gap)` for one range-facet request. */
+export declare const MAX_RANGE_FACET_BUCKETS = 200;
+/** One numeric range-facet request over an integer `search.filters` field. */
+export interface SearchRangeFacetRequest {
+    field: string;
+    /** Inclusive lower edge of the first bucket. */
+    start: number;
+    /** Exclusive upper edge of the last bucket. */
+    end: number;
+    /** Bucket width; must be finite and greater than zero. */
+    gap: number;
+}
+/** One range bucket: `[start, end)` and its match count. */
+export interface SearchRangeFacetBucket {
+    start: number;
+    end: number;
+    count: number;
+}
 /**
  * A search request. Either collection-scoped (`collectionPath`) for
  * homogeneous results, or zone-scoped (`zone`) for heterogeneous
@@ -201,6 +219,8 @@ export interface SearchQuery {
     where?: QueryPredicate;
     /** Field names to compute facet buckets for (driver-capability gated). */
     facets?: string[];
+    /** Integer range aggregates; requires `capabilities.rangeFacets: true`. */
+    rangeFacets?: SearchRangeFacetRequest[];
     /** Restrict to a single content locale. */
     locale?: string;
     /**
@@ -254,6 +274,12 @@ export interface SearchResults {
      * driver supports them.
      */
     facets?: Record<string, SearchFacetBucket[]>;
+    /**
+     * Contiguous ascending buckets keyed by field, including zero counts.
+     * Cover exactly the requested `[start, end)`, truncating the final bucket.
+     * Counts respect the query, where, locale, status, and collection/zone scope.
+     */
+    rangeFacets?: Record<string, SearchRangeFacetBucket[]>;
 }
 /**
  * What a given driver can actually do. Lets consumers (the admin UI, the
@@ -266,6 +292,14 @@ export interface SearchResults {
 export interface SearchCapabilities {
     /** Faceted aggregation over indexed fields. */
     facets: boolean;
+    /** Integer range aggregation. Omission means false; unsupported requests must fail. */
+    rangeFacets?: boolean;
+    /**
+     * Applies `SearchQuery.where`. Omission means false. Advertise-only: the
+     * client still forwards `where` when absent. Providers may support a
+     * documented subset, but must reject unsupported fields or operators.
+     */
+    structuredFilters?: boolean;
     /** Fuzzy / typo-tolerant matching (e.g. `pg_trgm`). */
     typoTolerance: boolean;
     /** Vector / semantic / hybrid retrieval. */

package/dist/@types/search-types.js

@@ -7,3 +7,5 @@
  */
 /** Maximum UTF-16 length accepted for one full-text query. */
 export const MAX_SEARCH_QUERY_LENGTH = 1_024;
+/** Maximum `ceil((end - start) / gap)` for one range-facet request. */
+export const MAX_RANGE_FACET_BUCKETS = 200;

package/dist/@types/search-types.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/@types/search-types.test.node.js

@@ -0,0 +1,21 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { expect, it } from 'vitest';
+import { MAX_RANGE_FACET_BUCKETS } from '../index.js';
+it('exports the range-facet contract and bucket cap from the public core entry point', () => {
+    const request = { field: 'year', start: 2000, end: 2003, gap: 2 };
+    const buckets = [
+        { start: 2000, end: 2002, count: 0 },
+        { start: 2002, end: 2003, count: 1 },
+    ];
+    const query = { query: '', rangeFacets: [request] };
+    const result = { hits: [], total: 1, rangeFacets: { year: buckets } };
+    expect(MAX_RANGE_FACET_BUCKETS).toBe(200);
+    expect(query.rangeFacets).toEqual([request]);
+    expect(result.rangeFacets?.year).toEqual(buckets);
+});

package/dist/query/parse-where.js

@@ -134,9 +134,13 @@ async function validateSecurityPredicate(predicate, definition, ctx, allowEmpty
 }
 function validateDocumentColumnPredicate(value, collectionPath, column) {
     validateSecurityOperator(value, collectionPath, column);
-    const parsed = normaliseToOperator(value);
-    if (parsed == null || !DOCUMENT_COLUMN_OPERATORS[column].has(parsed.operator)) {
-        throw invalidSecurityPredicate(collectionPath, `operator '${parsed?.operator ?? 'unknown'}' is not supported for '${column}'`);
+    for (const parsed of normaliseToOperators(value, collectionPath, column)) {
+        validateDocumentColumnOperator(parsed, collectionPath, column);
+    }
+}
+function validateDocumentColumnOperator(parsed, collectionPath, column) {
+    if (!DOCUMENT_COLUMN_OPERATORS[column].has(parsed.operator)) {
+        throw invalidSecurityPredicate(collectionPath, `operator '${parsed.operator}' is not supported for '${column}'`);
     }
     const values = Array.isArray(parsed.value) ? parsed.value : [parsed.value];
     if ((parsed.operator === '$in' || parsed.operator === '$nin') && !Array.isArray(parsed.value)) {
@@ -163,18 +167,20 @@ function validateSecurityOperator(value, collectionPath, fieldName) {
         throw invalidSecurityPredicate(collectionPath, `invalid predicate for '${fieldName}'`);
     }
     const entries = Object.entries(value);
-    if (entries.length !== 1 || !FILTER_OPERATORS.has(entries[0]?.[0] ?? '')) {
-        throw invalidSecurityPredicate(collectionPath, `predicate for '${fieldName}' must contain exactly one supported operator`);
-    }
-    const [operator, operand] = entries[0] ?? [];
-    if ((operator === '$in' || operator === '$nin') && !Array.isArray(operand)) {
-        throw invalidSecurityPredicate(collectionPath, `${operator} for '${fieldName}' requires an array`);
-    }
-    if (operator === '$contains' && typeof operand !== 'string') {
-        throw invalidSecurityPredicate(collectionPath, `$contains for '${fieldName}' requires a string`);
+    if (entries.length === 0 || entries.some(([operator]) => !FILTER_OPERATORS.has(operator))) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for '${fieldName}' must contain only supported operators`);
     }
-    if (operand === undefined) {
-        throw invalidSecurityPredicate(collectionPath, `operator for '${fieldName}' requires a value`);
+    // Every operator in the object applies (ANDed), so every one is checked.
+    for (const [operator, operand] of entries) {
+        if ((operator === '$in' || operator === '$nin') && !Array.isArray(operand)) {
+            throw invalidSecurityPredicate(collectionPath, `${operator} for '${fieldName}' requires an array`);
+        }
+        if (operator === '$contains' && typeof operand !== 'string') {
+            throw invalidSecurityPredicate(collectionPath, `$contains for '${fieldName}' requires a string`);
+        }
+        if (operand === undefined) {
+            throw invalidSecurityPredicate(collectionPath, `operator for '${fieldName}' requires a value`);
+        }
     }
 }
 function invalidSecurityPredicate(collectionPath, reason) {
@@ -241,8 +247,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
         // belong at the top level of the where clause.
         if (key === '$and' || key === '$or') {
             if (!Array.isArray(rawValue)) {
-                ctx?.logger?.debug({ key, collection: definition.path }, 'parse-where: dropping combinator — value is not an array of predicates');
-                continue;
+                throw invalidWhere(definition.path, `${key} must be an array of predicates`);
             }
             const childFilters = [];
             for (const child of rawValue) {
@@ -311,9 +316,10 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
         //     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) {
+            // A bare string at the top level keeps the scalar `status` form. An
+            // operator object takes the `DocumentColumnFilter` form at any scope.
+            if (isNested || inCombinator || typeof rawValue !== 'string') {
+                for (const parsed of normaliseToOperators(rawValue, definition.path, key)) {
                     result.filters.push({
                         kind: 'docColumn',
                         column: 'status',
@@ -323,9 +329,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                 }
                 continue;
             }
-            if (typeof rawValue === 'string') {
-                result.status = rawValue;
-            }
+            result.status = rawValue;
             continue;
         }
         if (key === 'query') {
@@ -343,9 +347,12 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
             continue;
         }
         if (key === 'path') {
-            if (isNested || inCombinator) {
-                const parsed = normaliseToOperator(rawValue);
-                if (parsed) {
+            const operators = normaliseToOperators(rawValue, definition.path, key);
+            // `pathFilter` holds one operator. Several operators on a top-level
+            // `path` take the `DocumentColumnFilter` form instead, which the
+            // adapter resolves against the top-level scope just as well.
+            if (isNested || inCombinator || operators.length > 1) {
+                for (const parsed of operators) {
                     result.filters.push({
                         kind: 'docColumn',
                         column: 'path',
@@ -355,7 +362,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                 }
                 continue;
             }
-            const parsed = normaliseToOperator(rawValue);
+            const [parsed] = operators;
             if (parsed) {
                 result.pathFilter = {
                     operator: parsed.operator,
@@ -373,8 +380,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
         // 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) {
+            for (const parsed of normaliseToOperators(rawValue, definition.path, key)) {
                 result.filters.push({
                     kind: 'docColumn',
                     column: 'id',
@@ -453,17 +459,16 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
         const storeInfo = fieldTypeToStore[field.type];
         if (!storeInfo)
             continue; // Structure fields can't be filtered directly
-        const parsed = normaliseToOperator(rawValue);
-        if (!parsed)
-            continue;
-        result.filters.push({
-            kind: 'field',
-            fieldName: key,
-            storeType: storeInfo.storeType,
-            valueColumn: storeInfo.valueColumn,
-            operator: parsed.operator,
-            value: parsed.value,
-        });
+        for (const parsed of normaliseToOperators(rawValue, definition.path, key)) {
+            result.filters.push({
+                kind: 'field',
+                fieldName: key,
+                storeType: storeInfo.storeType,
+                valueColumn: storeInfo.valueColumn,
+                operator: parsed.operator,
+                value: parsed.value,
+            });
+        }
     }
     return result;
 }
@@ -555,7 +560,7 @@ function isPlainSubWhere(raw) {
         return false;
     const keys = Object.keys(raw);
     // An empty object is not a meaningful sub-where; treat as non-match
-    // (ordinary field-filter path will then reject it via normaliseToOperator).
+    // (ordinary field-filter path will then reject it via normaliseToOperators).
     if (keys.length === 0)
         return false;
     for (const k of keys) {
@@ -565,28 +570,46 @@ function isPlainSubWhere(raw) {
     return true;
 }
 /**
- * Normalise a WhereValue (bare value or operator object) into a single
- * operator + value pair.
+ * Normalise a WhereValue (bare value or operator object) into a list of
+ * operator + value pairs. Every operator in an operator object applies, so
+ * `{ $gte: 10, $lte: 20 }` yields two pairs that the caller ANDs together.
+ * Operators whose value is `undefined` are skipped, matching how the parser
+ * skips `undefined` keys. An object with no operators left, or with an
+ * unknown operator, is a validation error rather than a dropped filter.
  */
-function normaliseToOperator(raw) {
+function normaliseToOperators(raw, collectionPath, key) {
     // Bare value → $eq
     if (raw === null ||
         typeof raw === 'string' ||
         typeof raw === 'number' ||
         typeof raw === 'boolean') {
-        return { operator: '$eq', value: raw };
+        return [{ operator: '$eq', value: raw }];
     }
-    // Operator object
-    const ops = raw;
-    const operatorEntries = Object.entries(ops);
-    if (operatorEntries.length === 0)
-        return undefined;
-    // Use the first operator found
-    const [op, val] = operatorEntries[0];
-    return {
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw invalidWhere(collectionPath, `invalid value for '${key}'`);
+    }
+    // Operator object. Names are checked before `undefined` operands are
+    // skipped, so an unknown operator throws even when its value is missing.
+    const entries = Object.entries(raw);
+    for (const [op] of entries) {
+        if (!FILTER_OPERATORS.has(op)) {
+            throw invalidWhere(collectionPath, `unknown operator '${op}' for '${key}'`);
+        }
+    }
+    const operatorEntries = entries.filter(([, val]) => val !== undefined);
+    if (operatorEntries.length === 0) {
+        throw invalidWhere(collectionPath, `operator object for '${key}' is empty`);
+    }
+    return operatorEntries.map(([op, val]) => ({
         operator: op,
         value: val,
-    };
+    }));
+}
+function invalidWhere(collectionPath, reason) {
+    return ERR_VALIDATION({
+        message: `invalid where clause for '${collectionPath}': ${reason}`,
+        details: { collectionPath, reason },
+    });
 }
 function stringifyDocumentColumnValue(value) {
     if (value === null)

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

@@ -522,12 +522,10 @@ describe('parseWhere — combinators', () => {
         // landmine if compiled to SQL.
         expect(result.filters).toEqual([]);
     });
-    it('drops a non-array combinator value (defensive)', async () => {
-        const result = await parseWhere({
-            // biome-ignore lint/suspicious/noExplicitAny: deliberately malformed input
-            $or: { title: 'Hello' },
-        }, testCollection);
-        expect(result.filters).toEqual([]);
+    it.each(['$and', '$or'])('rejects a non-array %s value', async (key) => {
+        await expect(parseWhere(
+        // biome-ignore lint/suspicious/noExplicitAny: deliberately malformed input
+        { [key]: { title: 'Hello' } }, testCollection)).rejects.toThrow(`${key} must be an array of predicates`);
     });
     it('nests $or inside $and correctly', async () => {
         const result = await parseWhere({
@@ -867,3 +865,132 @@ describe('parseWhere — relation quantifiers', () => {
         expect(result.filters).toHaveLength(0);
     });
 });
+// ---------------------------------------------------------------------------
+// Multi-operator objects
+// ---------------------------------------------------------------------------
+describe('parseWhere — multi-operator objects', () => {
+    const views = (operator, value) => ({
+        kind: 'field',
+        fieldName: 'views',
+        storeType: 'numeric',
+        valueColumn: 'value_integer',
+        operator,
+        value,
+    });
+    it('emits one filter per operator in a closed range', async () => {
+        const result = await parseWhere({ views: { $gte: 10, $lte: 20 } }, testCollection);
+        expect(result.filters).toEqual([views('$gte', 10), views('$lte', 20)]);
+    });
+    it('keeps every operator of the downstream date-range shape', async () => {
+        const result = await parseWhere({ views: { $gt: 0, $gte: 20200000, $lte: 20201231 } }, testCollection);
+        expect(result.filters).toEqual([
+            views('$gt', 0),
+            views('$gte', 20200000),
+            views('$lte', 20201231),
+        ]);
+    });
+    it('combines $eq with a range operator', async () => {
+        const result = await parseWhere({ views: { $eq: 42, $lt: 100 } }, testCollection);
+        expect(result.filters).toEqual([views('$eq', 42), views('$lt', 100)]);
+    });
+    it('skips operators whose value is undefined', async () => {
+        const result = await parseWhere({ views: { $gte: undefined, $lte: 20 } }, testCollection);
+        expect(result.filters).toEqual([views('$lte', 20)]);
+    });
+    it('keeps the $and workaround shape working', async () => {
+        const result = await parseWhere({ $and: [{ views: { $gt: 0 } }, { views: { $gte: 10 } }, { views: { $lte: 20 } }] }, testCollection);
+        expect(result.filters).toEqual([views('$gt', 0), views('$gte', 10), views('$lte', 20)]);
+    });
+    it('emits every operator on a document column', async () => {
+        const result = await parseWhere({ $or: [{ status: { $ne: 'archived', $in: ['draft', 'published'] } }] }, testCollection);
+        expect(result.filters).toEqual([
+            {
+                kind: 'or',
+                children: [
+                    {
+                        kind: 'and',
+                        children: [
+                            { kind: 'docColumn', column: 'status', operator: '$ne', value: 'archived' },
+                            {
+                                kind: 'docColumn',
+                                column: 'status',
+                                operator: '$in',
+                                value: ['draft', 'published'],
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]);
+    });
+    it('compiles a top-level status operator object instead of dropping it', async () => {
+        const scalar = await parseWhere({ status: 'draft' }, testCollection);
+        expect(scalar.status).toBe('draft');
+        expect(scalar.filters).toEqual([]);
+        const result = await parseWhere({ status: { $in: ['draft', 'published'] } }, testCollection);
+        expect(result.status).toBeUndefined();
+        expect(result.filters).toEqual([
+            { kind: 'docColumn', column: 'status', operator: '$in', value: ['draft', 'published'] },
+        ]);
+    });
+    it('moves a multi-operator top-level path to document-column filters', async () => {
+        const single = await parseWhere({ path: { $contains: 'docs' } }, testCollection);
+        expect(single.pathFilter).toEqual({ operator: '$contains', value: 'docs' });
+        const multi = await parseWhere({ path: { $contains: 'docs', $ne: 'docs/old' } }, testCollection);
+        expect(multi.pathFilter).toBeUndefined();
+        expect(multi.filters).toEqual([
+            { kind: 'docColumn', column: 'path', operator: '$contains', value: 'docs' },
+            { kind: 'docColumn', column: 'path', operator: '$ne', value: 'docs/old' },
+        ]);
+    });
+    it('emits every operator inside a relation sub-where', async () => {
+        const result = await parseWhere({ category: { slug: { $contains: 'new', $ne: 'news-old' } } }, testCollection, ctx);
+        expect(result.filters[0]).toMatchObject({
+            kind: 'relation',
+            fieldName: 'category',
+            nested: [
+                expect.objectContaining({ fieldName: 'slug', operator: '$contains', value: 'new' }),
+                expect.objectContaining({ fieldName: 'slug', operator: '$ne', value: 'news-old' }),
+            ],
+        });
+    });
+    it('emits every operator inside a quantified relation filter', async () => {
+        const result = await parseWhere({ tags: { $every: { slug: { $contains: 'a', $ne: 'b' } } } }, testCollection, ctx);
+        expect(result.filters[0]).toMatchObject({
+            kind: 'relation',
+            quantifier: 'every',
+            nested: [
+                expect.objectContaining({ operator: '$contains', value: 'a' }),
+                expect.objectContaining({ operator: '$ne', value: 'b' }),
+            ],
+        });
+    });
+    it.each([
+        [{ views: {} }, "operator object for 'views' is empty"],
+        [{ views: { $gte: undefined } }, "operator object for 'views' is empty"],
+        [{ views: { $gte: 10, $bogus: 1 } }, "unknown operator '$bogus' for 'views'"],
+        [{ views: { $gte: 10, $bogus: undefined } }, "unknown operator '$bogus' for 'views'"],
+        [{ status: { $wat: 'x' } }, "unknown operator '$wat' for 'status'"],
+        [{ id: {} }, "operator object for 'id' is empty"],
+        [{ views: [1, 2] }, "invalid value for 'views'"],
+        [{ category: {} }, "operator object for 'category' is empty"],
+    ])('rejects %o', async (where, message) => {
+        await expect(parseWhere(where, testCollection, ctx)).rejects.toThrow(message);
+    });
+    it('accepts multi-operator objects in strict security predicates', async () => {
+        const filters = await parsePredicateFilters({ views: { $gte: 10, $lte: 20 }, status: { $ne: 'archived', $in: ['published'] } }, testCollection, ctx, { strict: true });
+        expect(filters).toEqual([
+            views('$gte', 10),
+            views('$lte', 20),
+            { kind: 'docColumn', column: 'status', operator: '$ne', value: 'archived' },
+            { kind: 'docColumn', column: 'status', operator: '$in', value: ['published'] },
+        ]);
+    });
+    it.each([
+        [{ views: { $gte: 10, $wat: 1 } }, 'supported operators'],
+        [{ status: { $eq: 'published', $contains: 'pub' } }, "'$contains' is not supported"],
+        [{ status: { $ne: 'archived', $in: 'published' } }, 'requires an array'],
+    ])('validates every operator of strict predicate %o', async (predicate, message) => {
+        await expect(parsePredicateFilters(predicate, testCollection, ctx, { strict: true })).rejects.toThrow(message);
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.9.0",
+  "version": "6.10.1",
   "engines": {
     "node": ">=22.22.2"
   },
@@ -82,7 +82,7 @@
     "dist"
   ],
   "dependencies": {
-    "@byline/auth": "6.9.0",
+    "@byline/auth": "6.10.1",
     "dotenv": "^18.0.8",
     "pino": "^10.4.0",
     "sharp": "^0.35.5",
@@ -90,15 +90,15 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
+    "@biomejs/biome": "2.6.2",
     "@types/node": "^26.6.5",
-    "chokidar": "^5.0.0",
+    "chokidar": "^6.0.0",
     "chokidar-cli": "^3.0.0",
     "npm-run-all": "^4.1.5",
-    "tsc-alias": "^1.9.7",
+    "tsc-alias": "^1.9.8",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.4"
+    "vitest": "^5.0.5"
   },
   "publishConfig": {
     "access": "public",