mirror of https://github.com/acamarata/moon-cycle.git synced 2026-06-30 18:54:29 +00:00

Aric Camarata 24db90e9f5 feat: v2.0.0 — TypeScript rewrite, npm-publishable, off-by-one fix

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

2026-02-25 15:34:10 -05:00

2 KiB

Raw Blame History

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 for a full explanation of each approach.

Installation

npm install moon-cycle
pnpm add moon-cycle

Quick start

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.

Source

github.com/acamarata/moon-cycle

Part of the acamarata astronomical computing stack.

2 KiB Raw Blame History Unescape Escape