@metreeca/blue - v0.10.0
    Preparing search index...

    Function effective

    • Resolve the effective RangeShape a Probe yields against a shape.

      Traverses the Probe.path segments through nested resource entries to locate the target shape, then applies the Probe.pipe transforms to compute the effective value set with accumulated cardinality.

      Shape dispatch:

      • ResourceShape: traverses path segments through nested entries
      • ReferenceShape: eagerly resolves the lazy target shape, then proceeds as for ResourceShape
      • UnionShape: seeds traversal with each variant, then proceeds as for the per-variant shape
      • RangeShape: re-probes a previously resolved range, seeding traversal with each variant carrying the range's own accumulated cardinality, then proceeds as for the per-variant shape
      • Other shapes: any non-empty path fails resolution; the empty path applies the transform pipe directly

      Path traversal — at each step, flattens inheritance and looks up the next property. Unknown entries cause the path to fail. At UnionShape boundaries (either at the entry or encountered as a property range), variants lacking the property are skipped; the path fails only when no variant defines it. Mid-path traversal past an id or type field fails as an "undefined property path", since these resolve to scalar IRIs with no traversable structure; terminal id/type access remains valid.

      Pipe application — applies transforms to the shape resolved by path traversal, reducing each active variant independently when multiple remain. A pipe composing more than one aggregate transform is rejected upfront as "multiple aggregate transforms", independently of the resolved shape. A non-empty pipe is coalesced access to a localised leaf: a dictionary shape contributes the winning tag's value(s) as an ordinary xsd:string for domain matching and effective typing, at the leaf's per-tag cardinality (one value for single-string-per-tag, the winning tag's set for array-per-tag). Among processing-space literals (boolean, numeric, plain or temporal string), a transform applied to a literal outside its declared domain drops the offending variant from the effective set: within a union this retains only the compatible branches, so the pipe is well-typed as long as at least one variant survives. The same dropping extends to values outside the processing space (references and resources), which no transform other than count can act on. When no variant survives, including a single non-union shape whose sole variant falls outside the pipe's domain, the probe reports "incompatible transform input". The count aggregate accepts any value, references included; min and max accept the literal processing types (boolean, numeric, string, temporal); the remaining transforms accept their declared processing type only. avg always yields a decimal: the specification narrows its range to float for float input and double for double input, but that processing-space distinction is not preserved on egress, so the effective type is reported uniformly as decimal. A transform declaring returns: "same" reproduces the input's processing type: min and max, which keep the value within the element domain, preserve the input shape verbatim (value-domain facets included), whereas sum combines values and escapes the element domain and datatype range, so it widens to the bare integer type for integral input or the bare decimal type otherwise, carrying no value-domain facets.

      Cardinality — per-step constraints combine multiplicatively within a branch and by envelope across sibling branches:

      • Within a branchminCount and maxCount are the products of per-step bounds; either becomes undefined if any step has that bound undefined. A 0 product stands (for minCount an equivalent encoding of "no lower bound", for maxCount the strongest upper bound).
      • Across branches — at entry-union or mid-path union-range crossings, the effective bounds are the envelope of per-branch products: minCount takes the lowest lower bound (undefined absorbs — no lower bound wins), maxCount takes the highest upper bound (undefined absorbs — unbounded wins). The effective range admits any reachable branch, so its cardinality envelopes them all; discrimination to the single driving branch is resolved separately against the model.
      • UnionShape steps themselves contribute no per-step cardinality — the enclosing range carries the single cardinality shared by all variants.
      • A localised step enters the product like any other: a dictionary property is terminal (no path may traverse past it) and contributes its per-tag bounds (maxCount of 1 for single-string-per-tag, unbounded for array-per-tag), which multiply into the branch product. A single-string-per-tag leaf is single-valued on its own, but a multi-valued prefix multiplies through, so a deep coalescible key is correctly multi-valued for the sort/focus single-valued gates while matching and filtering stay cardinality-agnostic.
      • A non-empty pipe sets minCount to 1 for the total aggregates count and sum, which always yield a value (0 on the empty set), and to undefined for every other transform; scalar transforms preserve maxCount; aggregate transforms set maxCount to 1.

      Parameters

      Returns string | RangeShape

      An immutable RangeShape effective type carrying the accumulated cardinality and the reachable value-shape variants when the probe resolves, deduplicated to distinct shapes so an aggregate or path that collapses the union onto one type yields a single variant. Returns an atomic Trace string when the probe cannot be resolved against the shape: "undefined property path" if the path fails to resolve (including a step past a non-traversable id / type field), "multiple aggregate transforms" if the pipe composes more than one aggregate transform, or "incompatible transform input" if no resolved variant lies within the transform pipe's declared domain

      If shape transitively references itself, producing a circular extends chain

      TypeError If probe is not a well-formed Probe (a malformed path/pipe, or a pipe referencing an unknown transform)