moon-cycle

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).

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.

Installation

npm install moon-cycle
# or
pnpm add moon-cycle

Quick Start

import { cycleMonth, cycleYear, 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);
// => 'https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@main/mm-256-75/354.webp'

CommonJS:

const { cycleMonth, cycleYear, 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.

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.

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

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.

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 for analysis of the synodic and calendar-year mapping approaches, how they differ, and when to prefer each.

Documentation

Full reference: GitHub Wiki

• Home
• API Reference
• Architecture
• Migration Guide (v1 to v2)

Related

• nrel-spa: Pure JS NREL Solar Position Algorithm, zero dependencies
• pray-calc: Islamic prayer times with dynamic angle algorithm
• luxon-hijri: Hijri/Gregorian calendar conversion
• moon-sighting: Lunar crescent visibility using Yallop and Odeh criteria

Acknowledgments

Moon phase imagery from NASA's Scientific Visualization Studio:

Ernie Wright (2023). Moon Phase and Libration, 2023 [Data set]. NASA Scientific Visualization Studio. https://svs.gsfc.nasa.gov/5187

Images are in the public domain per NASA's media usage guidelines.

License

MIT. See LICENSE for the full text.