@byline/client 6.9.0 → 6.10.0

package/dist/collection-handle.js

@@ -9,7 +9,7 @@ import { applyAfterRead, assertActorCanPerform, assertLocaleVisibility, buildSea
 import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
 import { expectedDocumentId, readSingletonForEdit, } from './read-internals.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
-import { assertSearchFieldScope, assertSearchQueryLength, finalizeSearchHits } from './search.js';
+import { assertSearchFieldScope, assertSearchQueryLength, assertSearchRangeFacets, finalizeSearchHits, } from './search.js';
 function toScheduleInfo(schedule) {
     const { executionToken: _executionToken, executionExpiresAt: _executionExpiresAt, ...info } = schedule;
     return info;
@@ -210,6 +210,7 @@ export class CollectionHandle {
             });
         }
         assertSearchFieldScope(provider, options.fieldScope);
+        assertSearchRangeFacets(provider, options.rangeFacets, [this.definition]);
         const results = await provider.search({
             query: options.query,
             fieldScope: options.fieldScope,
@@ -219,6 +220,7 @@ export class CollectionHandle {
             status: readMode,
             where: options.where,
             facets: options.facets,
+            rangeFacets: options.rangeFacets?.length ? options.rangeFacets : undefined,
             limit: options.limit,
             offset: options.offset,
         });
@@ -242,7 +244,12 @@ export class CollectionHandle {
         });
         return aggregateRestricted
             ? { hits, total: hits.length }
-            : { hits, total: results.total, facets: results.facets };
+            : {
+                hits,
+                total: results.total,
+                facets: results.facets,
+                ...(results.rangeFacets === undefined ? {} : { rangeFacets: results.rangeFacets }),
+            };
     }
     // -------------------------------------------------------------------------
     // Search index maintenance

package/dist/search.d.ts

@@ -28,11 +28,13 @@
  * lag, logged at warn level, not a reason to degrade the response.
  */
 import type { RequestContext } from '@byline/auth';
-import type { LocaleVisibility, ReadContext, ReadMode, SearchHit, SearchProvider } from '@byline/core';
+import type { CollectionDefinition, LocaleVisibility, ReadContext, ReadMode, SearchHit, SearchProvider, SearchRangeFacetRequest } from '@byline/core';
 import type { BylineClient } from './client.js';
 import type { ClientSearchResults, HydratedSearchHit, ZoneSearchOptions } from './types.js';
 /** Validate the optional logical body-field scope before calling a provider. */
 export declare function assertSearchFieldScope(provider: SearchProvider, fieldScope: string[] | undefined): void;
+/** Validate range aggregates against every collection in the provider's scope. */
+export declare function assertSearchRangeFacets(provider: SearchProvider, rangeFacets: SearchRangeFacetRequest[] | undefined, collections: readonly CollectionDefinition[]): void;
 export interface FinalizeSearchHitsParams {
     client: BylineClient<any>;
     requestContext: RequestContext;

package/dist/search.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, MAX_SEARCH_QUERY_LENGTH, resolveLocaleVisibility, resolveSearchZones, } from '@byline/core';
+import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, MAX_RANGE_FACET_BUCKETS, MAX_SEARCH_QUERY_LENGTH, resolveLocaleVisibility, resolveSearchZones, } from '@byline/core';
 import { resolveReadRequestContext, resolveReadSecurityFilters } from './read-context.js';
 /** Validate the optional logical body-field scope before calling a provider. */
 export function assertSearchFieldScope(provider, fieldScope) {
@@ -21,6 +21,55 @@ export function assertSearchFieldScope(provider, fieldScope) {
         });
     }
 }
+/** Validate range aggregates against every collection in the provider's scope. */
+export function assertSearchRangeFacets(provider, rangeFacets, collections) {
+    if (rangeFacets == null)
+        return;
+    if (!Array.isArray(rangeFacets)) {
+        throw ERR_VALIDATION({ message: 'Search rangeFacets must be an array.' });
+    }
+    if (rangeFacets.length === 0)
+        return;
+    if (provider.capabilities.rangeFacets !== true) {
+        throw ERR_VALIDATION({
+            message: 'The registered search provider does not support range facets.',
+        });
+    }
+    const fields = new Set();
+    for (const request of rangeFacets) {
+        if (request == null || typeof request.field !== 'string' || request.field.trim() === '') {
+            throw ERR_VALIDATION({ message: 'Search rangeFacets must name a field for each request.' });
+        }
+        const { field, start, end, gap } = request;
+        if (![start, end, gap].every(Number.isFinite)) {
+            throw ERR_VALIDATION({
+                message: `Search range facet '${field}' requires finite start, end, and gap values.`,
+            });
+        }
+        if (gap <= 0 || end <= start) {
+            throw ERR_VALIDATION({
+                message: `Search range facet '${field}' requires gap > 0 and end > start.`,
+            });
+        }
+        if (Math.ceil((end - start) / gap) > MAX_RANGE_FACET_BUCKETS) {
+            throw ERR_VALIDATION({
+                message: `Search range facet '${field}' exceeds the maximum of ${MAX_RANGE_FACET_BUCKETS} buckets.`,
+            });
+        }
+        if (fields.has(field)) {
+            throw ERR_VALIDATION({ message: `Search rangeFacets contains duplicate field '${field}'.` });
+        }
+        fields.add(field);
+        for (const collection of collections) {
+            if (!collection.search?.filters?.includes(field) ||
+                collection.fields.find((definition) => definition.name === field)?.type !== 'integer') {
+                throw ERR_VALIDATION({
+                    message: `Search range facet '${field}' must name an integer field declared in search.filters for collection '${collection.path}'.`,
+                });
+            }
+        }
+    }
+}
 /**
  * Authorise (and optionally hydrate) provider hits, per collection:
  *
@@ -235,6 +284,7 @@ export async function zoneSearch(client, options) {
         throw firstAbilityError;
     }
     assertSearchFieldScope(provider, options.fieldScope);
+    assertSearchRangeFacets(provider, options.rangeFacets, members);
     let aggregateRestricted = readable.size !== members.length;
     if (!options._bypassBeforeRead) {
         for (const member of members) {
@@ -255,6 +305,7 @@ export async function zoneSearch(client, options) {
         status: readMode,
         where: options.where,
         facets: options.facets,
+        rangeFacets: options.rangeFacets?.length ? options.rangeFacets : undefined,
         limit: options.limit,
         offset: options.offset,
     });
@@ -273,7 +324,12 @@ export async function zoneSearch(client, options) {
     });
     return aggregateRestricted
         ? { hits, total: hits.length }
-        : { hits, total: results.total, facets: results.facets };
+        : {
+            hits,
+            total: results.total,
+            facets: results.facets,
+            ...(results.rangeFacets === undefined ? {} : { rangeFacets: results.rangeFacets }),
+        };
 }
 export function assertSearchQueryLength(query) {
     if (query.length <= MAX_SEARCH_QUERY_LENGTH)

package/dist/types.d.ts

@@ -6,8 +6,8 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, LocaleVisibility, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SingletonSavePrecondition, SlugifierFn, SortSpec, UnavailableBlock } from '@byline/core';
-export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, LocaleVisibility, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, SearchRangeFacetBucket, SearchRangeFacetRequest, ServerConfig, SingletonSavePrecondition, SlugifierFn, SortSpec, UnavailableBlock } from '@byline/core';
+export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchRangeFacetBucket, SearchRangeFacetRequest, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
      * Convenience shorthand: pass an already-resolved `ServerConfig` (typically
@@ -204,6 +204,8 @@ export interface CollectionSearchOptions extends BeforeReadControls {
     where?: QueryPredicate;
     /** Field names to compute facet buckets for (driver-capability gated). */
     facets?: string[];
+    /** Integer range aggregates; requires provider support and declared search filters. */
+    rangeFacets?: SearchRangeFacetRequest[];
     /** Max hits to return. */
     limit?: number;
     /** Offset for pagination. */
@@ -242,6 +244,8 @@ export interface ZoneSearchOptions extends BeforeReadControls {
     where?: QueryPredicate;
     /** Field names to compute facet buckets for (driver-capability gated). */
     facets?: string[];
+    /** Integer range aggregates over filter fields shared by every zone member. */
+    rangeFacets?: SearchRangeFacetRequest[];
     /** Max hits to return. */
     limit?: number;
     /** Offset for pagination. */
@@ -263,6 +267,7 @@ export interface ClientSearchResults {
     hits: HydratedSearchHit[];
     total: number;
     facets?: Record<string, SearchFacetBucket[]>;
+    rangeFacets?: Record<string, SearchRangeFacetBucket[]>;
 }
 /** Outcome of a collection `reindex()` — counts for reporting. */
 export interface ReindexResult {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.9.0",
+  "version": "6.10.0",
   "engines": {
     "node": ">=22.22.2"
   },
@@ -43,22 +43,22 @@
     "dist"
   ],
   "dependencies": {
-    "@byline/auth": "6.9.0",
-    "@byline/core": "6.9.0",
+    "@byline/auth": "6.10.0",
+    "@byline/core": "6.10.0",
     "uuid": "^14.0.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.15",
-    "@byline/db-postgres": "6.9.0",
-    "@byline/search-postgres": "6.9.0",
+    "@biomejs/biome": "2.6.2",
+    "@byline/db-postgres": "6.10.0",
+    "@byline/search-postgres": "6.10.0",
     "@types/node": "^26.6.5",
-    "chokidar": "^5.0.0",
+    "chokidar": "^6.0.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^18.0.8",
     "npm-run-all": "^4.1.5",
-    "tsc-alias": "^1.9.7",
+    "tsc-alias": "^1.9.8",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.4"
+    "vitest": "^5.0.5"
   },
   "publishConfig": {
     "access": "public",