@johnhenry/math-sample 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @johnhenry/math-sample
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sampling for plots, as a library with no DOM in it. Give it a `(x) => number`
+(or an `@johnhenry/math` expression) and a viewport; get back `Float64Array`s
+with the poles and jumps already turned into gaps, plus the viewport maths,
+"nice" ticks and SVG path output a plot needs. Pure ESM, zero runtime
+dependencies, no globals beyond the language: it runs unchanged in a Web
+Worker, so a plotter can send it *sources and a viewport*, and transfer the
+arrays back.
+
+```bash
+npm install @johnhenry/math-sample
+```
+
+```ts
+import { sampleAdaptive, samplesToSvgPath, axesToSvg, niceTicks } from "@johnhenry/math-sample";
+import { compileExpression } from "@johnhenry/math-sample/expr"; // needs @johnhenry/math
+
+const f = compileExpression("a*sin(x)", { params: { a: 2 } });
+const view = { xMin: -10, xMax: 10, yMin: -6, yMax: 6 };
+
+const s = sampleAdaptive(f, { min: view.xMin, max: view.xMax }, 400, {
+  visibleYRange: { min: view.yMin, max: view.yMax },
+});
+s.x; s.y;                                    // Float64Array, NaN in y = gap
+samplesToSvgPath(s, view, 600, 300);         // "M0.00 150.00 L1.50 ..."
+```
+
+## API
+
+### Samples
+
+`Samples` is `{ x: Float64Array; y: Float64Array }`. A row with `y = NaN` is a
+gap: do not draw between its neighbours. Gaps are never first, last or
+adjacent to another gap, so `runsOf(samples)` (half-open row ranges) is exactly
+the polylines to draw.
+
+| Function | Does |
+|---|---|
+| `sampleUniform(f, domain, n, options?)` | `n` evenly spaced evaluations, both ends included |
+| `sampleAdaptive(f, domain, n, options?)` | the same base grid, with cells bisected where the curve bends |
+| `runsOf(samples)` | `[start, end)` row ranges of consecutive data |
+| `findDiscontinuities(samples)` | `{ before, after }` points either side of every gap |
+| `findCrossings(samples, signedDistance)` | interpolated crossings of a boundary (`y => y` is the x-axis); not across gaps |
+| `findRoots(f, domain, { resolution? })` | sign changes on a grid, polished by bisection; poles rejected |
+| `findIntersections(f, g, domain, opts?)` | roots of `f - g`, each with `y = f(x)` |
+| `toPoints(samples)` | `[x, y \| null][]`, JSON-safe |
+
+`f` is any `(x: number) => number`. Domains are `{ min, max }` (finite, `min < max`);
+`n` is an integer >= 2. Bad input throws `RangeError`.
+
+**Options (all samplers):**
+
+- `visibleYRange: { min, max }`: the y-range on screen. A sample far outside it
+  (a pole's finite but enormous shoulders) is treated as a gap, and the curve
+  is capped with an interpolated point just inside the edge, so it runs up to
+  the border of the plot instead of stopping short. Also sets the default
+  tolerance and, for `sampleAdaptive`, enables jump detection (`sampleUniform` does not detect jumps).
+- `signal` (`{ aborted: boolean }`, so any `AbortSignal`) and `isCancelled: () => boolean`:
+  checked every 256 evaluations; either one makes the sampler throw
+  `SampleCancelledError`. `isCancelled: () => generation !== latest` is the
+  generation-counter pattern for pan/zoom.
+
+**Options (`sampleAdaptive`):**
+
+- `maxDepth` (4): bisections per base cell.
+- `tolerance`: a cell is split while its midpoint is further than this, in y
+  units, from the straight line through its ends. Default `1e-4` of the visible
+  y span, so zooming in refines more and zooming out less; with no
+  `visibleYRange`, `1e-3`.
+- `jumpFraction` (0.5 with `visibleYRange`; off without): a cell still this far
+  apart (as a fraction of the y span) at `maxDepth`, whose height has not
+  shrunk as it was halved, is a jump (a step, a pole) and becomes a gap. A
+  steep slope loses height as it is halved, so it stays connected. `Infinity` turns it off.
+
+### Viewport
+
+`Viewport` is `{ xMin, xMax, yMin, yMax }`. Everything is unit-agnostic: use CSS
+pixels or device pixels, as long as width and height agree.
+
+`toScreenX/toScreenY(v, viewport, size)`, `toDataX/toDataY(s, viewport, size)`,
+`panViewport(v, dxPx, dyPx, w, h)` (content follows the pointer),
+`zoomViewport(v, factor, sx, sy, w, h)` (the data under the cursor stays put),
+`viewportFromAnchor(...)`, `wheelZoomFactor(deltaY, step?)`,
+`pinchZoomFactor(startDist, currentDist)`, `fitViewport(x, y, padding?)`, and
+`backingStoreSize(cssW, cssH, dpr)` which returns `{ width, height, scale }` for
+sizing a canvas: set `canvas.width/height` to those, `ctx.scale(scale, scale)`,
+and draw in CSS pixels. A non-finite or non-positive `dpr` counts as 1.
+
+### Ticks
+
+`niceTicks(min, max, target = 6)` gives round values (1, 2 or 5 times a power of
+ten) with no float drift (`0.3`, not `0.30000000000000004`). `tickStep` is the
+step it chose, and `formatTick(v, step)` labels with matching decimals.
+Degenerate or non-finite ranges give `[]`.
+
+### SVG
+
+`samplesToSvgPath(samples, viewport, w, h, { digits = 2 })` returns path data,
+one `M ... L ...` subpath per run. `axesToSvg(viewport, w, h, { targetTickCount, stroke, labelFill, fontSize })`
+returns `<line>`/`<text>` elements with inline attributes (axes at zero, or
+hugging the nearest edge with labels flipped inward). `svgDocument(w, h, content)`
+wraps them.
+
+### Expressions (`@johnhenry/math-sample/expr`)
+
+`compileExpression(exprOrSource, { variable = "x", params = {} })` returns a
+`(x) => number` from an `@johnhenry/math` `Expr` or source string. This is the
+only entry that needs `@johnhenry/math`, which is an **optional peer
+dependency**; the main entry never imports it. In a Worker: post the source
+string and params, compile there, sample, and `postMessage` the arrays with
+`[s.x.buffer, s.y.buffer]` as transferables.
+
+## What it does not do (yet)
+
+- **Implicit multiplication is opt-in.** `2x` fails to parse by default; write
+  `2*x`, or pass `compileExpression(src, { implicitMultiplication: true })`
+  (needs `@johnhenry/math` 0.1.0+; multi-letter variable names such as `theta`
+  then become products, use `x_1`).
+- **1D `y = f(x)` only.** Implicit/interval curves, parametric and polar,
+  surfaces, ODEs and series samplers are planned as later parts.
+- **Gaps from steep or fast-oscillating functions.** Jump detection is a
+  heuristic; a function that oscillates faster than the grid resolves can read
+  as a jump. Raise the resolution or `maxDepth`, or set `jumpFraction: Infinity`.
+- **Double-root and tangent roots are missed** by `findRoots` (no sign change).
+- **No memoization or debouncing.** Callers own caching; use `isCancelled` to
+  drop stale work.
+- **Typed output is `Float64Array` only.** Convert with `Float32Array.from(s.y)`
+  if you need less.
+
+## Tests
+
+`npm test -w @johnhenry/math-sample`. Golden values from NumPy, SciPy
+(`brentq`) and SymPy (pole locations) are committed in `test/fixtures/goldens.json`;
+regenerate with `scripts/generate-goldens.py` (the tests never call Python).
+Behaviour was designed against [mallory](https://github.com/johnhenry/mallory)'s
+samplers (MIT, same author); the code here is a rewrite.

package/dist/expr.d.ts

@@ -0,0 +1,26 @@
+import { type Expr } from "@johnhenry/math";
+import type { Fn1 } from "./sample.ts";
+export interface CompileOptions {
+    /** The free variable that becomes the argument. Default `"x"`. */
+    variable?: string;
+    /** Fixed values for every other free variable (slider values, say). */
+    params?: Record<string, number>;
+    /**
+     * Read juxtaposition as multiplication in source text (`2x`, `3sin(x)`, `(x+1)(x-1)`), the way people
+     * type maths. Default `false`. Needs `@johnhenry/math` 0.1.0 or later; multi-letter variable names are
+     * unavailable when it is on (see `ParseOptions` in `@johnhenry/math`). Ignored when `expr` is already a parsed `Expr`.
+     */
+    implicitMultiplication?: boolean;
+}
+/**
+ * Compile an `@johnhenry/math` expression (source text or a parsed `Expr`)
+ * into a plain `(x) => number` the samplers take. The AST is walked once; the
+ * closure is cheap to call thousands of times. This is the only module that
+ * needs `@johnhenry/math` (an optional peer dependency), so a Worker can
+ * receive an expression string plus params, compile it here, and sample.
+ *
+ * Source text uses `@johnhenry/math`'s grammar: write `2*x`, or pass
+ * `implicitMultiplication: true` to accept `2x`.
+ */
+export declare function compileExpression(expr: Expr | string, options?: CompileOptions): Fn1;
+//# sourceMappingURL=expr.d.ts.map

package/dist/expr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr.d.ts","sourceRoot":"","sources":["../src/expr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAY,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,GAAG,CAYxF"}

package/dist/expr.js

@@ -0,0 +1,24 @@
+import { Symbolic } from "@johnhenry/math";
+/**
+ * Compile an `@johnhenry/math` expression (source text or a parsed `Expr`)
+ * into a plain `(x) => number` the samplers take. The AST is walked once; the
+ * closure is cheap to call thousands of times. This is the only module that
+ * needs `@johnhenry/math` (an optional peer dependency), so a Worker can
+ * receive an expression string plus params, compile it here, and sample.
+ *
+ * Source text uses `@johnhenry/math`'s grammar: write `2*x`, or pass
+ * `implicitMultiplication: true` to accept `2x`.
+ */
+export function compileExpression(expr, options = {}) {
+    const variable = options.variable ?? "x";
+    const tree = typeof expr === "string"
+        ? Symbolic.parse(expr, { implicitMultiplication: options.implicitMultiplication === true })
+        : expr;
+    const compiled = Symbolic.compile(tree);
+    const env = { ...options.params, [variable]: 0 };
+    return (x) => {
+        env[variable] = x;
+        return compiled(env);
+    };
+}
+//# sourceMappingURL=expr.js.map

package/dist/expr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expr.js","sourceRoot":"","sources":["../src/expr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAgBtD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAmB,EAAE,UAA0B,EAAE;IACjF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IACzC,MAAM,IAAI,GACR,OAAO,IAAI,KAAK,QAAQ;QACtB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,sBAAsB,EAAE,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;QAC3F,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,GAAG,GAA2B,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IACzE,OAAO,CAAC,CAAC,EAAE,EAAE;QACX,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAClB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type AdaptiveOptions, type CancelSignal, type Domain, type Fn1, findCrossings, findDiscontinuities, findIntersections, findRoots, type Point, type RootOptions, runsOf, SampleCancelledError, type SampleOptions, type Samples, sampleAdaptive, sampleUniform, toPoints, type YRange, } from "./sample.ts";
+export { type AxesOptions, axesToSvg, type PathOptions, samplesToSvgPath, svgDocument, type XY } from "./svg.ts";
+export { formatTick, niceTicks, tickStep } from "./ticks.ts";
+export { backingStoreSize, fitViewport, panViewport, pinchZoomFactor, toDataX, toDataY, toScreenX, toScreenY, type Viewport, viewportFromAnchor, wheelZoomFactor, zoomViewport, } from "./viewport.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,GAAG,EACR,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,MAAM,EACN,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,KAAK,MAAM,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,MAAM,UAAU,CAAC;AACjH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,eAAe,EACf,OAAO,EACP,OAAO,EACP,SAAS,EACT,SAAS,EACT,KAAK,QAAQ,EACb,kBAAkB,EAClB,eAAe,EACf,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { findCrossings, findDiscontinuities, findIntersections, findRoots, runsOf, SampleCancelledError, sampleAdaptive, sampleUniform, toPoints, } from "./sample.js";
+export { axesToSvg, samplesToSvgPath, svgDocument } from "./svg.js";
+export { formatTick, niceTicks, tickStep } from "./ticks.js";
+export { backingStoreSize, fitViewport, panViewport, pinchZoomFactor, toDataX, toDataY, toScreenX, toScreenY, viewportFromAnchor, wheelZoomFactor, zoomViewport, } from "./viewport.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EAGT,MAAM,EACN,oBAAoB,EAGpB,cAAc,EACd,aAAa,EACb,QAAQ,GAET,MAAM,aAAa,CAAC;AACrB,OAAO,EAAoB,SAAS,EAAoB,gBAAgB,EAAE,WAAW,EAAW,MAAM,UAAU,CAAC;AACjH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,eAAe,EACf,OAAO,EACP,OAAO,EACP,SAAS,EACT,SAAS,EAET,kBAAkB,EAClB,eAAe,EACf,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/sample.d.ts

@@ -0,0 +1,114 @@
+/** A real function of one variable, e.g. a compiled expression. */
+export type Fn1 = (x: number) => number;
+/** A closed interval of the x-axis. */
+export interface Domain {
+    min: number;
+    max: number;
+}
+/** The y-range currently on screen; lets the sampler cap blow-ups and scale its tolerance. */
+export interface YRange {
+    min: number;
+    max: number;
+}
+/**
+ * Sampled curve as two parallel typed arrays. A row whose `y` is `NaN` is a
+ * gap: the curve is not drawn between the rows on either side of it (a pole,
+ * a domain edge, a jump). Gaps are never first, last, or adjacent to another
+ * gap.
+ */
+export interface Samples {
+    x: Float64Array;
+    y: Float64Array;
+}
+/** Anything that looks like an `AbortSignal`; kept structural so the package needs no DOM or Node types. */
+export interface CancelSignal {
+    readonly aborted: boolean;
+}
+export interface SampleOptions {
+    /**
+     * The y-range on screen. Samples far outside it (a pole's shoulders, which
+     * are finite but huge) are treated as gaps, and the curve is capped with an
+     * interpolated point at the edge of the range. Also sets the default
+     * adaptive tolerance, and (for `sampleAdaptive` only; `sampleUniform` does
+     * not detect jumps) enables jump detection.
+     */
+    visibleYRange?: YRange;
+    /** Abort when `signal.aborted` becomes true. Checked every few hundred evaluations. */
+    signal?: CancelSignal;
+    /** Polled alongside `signal`; return true to abort (the generation-counter pattern: `() => gen !== latest`). */
+    isCancelled?: () => boolean;
+}
+export interface AdaptiveOptions extends SampleOptions {
+    /** How many times one base-grid cell may be bisected. Default 4. */
+    maxDepth?: number;
+    /**
+     * Bisect a cell while its midpoint sits further than this (in y units) from
+     * the straight line between its ends. Default: `1e-4` of the visible y span
+     * when `visibleYRange` is given, else `1e-3`.
+     */
+    tolerance?: number;
+    /**
+     * A cell that is still this far apart at `maxDepth` (as a fraction of the
+     * visible y span) is a jump, not a steep slope, and becomes a gap. Default
+     * `0.5` when `visibleYRange` is given; with no range there is no scale to
+     * judge against and jumps are not detected. `Infinity` disables it. To tell
+     * a jump from a steep slope, the height must also persist (at least 80%)
+     * from the parent cell to the finest one. A function that oscillates faster
+     * than the grid can resolve can still look like a jump; raise the
+     * resolution or `maxDepth`.
+     */
+    jumpFraction?: number;
+}
+/** Thrown by the samplers when `signal` or `isCancelled` reports cancellation. */
+export declare class SampleCancelledError extends Error {
+    constructor();
+}
+/** Evaluate `f` at `resolution` evenly spaced points over `domain` (both ends included). */
+export declare function sampleUniform(f: Fn1, domain: Domain, resolution: number, options?: SampleOptions): Samples;
+/**
+ * Like {@link sampleUniform}, but bisects each cell of the base grid where the
+ * curve bends: a cell is split while its midpoint deviates from the straight
+ * line through its ends by more than the tolerance, up to `maxDepth` times. A
+ * straight stretch costs nothing extra; a sharp bend or narrow spike that a
+ * uniform grid would straddle is resolved. Cells that still jump at the
+ * deepest level become gaps (see `jumpFraction`).
+ */
+export declare function sampleAdaptive(f: Fn1, domain: Domain, baseResolution: number, options?: AdaptiveOptions): Samples;
+/** Half-open row ranges `[start, end)` of consecutive data rows, i.e. the polylines to draw. */
+export declare function runsOf(samples: Samples): [number, number][];
+/**
+ * The two edges of every gap: the last point before it and the first after.
+ * Where the curve really breaks lies between them; the distance is at most one
+ * sampling cell, so mark both edges rather than guessing a position.
+ */
+export declare function findDiscontinuities(samples: Samples): {
+    before: Point;
+    after: Point;
+}[];
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Where the polyline crosses a boundary. `signedDistance(y)` is negative on
+ * one side and non-negative on the other, and linear in y (`y` for the x-axis,
+ * `y - c` for the line y = c), so zero can be interpolated between two rows.
+ * Pairs across a gap never count.
+ */
+export declare function findCrossings(samples: Samples, signedDistance: (y: number) => number): Point[];
+export interface RootOptions extends SampleOptions {
+    /** Grid points scanned for sign changes. Default 1000. */
+    resolution?: number;
+}
+/**
+ * Roots of `f` on `domain`: scan a uniform grid for sign changes (or exact
+ * zeros) and polish each by bisection. Poles (sign change through infinity)
+ * are not roots and are rejected. Roots where `f` only touches zero without
+ * changing sign (such as x^2 at 0) fall between grid points and are missed.
+ */
+export declare function findRoots(f: Fn1, domain: Domain, options?: RootOptions): number[];
+/** Where `f` and `g` meet on `domain`: the roots of `f - g`, each with `y = f(x)`. Same caveats as {@link findRoots}. */
+export declare function findIntersections(f: Fn1, g: Fn1, domain: Domain, options?: RootOptions): Point[];
+/** `[x, y]` pairs as plain arrays, with `y = null` at gaps (JSON-safe, unlike NaN). */
+export declare function toPoints(samples: Samples): [number, number | null][];
+//# sourceMappingURL=sample.d.ts.map

package/dist/sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample.d.ts","sourceRoot":"","sources":["../src/sample.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAExC,uCAAuC;AACvC,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,8FAA8F;AAC9F,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,YAAY,CAAC;IAChB,CAAC,EAAE,YAAY,CAAC;CACjB;AAED,4GAA4G;AAC5G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,gHAAgH;IAChH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAsGD,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAY9G;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CA6DrH;AAED,gGAAgG;AAChG,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAa3D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,EAAE,CAUvF;AAED,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,EAAE,CAe9F;AAED,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,EAAE,CAyCrF;AAED,yHAAyH;AACzH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,KAAK,EAAE,CAEpG;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,EAAE,CAOpE"}

package/dist/sample.js

@@ -0,0 +1,308 @@
+/** Thrown by the samplers when `signal` or `isCancelled` reports cancellation. */
+export class SampleCancelledError extends Error {
+    constructor() {
+        super("sampling cancelled");
+        this.name = "SampleCancelledError";
+    }
+}
+const CANCEL_CHECK_INTERVAL = 256;
+const DEFAULT_MAX_DEPTH = 4;
+const FALLBACK_TOLERANCE = 1e-3;
+const RELATIVE_TOLERANCE = 1e-4;
+const DEFAULT_JUMP_FRACTION = 0.5;
+const JUMP_PERSISTENCE = 0.8;
+function checkDomain(domain, resolution) {
+    if (!Number.isFinite(domain.min) || !Number.isFinite(domain.max) || !(domain.max > domain.min)) {
+        throw new RangeError(`domain must be finite with min < max, got [${domain.min}, ${domain.max}]`);
+    }
+    if (!Number.isInteger(resolution) || resolution < 2) {
+        throw new RangeError(`resolution must be an integer >= 2, got ${resolution}`);
+    }
+}
+function guardedEval(f, options) {
+    const { signal, isCancelled } = options;
+    if (!signal && !isCancelled)
+        return f;
+    let count = 0;
+    const poll = () => {
+        if (signal?.aborted || isCancelled?.())
+            throw new SampleCancelledError();
+    };
+    poll();
+    return (x) => {
+        if (++count % CANCEL_CHECK_INTERVAL === 0)
+            poll();
+        return f(x);
+    };
+}
+function isOffRange(y, range) {
+    if (!range)
+        return false;
+    const span = range.max - range.min;
+    return Math.abs(y) > Math.abs(range.min) + Math.abs(range.max) + 5 * span;
+}
+/** Where segment a-b crosses the nearer edge of `range`, inset 3% so end markers are not clipped. Null if undefined. */
+function edgeCrossing(ax, ay, bx, by, range) {
+    if (!range || !Number.isFinite(ay) || !Number.isFinite(by) || ay === by)
+        return null;
+    const span = range.max - range.min;
+    const edge = by > ay ? range.max - 0.03 * span : range.min + 0.03 * span;
+    const t = (edge - ay) / (by - ay);
+    if (!Number.isFinite(t) || t < 0 || t > 1)
+        return null;
+    return [ax + t * (bx - ax), edge];
+}
+/** Turn raw points (NaN / Infinity / off-range = invalid) into the gap-marked `Samples` form. */
+function toSamples(rx, ry, range) {
+    const ox = [];
+    const oy = [];
+    let prevValid = false;
+    let px = 0;
+    let py = 0;
+    let havePrev = false;
+    for (let i = 0; i < rx.length; i++) {
+        const x = rx[i];
+        const y = ry[i];
+        const finite = Number.isFinite(y);
+        const valid = finite && !isOffRange(y, range);
+        if (valid) {
+            if (!prevValid && havePrev) {
+                const e = edgeCrossing(px, py, x, y, range);
+                if (e) {
+                    ox.push(e[0]);
+                    oy.push(e[1]);
+                }
+            }
+            ox.push(x);
+            oy.push(y);
+        }
+        else {
+            if (oy.length > 0 && !Number.isNaN(oy[oy.length - 1])) {
+                if (prevValid && finite) {
+                    const e = edgeCrossing(px, py, x, y, range);
+                    if (e) {
+                        ox.push(e[0]);
+                        oy.push(e[1]);
+                    }
+                }
+                ox.push(x);
+                oy.push(Number.NaN);
+            }
+        }
+        px = x;
+        py = y;
+        prevValid = valid;
+        havePrev = true;
+    }
+    if (oy.length > 0 && Number.isNaN(oy[oy.length - 1])) {
+        ox.pop();
+        oy.pop();
+    }
+    return { x: Float64Array.from(ox), y: Float64Array.from(oy) };
+}
+/** Evaluate `f` at `resolution` evenly spaced points over `domain` (both ends included). */
+export function sampleUniform(f, domain, resolution, options = {}) {
+    checkDomain(domain, resolution);
+    const g = guardedEval(f, options);
+    const rx = new Array(resolution);
+    const ry = new Array(resolution);
+    const span = domain.max - domain.min;
+    for (let i = 0; i < resolution; i++) {
+        const x = i === resolution - 1 ? domain.max : domain.min + (i / (resolution - 1)) * span;
+        rx[i] = x;
+        ry[i] = g(x);
+    }
+    return toSamples(rx, ry, options.visibleYRange);
+}
+/**
+ * Like {@link sampleUniform}, but bisects each cell of the base grid where the
+ * curve bends: a cell is split while its midpoint deviates from the straight
+ * line through its ends by more than the tolerance, up to `maxDepth` times. A
+ * straight stretch costs nothing extra; a sharp bend or narrow spike that a
+ * uniform grid would straddle is resolved. Cells that still jump at the
+ * deepest level become gaps (see `jumpFraction`).
+ */
+export function sampleAdaptive(f, domain, baseResolution, options = {}) {
+    checkDomain(domain, baseResolution);
+    const range = options.visibleYRange;
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const tolerance = options.tolerance ?? (range ? (range.max - range.min) * RELATIVE_TOLERANCE : FALLBACK_TOLERANCE);
+    const jumpFraction = options.jumpFraction ?? (range ? DEFAULT_JUMP_FRACTION : Number.POSITIVE_INFINITY);
+    const jumpAbs = range ? jumpFraction * (range.max - range.min) : Number.POSITIVE_INFINITY;
+    const g = guardedEval(f, options);
+    const rx = [];
+    const ry = [];
+    // Pushes `a` and the refinement points strictly between a and b (not b).
+    const refine = (ax, ay, bx, by, depth, parentDy) => {
+        if (!Number.isFinite(ay) || !Number.isFinite(by) || isOffRange(ay, range) || isOffRange(by, range)) {
+            rx.push(ax);
+            ry.push(ay);
+            return;
+        }
+        if (depth >= maxDepth) {
+            rx.push(ax);
+            ry.push(ay);
+            const dy = Math.abs(by - ay);
+            // A jump keeps its height as the cell halves; a steep slope loses about half of it per halving.
+            if (dy > jumpAbs && dy >= JUMP_PERSISTENCE * parentDy) {
+                rx.push((ax + bx) / 2);
+                ry.push(Number.NaN);
+            }
+            return;
+        }
+        const mx = (ax + bx) / 2;
+        const my = g(mx);
+        // A non-finite midpoint is a singularity between a and b: record it as the gap it is.
+        if (!Number.isFinite(my)) {
+            rx.push(ax, mx);
+            ry.push(ay, my);
+            return;
+        }
+        if (Math.abs(my - (ay + by) / 2) <= tolerance) {
+            rx.push(ax);
+            ry.push(ay);
+            return;
+        }
+        const dy = Math.abs(by - ay);
+        refine(ax, ay, mx, my, depth + 1, dy);
+        refine(mx, my, bx, by, depth + 1, dy);
+    };
+    const span = domain.max - domain.min;
+    let lx = domain.min;
+    let ly = g(lx);
+    for (let i = 1; i < baseResolution; i++) {
+        const x = i === baseResolution - 1 ? domain.max : domain.min + (i / (baseResolution - 1)) * span;
+        const y = g(x);
+        refine(lx, ly, x, y, 0, Number.POSITIVE_INFINITY);
+        lx = x;
+        ly = y;
+    }
+    rx.push(lx);
+    ry.push(ly);
+    return toSamples(rx, ry, range);
+}
+/** Half-open row ranges `[start, end)` of consecutive data rows, i.e. the polylines to draw. */
+export function runsOf(samples) {
+    const runs = [];
+    let start = -1;
+    for (let i = 0; i < samples.y.length; i++) {
+        if (Number.isNaN(samples.y[i])) {
+            if (start >= 0)
+                runs.push([start, i]);
+            start = -1;
+        }
+        else if (start < 0) {
+            start = i;
+        }
+    }
+    if (start >= 0)
+        runs.push([start, samples.y.length]);
+    return runs;
+}
+/**
+ * The two edges of every gap: the last point before it and the first after.
+ * Where the curve really breaks lies between them; the distance is at most one
+ * sampling cell, so mark both edges rather than guessing a position.
+ */
+export function findDiscontinuities(samples) {
+    const out = [];
+    for (let i = 1; i < samples.y.length - 1; i++) {
+        if (!Number.isNaN(samples.y[i]))
+            continue;
+        out.push({
+            before: { x: samples.x[i - 1], y: samples.y[i - 1] },
+            after: { x: samples.x[i + 1], y: samples.y[i + 1] },
+        });
+    }
+    return out;
+}
+/**
+ * Where the polyline crosses a boundary. `signedDistance(y)` is negative on
+ * one side and non-negative on the other, and linear in y (`y` for the x-axis,
+ * `y - c` for the line y = c), so zero can be interpolated between two rows.
+ * Pairs across a gap never count.
+ */
+export function findCrossings(samples, signedDistance) {
+    const out = [];
+    for (const [start, end] of runsOf(samples)) {
+        for (let i = start + 1; i < end; i++) {
+            const d0 = signedDistance(samples.y[i - 1]);
+            const d1 = signedDistance(samples.y[i]);
+            if (d0 >= 0 === d1 >= 0)
+                continue;
+            const t = d0 / (d0 - d1);
+            out.push({
+                x: samples.x[i - 1] + t * (samples.x[i] - samples.x[i - 1]),
+                y: samples.y[i - 1] + t * (samples.y[i] - samples.y[i - 1]),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Roots of `f` on `domain`: scan a uniform grid for sign changes (or exact
+ * zeros) and polish each by bisection. Poles (sign change through infinity)
+ * are not roots and are rejected. Roots where `f` only touches zero without
+ * changing sign (such as x^2 at 0) fall between grid points and are missed.
+ */
+export function findRoots(f, domain, options = {}) {
+    const n = options.resolution ?? 1000;
+    checkDomain(domain, n);
+    const g = guardedEval(f, options);
+    const span = domain.max - domain.min;
+    const roots = [];
+    let ax = domain.min;
+    let ay = g(ax);
+    if (ay === 0)
+        roots.push(ax);
+    for (let i = 1; i < n; i++) {
+        const bx = i === n - 1 ? domain.max : domain.min + (i / (n - 1)) * span;
+        const by = g(bx);
+        if (by === 0) {
+            roots.push(bx);
+        }
+        else if (Number.isFinite(ay) && Number.isFinite(by) && ay !== 0 && ay < 0 !== by < 0) {
+            let lo = ax;
+            let hi = bx;
+            let flo = ay;
+            for (let k = 0; k < 100; k++) {
+                const mid = (lo + hi) / 2;
+                if (mid === lo || mid === hi)
+                    break;
+                const fm = g(mid);
+                if (fm === 0) {
+                    lo = hi = mid;
+                    break;
+                }
+                if (flo < 0 === fm < 0) {
+                    lo = mid;
+                    flo = fm;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            const r = (lo + hi) / 2;
+            const fr = g(r);
+            if (Math.abs(fr) <= Math.max(Math.abs(ay), Math.abs(by)))
+                roots.push(r);
+        }
+        ax = bx;
+        ay = by;
+    }
+    return roots;
+}
+/** Where `f` and `g` meet on `domain`: the roots of `f - g`, each with `y = f(x)`. Same caveats as {@link findRoots}. */
+export function findIntersections(f, g, domain, options = {}) {
+    return findRoots((x) => f(x) - g(x), domain, options).map((x) => ({ x, y: f(x) }));
+}
+/** `[x, y]` pairs as plain arrays, with `y = null` at gaps (JSON-safe, unlike NaN). */
+export function toPoints(samples) {
+    const out = new Array(samples.x.length);
+    for (let i = 0; i < out.length; i++) {
+        const y = samples.y[i];
+        out[i] = [samples.x[i], Number.isNaN(y) ? null : y];
+    }
+    return out;
+}
+//# sourceMappingURL=sample.js.map