@metreeca/keep-sparql 0.10.0

package/dist/_/_encode.js

@@ -0,0 +1,262 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { sh } from "@metreeca/blue";
+import { getShapeClass, getShapeId } from "@metreeca/blue/resource";
+import { getBoundVariant, getStateVariant } from "@metreeca/blue/union";
+import { error, isBoolean, isNumber, isObject, isString, opt } from "@metreeca/core";
+import { some } from "@metreeca/core/arrays";
+import { xsd } from "@metreeca/core/datatype";
+import { isReference } from "@metreeca/qest/resource";
+import { named, rdf, tagged, typed } from "@metreeca/trio";
+import { abs, and, avg, ceil, count, datatype, day, eq, filter, floor, gt, hours, iif, isIRI, isLiteral, isNumeric, lang, lcase, max, min, minutes, month, ne, nil, not, number, pattern, reference, round, seconds, string, strlen, sum, ucase, variable, year } from "@metreeca/wire-sparql/builder";
+/**
+ * The RDF {@link Term} of a comparison bound (`<` / `>` / `<=` / `>=`), typed against the {@link RangeShape |
+ * shape} variant it resolves to so the comparison resolves in the target's processing type (§5.7.1).
+ * {@link getBoundVariant} routes the bound, relaxing the value-domain facets a bound need not satisfy. A
+ * string variant carrying the `sh:IRI` datatype (an id / type entry, or a reference-ranged property) renders
+ * an IRI node rather than a literal, told apart from an IRI-shaped literal (a `url`) by datatype alone.
+ */
+export function boundToTerm(value, shape) {
+    return valueToTerm(value, getBoundVariant(value, shape.variants)
+        ?? (isString(value) ? shape.variants.find(variant => variant.kind === "dictionary") : undefined)
+        ?? error(new RangeError(`unresolved range variant for value <${String(value)}>`)));
+}
+/**
+ * Flattens the options of a set-matching or focus constraint to individual match {@link Term | terms}: a
+ * localised dictionary set expands to one language-tagged term per language tag (its value, or every element of
+ * its value array), a scalar option maps to its term typed by the {@link RangeShape | shape} variant it
+ * fits, and an option array maps element-wise. A `null` scalar survives as the absent-value option
+ * (§5.7.3).
+ */
+export function optionsToTerms(value, shape) {
+    if (isObject(value)) {
+        // the `und` tag is stored as a plain literal, every other tag as a language-tagged one (§6), so
+        // an und option matches by its plain value while a tagged option matches the raw tagged literal
+        return Object.entries(value).flatMap(([language, values]) => some(values).map(text => language === "und" ? typed(text) : tagged(text, language)));
+    }
+    else {
+        return some(value).map(option => option === null ? null : valueToTerm(option, getStateVariant(option, shape.variants)
+            ?? (isString(option) ? shape.variants.find(variant => variant.kind === "dictionary") : undefined)
+            ?? error(new RangeError(`unresolved range variant for value <${String(option)}>`))));
+    }
+}
+/**
+ * Types an operand against its resolved {@link ValuesShape | shape} (§5.7.1). A string shape carrying the
+ * `sh:IRI` datatype (an id / type entry, or a reference-ranged property) renders an IRI node rather than a
+ * literal, told apart from an IRI-shaped literal (a `url`) by datatype alone.
+ */
+export function valueToTerm(value, shape) {
+    switch (shape.kind) {
+        case "boolean":
+            return typed(String(value), xsd.boolean);
+        case "number":
+            return typed(String(value), shape.datatype ?? xsd.double);
+        case "string":
+            return shape.datatype === sh.IRI
+                ? named(String(value))
+                : typed(String(value), shape.datatype);
+        case "dictionary": // a localised dictionary shape is coalesced to a plain xsd:string (§6)
+            return typed(String(value));
+        case "reference":
+            return named(String(value));
+        case "resource": // a scalar operand never resolves to an expanded resource shape
+            throw new RangeError(`unsupported embedded resource variant for value <${String(value)}>`);
+    }
+}
+/**
+ * Types a property's write value(s) to the RDF {@link Term | terms} to store, flattening a single value or
+ * a value set against the resolved {@link ValuesShape | shape} variant (§5.7.1).
+ *
+ * Each element is typed by the variant it fits: a boolean, number, or string operand to its datatype-typed
+ * literal (a string shape carrying the `sh:IRI` datatype renders an IRI node instead, as in
+ * {@link valueToTerm}); a localised dictionary to one plain or language-tagged term per tag (§6); a reference to
+ * its IRI as-is; and a nested resource to its declared id when present (a captive resource with its own
+ * identity), else a freshly skolemised IRI addressing the embedded sub-resource. Values not fitting the
+ * variant are dropped.
+ */
+export function valuesToTerms(values, shape) {
+    switch (shape.kind) {
+        case "boolean":
+            return some(values).filter(isBoolean).map(value => typed(value, xsd.boolean));
+        case "number":
+            return some(values).filter(isNumber).map(value => typed(value, shape.datatype ?? xsd.double));
+        case "string":
+            return some(values).filter(isString).map(value => shape.datatype === sh.IRI
+                ? named(value)
+                : typed(value, shape.datatype));
+        case "dictionary":
+            return some(values).flatMap(value => {
+                if (isString(value)) {
+                    return [typed(value)];
+                }
+                else if (isObject(value)) {
+                    return Object.entries(value).flatMap(([tag, texts]) => some(texts).filter(isString).map(text => tag === "und" ? typed(text) : tagged(text, tag)));
+                }
+                else {
+                    return [];
+                }
+            });
+        case "reference":
+            return some(values).filter(isReference).map(value => named(value));
+        case "resource":
+            const id = getShapeId(shape);
+            return some(values).filter(v => isObject(v)).map(value => {
+                const node = id !== undefined ? value[id] : undefined;
+                return isReference(node) ? named(node) : named();
+            });
+    }
+}
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * The stored edge connecting `source` to `target` through a {@link Property | property}'s declared
+ * predicate. Renders the forward direction when the property declares one and `source` may stand in
+ * subject position, else the reverse direction when `target` may; both directions carry the value, so
+ * either connects the pair. Yields the empty fragment when neither applies.
+ */
+export function link([source, property, target]) {
+    return property.forward !== undefined && isAnchor(source) ? pattern([source, named(property.forward), target])
+        : property.reverse !== undefined && isAnchor(target) ? pattern([target, named(property.reverse), source])
+            : nil();
+    function isAnchor(value) {
+        return isString(value) || value.kind === "blank" || value.kind === "named";
+    }
+}
+/**
+ * Generates the SPARQL triple pattern rendering a {@link Property | property}'s forward direction.
+ *
+ * Emits `subject forward object` when the property declares a `forward` predicate; an undeclared
+ * forward direction contributes no pattern, yielding the empty fragment. The reverse-direction
+ * counterpart is {@link reverse}.
+ *
+ * @param edge The edge to render, as a `[subject, property, object]` tuple
+ *
+ * @returns The generated triple pattern, or the empty fragment when the property declares no forward
+ * predicate
+ *
+ * @see {@link https://www.w3.org/TR/sparql11-query/#QSynTriples SPARQL 1.1 Triple Patterns}
+ */
+export function forward([subject, property, object]) {
+    return property.forward !== undefined ? pattern([subject, named(property.forward), object]) : nil();
+}
+/**
+ * Generates the SPARQL triple pattern rendering a {@link Property | property}'s reverse direction.
+ *
+ * Emits `subject reverse object`, flipping object and subject, when the property declares a `reverse`
+ * predicate; an undeclared reverse direction contributes no pattern, yielding the empty fragment. The
+ * subject lands in the triple's object position, so it is constrained to an IRI {@link Reference}. The
+ * forward-direction counterpart is {@link forward}.
+ *
+ * @param edge The edge to render, as a `[object, property, subject]` tuple
+ *
+ * @returns The generated triple pattern, or the empty fragment when the property declares no reverse
+ * predicate
+ *
+ * @see {@link https://www.w3.org/TR/sparql11-query/#QSynTriples SPARQL 1.1 Triple Patterns}
+ */
+export function reverse([object, property, subject]) {
+    return property.reverse !== undefined ? pattern([subject, named(property.reverse), object]) : nil();
+}
+/**
+ * The gate binding a union shape's discriminator only for members belonging to it (union.md §Model).
+ *
+ * A classed node shape is gated by its stored `rdf:type` triple; a plain-string literal by a
+ * datatype/kind `filter` (boolean datatype, numeric test, or plain string); a localised `dictionary` shape by
+ * the language-tagged literal test, disjoint from the plain string; a classless node shape by the bare
+ * IRI-kind test. Under the modeller's disjointness guarantee (union.md §State) at most one shape's arm
+ * binds a given value.
+ *
+ * @param anchor The shape's value variable
+ * @param shape The shape to gate on
+ *
+ * @returns The gating triple pattern or `filter`
+ */
+export function membership(anchor, shape) {
+    const value = variable(anchor);
+    switch (shape.kind) {
+        case "boolean":
+            return filter(and(isLiteral(value), eq(datatype(value), reference(xsd.boolean))));
+        case "number":
+            return filter(isNumeric(value));
+        case "string": // !!! review
+            return filter(and(isLiteral(value), eq(lang(value), string("")), ne(datatype(value), reference(xsd.boolean)), not(isNumeric(value))));
+        case "dictionary":
+            return filter(and(isLiteral(value), ne(lang(value), string(""))));
+        case "reference":
+        case "resource":
+            return opt(getShapeClass(shape), clazz => pattern([anchor, named(rdf.type), named(clazz)]), () => filter(isIRI(value)));
+    }
+}
+/**
+ * The SPARQL expression applying a transform `pipe` to a value variable.
+ *
+ * Composes the pipe right-to-left (`reduceRight`), so the pipe's trailing transform applies to `anchor`
+ * first and each earlier transform wraps the running expression, leaving the leading transform
+ * outermost; an empty pipe yields the bare variable. Each {@link Transform} maps to its SPARQL aggregate
+ * (`count`/`sum`/`min`/`max`/`avg`, with the empty-set patch keeping `avg` over no rows unbound rather
+ * than erroring, Appendix A.4.3) or scalar function (string, numeric, and date-part).
+ *
+ * @param anchor The value variable the pipe transforms
+ * @param pipe The transforms to compose, leading (outermost) first
+ *
+ * @returns The SPARQL expression applying `pipe` to `anchor`, or the bare `anchor` variable when `pipe`
+ * is empty
+ *
+ * @see {@link https://www.w3.org/TR/sparql11-query/#aggregates SPARQL 1.1 Aggregates}
+ */
+export function expression(anchor, pipe) {
+    return pipe.reduceRight((expression, transform) => apply(expression, transform), variable(anchor));
+    function apply(expression, transform) {
+        switch (transform) {
+            case "count":
+                return count(expression);
+            case "sum":
+                return sum(expression);
+            case "min":
+                return min(expression);
+            case "max":
+                return max(expression);
+            case "avg": // !!! document rationale
+                return iif(gt(count(expression), number(0)), avg(expression), `${reference(xsd.integer)}("!")`);
+            case "length":
+                return strlen(expression);
+            case "lower":
+                return lcase(expression);
+            case "upper":
+                return ucase(expression);
+            case "abs":
+                return abs(expression);
+            case "floor":
+                return floor(expression);
+            case "ceil":
+                return ceil(expression);
+            case "round":
+                return round(expression);
+            case "year":
+                return year(expression);
+            case "month":
+                return month(expression);
+            case "day":
+                return day(expression);
+            case "hours":
+                return hours(expression);
+            case "minutes":
+                return minutes(expression);
+            case "seconds":
+                return seconds(expression);
+        }
+    }
+}
+//# sourceMappingURL=_encode.js.map

package/dist/_/_encode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_encode.js","sourceRoot":"","sources":["../../src/_/_encode.ts"],"names":[],"mappings":"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"}

package/dist/_/_flake.d.ts

@@ -0,0 +1,16 @@
+import { type Branch, type Flake } from "@metreeca/keep-flake";
+export declare function isXComputed(branch: Flake): boolean;
+export declare function isXScalar(branch: Flake): boolean;
+/**
+ * Whether a union node is a crossing intermediate: a path step under a shared predicate (§5.8.1) whose own
+ * value is never surfaced (no projection alias, no direct constraint / ordering / focus) and all of whose
+ * branches every variant declares. Such a node is traversed like a resource — its shared branches descended
+ * once off the anchor — rather than fanned into a membership-gated arm per variant. A surfaced union (a
+ * projected or constrained column) or one carrying a variant-specific branch keeps the arm machinery.
+ *
+ * `isDrainedFlake` / `isConstrainedFlake` are recursive (they reach descendant columns), so this checks the
+ * node's own slots directly: a deeper aliased or constrained column is what the crossing navigates toward.
+ */
+export declare function crossing(flake: Flake): boolean;
+export declare function references(branch: Branch): boolean;
+//# sourceMappingURL=_flake.d.ts.map

package/dist/_/_flake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_flake.d.ts","sourceRoot":"","sources":["../../src/_/_flake.ts"],"names":[],"mappings":"AAiBA,OAAO,EACN,KAAK,MAAM,EACX,KAAK,KAAK,EAOV,MAAM,sBAAsB,CAAC;AAG9B,wBAAgB,WAAW,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAIlD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAIhD;AAeD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAqB9C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIlD"}

package/dist/_/_flake.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { getShapeProperties } from "@metreeca/blue/resource";
+import { getFlakeEntries, getFlakeTransforms, isConstrainedFlake, isDrainedFlake, isPropertyBranch, isScalarFlake } from "@metreeca/keep-flake";
+export function isXComputed(branch) {
+    return isDrainedFlake(branch)
+        || isConstrainedFlake(branch)
+        || bindsComputed(branch);
+}
+export function isXScalar(branch) {
+    return isDrainedFlake(branch)
+        || isConstrainedFlake(branch)
+        || bindsScalar(branch);
+}
+function bindsComputed(flake) {
+    return getFlakeTransforms(flake).length > 0 // every transform stage is computed (Flake.pipe non-empty)
+        || getFlakeEntries(flake).some(bindsComputed);
+}
+function bindsScalar(flake) {
+    return getFlakeTransforms(flake).some(isScalarFlake)
+        || getFlakeEntries(flake).some(bindsScalar);
+}
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Whether a union node is a crossing intermediate: a path step under a shared predicate (§5.8.1) whose own
+ * value is never surfaced (no projection alias, no direct constraint / ordering / focus) and all of whose
+ * branches every variant declares. Such a node is traversed like a resource — its shared branches descended
+ * once off the anchor — rather than fanned into a membership-gated arm per variant. A surfaced union (a
+ * projected or constrained column) or one carrying a variant-specific branch keeps the arm machinery.
+ *
+ * `isDrainedFlake` / `isConstrainedFlake` are recursive (they reach descendant columns), so this checks the
+ * node's own slots directly: a deeper aliased or constrained column is what the crossing navigates toward.
+ */
+export function crossing(flake) {
+    return flake.drain?.alias === undefined && !surfaced(flake) && shared(flake);
+    function surfaced(flake) {
+        return [flake.lt, flake.gt, flake.lte, flake.gte, flake.like, flake.any, flake.all, flake.order, flake.focus]
+            .some(slot => slot !== undefined);
+    }
+    function shared(flake) {
+        // a childless union is a leaf column whose own references are retrieved (a bare `media` placeholder),
+        // not an intermediate step; it keeps the arm machinery to bind its variant shards
+        const branches = getFlakeEntries(flake);
+        return branches.length > 0 && branches.every(branch => flake.range.variants.every(variant => getShapeProperties(variant)[branch.path[branch.path.length - 1]] !== undefined));
+    }
+}
+export function references(branch) {
+    return branch.entry.kind === "id" || branch.entry.kind === "type" ? true
+        : isPropertyBranch(branch) ? branch.entry.range.shape.kind === "reference"
+            : false;
+}
+//# sourceMappingURL=_flake.js.map

package/dist/_/_flake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_flake.js","sourceRoot":"","sources":["../../src/_/_flake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAGN,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,MAAM,sBAAsB,CAAC;AAG9B,MAAM,UAAU,WAAW,CAAC,MAAa;IACxC,OAAO,cAAc,CAAC,MAAM,CAAC;WACzB,kBAAkB,CAAC,MAAM,CAAC;WAC1B,aAAa,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAa;IACtC,OAAO,cAAc,CAAC,MAAM,CAAC;WACzB,kBAAkB,CAAC,MAAM,CAAC;WAC1B,WAAW,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,aAAa,CAAC,KAAY;IAClC,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,2DAA2D;WACnG,eAAe,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,WAAW,CAAC,KAAY;IAChC,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC;WAChD,eAAe,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC9C,CAAC;AAGD,wHAAwH;AAExH;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAY;IAEpC,OAAO,KAAK,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAE7E,SAAS,QAAQ,CAAC,KAAY;QAC7B,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;aAC3G,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,SAAS,MAAM,CAAC,KAAY;QAE3B,sGAAsG;QACtG,kFAAkF;QAElF,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QAExC,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAC3F,kBAAkB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAC5E,CAAC,CAAC;IACJ,CAAC;AAEF,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;QACvE,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW;YACzE,CAAC,CAAC,KAAK,CAAC;AACX,CAAC"}

package/dist/_/_union.d.ts

@@ -0,0 +1,28 @@
+import type { ValuesShape } from "@metreeca/blue/value";
+/**
+ * Resolves which union variants a retrieval placeholder requests, and the sub-placeholder that projects
+ * each (union.md §Model).
+ *
+ * The model addresses a union in one of two forms:
+ *
+ *  - a **keyed** placeholder (an object whose keys are opaque `${number}` strings) supplies one
+ *    alternative per entry. Each alternative is matched independently against the variants by kind and
+ *    structure ({@link @metreeca/blue/union!getModelVariants | getModelVariants}), so one alternative may
+ *    reach several variants and one variant may be reached by several alternatives.
+ *  - any **other** placeholder is itself a single alternative, reaching every variant its kind fits.
+ *
+ * The result pairs each requested variant with the alternative that projects it. When several
+ * alternatives reach the same variant, the last in key order wins (plain `Map` semantics); the choice is
+ * immaterial, since same-variant alternatives project it identically. The map is the single source of
+ * truth shared by the encoder, which emits one arm per requested variant, and the decoder, which reads
+ * each requested variant's column and projects it through the paired alternative.
+ *
+ * @param variants The union variants to resolve against
+ * @param placeholder The union property's retrieval placeholder: a keyed alternative map, or a single
+ * alternative
+ *
+ * @returns Each requested variant mapped to its projecting alternative; empty when the placeholder
+ * requests no variant
+ */
+export declare function getUnionPlaceholders<V extends ValuesShape>(variants: readonly V[], placeholder: unknown): ReadonlyMap<V, unknown>;
+//# sourceMappingURL=_union.d.ts.map

package/dist/_/_union.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_union.d.ts","sourceRoot":"","sources":["../../src/_/_union.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,EACzD,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,WAAW,EAAE,OAAO,GAClB,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAUzB"}

package/dist/_/_union.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { getModelVariants } from "@metreeca/blue/union";
+import { isObject } from "@metreeca/core";
+import { isBranch } from "@metreeca/qest/template";
+/**
+ * Resolves which union variants a retrieval placeholder requests, and the sub-placeholder that projects
+ * each (union.md §Model).
+ *
+ * The model addresses a union in one of two forms:
+ *
+ *  - a **keyed** placeholder (an object whose keys are opaque `${number}` strings) supplies one
+ *    alternative per entry. Each alternative is matched independently against the variants by kind and
+ *    structure ({@link @metreeca/blue/union!getModelVariants | getModelVariants}), so one alternative may
+ *    reach several variants and one variant may be reached by several alternatives.
+ *  - any **other** placeholder is itself a single alternative, reaching every variant its kind fits.
+ *
+ * The result pairs each requested variant with the alternative that projects it. When several
+ * alternatives reach the same variant, the last in key order wins (plain `Map` semantics); the choice is
+ * immaterial, since same-variant alternatives project it identically. The map is the single source of
+ * truth shared by the encoder, which emits one arm per requested variant, and the decoder, which reads
+ * each requested variant's column and projects it through the paired alternative.
+ *
+ * @param variants The union variants to resolve against
+ * @param placeholder The union property's retrieval placeholder: a keyed alternative map, or a single
+ * alternative
+ *
+ * @returns Each requested variant mapped to its projecting alternative; empty when the placeholder
+ * requests no variant
+ */
+export function getUnionPlaceholders(variants, placeholder) {
+    const placeholders = isObject(placeholder, (_, key) => isBranch(key)) && Object.keys(placeholder).length > 0
+        ? Object.values(placeholder)
+        : [placeholder];
+    return new Map(placeholders.flatMap(alternative => (getModelVariants(alternative, variants) ?? []).map(variant => [variant, alternative])));
+}
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//# sourceMappingURL=_union.js.map

package/dist/_/_union.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_union.js","sourceRoot":"","sources":["../../src/_/_union.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,oBAAoB,CACnC,QAAsB,EACtB,WAAoB;IAGpB,MAAM,YAAY,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;QAC3G,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC;QAC5B,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAEjB,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CACjD,CAAC,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CACtF,CAAC,CAAC;AAEJ,CAAC;AAGD,wHAAwH"}

package/dist/detect/decode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Detect-pass result decoder.
+ *
+ * Settles each queued {@link Detect} against the existence query's solution tuples: the entries
+ * that came back are the candidates that are the subject of at least one stored triple. The subject
+ * token is recovered from the shared {@link Scope} threaded from the driver, so it matches the
+ * encoder's projection, and every request's deferred resolves to whether its entry is present.
+ *
+ * @module
+ */
+import type { Scope } from "@metreeca/core/scope";
+import type { Deferred, Detect } from "@metreeca/keep/batching";
+import type { Tuple, Variable } from "@metreeca/wire-sparql";
+/**
+ * Resolves a batch of detect requests against the existence query's present entries.
+ *
+ * Recovers the entries bound to the subject variable, folds them into a membership set, and settles
+ * each request's deferred to whether its `entry` is present.
+ *
+ * @param scope The shared variable scope, also threaded into the encoder
+ * @param batch The queued detect requests to settle, each carrying the `request` whose `entry` is tested
+ * @param tuples The solution tuples returned by the batched existence `select`
+ */
+export declare function decode(scope: Scope<Variable>, batch: readonly Deferred<Detect>[], tuples: readonly Tuple[]): void;
+//# sourceMappingURL=decode.d.ts.map

package/dist/detect/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/detect/decode.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG7D;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CACrB,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EACtB,KAAK,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,EAAE,EAClC,MAAM,EAAE,SAAS,KAAK,EAAE,GACtB,IAAI,CAaN"}

package/dist/detect/decode.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Resolves a batch of detect requests against the existence query's present entries.
+ *
+ * Recovers the entries bound to the subject variable, folds them into a membership set, and settles
+ * each request's deferred to whether its `entry` is present.
+ *
+ * @param scope The shared variable scope, also threaded into the encoder
+ * @param batch The queued detect requests to settle, each carrying the `request` whose `entry` is tested
+ * @param tuples The solution tuples returned by the batched existence `select`
+ */
+export function decode(scope, batch, tuples) {
+    const subject = scope.resolve(batch);
+    const entries = new Set(tuples.flatMap(tuple => {
+        const term = tuple[subject];
+        return term?.kind === "named" ? [term.iri] : [];
+    }));
+    batch.forEach(({ request, resolve }) => resolve(entries.has(request.entry)));
+}
+//# sourceMappingURL=decode.js.map

package/dist/detect/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../src/detect/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CACrB,KAAsB,EACtB,KAAkC,EAClC,MAAwB;IAGxB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAErC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;QAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,CAAC,CAAC,CAAC,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CACtC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACnC,CAAC;AAEH,CAAC"}

package/dist/detect/encode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Detect-pass query encoder.
+ *
+ * Folds a batch of candidate entries into one batched `select`: a `values` block binds every
+ * entry to the subject variable, a single triple pattern joins it as a subject, and `distinct`
+ * collapses the multiple triples each present entry produces. The projection returns exactly the
+ * entries that are the subject of at least one stored triple. Variables are allocated through the
+ * shared {@link Scope} threaded from the driver, so the decoder recovers the same subject token.
+ *
+ * @module
+ */
+import type { Scope } from "@metreeca/core/scope";
+import type { Deferred, Detect } from "@metreeca/keep/batching";
+import type { SPARQL, Variable } from "@metreeca/wire-sparql";
+/**
+ * Encodes the batched existence query for a set of candidate entries.
+ *
+ * @param scope The shared variable scope, also threaded into the decoder
+ * @param batch The candidate items to probe, each carrying the `request` whose `entry` is tested for existence
+ *
+ * @returns A `select distinct` query projecting the subject variable for every entry that is the
+ * subject of at least one stored triple; an entry with no triples yields no row
+ */
+export declare function encode(scope: Scope<Variable>, batch: readonly Deferred<Detect>[]): SPARQL;
+//# sourceMappingURL=encode.d.ts.map

package/dist/detect/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../../src/detect/encode.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAI9D;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CACrB,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EACtB,KAAK,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,EAAE,GAChC,MAAM,CAeR"}

package/dist/detect/encode.js

@@ -0,0 +1,30 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { distinct, edge, reference, select, values, variable, where } from "@metreeca/wire-sparql/builder";
+/**
+ * Encodes the batched existence query for a set of candidate entries.
+ *
+ * @param scope The shared variable scope, also threaded into the decoder
+ * @param batch The candidate items to probe, each carrying the `request` whose `entry` is tested for existence
+ *
+ * @returns A `select distinct` query projecting the subject variable for every entry that is the
+ * subject of at least one stored triple; an entry with no triples yields no row
+ */
+export function encode(scope, batch) {
+    const subject = scope.resolve(batch);
+    return select(distinct(variable(subject)), where(values([variable(subject)], batch.map(({ request }) => [reference(request.entry)])), edge(variable(subject), variable(scope.resolve()), variable(scope.resolve()))));
+}
+//# sourceMappingURL=encode.js.map

package/dist/detect/encode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.js","sourceRoot":"","sources":["../../src/detect/encode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAG3G;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CACrB,KAAsB,EACtB,KAAkC;IAGlC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAErC,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,CAC/C,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CACrD,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAC1B,CAAC,EACF,IAAI,CACH,QAAQ,CAAC,OAAO,CAAC,EACjB,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EACzB,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CACzB,CACD,CAAC,CAAC;AAEJ,CAAC"}

package/dist/detect/index.d.ts

@@ -0,0 +1,17 @@
+import type { Deferred, Detect } from "@metreeca/keep/batching";
+import { type RepositoryClient } from "@metreeca/wire-sparql";
+/**
+ * Per-batch body for the detect handler.
+ *
+ * Two phases run in sequence: **fetch** by folding the batch's candidate entries into one batched
+ * existence `select` through {@link encode} and running it; **deliver** by {@link decode | decoding}
+ * the solution to the present entries, folding them into a set, and resolving each request to whether
+ * its entry is present.
+ *
+ * @param batch The queued detect requests to resolve
+ * @param client The repository the existence query runs against
+ *
+ * @returns A promise settling once every request in the batch has been resolved
+ */
+export declare function detect(batch: readonly Deferred<Detect>[], client: RepositoryClient): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/detect/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/detect/index.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,uBAAuB,CAAC;AAKxE;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,EAAE,EAClC,MAAM,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAQf"}