Initial Commit

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

@@ -0,0 +1,50 @@
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```ts
+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
+
+```ts
+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.