mirror of
https://github.com/acamarata/moon-cycle.git
synced 2026-07-02 11:40:44 +00:00
24db90e9f5
Port to TypeScript with dual CJS/ESM build via tsup. Fix off-by-one bug in both cycleMonth and cycleYear (images are 1-indexed; v1 returned 000.webp/0000.webp which don't exist). Add imageFolder and cdnUrl helpers for jsDelivr CDN integration. Export constants and types. Separate the ~438 MB image dataset from the npm package via the files field, making moon-cycle publishable to npm for the first time. Add CI workflow with Node 20/22/24 matrix, typecheck, and pack-check jobs. Add wiki-sync workflow and full .wiki/ documentation (Home, API Reference, Architecture, Migration Guide).
60 lines
2 KiB
Markdown
60 lines
2 KiB
Markdown
# moon-cycle
|
||
|
||
Maps any JavaScript `Date` to the correct NASA moon phase image filename. Built on two independent algorithms, the package ships ~2 KB of code to npm while the ~438 MB image dataset stays in the GitHub repository, served via CDN on demand.
|
||
|
||
## What it does
|
||
|
||
Given any date, you get a filename like `354.webp` or `4380.webp` that corresponds to an hourly NASA moon photograph. Pair it with `cdnUrl()` to construct a ready-to-use image URL, or host the image folders yourself.
|
||
|
||
Two algorithms are provided because they answer different questions:
|
||
|
||
| Function | Algorithm | Use when |
|
||
| --- | --- | --- |
|
||
| `cycleMonth` | Synodic (lunar) cycle | You want the actual lunar phase for the date |
|
||
| `cycleYear` | Calendar year (2023) | You want a consistent annual visual rhythm |
|
||
|
||
See [Architecture](Architecture) for a full explanation of each approach.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
npm install moon-cycle
|
||
pnpm add moon-cycle
|
||
```
|
||
|
||
## Quick start
|
||
|
||
```ts
|
||
import { cycleMonth, cdnUrl } from 'moon-cycle';
|
||
|
||
const file = cycleMonth(); // e.g. "354.webp" — current lunar phase
|
||
const url = cdnUrl(file, 'mm', 256, 75);
|
||
// => 'https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@main/mm-256-75/354.webp'
|
||
```
|
||
|
||
## Image options
|
||
|
||
Pick the folder that fits your use case:
|
||
|
||
| Folder | Images | Size |
|
||
| --- | --- | --- |
|
||
| `mm-256-75` | 708 (monthly) | ~4 MB |
|
||
| `mm-512-85` | 708 (monthly) | ~14 MB |
|
||
| `my-256-75` | 8,760 (yearly) | ~51 MB |
|
||
| `my-512-85` | 8,760 (yearly) | ~176 MB |
|
||
|
||
All eight combinations (`mm`/`my` × `256`/`512` × `75`/`85`) are available. Use `imageFolder()` to construct the directory name programmatically.
|
||
|
||
## Pages
|
||
|
||
- [API Reference](API-Reference) — full function and type documentation
|
||
- [Architecture](Architecture) — algorithm design, dataset description, tradeoffs
|
||
- [Migration Guide](Migration) — upgrading from v1
|
||
|
||
## Source
|
||
|
||
[github.com/acamarata/moon-cycle](https://github.com/acamarata/moon-cycle)
|
||
|
||
---
|
||
|
||
*Part of the [acamarata](https://github.com/acamarata) astronomical computing stack.*
|