aric/moon-cycle
1
0
Fork 0
mirror of https://github.com/acamarata/moon-cycle.git synced 2026-06-30 18:54:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

style: fix prettier table formatting in wiki

Browse source
This commit is contained in:
Aric Camarata 2026-03-08 17:30:34 -04:00
parent 0744ae0080
commit bf92d67a56
4 changed files with 70 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
.wiki/API-Reference.md
View file

@ -7,7 +7,7 @@ Complete reference for moon-cycle v2.
### `cycleMonth(date?)`
```ts
function cycleMonth(date?: Date): string
function cycleMonth(date?: Date): string;
```
Maps a date to an image filename in the **monthly (synodic) dataset**.
@ -16,8 +16,8 @@ The 708 images cover one complete synodic month at hourly resolution. The functi
**Parameters:**
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Name | Type | Default | Description |
| ------ | ------ | ------------ | ------------------- |
| `date` | `Date` | `new Date()` | The date to resolve |
**Returns:** A zero-padded filename string, e.g. `"354.webp"`. Always in the range `"001.webp"` to `"708.webp"`.
@ -27,9 +27,9 @@ The 708 images cover one complete synodic month at hourly resolution. The functi
```ts
import { cycleMonth } from 'moon-cycle';
cycleMonth(); // current lunar phase
cycleMonth(new Date('2024-01-15')); // specific date
cycleMonth(new Date('2020-06-21')); // any past date works
cycleMonth(); // current lunar phase
cycleMonth(new Date('2024-01-15')); // specific date
cycleMonth(new Date('2020-06-21')); // any past date works
```
---
@ -37,7 +37,7 @@ cycleMonth(new Date('2020-06-21')); // any past date works
### `cycleYear(date?)`
```ts
function cycleYear(date?: Date): string
function cycleYear(date?: Date): string;
```
Maps a date to an image filename in the **yearly dataset**.
@ -46,8 +46,8 @@ The 8,760 images cover the full calendar year 2023 at hourly resolution. The fun
**Parameters:**
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Name | Type | Default | Description |
| ------ | ------ | ------------ | ------------------- |
| `date` | `Date` | `new Date()` | The date to resolve |
**Returns:** A zero-padded filename string, e.g. `"4380.webp"`. Always in the range `"0001.webp"` to `"8760.webp"`.
@ -57,7 +57,7 @@ The 8,760 images cover the full calendar year 2023 at hourly resolution. The fun
```ts
import { cycleYear } from 'moon-cycle';
cycleYear(); // current hour-of-year position
cycleYear(); // current hour-of-year position
cycleYear(new Date('2025-07-04T12:00Z')); // July 4, noon
```
@ -66,7 +66,7 @@ cycleYear(new Date('2025-07-04T12:00Z')); // July 4, noon
### `imageFolder(set, size, quality)`
```ts
function imageFolder(set: ImageSet, size: ImageSize, quality: ImageQuality): string
function imageFolder(set: ImageSet, size: ImageSize, quality: ImageQuality): string;
```
Returns the directory name for a given combination of image set, size, and quality.
@ -75,11 +75,11 @@ Directory names follow the pattern `{set}-{size}-{quality}`, matching the layout
**Parameters:**
| Name | Type | Description |
| --- | --- | --- |
| `set` | `'mm' \| 'my'` | Monthly or yearly dataset |
| `size` | `256 \| 512` | Image dimension in pixels |
| `quality` | `75 \| 85` | WebP compression quality |
| Name | Type | Description |
| --------- | -------------- | ------------------------- |
| `set` | `'mm' \| 'my'` | Monthly or yearly dataset |
| `size` | `256 \| 512` | Image dimension in pixels |
| `quality` | `75 \| 85` | WebP compression quality |
**Returns:** A string like `"mm-256-75"`.
@ -88,12 +88,12 @@ Directory names follow the pattern `{set}-{size}-{quality}`, matching the layout
```ts
import { imageFolder } from 'moon-cycle';
imageFolder('mm', 256, 75) // => 'mm-256-75'
imageFolder('my', 512, 85) // => 'my-512-85'
imageFolder('mm', 256, 75); // => 'mm-256-75'
imageFolder('my', 512, 85); // => 'my-512-85'
// Use with a local public directory:
const filename = cycleMonth();
const folder = imageFolder('mm', 512, 85);
const folder = imageFolder('mm', 512, 85);
const localUrl = `/public/${folder}/${filename}`;
```
@ -107,21 +107,21 @@ function cdnUrl(
set: ImageSet,
size: ImageSize,
quality: ImageQuality,
ref?: string
): string
ref?: string,
): string;
```
Returns a jsDelivr CDN URL serving the specified image directly from the GitHub repository. jsDelivr caches GitHub content via a global CDN with no account or configuration required.
**Parameters:**
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `filename` | `string` |: | Filename from `cycleMonth()` or `cycleYear()` |
| `set` | `'mm' \| 'my'` |: | Monthly or yearly dataset |
| `size` | `256 \| 512` |: | Image dimension in pixels |
| `quality` | `75 \| 85` |: | WebP compression quality |
| `ref` | `string` | `'main'` | Branch name, git tag, or commit SHA |
| Name | Type | Default | Description |
| ---------- | -------------- | -------- | --------------------------------------------- |
| `filename` | `string` | : | Filename from `cycleMonth()` or `cycleYear()` |
| `set` | `'mm' \| 'my'` | : | Monthly or yearly dataset |
| `size` | `256 \| 512` | : | Image dimension in pixels |
| `quality` | `75 \| 85` | : | WebP compression quality |
| `ref` | `string` | `'main'` | Branch name, git tag, or commit SHA |
**Returns:** A full URL string, e.g. `"https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@main/mm-256-75/354.webp"`.
@ -148,13 +148,13 @@ function MoonImage() {
## Constants
| Export | Type | Value | Description |
| --- | --- | --- | --- |
| `SYNODIC_MONTH` | `number` | `29.53058821398858` | IAU mean synodic month in days |
| `MONTH_IMAGES` | `number` | `708` | Image count in the monthly dataset |
| `YEAR_IMAGES` | `number` | `8760` | Image count in the yearly dataset |
| `MONTH_ANCHOR` | `Date` | `2023-11-13T09:27:00Z` | New moon reference for `cycleMonth` |
| `YEAR_ANCHOR` | `Date` | `2023-01-01T00:00:00Z` | Year start reference for `cycleYear` |
| Export | Type | Value | Description |
| --------------- | -------- | ---------------------- | ------------------------------------ |
| `SYNODIC_MONTH` | `number` | `29.53058821398858` | IAU mean synodic month in days |
| `MONTH_IMAGES` | `number` | `708` | Image count in the monthly dataset |
| `YEAR_IMAGES` | `number` | `8760` | Image count in the yearly dataset |
| `MONTH_ANCHOR` | `Date` | `2023-11-13T09:27:00Z` | New moon reference for `cycleMonth` |
| `YEAR_ANCHOR` | `Date` | `2023-01-01T00:00:00Z` | Year start reference for `cycleYear` |
**Example:**
@ -164,7 +164,7 @@ import { SYNODIC_MONTH, MONTH_ANCHOR } from 'moon-cycle';
// Compute the next new moon after a given date
function nextNewMoon(after: Date): Date {
const elapsed = (after.getTime() - MONTH_ANCHOR.getTime()) / (1000 * 60 * 60 * 24);
const cycles = Math.ceil(elapsed / SYNODIC_MONTH);
const cycles = Math.ceil(elapsed / SYNODIC_MONTH);
return new Date(MONTH_ANCHOR.getTime() + cycles * SYNODIC_MONTH * 86400000);
}
```
@ -189,19 +189,19 @@ type ImageQuality = 75 | 85;
## Image Dataset Reference
| Folder | Set | Images | Resolution | Quality | Approx. Size |
| --- | --- | --- | --- | --- | --- |
| `mm-256-75` | monthly | 708 | 256x256 | 75 | ~4 MB |
| `mm-256-85` | monthly | 708 | 256x256 | 85 | ~5 MB |
| `mm-512-75` | monthly | 708 | 512x512 | 75 | ~9 MB |
| `mm-512-85` | monthly | 708 | 512x512 | 85 | ~14 MB |
| `my-256-75` | yearly | 8,760 | 256x256 | 75 | ~51 MB |
| `my-256-85` | yearly | 8,760 | 256x256 | 85 | ~66 MB |
| `my-512-75` | yearly | 8,760 | 512x512 | 75 | ~113 MB |
| `my-512-85` | yearly | 8,760 | 512x512 | 85 | ~176 MB |
| Folder | Set | Images | Resolution | Quality | Approx. Size |
| ----------- | ------- | ------ | ---------- | ------- | ------------ |
| `mm-256-75` | monthly | 708 | 256x256 | 75 | ~4 MB |
| `mm-256-85` | monthly | 708 | 256x256 | 85 | ~5 MB |
| `mm-512-75` | monthly | 708 | 512x512 | 75 | ~9 MB |
| `mm-512-85` | monthly | 708 | 512x512 | 85 | ~14 MB |
| `my-256-75` | yearly | 8,760 | 256x256 | 75 | ~51 MB |
| `my-256-85` | yearly | 8,760 | 256x256 | 85 | ~66 MB |
| `my-512-75` | yearly | 8,760 | 512x512 | 75 | ~113 MB |
| `my-512-85` | yearly | 8,760 | 512x512 | 85 | ~176 MB |
All images are square WebP, transparent background, named with zero-padded indices (`001.webp` to `708.webp` for monthly, `0001.webp` to `8760.webp` for yearly).
---
*[Home](Home) | [Architecture](Architecture) | [Migration Guide](Migration)*
_[Home](Home) | [Architecture](Architecture) | [Migration Guide](Migration)_

18
.wiki/Architecture.md
View file

@ -45,7 +45,7 @@ index = floor(fraction * 708) + 1
### Limitation
The synodic month is not exactly 29.53058821398858 days: that value is the IAU *mean* (averaged over centuries). The actual length of a given synodic month varies by up to ~7 hours depending on the Moon's position in its elliptical orbit. For dates far from the 2023 reference period, accumulated drift means the image may be off by a few frames from the true observed phase. For UI purposes, this is imperceptible.
The synodic month is not exactly 29.53058821398858 days: that value is the IAU _mean_ (averaged over centuries). The actual length of a given synodic month varies by up to ~7 hours depending on the Moon's position in its elliptical orbit. For dates far from the 2023 reference period, accumulated drift means the image may be off by a few frames from the true observed phase. For UI purposes, this is imperceptible.
## Algorithm 2: Calendar Year (`cycleYear`)
@ -79,13 +79,13 @@ The year 2023 had 365 days (not a leap year), so the 8,760 images correspond exa
## Choosing Between the Two
| Scenario | Recommendation |
| --- | --- |
| Show the actual current moon phase | `cycleMonth` |
| Animate through a year of moon phases for a calendar app | `cycleYear` |
| Show a consistent seasonal moon appearance | `cycleYear` |
| Compute when the next full moon occurs | `cycleMonth` + `SYNODIC_MONTH` |
| Display a decorative moon that changes daily | Either: `cycleYear` has smoother hourly progression |
| Scenario | Recommendation |
| -------------------------------------------------------- | --------------------------------------------------- |
| Show the actual current moon phase | `cycleMonth` |
| Animate through a year of moon phases for a calendar app | `cycleYear` |
| Show a consistent seasonal moon appearance | `cycleYear` |
| Compute when the next full moon occurs | `cycleMonth` + `SYNODIC_MONTH` |
| Display a decorative moon that changes daily | Either: `cycleYear` has smoother hourly progression |
## Package Structure
@ -131,4 +131,4 @@ The probability of hitting the exact boundary where `000.webp` would have been r
---
*[Home](Home) | [API Reference](API-Reference) | [Migration Guide](Migration)*
_[Home](Home) | [API Reference](API-Reference) | [Migration Guide](Migration)_

20
.wiki/Home.md
View file

@ -8,10 +8,10 @@ Given any date, you get a filename like `354.webp` or `4380.webp` that correspon
Two algorithms are provided because they answer different questions:
| Function | Algorithm | Use when |
| --- | --- | --- |
| 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 |
| `cycleYear` | Calendar year (2023) | You want a consistent annual visual rhythm |
See [Architecture](Architecture) for a full explanation of each approach.
@ -28,7 +28,7 @@ pnpm add moon-cycle
import { cycleMonth, cdnUrl } from 'moon-cycle';
const file = cycleMonth(); // e.g. "354.webp": current lunar phase
const url = cdnUrl(file, 'mm', 256, 75);
const url = cdnUrl(file, 'mm', 256, 75);
// => 'https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@main/mm-256-75/354.webp'
```
@ -36,11 +36,11 @@ const url = cdnUrl(file, 'mm', 256, 75);
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 |
| 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.
@ -57,4 +57,4 @@ All eight combinations (`mm`/`my` × `256`/`512` × `75`/`85`) are available. Us
---
*Part of the [acamarata](https://github.com/acamarata) astronomical computing stack.*
_Part of the [acamarata](https://github.com/acamarata) astronomical computing stack._

6
.wiki/Migration.md
View file

@ -26,7 +26,9 @@ v1 shipped a hand-written `index.d.ts` that incorrectly declared both functions
```ts
// v1: incorrect
export function cycleMonth(date: Date): MonthResult;
interface MonthResult { result: string }
interface MonthResult {
result: string;
}
```
The actual runtime behavior in v1 was to return a plain `string`, not an object. v2 types match the implementation:
@ -75,4 +77,4 @@ v2 ships dual CJS and ESM builds. If you use a bundler, it will now automaticall
---
*[Home](Home) | [API Reference](API-Reference) | [Architecture](Architecture)*
_[Home](Home) | [API Reference](API-Reference) | [Architecture](Architecture)_