# packages/core/src/features/viz/inspection/queries.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/dd39ce2036d0e4f9323e032ed48793453244d7ef/packages/core/src/features/viz/inspection/queries.ts#L123). [Back to reference](/reference/functions/rendered-series-inspection/)
1 import type {
2   NearestRecordedPointHit,
3   NearestRecordedXHit,
4   NumericDomainInterpolation,
5   NumericDuplicateResolver,
6   InspectionCandidate,
7   NumericRenderedFilter,
8   NumericRenderedObservation,
9   NumericRenderedSeries,
10   RecordedXSample,
11   RenderedSeriesPoint,
12 } from "./query-types.js";
13 
14 function finite(value: unknown, name: string): asserts value is number {
15   if (typeof value !== "number" || !Number.isFinite(value))
16     throw new RangeError(`${name} must be finite.`);
17 }
18 
19 function limit(value: number | undefined, name: string): void {
20   if (value === undefined) return;
21   finite(value, name);
22   if (value < 0) throw new RangeError(`${name} must be nonnegative.`);
23 }
24 
25 function point(value: Readonly<RenderedSeriesPoint>, name: string): void {
26   finite(value.x, `${name}.x`);
27   finite(value.y, `${name}.y`);
28 }
29 
30 function candidate<D>(
31   rendered: NumericRenderedSeries<D>,
32   observation: NumericRenderedObservation<D>,
33 ): InspectionCandidate<D> {
34   return Object.freeze({
35     ...observation,
36     anchorInsideClips: () =>
37       rendered.anchorInsideClips(observation.anchorLocal),
38   });
39 }
40 
41 function accepts<D>(
42   rendered: NumericRenderedSeries<D>,
43   observation: NumericRenderedObservation<D>,
44   filter: NumericRenderedFilter<D> | undefined,
45 ): boolean {
46   return filter === undefined || filter(candidate(rendered, observation));
47 }
48 
49 function anchored<D>(
50   rendered: NumericRenderedSeries<D>,
51   observation: NumericRenderedObservation<D>,
52 ): NumericRenderedObservation<D> {
53   return { ...observation, ...rendered.anchorAtDomain(observation) };
54 }
55 
56 /**
57  * Retains the first source observation at a duplicate domain coordinate.
58  *
59  * @param first - First selected observation at this domain coordinate.
60  * @param _next - Later observation at the same domain coordinate.
61  * @returns The earliest source observation.
62  * @see {@link NumericDuplicateResolver}
63  */
64 export function firstSourceObservation<D>(
65   first: NumericRenderedObservation<D>,
66   _next: NumericRenderedObservation<D>,
67 ): NumericRenderedObservation<D> {
68   return first;
69 }
70 
71 /**
72  * Replaces a source observation with the next one at a duplicate domain coordinate.
73  *
74  * @param _first - Earlier selected observation at this domain coordinate.
75  * @param next - Later observation at the same domain coordinate.
76  * @returns The latest source observation.
77  * @see {@link NumericDuplicateResolver}
78  */
79 export function lastSourceObservation<D>(
80   _first: NumericRenderedObservation<D>,
81   next: NumericRenderedObservation<D>,
82 ): NumericRenderedObservation<D> {
83   return next;
84 }
85 
86 /**
87  * Returns whether a filter candidate's anchor lies inside the committed clip stack.
88  *
89  * Pass this function as a query filter when visibility at the anchor is required.
90  * Queries otherwise examine all eligible rendered observations.
91  *
92  * @param candidate - Candidate whose committed local anchor should be clip-tested.
93  * @returns Whether the candidate anchor lies within every committed clip.
94  * @see {@link NumericRenderedFilter}
95  */
96 export function anchorInsideClips<D>(
97   candidate: InspectionCandidate<D>,
98 ): boolean {
99   return candidate.anchorInsideClips();
100 }
101 
102 /** Options for {@link nearestRecordedX}. */
103 export interface NearestRecordedXOptions<D> {
104   /** Numeric horizontal domain value to inspect, or undefined for no request. */
105   readonly domainX: number | undefined;
106   /** Maximum accepted absolute horizontal-domain delta. */
107   readonly maxDomainDelta?: number;
108   /** Further restricts committed observations for this request. */
109   readonly filter?: NumericRenderedFilter<D>;
110 }
111 
112 /**
113  * Finds the recorded observation nearest to a numeric horizontal domain value in O(n) time.
114  *
115  * Ties retain source order. Distance is measured in domain units, while both
116  * returned anchors retain their explicitly named local and root-logical units.
117  *
118  * @param rendered - Committed rendered-series generation to inspect synchronously.
119  * @param options - Domain position, optional limit, and observation filter.
120  * @returns The selected recorded observation, or undefined when none qualifies.
121  * @see {@link NearestRecordedXOptions}
122  */
123 export function nearestRecordedX<D>(
124   rendered: NumericRenderedSeries<D>,
125   options: NearestRecordedXOptions<D>,
126 ): NearestRecordedXHit<D> | undefined {
127   rendered.assertLive();
128   const query = options.domainX;
129   if (query === undefined) return undefined;
130   finite(query, "nearestRecordedX domainX");
131   limit(options.maxDomainDelta, "nearestRecordedX maxDomainDelta");
132   let best: NearestRecordedXHit<D> | undefined;
133   let delta = Infinity;
134   for (const observation of rendered.observations) {
135     if (!accepts(rendered, observation, options.filter)) continue;
136     const next = Math.abs(observation.domainX - query);
137     finite(next, "nearestRecordedX domain delta");
138     if (
139       next < delta &&
140       (options.maxDomainDelta === undefined || next <= options.maxDomainDelta)
141     ) {
142       delta = next;
143       best = Object.freeze({
144         ...anchored(rendered, observation),
145         domainDelta: next,
146       });
147     }
148   }
149   return best;
150 }
151 
152 /** Options for {@link nearestRecordedPoint}. */
153 export interface NearestRecordedPointOptions<D> {
154   /** Root-logical point to inspect, or undefined for no request. */
155   readonly rootPoint: Readonly<RenderedSeriesPoint> | undefined;
156   /** Maximum accepted Euclidean root-logical distance. */
157   readonly maxRootDistance?: number;
158   /** Further restricts committed observations for this request. */
159   readonly filter?: NumericRenderedFilter<D>;
160 }
161 
162 /**
163  * Finds the recorded observation nearest to a root-logical point in O(n) time.
164  *
165  * Ties retain source order. This query measures distance in root-logical units
166  * so it remains meaningful under nonuniform series transforms.
167  *
168  * @param rendered - Committed rendered-series generation to inspect synchronously.
169  * @param options - Root position, optional limit, and observation filter.
170  * @returns The selected recorded observation, or undefined when none qualifies.
171  * @see {@link NearestRecordedPointOptions}
172  */
173 export function nearestRecordedPoint<D>(
174   rendered: NumericRenderedSeries<D>,
175   options: NearestRecordedPointOptions<D>,
176 ): NearestRecordedPointHit<D> | undefined {
177   rendered.assertLive();
178   const query = options.rootPoint;
179   if (query === undefined) return undefined;
180   point(query, "nearestRecordedPoint rootPoint");
181   limit(options.maxRootDistance, "nearestRecordedPoint maxRootDistance");
182   let best: NearestRecordedPointHit<D> | undefined;
183   let distance = Infinity;
184   for (const observation of rendered.observations) {
185     if (!accepts(rendered, observation, options.filter)) continue;
186     const next = Math.hypot(
187       observation.anchorRoot.x - query.x,
188       observation.anchorRoot.y - query.y,
189     );
190     finite(next, "nearestRecordedPoint root distance");
191     if (
192       next < distance &&
193       (options.maxRootDistance === undefined || next <= options.maxRootDistance)
194     ) {
195       distance = next;
196       best = Object.freeze({
197         ...anchored(rendered, observation),
198         rootDistance: next,
199       });
200     }
201   }
202   return best;
203 }
204 
205 /** Options for {@link sampleRecordedX}. */
206 export interface SampleRecordedXOptions<D> {
207   /** Numeric horizontal domain value to sample, or undefined for no request. */
208   readonly domainX: number | undefined;
209   /** Computes the estimated numeric domain value between two recorded values. */
210   readonly interpolation: NumericDomainInterpolation;
211   /** Explicitly chooses one observation from each duplicate-domain group. */
212   readonly resolveDuplicate?: NumericDuplicateResolver<D>;
213   /** Maximum domain interval that may be interpolated across. */
214   readonly maxDomainGap?: number;
215   /** Further restricts committed observations for this request. */
216   readonly filter?: NumericRenderedFilter<D>;
217 }
218 
219 function resolvedRows<D>(
220   rendered: NumericRenderedSeries<D>,
221   filter: NumericRenderedFilter<D> | undefined,
222   resolver: NumericDuplicateResolver<D> | undefined,
223 ): readonly (readonly NumericRenderedObservation<D>[])[] {
224   let validatedRun: number | undefined;
225   let validatedX = -Infinity;
226   for (const observation of rendered.observations) {
227     finite(observation.domainX, "sampleRecordedX observation.domainX");
228     finite(observation.domainY, "sampleRecordedX observation.domainY");
229     if (validatedRun === observation.run && observation.domainX < validatedX)
230       throw new RangeError(
231         "sampleRecordedX requires nondecreasing domainX within each rendered run.",
232       );
233     validatedRun = observation.run;
234     validatedX = observation.domainX;
235   }
236   const runs: NumericRenderedObservation<D>[][] = [];
237   let current: NumericRenderedObservation<D>[] = [];
238   let previousRun: number | undefined;
239   const finish = () => {
240     if (current.length) runs.push(current);
241     current = [];
242     previousRun = undefined;
243   };
244   for (const observation of rendered.observations) {
245     if (previousRun !== undefined && observation.run !== previousRun) finish();
246     previousRun = observation.run;
247     if (!accepts(rendered, observation, filter)) {
248       finish();
249       continue;
250     }
251     current.push(observation);
252   }
253   finish();
254   return runs.map((run) => {
255     const resolved: NumericRenderedObservation<D>[] = [];
256     for (let start = 0; start < run.length;) {
257       let end = start + 1;
258       while (end < run.length && run[end]!.domainX === run[start]!.domainX)
259         end++;
260       let selected = run[start]!;
261       for (let duplicate = start + 1; duplicate < end; duplicate++) {
262         const next = run[duplicate]!;
263         if (resolver === undefined)
264           throw new RangeError(
265             "sampleRecordedX duplicate domainX requires resolveDuplicate.",
266           );
267         const resolved = resolver(selected, next);
268         if (resolved !== selected && resolved !== next)
269           throw new TypeError(
270             "sampleRecordedX resolveDuplicate must return its first or next observation.",
271           );
272         selected = resolved;
273       }
274       resolved.push(selected);
275       start = end;
276     }
277     return resolved;
278   });
279 }
280 
281 /**
282  * Returns an exact recorded observation or a caller-defined interpolation between records.
283  *
284  * It never bridges separate rendered runs, filtered observations, or an interval larger
285  * than `maxDomainGap`. Duplicate x values reject by default and require an explicit
286  * `resolveDuplicate` function. Estimated results retain their two source observations and
287  * map explicit local/root anchors through the committed generation. This is O(n) in captured
288  * observations and the result is borrowed until the rendered generation is replaced or disposed.
289  *
290  * @param rendered - Committed rendered-series generation to inspect synchronously.
291  * @param options - Domain position, interpolation, duplicate policy, and filter.
292  * @returns An exact record, an explicitly interpolated estimate, or undefined.
293  * @see {@link SampleRecordedXOptions}
294  */
295 export function sampleRecordedX<D>(
296   rendered: NumericRenderedSeries<D>,
297   options: SampleRecordedXOptions<D>,
298 ): RecordedXSample<D> | undefined {
299   rendered.assertLive();
300   const query = options.domainX;
301   if (query === undefined) return undefined;
302   finite(query, "sampleRecordedX domainX");
303   limit(options.maxDomainGap, "sampleRecordedX maxDomainGap");
304   if (typeof options.interpolation !== "function")
305     throw new TypeError("sampleRecordedX interpolation must be a function.");
306   if (
307     options.resolveDuplicate !== undefined &&
308     typeof options.resolveDuplicate !== "function"
309   )
310     throw new TypeError("sampleRecordedX resolveDuplicate must be a function.");
311   for (const run of resolvedRows(
312     rendered,
313     options.filter,
314     options.resolveDuplicate,
315   )) {
316     for (let index = 0; index < run.length; index++) {
317       const before = run[index]!;
318       if (before.domainX === query)
319         return Object.freeze({ ...anchored(rendered, before), kind: "exact" });
320       const after = run[index + 1];
321       if (!after || query <= before.domainX || query >= after.domainX) continue;
322       const gap = after.domainX - before.domainX;
323       finite(gap, "sampleRecordedX domain gap");
324       if (options.maxDomainGap !== undefined && gap > options.maxDomainGap)
325         return undefined;
326       const fraction = (query - before.domainX) / gap;
327       const domainY = options.interpolation(
328         before.domainY,
329         after.domainY,
330         fraction,
331       );
332       finite(domainY, "sampleRecordedX interpolation result");
333       return Object.freeze({
334         kind: "interpolated",
335         domainX: query,
336         domainY,
337         ...rendered.anchorAtDomain({ domainX: query, domainY }),
338         before,
339         after,
340         fraction,
341       });
342     }
343   }
344   return undefined;
345 }
346
## Documentation version Documentation built with @pibbl/core 0.0.2, revision dd39ce2. ALPHA — NOT FOR PRODUCTION USE.