La lib

astralmanach

Le ciel d'un instant, en données. Une date, une heure, un lieu : la Lune et sa phase, les planètes qu'on voyait et où, les éclipses, les passages de la Station spatiale, les météores — et une carte des étoiles prête à dessiner.

npm GitHub Les sources

L'installer

npm install astralmanach

ESM, typée, sans étape de construction de votre côté. Elle s'appuie sur astronomy-engine et sur satellite.js et répond à la question qu'ils vous laissent : à quoi ressemblait le ciel, ici, à ce moment, en mots et en formes ?

Trois exemples

Le ciel d'un jour, en une phrase

La Lune, le Soleil, ce qu'on voyait à l'œil nu.

import { skyRecap } from "astralmanach";

const r = skyRecap({ date: "2026-09-30", time: "21:00", place: { name: "Paris", lat: 48.8566, lon: 2.3522, tz: "Europe/Paris" } });
console.log(r.headline);

Une carte du ciel, en données

Les étoiles, les figures des constellations et leurs noms, projetés dans un disque : à dessiner en SVG, sur un canevas, dans un PDF.

import { skyAt, skyMap } from "astralmanach/voute";

const sky = skyAt(new Date("2026-09-30T19:00:00Z"), { name: "Paris", lat: 48.8566, lon: 2.3522 });
const map = skyMap(sky, { maxMag: 4, projection: "stereo" });

Les événements du jour, la Station spatiale, les météores

Des cartes typées, prêtes à afficher ; une source qui échoue rend un statut, jamais une exception.

import { makeContext, runQuery, skyEvents, issPasses, fireballs } from "astralmanach";

const ctx = makeContext({ date: "2013-02-15", tz: "Asia/Yekaterinburg", place: { name: "Tcheliabinsk", lat: 55.16, lon: 61.4 } });
const opts = { key: process.env.NASA_API_KEY ?? "DEMO_KEY", userAgent: "mon-site/1.0 (contact@exemple.org)" };

for (const q of [skyEvents, issPasses, fireballs]) {
  const r = await runQuery(q, ctx, opts);
  console.log(q.id, r.status, r.cards.map((c) => c.title));
}

Les modules

Import	Ce qu'il y a dedans
`astralmanach`	Les fonctions et les types les plus utilisés, réexportés.
`astralmanach/time`	Les dates civiles, les fuseaux IANA, l'instant d'une date et d'une heure locales (makeContext, zonedToUtc, formatLocal).
`astralmanach/voute`	La voûte céleste : skyAt (Soleil, Lune, planètes, hauteur et azimut), skyMap, projectAltAz, moonPhaseName, equationOfTime.
`astralmanach/sky-recap`	skyRecap : le ciel d'un jour en une phrase.
`astralmanach/queries/astro-evenements`	skyEvents et SHOWERS (la table des pluies d'étoiles de l'IMO).
`astralmanach/queries/celestrak-iss`	issPasses : les passages visibles de la Station spatiale.
`astralmanach/queries/jpl-fireball`	fireballs : les astéroïdes entrés dans l'atmosphère (NASA/JPL, CNEOS).
`astralmanach/run, astralmanach/fetcher`	runQuery, fetchProvider : couverture, concurrence bornée, une reprise sur 429/503, clés caviardées, un cache que vous fournissez.
`astralmanach/cards, astralmanach/queries/types`	Les types des cartes et des sources, pour écrire les vôtres.
`astralmanach/data/celestial/*.json`	Les catalogues bruts des étoiles, des lignes et des noms.

Ses principes

Ni secret, ni disque. Elle ne lit jamais .env, process.env ni un fichier : votre clé, votre User-Agent et votre cache lui sont passés. Les clés sont caviardées de chaque adresse et de chaque réponse.
Elle ne jette jamais. Une forme de réponse inconnue donne []; un fournisseur en panne donne un statut « error » et un message. Votre page s'affiche toujours.
Du pur quand c'est possible. Tout ce qui se calcule se calcule ici, sans réseau (skyEvents, skyAt, skyMap, skyRecap) ; seuls la Station spatiale et les météores vont sur le réseau.
Le temps civil, bien fait. Une date est celle du lieu, par les fuseaux IANA, heure d'été comprise ; sans heure, l'instant est midi local.
Des positions géocentriques. La Lune à la minute d'arc près contre JPL Horizons ; la hauteur et l'azimut topocentriques pour ce qu'on voit d'un lieu.
Des libellés en français pour l'instant (titres de cartes, faits, résumés) ; les données, elles, ne parlent aucune langue.

Elle en action

astralmanach.vercel.app — ce site : le Thème, le Ciel et le Certificat sont écrits avec la lib. Une date, une heure, un lieu, et le ciel de cet instant en cartes.
uavv.fr/observations — l'autre usage : la planche imprimable d'un ciel, dont la carte des étoiles, la Lune et les astres viennent de la lib.

Sur GitHub

Le code, le journal des versions et les questions sont dans le dépôt public.

Le dépôt Une question, un défaut Les versions

Ce qu'elle emprunte

astronomy-engine (Don Cross) — MIT, les positions et les recherches.
satellite.js — MIT, les orbites.
d3-celestial (Olaf Frohn) — BSD-3-Clause, les étoiles, les figures des constellations et leurs noms.
CelesTrak — accès libre, à ménager (cache), les éléments orbitaux de la Station.
NASA/JPL CNEOS — domaine public, les météores.
International Meteor Organization — liste de travail, au jour près, les pluies d'étoiles.

Licence du paquet : MIT.

Les images

En-tête de la page de la lib — 17 avril 1912. L'éclipse de Soleil, Hambourg (plaque LA00028). A. Schwassmann, CC0. Source : APPLAUSE, archive de plaques photographiques (plate-archive.org).

Trois exemples

Le ciel d'un jour, en une phrase

La Lune, le Soleil, ce qu'on voyait à l'œil nu.

import { skyRecap } from "astralmanach";

const r = skyRecap({ date: "2026-09-30", time: "21:00", place: { name: "Paris", lat: 48.8566, lon: 2.3522, tz: "Europe/Paris" } });
console.log(r.headline);

Une carte du ciel, en données

Les étoiles, les figures des constellations et leurs noms, projetés dans un disque : à dessiner en SVG, sur un canevas, dans un PDF.

import { skyAt, skyMap } from "astralmanach/voute";

const sky = skyAt(new Date("2026-09-30T19:00:00Z"), { name: "Paris", lat: 48.8566, lon: 2.3522 });
const map = skyMap(sky, { maxMag: 4, projection: "stereo" });

Les événements du jour, la Station spatiale, les météores

Des cartes typées, prêtes à afficher ; une source qui échoue rend un statut, jamais une exception.

import { makeContext, runQuery, skyEvents, issPasses, fireballs } from "astralmanach";

const ctx = makeContext({ date: "2013-02-15", tz: "Asia/Yekaterinburg", place: { name: "Tcheliabinsk", lat: 55.16, lon: 61.4 } });
const opts = { key: process.env.NASA_API_KEY ?? "DEMO_KEY", userAgent: "mon-site/1.0 (contact@exemple.org)" };

for (const q of [skyEvents, issPasses, fireballs]) {
  const r = await runQuery(q, ctx, opts);
  console.log(q.id, r.status, r.cards.map((c) => c.title));
}

Les modules

Import	Ce qu'il y a dedans
`astralmanach`	Les fonctions et les types les plus utilisés, réexportés.
`astralmanach/time`	Les dates civiles, les fuseaux IANA, l'instant d'une date et d'une heure locales (makeContext, zonedToUtc, formatLocal).
`astralmanach/voute`	La voûte céleste : skyAt (Soleil, Lune, planètes, hauteur et azimut), skyMap, projectAltAz, moonPhaseName, equationOfTime.
`astralmanach/sky-recap`	skyRecap : le ciel d'un jour en une phrase.
`astralmanach/queries/astro-evenements`	skyEvents et SHOWERS (la table des pluies d'étoiles de l'IMO).
`astralmanach/queries/celestrak-iss`	issPasses : les passages visibles de la Station spatiale.
`astralmanach/queries/jpl-fireball`	fireballs : les astéroïdes entrés dans l'atmosphère (NASA/JPL, CNEOS).
`astralmanach/run, astralmanach/fetcher`	runQuery, fetchProvider : couverture, concurrence bornée, une reprise sur 429/503, clés caviardées, un cache que vous fournissez.
`astralmanach/cards, astralmanach/queries/types`	Les types des cartes et des sources, pour écrire les vôtres.
`astralmanach/data/celestial/*.json`	Les catalogues bruts des étoiles, des lignes et des noms.

Ses principes

Ni secret, ni disque. Elle ne lit jamais .env, process.env ni un fichier : votre clé, votre User-Agent et votre cache lui sont passés. Les clés sont caviardées de chaque adresse et de chaque réponse.

Elle ne jette jamais. Une forme de réponse inconnue donne []; un fournisseur en panne donne un statut « error » et un message. Votre page s'affiche toujours.

Du pur quand c'est possible. Tout ce qui se calcule se calcule ici, sans réseau (skyEvents, skyAt, skyMap, skyRecap) ; seuls la Station spatiale et les météores vont sur le réseau.

Le temps civil, bien fait. Une date est celle du lieu, par les fuseaux IANA, heure d'été comprise ; sans heure, l'instant est midi local.

Des positions géocentriques. La Lune à la minute d'arc près contre JPL Horizons ; la hauteur et l'azimut topocentriques pour ce qu'on voit d'un lieu.

Des libellés en français pour l'instant (titres de cartes, faits, résumés) ; les données, elles, ne parlent aucune langue.

Elle en action

astralmanach.vercel.app — ce site : le Thème, le Ciel et le Certificat sont écrits avec la lib. Une date, une heure, un lieu, et le ciel de cet instant en cartes.

uavv.fr/observations — l'autre usage : la planche imprimable d'un ciel, dont la carte des étoiles, la Lune et les astres viennent de la lib.

Ce qu'elle emprunte

astronomy-engine (Don Cross) — MIT, les positions et les recherches.

satellite.js — MIT, les orbites.

d3-celestial (Olaf Frohn) — BSD-3-Clause, les étoiles, les figures des constellations et leurs noms.

CelesTrak — accès libre, à ménager (cache), les éléments orbitaux de la Station.

NASA/JPL CNEOS — domaine public, les météores.

International Meteor Organization — liste de travail, au jour près, les pluies d'étoiles.

Licence du paquet : MIT.