suaveplan/packages/geospatial/geo/stars/src/catalog/catalog.md

(no submodules)

Purpose

The catalog module provides an in-memory implementation of the StarCatalogSource contract used by @suaveplan/stars providers. It accepts a static array of RawStar records and exposes them through the same queryCone and getStar surface that production catalog adapters (Hipparcos, Tycho-2, Gaia DR3) implement, so consumers can swap real catalogs for fixtures without touching call sites.

It is the recommended source for tests, demos, offline planetariums, and bootstrap data flows where pulling a remote catalog is unnecessary or undesirable. The implementation favours predictability over scale: lookups are O(n) for cone queries and O(1) for id resolution backed by a single Map.

Features

• Pure in-memory StarCatalogSource with no external dependencies.
• Constant-time getStar(catalogId) lookup via internal Map.
• Naive Cartesian cone filter on (ra, dec) for deterministic test output.
• Returns the same RawStar shape consumed by createStarProvider.
• Zero allocations on the hot path beyond the result array.

Usage: Basic Example

import { createInMemoryCatalogSource } from "@suaveplan/stars";

const source = createInMemoryCatalogSource([
    { catalogId: "HIP-32349", ra: 101.287, dec: -16.716, apparentMagnitude: -1.46 },
]);

const sirius = await source.getStar("HIP-32349");

Usage: Advanced Example

import { createInMemoryCatalogSource, createStarProvider } from "@suaveplan/stars";

const source = createInMemoryCatalogSource([
    { catalogId: "HIP-32349", ra: 101.287, dec: -16.716, apparentMagnitude: -1.46, spectralClass: "A1V", distance: 2.64 },
    { catalogId: "HIP-37279", ra: 114.825, dec: 5.225, apparentMagnitude: 0.4, spectralClass: "F5IV-V" },
]);
const provider = createStarProvider([source]);
const nearby = await provider.queryCone(101, -16, 5);

API Reference

• createInMemoryCatalogSource(stars: RawStar[]): StarCatalogSource — builds a source whose queryCone(ra, dec, radiusDeg) returns every star inside the Cartesian disk of the given radius (degrees) around the centre, and whose getStar(catalogId) returns the matching record or null. Both methods are async to satisfy the interface; neither throws.

Implementation Notes

The cone filter uses Euclidean distance on raw (ra, dec) pairs rather than a spherical-trig great-circle distance. This is deliberate: the source is for fixtures and small catalogs, where simplicity and determinism beat correctness near the poles or across the RA wrap. For real-sky use, layer a cosine-correction adapter or replace the source with a HEALPix-backed implementation. The internal Map is built once at construction; mutating the input array post-construction is not supported.