mirror of
https://github.com/acamarata/moon-cycle.git
synced 2026-06-30 18:54:29 +00:00
docs: update README, wiki examples, and CI coverage (P1)
This commit is contained in:
Aric Camarata
parent
2908ae7fa0
commit
2d18b68794
6 changed files with 183 additions and 165 deletions
9
.github/wiki/_Sidebar.md
vendored
9
.github/wiki/_Sidebar.md
vendored
|
|
@ -6,6 +6,15 @@
|
|||
|
||||
**Examples**
|
||||
- [Basic Usage](examples/basic-usage)
|
||||
- [Prayer App Integration](examples/prayer-app)
|
||||
|
||||
**API**
|
||||
- [cycleMonth](api/cycleMonth)
|
||||
- [cycleYear](api/cycleYear)
|
||||
- [cdnUrl](api/cdnUrl)
|
||||
- [imageFolder](api/imageFolder)
|
||||
- [Constants](api/constants)
|
||||
- [Types](api/types)
|
||||
|
||||
**Reference**
|
||||
- [API Reference](API-Reference)
|
||||
|
|
|
|||
10
.github/wiki/examples/basic-usage.md
vendored
10
.github/wiki/examples/basic-usage.md
vendored
|
|
@ -26,20 +26,18 @@ console.log(filename); // e.g. '001.webp'
|
|||
console.log(url);
|
||||
```
|
||||
|
||||
## Use a larger image size
|
||||
## Use different sizes and quality levels
|
||||
|
||||
```javascript
|
||||
import { cycleMonth, cdnUrl } from 'moon-cycle';
|
||||
|
||||
const filename = cycleMonth(new Date());
|
||||
|
||||
// Available sizes: 64, 128, 256, 512
|
||||
// Available quality: 75, 85, 95
|
||||
const urlSmall = cdnUrl(filename, 'mm', 64, 75);
|
||||
// Available sizes: 256 or 512 pixels
|
||||
// Available quality: 75 or 85
|
||||
const urlMedium = cdnUrl(filename, 'mm', 256, 75);
|
||||
const urlLarge = cdnUrl(filename, 'mm', 512, 85);
|
||||
|
||||
console.log(urlSmall);
|
||||
console.log(urlMedium);
|
||||
console.log(urlLarge);
|
||||
```
|
||||
|
|
@ -51,7 +49,7 @@ import { cycleYear, cdnUrl } from 'moon-cycle';
|
|||
|
||||
// cycleYear maps to 2023 hourly NASA photographs
|
||||
const filename = cycleYear(new Date());
|
||||
const url = cdnUrl(filename, 'yr', 256, 75);
|
||||
const url = cdnUrl(filename, 'my', 256, 75);
|
||||
|
||||
console.log(url);
|
||||
```
|
||||
|
|
|
|||
68
.github/wiki/examples/prayer-app.md
vendored
Normal file
68
.github/wiki/examples/prayer-app.md
vendored
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Prayer App Integration
|
||||
|
||||
Displaying the current moon phase alongside Islamic prayer times is a natural pairing. `moon-cycle` maps the current date to the correct NASA image; [pray-calc](https://github.com/acamarata/pray-calc) computes the prayer schedule for the same moment.
|
||||
|
||||
## React component
|
||||
|
||||
```tsx
|
||||
import { cycleMonth, cdnUrl } from 'moon-cycle';
|
||||
import { getPrayerTimes } from 'pray-calc';
|
||||
|
||||
interface PrayerCardProps {
|
||||
date: Date;
|
||||
latitude: number;
|
||||
longitude: number;
|
||||
timezone: string;
|
||||
}
|
||||
|
||||
function PrayerCard({ date, latitude, longitude, timezone }: PrayerCardProps) {
|
||||
const filename = cycleMonth(date);
|
||||
const moonUrl = cdnUrl(filename, 'mm', 256, 75);
|
||||
|
||||
const times = getPrayerTimes({ date, latitude, longitude, timezone });
|
||||
|
||||
return (
|
||||
<div className="prayer-card">
|
||||
<img src={moonUrl} alt="Current moon phase" width={128} height={128} />
|
||||
<ul>
|
||||
<li>Fajr: {times.fajr}</li>
|
||||
<li>Dhuhr: {times.dhuhr}</li>
|
||||
<li>Asr: {times.asr}</li>
|
||||
<li>Maghrib: {times.maghrib}</li>
|
||||
<li>Isha: {times.isha}</li>
|
||||
</ul>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Plain JavaScript
|
||||
|
||||
```js
|
||||
import { cycleMonth, cdnUrl } from 'moon-cycle';
|
||||
|
||||
const date = new Date();
|
||||
const filename = cycleMonth(date);
|
||||
const moonUrl = cdnUrl(filename, 'mm', 256, 75);
|
||||
|
||||
// Inject into an existing img element
|
||||
document.getElementById('moon-img').src = moonUrl;
|
||||
```
|
||||
|
||||
## Pinning to a stable image set
|
||||
|
||||
If you want the moon image to stay consistent across deploys, pin the CDN reference to a specific release tag:
|
||||
|
||||
```ts
|
||||
const url = cdnUrl(filename, 'mm', 256, 75, 'v2.0.0');
|
||||
```
|
||||
|
||||
## Choosing the right dataset
|
||||
|
||||
For a prayer app, the monthly dataset (`'mm'`) is generally the better choice. It reflects the current phase of the synodic cycle, which corresponds to the Islamic lunar calendar month. The yearly dataset (`'my'`) is better when you want to show the actual NASA photograph for today's date in 2023 imagery.
|
||||
|
||||
## See Also
|
||||
|
||||
- [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times library
|
||||
- [Basic Usage](basic-usage) — other usage patterns
|
||||
- [API Reference](../API-Reference) — full function documentation
|
||||
21
.github/workflows/ci.yml
vendored
21
.github/workflows/ci.yml
vendored
|
|
@ -77,3 +77,24 @@ jobs:
|
|||
done
|
||||
echo "$PACK" | grep -q "src/" && (echo "ERROR: src/ should not be in pack" && exit 1) || true
|
||||
echo "Pack check passed"
|
||||
|
||||
coverage:
|
||||
name: Coverage
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Enable corepack
|
||||
run: corepack enable
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 24
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: pnpm build
|
||||
- run: pnpm run coverage
|
||||
- name: Upload to Codecov
|
||||
uses: codecov/codecov-action@v4
|
||||
with:
|
||||
files: ./coverage/lcov.info
|
||||
token: ${{ secrets.CODECOV_TOKEN }}
|
||||
fail_ci_if_error: false
|
||||
|
|
|
|||
165
README.md
165
README.md
|
|
@ -1,190 +1,51 @@
|
|||
# moon-cycle
|
||||
|
||||
[](https://www.npmjs.com/package/moon-cycle)
|
||||
[](https://github.com/acamarata/moon-cycle/actions/workflows/ci.yml)
|
||||
[](LICENSE)
|
||||
|
||||
Maps any JavaScript `Date` to the correct NASA moon phase image filename. Two algorithms: synodic-cycle mapping (monthly, 708 images) and calendar-year mapping (yearly, 8,760 images).
|
||||
Maps any JavaScript `Date` to the correct NASA moon phase image filename. Two algorithms: synodic-cycle mapping (708 images) and calendar-year mapping (8,760 images).
|
||||
|
||||
The image dataset (~438 MB of hourly WebP photos from NASA's Scientific Visualization Studio) lives in this repository. The npm package ships only the code. Serve images via CDN (jsDelivr, see below) or by cloning the repo and hosting the folders yourself.
|
||||
Not published to npm. The image dataset (~438 MB of hourly WebP photos from NASA's Scientific Visualization Studio) lives in this repository. Use CDN or clone.
|
||||
|
||||
## Distribution
|
||||
|
||||
This package is **not published to npm**. The image dataset (~438 MB) exceeds the npm registry limit. Install via git clone or reference the CDN directly.
|
||||
## Install
|
||||
|
||||
```bash
|
||||
# Clone the repo to get the code and images together
|
||||
# Clone to get code and images together
|
||||
git clone https://github.com/acamarata/moon-cycle.git
|
||||
|
||||
# Or install the code-only package from GitHub Packages / direct git
|
||||
# Or add the code-only package via git
|
||||
pnpm add github:acamarata/moon-cycle
|
||||
```
|
||||
|
||||
For most web use cases, you do not need to install the package at all. Use `cdnUrl()` to serve images via jsDelivr directly from the GitHub repository (see API below).
|
||||
|
||||
## Quick Start
|
||||
|
||||
```ts
|
||||
import { cycleMonth, cycleYear, cdnUrl } from 'moon-cycle';
|
||||
import { cycleMonth, cdnUrl } from 'moon-cycle';
|
||||
|
||||
const date = new Date();
|
||||
|
||||
// Get the current moon phase filename
|
||||
const monthlyFile = cycleMonth(date); // e.g. "354.webp"
|
||||
const yearlyFile = cycleYear(date); // e.g. "4380.webp"
|
||||
|
||||
// Construct a CDN URL served from GitHub via jsDelivr
|
||||
const url = cdnUrl(monthlyFile, 'mm', 256, 75);
|
||||
const filename = cycleMonth(); // e.g. "354.webp"
|
||||
const url = cdnUrl(filename, 'mm', 256, 75);
|
||||
// => 'https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@main/mm-256-75/354.webp'
|
||||
```
|
||||
|
||||
CommonJS:
|
||||
|
||||
```js
|
||||
const { cycleMonth, cycleYear, cdnUrl } = require('moon-cycle');
|
||||
const { cycleMonth, cdnUrl } = require('moon-cycle');
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### `cycleMonth(date?: Date): string`
|
||||
|
||||
Maps a date to an image filename in the monthly (synodic) dataset.
|
||||
|
||||
Uses the IAU mean synodic month (29.530588 days) and a 2023-11-13 new moon anchor. The 708 hourly images span one complete synodic cycle. The result wraps continuously: any past or future date resolves to a valid image.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `date` | `Date` | `new Date()` | The date to resolve |
|
||||
|
||||
Returns a zero-padded filename string in the range `"001.webp"` to `"708.webp"`.
|
||||
|
||||
### `cycleYear(date?: Date): string`
|
||||
|
||||
Maps a date to an image filename in the yearly dataset.
|
||||
|
||||
The 8,760 images are hourly photographs from the full calendar year 2023 (365 days). The result maps to the equivalent hour-of-year position and repeats annually.
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `date` | `Date` | `new Date()` | The date to resolve |
|
||||
|
||||
Returns a zero-padded filename string in the range `"0001.webp"` to `"8760.webp"`.
|
||||
|
||||
### `imageFolder(set, size, quality): string`
|
||||
|
||||
Returns the directory name for a given image set and quality level.
|
||||
|
||||
```ts
|
||||
imageFolder('mm', 256, 75) // => 'mm-256-75'
|
||||
imageFolder('my', 512, 85) // => 'my-512-85'
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `set` | `'mm' \| 'my'` | Monthly or yearly dataset |
|
||||
| `size` | `256 \| 512` | Image dimension in pixels |
|
||||
| `quality` | `75 \| 85` | WebP compression quality |
|
||||
|
||||
### `cdnUrl(filename, set, size, quality, ref?): string`
|
||||
|
||||
Returns a jsDelivr CDN URL for a specific image, served directly from this GitHub repository.
|
||||
|
||||
```ts
|
||||
const file = cycleMonth();
|
||||
const url = cdnUrl(file, 'mm', 256, 75);
|
||||
// => 'https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@main/mm-256-75/354.webp'
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `filename` | `string` |: | Result from `cycleMonth` or `cycleYear` |
|
||||
| `set` | `'mm' \| 'my'` |: | Monthly or yearly dataset |
|
||||
| `size` | `256 \| 512` |: | Image dimension |
|
||||
| `quality` | `75 \| 85` |: | WebP quality |
|
||||
| `ref` | `string` | `'main'` | Branch, tag, or commit SHA |
|
||||
|
||||
### Constants
|
||||
|
||||
| Export | Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `SYNODIC_MONTH` | `29.53058821398858` | IAU mean synodic month in days |
|
||||
| `MONTH_IMAGES` | `708` | Image count in the monthly dataset |
|
||||
| `YEAR_IMAGES` | `8760` | Image count in the yearly dataset |
|
||||
| `MONTH_ANCHOR` | `Date('2023-11-13T09:27:00Z')` | Reference new moon for `cycleMonth` |
|
||||
| `YEAR_ANCHOR` | `Date('2023-01-01T00:00:00Z')` | Reference start date for `cycleYear` |
|
||||
|
||||
### Types
|
||||
|
||||
```ts
|
||||
type ImageSet = 'mm' | 'my';
|
||||
type ImageSize = 256 | 512;
|
||||
type ImageQuality = 75 | 85;
|
||||
```
|
||||
|
||||
## Image Dataset
|
||||
|
||||
The repository contains eight image folders, each a complete set of hourly NASA moon photos in WebP format:
|
||||
|
||||
| Folder | Images | Resolution | Quality | Size |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `mm-256-75` | 708 | 256x256 | 75 | ~4 MB |
|
||||
| `mm-256-85` | 708 | 256x256 | 85 | ~5 MB |
|
||||
| `mm-512-75` | 708 | 512x512 | 75 | ~9 MB |
|
||||
| `mm-512-85` | 708 | 512x512 | 85 | ~14 MB |
|
||||
| `my-256-75` | 8,760 | 256x256 | 75 | ~51 MB |
|
||||
| `my-256-85` | 8,760 | 256x256 | 85 | ~66 MB |
|
||||
| `my-512-75` | 8,760 | 512x512 | 75 | ~113 MB |
|
||||
| `my-512-85` | 8,760 | 512x512 | 85 | ~176 MB |
|
||||
|
||||
Images are not included in the npm package. Options for serving them:
|
||||
|
||||
1. **CDN (recommended for web apps):** Use `cdnUrl()` to serve from jsDelivr, which caches GitHub content globally at no cost.
|
||||
2. **Self-hosted:** Clone the repo and copy the relevant folder(s) into your `public/` directory.
|
||||
3. **Pinned version:** Pass a specific git tag as `ref` to `cdnUrl()` to lock to a stable image set.
|
||||
|
||||
## TypeScript
|
||||
|
||||
The package ships dual CJS and ESM builds with full type definitions. No `@types/` package is needed.
|
||||
|
||||
```ts
|
||||
import { cycleMonth, cycleYear, cdnUrl } from 'moon-cycle';
|
||||
import type { ImageSet, ImageSize, ImageQuality } from 'moon-cycle';
|
||||
|
||||
function getMoonUrl(date: Date, set: ImageSet, size: ImageSize, quality: ImageQuality): string {
|
||||
const filename = set === 'mm' ? cycleMonth(date) : cycleYear(date);
|
||||
return cdnUrl(filename, set, size, quality);
|
||||
}
|
||||
```
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Runtime | Support |
|
||||
| --- | --- |
|
||||
| Node.js | >= 20 |
|
||||
| Browser | Yes (ESM) |
|
||||
| Bundlers | Vite, webpack, esbuild, Rollup |
|
||||
| React / Next.js | Yes |
|
||||
| Deno | Yes |
|
||||
|
||||
## Architecture
|
||||
|
||||
Two distinct algorithms, one shared image source. See the [Architecture wiki page](https://github.com/acamarata/moon-cycle/wiki/Architecture) for analysis of the synodic and calendar-year mapping approaches, how they differ, and when to prefer each.
|
||||
|
||||
## Documentation
|
||||
|
||||
Full reference: [GitHub Wiki](https://github.com/acamarata/moon-cycle/wiki)
|
||||
|
||||
- [Home](https://github.com/acamarata/moon-cycle/wiki/Home)
|
||||
- [API Reference](https://github.com/acamarata/moon-cycle/wiki/API-Reference)
|
||||
- [Architecture](https://github.com/acamarata/moon-cycle/wiki/Architecture)
|
||||
- [Migration Guide (v1 to v2)](https://github.com/acamarata/moon-cycle/wiki/Migration)
|
||||
- [Examples](https://github.com/acamarata/moon-cycle/wiki/examples/basic-usage)
|
||||
|
||||
## Related
|
||||
|
||||
- [nrel-spa](https://github.com/acamarata/nrel-spa): Pure JS NREL Solar Position Algorithm, zero dependencies
|
||||
- [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times with dynamic angle algorithm
|
||||
- [luxon-hijri](https://github.com/acamarata/luxon-hijri): Hijri/Gregorian calendar conversion
|
||||
- [moon-sighting](https://github.com/acamarata/moon-sighting): Lunar crescent visibility using Yallop and Odeh criteria
|
||||
- [nrel-spa](https://github.com/acamarata/nrel-spa): Pure JS NREL Solar Position Algorithm
|
||||
- [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times
|
||||
- [moon-sighting](https://github.com/acamarata/moon-sighting): Lunar crescent visibility
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
|
|
|
|||
75
src/types.ts
75
src/types.ts
|
|
@ -1,40 +1,101 @@
|
|||
/**
|
||||
* Image set identifier.
|
||||
* - 'mm' = moon monthly (synodic cycle, 708 images)
|
||||
* - 'my' = moon yearly (calendar year, 8,760 images)
|
||||
*
|
||||
* - `'mm'` = monthly dataset: 708 hourly images covering one synodic cycle
|
||||
* - `'my'` = yearly dataset: 8,760 hourly images covering calendar year 2023
|
||||
*
|
||||
* @example
|
||||
* import type { ImageSet } from 'moon-cycle';
|
||||
* const set: ImageSet = 'mm'; // monthly synodic cycle
|
||||
*/
|
||||
export type ImageSet = 'mm' | 'my';
|
||||
|
||||
/**
|
||||
* Image dimension in pixels (square).
|
||||
*
|
||||
* Both values produce square images. Use `256` for thumbnails and smaller
|
||||
* displays; use `512` for high-DPI or full-size display contexts.
|
||||
*
|
||||
* @example
|
||||
* import type { ImageSize } from 'moon-cycle';
|
||||
* const size: ImageSize = 256;
|
||||
*/
|
||||
export type ImageSize = 256 | 512;
|
||||
|
||||
/**
|
||||
* WebP compression quality level.
|
||||
*
|
||||
* `75` gives smaller files with minor quality loss. `85` gives higher visual
|
||||
* fidelity at roughly 1.5x the file size. The difference is most visible on
|
||||
* large displays or when zoomed in.
|
||||
*
|
||||
* @example
|
||||
* import type { ImageQuality } from 'moon-cycle';
|
||||
* const quality: ImageQuality = 75; // smaller, faster
|
||||
*/
|
||||
export type ImageQuality = 75 | 85;
|
||||
|
||||
/**
|
||||
* Length of one synodic month in days.
|
||||
* Source: IAU mean value (J2000.0 epoch).
|
||||
*
|
||||
* IAU mean value at J2000.0. Used by `cycleMonth` to divide the elapsed
|
||||
* time into a fractional position within the current lunar cycle.
|
||||
*
|
||||
* @example
|
||||
* import { SYNODIC_MONTH } from 'moon-cycle';
|
||||
* // Days old: how far into the current cycle
|
||||
* const now = new Date();
|
||||
* const elapsed = (now.getTime() - MONTH_ANCHOR.getTime()) / 86400000;
|
||||
* const age = ((elapsed % SYNODIC_MONTH) + SYNODIC_MONTH) % SYNODIC_MONTH;
|
||||
*/
|
||||
export const SYNODIC_MONTH = 29.53058821398858;
|
||||
|
||||
/** Number of images in the monthly (mm) dataset. */
|
||||
/**
|
||||
* Number of images in the monthly (`mm`) dataset.
|
||||
*
|
||||
* Equals the number of hours in one synodic month, rounded to the nearest
|
||||
* integer. Filenames range from `"001.webp"` to `"708.webp"`.
|
||||
*
|
||||
* @example
|
||||
* import { MONTH_IMAGES } from 'moon-cycle';
|
||||
* // Fraction of the way through the synodic cycle
|
||||
* const index = Math.floor(fraction * MONTH_IMAGES) + 1;
|
||||
*/
|
||||
export const MONTH_IMAGES = 708;
|
||||
|
||||
/** Number of images in the yearly (my) dataset. */
|
||||
/**
|
||||
* Number of images in the yearly (`my`) dataset.
|
||||
*
|
||||
* Equals 365 days × 24 hours. Filenames range from `"0001.webp"` to
|
||||
* `"8760.webp"`.
|
||||
*
|
||||
* @example
|
||||
* import { YEAR_IMAGES } from 'moon-cycle';
|
||||
* // Total hours in the yearly dataset
|
||||
* console.log(YEAR_IMAGES); // 8760
|
||||
*/
|
||||
export const YEAR_IMAGES = 8760;
|
||||
|
||||
/**
|
||||
* Anchor date for the monthly cycle: the 2023-11-13 new moon (UTC).
|
||||
* All synodic phase calculations are derived from this reference point.
|
||||
*
|
||||
* All synodic phase calculations measure elapsed time from this reference
|
||||
* point. Confirmed against JPL Horizons ephemeris data.
|
||||
*
|
||||
* @example
|
||||
* import { MONTH_ANCHOR } from 'moon-cycle';
|
||||
* const ageMs = Date.now() - MONTH_ANCHOR.getTime();
|
||||
*/
|
||||
export const MONTH_ANCHOR = new Date('2023-11-13T09:27:00Z');
|
||||
|
||||
/**
|
||||
* Anchor date for the yearly cycle: start of the 2023 NASA image collection.
|
||||
* The 8,760 images correspond to one per hour for the full calendar year 2023.
|
||||
*
|
||||
* The 8,760 images correspond to one per hour for the full calendar year
|
||||
* 2023. `cycleYear` measures elapsed time from this reference point.
|
||||
*
|
||||
* @example
|
||||
* import { YEAR_ANCHOR } from 'moon-cycle';
|
||||
* const hours = (Date.now() - YEAR_ANCHOR.getTime()) / 3600000;
|
||||
*/
|
||||
export const YEAR_ANCHOR = new Date('2023-01-01T00:00:00Z');
|
||||
|
|
|
|||
Loading…
Reference in a new issue