curvy 2.0.0-alpha.2 → 2.0.0-alpha.5

package/dist/interval/interval.d.ts

@@ -0,0 +1,525 @@
+import type { Pipeable } from '../utils';
+/**
+ * The structural minimum: any value with numeric `start` and `end` fields.
+ *
+ * Operations that don't read endpoint inclusivity (e.g. `lerp`, `normalize`,
+ * `remap`, `size`) accept `Bounds` so the signature itself documents what
+ * the operation depends on.
+ *
+ * @since 2.0.0
+ */
+export interface Bounds {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * A mathematical interval. Discriminated union of four variants by endpoint
+ * inclusivity: `Closed`, `OpenStart`, `OpenEnd`, `Open`. Operations that
+ * depend on inclusivity (e.g. `contains`, `filter`, `equals`) dispatch on
+ * the `kind` field; operations that don't accept the broader `Bounds` type.
+ *
+ * All fields are readonly and immutable, and all operations create new instances.
+ *
+ * @since 1.0.0
+ */
+export type Interval = Closed | OpenStart | OpenEnd | Open;
+/**
+ * `[start, end]` — both endpoints included.
+ *
+ * @since 2.0.0
+ */
+export interface Closed extends Pipeable, Bounds {
+    readonly kind: 'closed';
+}
+/**
+ * `(start, end]` — start excluded, end included.
+ *
+ * @since 2.0.0
+ */
+export interface OpenStart extends Pipeable, Bounds {
+    readonly kind: 'open-start';
+}
+/**
+ * `[start, end)` — start included, end excluded.
+ *
+ * @since 2.0.0
+ */
+export interface OpenEnd extends Pipeable, Bounds {
+    readonly kind: 'open-end';
+}
+/**
+ * `(start, end)` — both endpoints excluded.
+ *
+ * @since 2.0.0
+ */
+export interface Open extends Pipeable, Bounds {
+    readonly kind: 'open';
+}
+/**
+ * Checks if a value is an `Interval`.
+ *
+ * @param v - The value to check.
+ * @returns `true` if the value is an `Interval`, `false` otherwise.
+ * @since 1.0.0
+ */
+export declare const isInterval: (v: unknown) => v is Interval;
+export declare const equals: {
+    /**
+     * Checks if two `Interval` instances are approximately equal within the
+     * default absolute tolerance ({@link EPSILON}).
+     *
+     * Both endpoints AND the kind must match — a `Closed` and an `OpenStart` with
+     * the same numeric endpoints are not equal. Use `aligned` for the looser
+     * "same numeric range" check.
+     *
+     * @param a - The first interval.
+     * @param b - The second interval.
+     * @returns `true` when both intervals share a kind and both endpoints are within tolerance.
+     * @since 1.1.0
+     */
+    (a: Interval, b: Interval): boolean;
+    /**
+     * Checks if two `Interval` instances are approximately equal within the
+     * default absolute tolerance ({@link EPSILON}).
+     *
+     * @param b - The second interval.
+     * @returns A function that takes the first interval and returns the comparison result.
+     * @since 1.1.0
+     */
+    (b: Interval): (a: Interval) => boolean;
+};
+export declare const aligned: {
+    /**
+     * Checks if two values share the same numeric range, ignoring endpoint
+     * inclusivity. Accepts any `Bounds`-shaped value.
+     *
+     * @param a - The first bounds.
+     * @param b - The second bounds.
+     * @returns `true` when both endpoints are within the default tolerance ({@link EPSILON}).
+     * @since 2.0.0
+     */
+    (a: Bounds, b: Bounds): boolean;
+    /**
+     * @param b - The second bounds.
+     * @returns A function that takes the first bounds and returns the comparison result.
+     * @since 2.0.0
+     */
+    (b: Bounds): (a: Bounds) => boolean;
+};
+export declare const make: {
+    /**
+     * Creates a new closed `Interval` instance.
+     *
+     * @param point - The point of the interval.
+     * @returns A new `Closed` interval `[point, point]`.
+     * @since 1.0.0
+     */
+    (point: number): Closed;
+    /**
+     * Creates a new closed `Interval` instance.
+     *
+     * @param start - The start of the interval.
+     * @param end - The end of the interval.
+     * @returns A new `Closed` interval `[start, end]`.
+     * @since 1.0.0
+     */
+    (start: number, end: number): Closed;
+};
+export declare const makeOpenStart: {
+    /**
+     * Creates a new left-open `Interval` instance.
+     *
+     * @param point - The point of the interval.
+     * @returns A new `OpenStart` interval `(point, point]` (degenerate, empty).
+     * @since 2.0.0
+     */
+    (point: number): OpenStart;
+    /**
+     * Creates a new left-open `Interval` instance.
+     *
+     * @param start - The start of the interval (excluded).
+     * @param end - The end of the interval (included).
+     * @returns A new `OpenStart` interval `(start, end]`.
+     * @since 2.0.0
+     */
+    (start: number, end: number): OpenStart;
+};
+export declare const makeOpenEnd: {
+    /**
+     * Creates a new right-open `Interval` instance.
+     *
+     * @param point - The point of the interval.
+     * @returns A new `OpenEnd` interval `[point, point)` (degenerate, empty).
+     * @since 2.0.0
+     */
+    (point: number): OpenEnd;
+    /**
+     * Creates a new right-open `Interval` instance.
+     *
+     * @param start - The start of the interval (included).
+     * @param end - The end of the interval (excluded).
+     * @returns A new `OpenEnd` interval `[start, end)`.
+     * @since 2.0.0
+     */
+    (start: number, end: number): OpenEnd;
+};
+export declare const makeOpen: {
+    /**
+     * Creates a new fully open `Interval` instance.
+     *
+     * @param point - The point of the interval.
+     * @returns A new `Open` interval `(point, point)` (degenerate, empty).
+     * @since 2.0.0
+     */
+    (point: number): Open;
+    /**
+     * Creates a new fully open `Interval` instance.
+     *
+     * @param start - The start of the interval (excluded).
+     * @param end - The end of the interval (excluded).
+     * @returns A new `Open` interval `(start, end)`.
+     * @since 2.0.0
+     */
+    (start: number, end: number): Open;
+};
+export declare const fromSize: {
+    /**
+     * Creates a new closed `Interval` instance from a size.
+     *
+     * @param size - The size of the interval.
+     * @returns A new `Closed` interval `[0, size]`.
+     * @since 1.0.0
+     */
+    (size: number): Closed;
+    /**
+     * Creates a new closed `Interval` instance from a size.
+     *
+     * @param start - The start of the interval.
+     * @param size - The size of the interval.
+     * @returns A new `Closed` interval `[start, start + size]`.
+     * @since 1.0.0
+     */
+    (start: number, size: number): Closed;
+};
+/**
+ * Creates a new closed `Interval` from a minimum and maximum value, in any order.
+ *
+ * @param values - The values to take the min and max of.
+ * @returns A new `Closed` interval `[min(values), max(values)]`.
+ * @since 1.0.0
+ */
+export declare const fromMinMax: (...values: ReadonlyArray<number>) => Closed;
+/**
+ * Calculates the size of an interval.
+ *
+ * Kind-agnostic — `size` of `[0, 1]` and `(0, 1)` are both `1`.
+ *
+ * @param i - The bounds to calculate the size of.
+ * @returns The size of the bounds.
+ * @since 1.0.0
+ */
+export declare const size: (i: Bounds) => number;
+export declare const contains: {
+    /**
+     * Checks if a value is contained within an interval. Endpoint inclusivity
+     * follows the interval's `kind`.
+     *
+     * @param interval - The interval to check.
+     * @param value - The value to check.
+     * @returns `true` if the value is contained within the interval, `false` otherwise.
+     * @since 1.0.0
+     */
+    (interval: Interval, value: number): boolean;
+    /**
+     * Checks if a value is contained within an interval. Endpoint inclusivity
+     * follows the interval's `kind`.
+     *
+     * @param value - The value to check.
+     * @returns A function that takes an interval and returns `true` if the value is contained within the interval, `false` otherwise.
+     * @since 1.0.0
+     */
+    (value: number): (interval: Interval) => boolean;
+};
+export declare const containsInterval: {
+    /**
+     * Checks if `inner` is a subset of `outer` — every point of `inner` is also
+     * in `outer`. Respects endpoint inclusivity on both sides: a closed inner
+     * endpoint must be inside (or on a closed boundary of) the outer, while an
+     * open inner endpoint can sit exactly on an open outer boundary.
+     *
+     * @param outer - The enclosing interval.
+     * @param inner - The candidate inner interval.
+     * @returns `true` when `inner` is a subset of `outer`.
+     * @since 2.0.0
+     */
+    (outer: Interval, inner: Interval): boolean;
+    /**
+     * @param inner - The candidate inner interval.
+     * @returns A function that takes the outer interval and returns the containment result.
+     * @since 2.0.0
+     */
+    (inner: Interval): (outer: Interval) => boolean;
+};
+export declare const union: {
+    /**
+     * Returns the smallest interval enclosing both inputs. Each endpoint's
+     * inclusivity follows the input that contributed it; when both endpoints
+     * tie, the result is closed at that point if either input includes it.
+     *
+     * @param a - The first interval.
+     * @param b - The second interval.
+     * @returns A new interval enclosing both inputs.
+     * @since 2.0.0
+     */
+    (a: Interval, b: Interval): Interval;
+    /**
+     * @param b - The second interval.
+     * @returns A function that takes the first interval and returns the union.
+     * @since 2.0.0
+     */
+    (b: Interval): (a: Interval) => Interval;
+};
+export declare const filter: {
+    /**
+     * Filters an array of values to those contained within an interval.
+     * Endpoint inclusivity follows the interval's `kind`.
+     *
+     * @param interval - The interval to filter the values to.
+     * @param value - The values to filter.
+     * @returns The filtered values.
+     * @since 1.0.0
+     */
+    <V extends ReadonlyArray<number>>(interval: Interval, value: V): V;
+    /**
+     * Filters an array of values to those contained within an interval.
+     *
+     * @param value - The values to filter.
+     * @returns A function that takes an interval and returns the filtered values.
+     * @since 1.0.0
+     */
+    <V extends ReadonlyArray<number>>(value: V): (interval: Interval) => V;
+};
+export declare const clamp: {
+    /**
+     * Clamps a value to be within bounds. Kind-agnostic — clamps to the numeric
+     * range regardless of endpoint inclusivity.
+     *
+     * @param interval - The bounds to clamp the value to.
+     * @param value - The value to clamp.
+     * @returns The clamped value.
+     * @since 1.0.0
+     */
+    (interval: Bounds, value: number): number;
+    /**
+     * Clamps a value to be within bounds. Kind-agnostic.
+     *
+     * @param value - The value to clamp.
+     * @returns A function that takes bounds and returns the clamped value.
+     * @since 1.0.0
+     */
+    (value: number): (interval: Bounds) => number;
+    /**
+     * Clamps an array of values to be within bounds. Kind-agnostic.
+     *
+     * @param interval - The bounds to clamp the values to.
+     * @param value - The values to clamp.
+     * @returns The clamped values.
+     * @since 1.0.0
+     */
+    (interval: Bounds, value: ReadonlyArray<number>): ReadonlyArray<number>;
+    /**
+     * Clamps an array of values to be within bounds. Kind-agnostic.
+     *
+     * @param value - The values to clamp.
+     * @returns A function that takes bounds and returns the clamped values.
+     * @since 1.0.0
+     */
+    (value: ReadonlyArray<number>): (interval: Bounds) => ReadonlyArray<number>;
+};
+/**
+ * Returns an interval with the start endpoint open. Preserves the end endpoint's inclusivity.
+ *
+ * @since 2.0.0
+ */
+export declare const toStartOpen: {
+    (i: Closed | OpenStart): OpenStart;
+    (i: OpenEnd | Open): Open;
+};
+/**
+ * Returns an interval with the start endpoint closed. Preserves the end endpoint's inclusivity.
+ *
+ * @since 2.0.0
+ */
+export declare const toStartClosed: {
+    (i: Closed | OpenEnd): Closed;
+    (i: OpenStart | Open): OpenEnd;
+};
+/**
+ * Returns an interval with the end endpoint open. Preserves the start endpoint's inclusivity.
+ *
+ * @since 2.0.0
+ */
+export declare const toEndOpen: {
+    (i: Closed | OpenEnd): OpenEnd;
+    (i: OpenStart | Open): Open;
+};
+/**
+ * Returns an interval with the end endpoint closed. Preserves the start endpoint's inclusivity.
+ *
+ * @since 2.0.0
+ */
+export declare const toEndClosed: {
+    (i: Closed | OpenEnd): Closed;
+    (i: OpenStart | Open): OpenStart;
+};
+/**
+ * Returns a closed interval over the same numeric range.
+ *
+ * @since 2.0.0
+ */
+export declare const toClosed: (i: Interval) => Closed;
+/**
+ * Returns a fully open interval over the same numeric range.
+ *
+ * @since 2.0.0
+ */
+export declare const toOpen: (i: Interval) => Open;
+/**
+ * Type-narrowing predicate: refines `Interval` to `Closed`.
+ *
+ * @since 2.0.0
+ */
+export declare const isClosed: (i: Interval) => i is Closed;
+/**
+ * Type-narrowing predicate: refines `Interval` to `Open`.
+ *
+ * @since 2.0.0
+ */
+export declare const isOpen: (i: Interval) => i is Open;
+/**
+ * Type-narrowing predicate: refines `Interval` to `OpenStart`.
+ *
+ * @since 2.0.0
+ */
+export declare const isOpenStart: (i: Interval) => i is OpenStart;
+/**
+ * Type-narrowing predicate: refines `Interval` to `OpenEnd`.
+ *
+ * @since 2.0.0
+ */
+export declare const isOpenEnd: (i: Interval) => i is OpenEnd;
+/**
+ * Type-narrowing predicate: refines `Interval` to those with an open start endpoint.
+ *
+ * @since 2.0.0
+ */
+export declare const isOpenAtStart: (i: Interval) => i is OpenStart | Open;
+/**
+ * Type-narrowing predicate: refines `Interval` to those with an open end endpoint.
+ *
+ * @since 2.0.0
+ */
+export declare const isOpenAtEnd: (i: Interval) => i is OpenEnd | Open;
+/**
+ * Type-narrowing predicate: refines `Interval` to those with a closed start endpoint.
+ *
+ * @since 2.0.0
+ */
+export declare const isClosedAtStart: (i: Interval) => i is Closed | OpenEnd;
+/**
+ * Type-narrowing predicate: refines `Interval` to those with a closed end endpoint.
+ *
+ * @since 2.0.0
+ */
+export declare const isClosedAtEnd: (i: Interval) => i is Closed | OpenStart;
+/**
+ * The unit interval, `[0, 1]`.
+ *
+ * @since 1.0.0
+ */
+export declare const unit: Closed;
+/**
+ * The open unit interval, `(0, 1)`. The symmetric open analog of {@link unit};
+ * convenient for "strict interior" use cases such as filtering roots that
+ * must lie strictly inside the unit parameter range.
+ *
+ * @since 2.0.0
+ */
+export declare const unitOpen: Open;
+/**
+ * The biunit interval, `[-1, 1]`.
+ *
+ * @since 1.0.0
+ */
+export declare const biunit: Closed;
+/**
+ * Linearly interpolates a value within bounds.
+ *
+ * @param interval - The bounds to interpolate within.
+ * @param t - The interpolation factor, typically between 0 and 1.
+ * @returns The interpolated value.
+ * @since 1.0.0
+ */
+export declare const lerp: (interval: Bounds, t: number) => number;
+/**
+ * Creates a linear interpolation function for given bounds.
+ *
+ * @param interval - The bounds to create the interpolation function for.
+ * @returns A function that takes a factor `t` and returns the interpolated value.
+ * @since 1.0.0
+ */
+export declare const toLerpFn: (interval: Bounds) => (t: number) => number;
+/**
+ * Normalizes a value within bounds.
+ *
+ * @param interval - The bounds to normalize within.
+ * @param x - The value to normalize.
+ * @returns The normalized value.
+ * @since 1.0.0
+ */
+export declare const normalize: (interval: Bounds, x: number) => number;
+/**
+ * Creates a normalization function for given bounds.
+ *
+ * @param interval - The bounds to create the normalization function for.
+ * @returns A function that takes a value `x` and returns the normalized value.
+ * @since 1.0.0
+ */
+export declare const toNormalizeFn: (interval: Bounds) => (x: number) => number;
+/**
+ * Remaps a value from one bounds to another.
+ *
+ * @param source - The source bounds.
+ * @param target - The target bounds.
+ * @param x - The value to remap.
+ * @returns The remapped value.
+ * @since 1.0.0
+ */
+export declare const remap: (source: Bounds, target: Bounds, x: number) => number;
+/**
+ * Creates a remapping function for given bounds.
+ *
+ * @param source - The source bounds.
+ * @param target - The target bounds.
+ * @returns A function that takes a value `x` and returns the remapped value.
+ * @since 1.0.0
+ */
+export declare const toRemapFn: (source: Bounds, target: Bounds) => (x: number) => number;
+/**
+ * Calculates the scale and shift needed to map a source bounds to a target bounds.
+ *
+ * @param source - The source bounds.
+ * @param target - The target bounds.
+ * @returns An object containing the scale and shift values.
+ * @since 1.0.0
+ */
+export declare const scaleShift: (source: Bounds, target: Bounds) => ScaleShift;
+/**
+ * The scale and shift needed to map a source bounds to a target bounds.
+ *
+ * @since 1.0.0
+ */
+export interface ScaleShift {
+    readonly scale: number;
+    readonly shift: number;
+}

package/dist/interval/interval2d.d.ts

@@ -0,0 +1,167 @@
+import type { Pipeable } from '../utils';
+import type { Vector2 } from '../vector/vector2';
+import type { Bounds, Closed, Interval } from './interval';
+
+declare const Interval2dTypeId: unique symbol;
+type Interval2dTypeId = typeof Interval2dTypeId;
+
+
+/**
+ * An axis-aligned 2D interval — the Cartesian product of two 1D intervals.
+ * Used as a bounding box for curves and paths, and as a region for
+ * containment tests.
+ *
+ * The two type parameters carry the per-axis interval subtype so that a value
+ * built from closed intervals stays `Interval2d<Closed, Closed>` and a value
+ * with mixed openness preserves that information at the type level.
+ *
+ * All fields are readonly and immutable, and all operations create new instances.
+ *
+ * @since 2.0.0
+ */
+export interface Interval2d<X extends Interval = Interval, Y extends Interval = Interval> extends Pipeable {
+    readonly [Interval2dTypeId]: Interval2dTypeId;
+    readonly x: X;
+    readonly y: Y;
+}
+/**
+ * The structural minimum: any value with `x` and `y` fields shaped like
+ * {@link Bounds}. Operations that don't read endpoint inclusivity (e.g.
+ * {@link size}) accept `Bounds2d` so the signature itself documents what the
+ * operation depends on. Mirrors the {@link Bounds}/{@link Interval} split in 1D.
+ *
+ * @since 2.0.0
+ */
+export interface Bounds2d {
+    readonly x: Bounds;
+    readonly y: Bounds;
+}
+/**
+ * Checks if a value is an `Interval2d`.
+ *
+ * @param v - The value to check.
+ * @returns `true` if the value is an `Interval2d`, `false` otherwise.
+ * @since 2.0.0
+ */
+export declare const isInterval2d: (v: unknown) => v is Interval2d;
+/**
+ * Creates a new `Interval2d` from two intervals — one for the x axis, one
+ * for the y axis. Preserves both interval subtypes at the type level.
+ *
+ * @param x - The x-axis interval.
+ * @param y - The y-axis interval.
+ * @returns A new `Interval2d` instance.
+ * @since 2.0.0
+ */
+export declare const make: <X extends Interval, Y extends Interval>(x: X, y: Y) => Interval2d<X, Y>;
+/**
+ * Creates a closed `Interval2d` from two corner points. The corners can be in
+ * any order — each axis is built from the min and max of the coordinate.
+ *
+ * @param p0 - The first corner.
+ * @param p1 - The second corner.
+ * @returns A new `Interval2d<Closed, Closed>` enclosing both corners.
+ * @since 2.0.0
+ */
+export declare const fromCorners: (p0: Vector2, p1: Vector2) => Interval2d<Closed, Closed>;
+/**
+ * Creates the smallest closed `Interval2d` enclosing the given points. Useful
+ * for computing a bounding box from sampled points.
+ *
+ * @param points - One or more points to enclose.
+ * @returns A new `Interval2d<Closed, Closed>` enclosing all input points.
+ * @throws When called with zero points.
+ * @since 2.0.0
+ */
+export declare const fromVectors: (...points: ReadonlyArray<Vector2>) => Interval2d<Closed, Closed>;
+export declare const containsVector: {
+    /**
+     * Checks if a vector lies within the 2D interval. Per-axis endpoint
+     * inclusivity follows each axis interval's `kind`.
+     *
+     * @param box - The 2D interval to test against.
+     * @param v - The vector to test.
+     * @returns `true` when the vector lies within the box on both axes.
+     * @since 2.0.0
+     */
+    (box: Interval2d, v: Vector2): boolean;
+    /**
+     * @param v - The vector to test.
+     * @returns A function that takes a 2D interval and returns the containment result.
+     * @since 2.0.0
+     */
+    (v: Vector2): (box: Interval2d) => boolean;
+};
+export declare const containsInterval2d: {
+    /**
+     * Checks if `inner` is a subset of `outer`. The check is per-axis interval
+     * containment — for each axis, every point of the inner interval must also
+     * be in the outer interval, respecting endpoint inclusivity on both sides.
+     *
+     * @param outer - The enclosing 2D interval.
+     * @param inner - The candidate inner 2D interval.
+     * @returns `true` when every point of `inner` is also in `outer`.
+     * @since 2.0.0
+     */
+    (outer: Interval2d, inner: Interval2d): boolean;
+    /**
+     * @param inner - The candidate inner 2D interval.
+     * @returns A function that takes the outer 2D interval and returns the containment result.
+     * @since 2.0.0
+     */
+    (inner: Interval2d): (outer: Interval2d) => boolean;
+};
+/**
+ * Returns the size as a vector `(width, height)`. Accepts the broader
+ * {@link Bounds2d} type because size does not depend on endpoint inclusivity.
+ *
+ * @param box - The 2D interval (or bounds-shaped value) to measure.
+ * @returns The size as a `Vector2`.
+ * @since 2.0.0
+ */
+export declare const size: (box: Bounds2d) => Vector2;
+export declare const union: {
+    /**
+     * Returns the smallest 2D interval enclosing both inputs.
+     *
+     * The per-axis return kind is determined by which input's endpoint wins on
+     * each side, with the contributor's openness preserved (or unioned to
+     * "closed" when endpoints are numerically equal and either is closed at
+     * that point).
+     *
+     * When both inputs share the same kind on an axis, the result collapses
+     * back to that kind. Otherwise the axis falls back to the open
+     * {@link Interval} type since the runtime kind depends on the values.
+     *
+     * @param a - The first 2D interval.
+     * @param b - The second 2D interval.
+     * @returns A new `Interval2d` enclosing both inputs.
+     * @since 2.0.0
+     */
+    <AX extends Interval, AY extends Interval, BX extends Interval, BY extends Interval>(a: Interval2d<AX, AY>, b: Interval2d<BX, BY>): Interval2d<AX extends BX ? (BX extends AX ? AX : Interval) : Interval, AY extends BY ? (BY extends AY ? AY : Interval) : Interval>;
+    /**
+     * @param b - The second 2D interval.
+     * @returns A function that takes the first 2D interval and returns the union.
+     * @since 2.0.0
+     */
+    <BX extends Interval, BY extends Interval>(b: Interval2d<BX, BY>): <AX extends Interval, AY extends Interval>(a: Interval2d<AX, AY>) => Interval2d<AX extends BX ? (BX extends AX ? AX : Interval) : Interval, AY extends BY ? (BY extends AY ? AY : Interval) : Interval>;
+};
+export declare const equals: {
+    /**
+     * Checks if two `Interval2d` values are approximately equal within the
+     * default absolute tolerance ({@link EPSILON}). Both the numeric endpoints
+     * AND the per-axis kinds must match.
+     *
+     * @param a - The first 2D interval.
+     * @param b - The second 2D interval.
+     * @returns `true` when both axes are equal.
+     * @since 2.0.0
+     */
+    (a: Interval2d, b: Interval2d): boolean;
+    /**
+     * @param b - The second 2D interval.
+     * @returns A function that takes the first 2D interval and returns the comparison result.
+     * @since 2.0.0
+     */
+    (b: Interval2d): (a: Interval2d) => boolean;
+};