nearestfunction

The things nearest a star, a deep-sky object or a point, nearest first. By angle (by: "sky", the default) it measures the angle on the sky with the form atan2(|a x b|, a . b) of unit vectors, which keeps its accuracy at 0 and at 180 degrees and across right ascension 0 and 360. By space (by: "space") it places each star from its parallax and finds the straight-line distance, in light-years and in parsecs; it needs a target with a distance and leaves out every candidate without one, counting them in skipped. The target itself is never in its own answer.

By default the three-dimensional answers cover only the bright stars: the 2,533 of the 5,080 Yale stars that have a positive parallax, so the neighbours are bright stars, not the nearest ones. Their parallaxes are whole milliarcseconds, so a distance is good to a few per cent for a star within 100 light-years and not at all for a faint, far one; error is undefined for them. To include the stars of /nearby (Proxima Centauri, Barnard's Star, the red dwarfs, with a parallax error each) pass among: [...stars(), ...nearbyStars()]; error is then worked out for a nearby star from a target that is a point or a nearby star.

Every candidate is looked at (no index); one query over all the stars takes about a millisecond.

import { nearest } from "@johnmorrisdotca/hoshi-stars/nearest";

function nearest(target: NearestTarget, options: SkyOptions & { kind: "deep-sky"; among?: undefined; }): NearestList<NearestInSky<DeepSkyObject>>
function nearest<T extends NearestThing>(target: NearestTarget, options: SkyOptions & { kind?: "star" | "deep-sky"; among: readonly T[]; }): NearestList<NearestInSky<T>>
function nearest(target: NearestTarget, options?: SkyOptions & { kind?: "star"; among?: undefined; }): NearestList<NearestInSky>
function nearest<T extends NearestThing>(target: NearestTarget, options: NearestOptions & { by: "space"; among: readonly T[]; }): NearestList<NearestInSpace<Extract<T, Star | NearbyStar>>>
function nearest(target: NearestTarget, options: NearestOptions & { by: "space"; }): NearestList<NearestInSpace>
function nearest(target: NearestTarget, options: NearestOptions): NearestList<NearestInSky<NearestThing> | NearestInSpace<Star | NearbyStar>>

import { nearest } from "@johnmorrisdotca/hoshi-stars/nearest";

const near = nearest("Mizar", { count: 1 });
console.log(near[0]?.thing.name, near[0]?.angle.toFixed(2)); // Alcor 0.20
const close = nearest("Sirius", { by: "space", count: 1 });
console.log(close[0]?.thing.designation, close[0]?.distance.toFixed(1)); //

undefined 0.00
α CMi 5.1