@lde/search 0.32.3 → 0.33.0

package/dist/adapter.d.ts

@@ -15,4 +15,5 @@ export { joinGraph, MAX_JOIN_DEPTH } from './join-graph.js';
 export type { JoinGraph } from './join-graph.js';
 export { filterOperatorFor, filterOperator, filterOn, isWelded, isUnsatisfiable, facetSearches, validateQuery, assertValidQuery, resolvePath, pageForOffset, } from './query.js';
 export type { FacetSearch, FilterOperator, QueryIssue, ResolvedPath, PathFailure, } from './query.js';
+export type { RebuildRequests } from './rebuild.js';
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.d.ts

@@ -9,4 +9,5 @@ export type { SearchQuery, ReferenceProjection, Filter, Criterion, CriterionBase
 export { NESTED_DOCUMENT_TYPE } from './engine.js';
 export type { SearchEngine, SearchResult, SearchHit, ResultDocument, SearchValue, LocalizedValue, Reference, NestedDocument, Facet, FacetBucket, FacetExtent, FacetMap, FacetsOutcome, FacetFieldsOf, OutputFieldsOf, } from './engine.js';
 export type { FramedNode } from './frame-by-type.js';
+export { RebuildAlreadyRunning, requestRebuild } from './rebuild.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAKtB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,OAAO,EACP,MAAM,EAMN,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOjD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,MAAM,EACN,SAAS,EACT,aAAa,EACb,eAAe,EACf,IAAI,GACL,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAKtB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,OAAO,EACP,MAAM,EAMN,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOjD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,MAAM,EACN,SAAS,EACT,aAAa,EACb,eAAe,EACf,IAAI,GACL,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,EACL,WAAW,EACX,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAKrD,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -30,3 +30,7 @@ export { filterOn } from './query.js';
 // Engine port + the logical result document returned across it. An engine is
 // bound to the whole SearchSchema at construction by its adapter factory.
 export { NESTED_DOCUMENT_TYPE } from './engine.js';
+// Rebuild requests: hand a request to the run holding an index’s rebuild lock
+// instead of dropping it. The store a port records requests in
+// (`RebuildRequests`) is on the adapter surface.
+export { RebuildAlreadyRunning, requestRebuild } from './rebuild.js';

package/dist/rebuild.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Another run already holds the index’s rebuild lock, so this run refuses to
+ * open. Rebuilds are single-flight per index across pods: an engine port’s
+ * rebuild writer throws this from `openRun` when its lock is held.
+ * {@link requestRebuild} catches it to hand the request to the run holding the
+ * lock; a caller driving a writer directly can catch it to treat a concurrent
+ * rebuild as a graceful skip.
+ */
+export declare class RebuildAlreadyRunning extends Error {
+    constructor(name: string);
+}
+/**
+ * Where an index’s rebuild requests are recorded, next to its rebuild lock, so
+ * the run holding the lock sees that a request arrived while it ran. An engine
+ * port implements it on its own store; {@link requestRebuild} is its only
+ * caller.
+ */
+export interface RebuildRequests {
+    /** Record a new request, replacing the previous one. */
+    record(): Promise<void>;
+    /**
+     * The latest request, or `undefined` when none was ever recorded. Opaque:
+     * only compared for equality, to tell whether a request arrived since the
+     * last read.
+     */
+    latest(): Promise<string | undefined>;
+}
+/**
+ * Request a rebuild of one index, so that a change made before the call ends
+ * up in it – even when another pod is rebuilding the index right now.
+ *
+ * The request is recorded first, then `rebuild` runs. When another run holds
+ * the lock (`rebuild` throws {@link RebuildAlreadyRunning}), this call resolves
+ * at once: the holder reads the requests after its run and runs again,
+ * picking the change up. A run that finds a request recorded since it began
+ * runs again too, so a burst of requests during one run costs a single rerun.
+ * Requests that keep arriving keep the holder running until one run sees none.
+ *
+ * The ordering is what makes it safe: a requester records before it tries the
+ * lock, and the holder reads after its run released the lock. So either the
+ * requester takes the lock, or the holder sees its request.
+ *
+ * Every rebuild of the index must go through `requestRebuild` with the same
+ * `rebuild`: the holder runs its own on another’s behalf, and a run started
+ * any other way never reads the requests. `requests` must be named after the
+ * one lock `rebuild` can be refused by. On failure this rejects without
+ * running again; requests recorded during the failed run are served by the
+ * next `requestRebuild`.
+ */
+export declare function requestRebuild(rebuild: () => Promise<unknown>, requests: RebuildRequests): Promise<void>;
+//# sourceMappingURL=rebuild.d.ts.map

package/dist/rebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild.d.ts","sourceRoot":"","sources":["../src/rebuild.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,IAAI,EAAE,MAAM;CAIzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/rebuild.js

@@ -0,0 +1,60 @@
+/**
+ * Another run already holds the index’s rebuild lock, so this run refuses to
+ * open. Rebuilds are single-flight per index across pods: an engine port’s
+ * rebuild writer throws this from `openRun` when its lock is held.
+ * {@link requestRebuild} catches it to hand the request to the run holding the
+ * lock; a caller driving a writer directly can catch it to treat a concurrent
+ * rebuild as a graceful skip.
+ */
+export class RebuildAlreadyRunning extends Error {
+    constructor(name) {
+        super(`Another rebuild of “${name}” is already running`);
+        this.name = 'RebuildAlreadyRunning';
+    }
+}
+/**
+ * Request a rebuild of one index, so that a change made before the call ends
+ * up in it – even when another pod is rebuilding the index right now.
+ *
+ * The request is recorded first, then `rebuild` runs. When another run holds
+ * the lock (`rebuild` throws {@link RebuildAlreadyRunning}), this call resolves
+ * at once: the holder reads the requests after its run and runs again,
+ * picking the change up. A run that finds a request recorded since it began
+ * runs again too, so a burst of requests during one run costs a single rerun.
+ * Requests that keep arriving keep the holder running until one run sees none.
+ *
+ * The ordering is what makes it safe: a requester records before it tries the
+ * lock, and the holder reads after its run released the lock. So either the
+ * requester takes the lock, or the holder sees its request.
+ *
+ * Every rebuild of the index must go through `requestRebuild` with the same
+ * `rebuild`: the holder runs its own on another’s behalf, and a run started
+ * any other way never reads the requests. `requests` must be named after the
+ * one lock `rebuild` can be refused by. On failure this rejects without
+ * running again; requests recorded during the failed run are served by the
+ * next `requestRebuild`.
+ */
+export async function requestRebuild(rebuild, requests) {
+    await requests.record();
+    // Read before the run reads its source, so a request recorded after this
+    // point shows up as a change once the run is done.
+    let served = await requests.latest();
+    for (;;) {
+        try {
+            await rebuild();
+        }
+        catch (error) {
+            // By name, not `instanceof`: the port may resolve its own copy of this
+            // package, whose class is a different one.
+            if (error instanceof Error && error.name === 'RebuildAlreadyRunning') {
+                return;
+            }
+            throw error;
+        }
+        const latest = await requests.latest();
+        if (latest === served) {
+            return;
+        }
+        served = latest;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.32.3",
+  "version": "0.33.0",
   "description": "Engine- and domain-agnostic core for RDF-backed search: a unified declarative field model (SearchField/SearchType/SearchSchema), a neutral query IR, the SearchEngine port with logical result types, and a streaming CONSTRUCT-to-document projection. Bakes in no engine, protocol, or domain.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",