mirror of
https://github.com/acamarata/moon-cycle.git
synced 2026-06-30 18:54:29 +00:00
60 lines
2.1 KiB
Markdown
60 lines
2.1 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._
|