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?)` ### `cycleMonth(date?)`
```ts ```ts
function cycleMonth(date?: Date): string function cycleMonth(date?: Date): string;
``` ```
Maps a date to an image filename in the **monthly (synodic) dataset**. 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:** **Parameters:**
| Name | Type | Default | Description | | Name | Type | Default | Description |
| --- | --- | --- | --- | | ------ | ------ | ------------ | ------------------- |
| `date` | `Date` | `new Date()` | The date to resolve | | `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"`. **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 ```ts
import { cycleMonth } from 'moon-cycle'; import { cycleMonth } from 'moon-cycle';
cycleMonth(); // current lunar phase cycleMonth(); // current lunar phase
cycleMonth(new Date('2024-01-15')); // specific date cycleMonth(new Date('2024-01-15')); // specific date
cycleMonth(new Date('2020-06-21')); // any past date works 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?)` ### `cycleYear(date?)`
```ts ```ts
function cycleYear(date?: Date): string function cycleYear(date?: Date): string;
``` ```
Maps a date to an image filename in the **yearly dataset**. 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:** **Parameters:**
| Name | Type | Default | Description | | Name | Type | Default | Description |
| --- | --- | --- | --- | | ------ | ------ | ------------ | ------------------- |
| `date` | `Date` | `new Date()` | The date to resolve | | `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"`. **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 ```ts
import { cycleYear } from 'moon-cycle'; 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 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)` ### `imageFolder(set, size, quality)`
```ts ```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. 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:** **Parameters:**
| Name | Type | Description | | Name | Type | Description |
| --- | --- | --- | | --------- | -------------- | ------------------------- |
| `set` | `'mm' \| 'my'` | Monthly or yearly dataset | | `set` | `'mm' \| 'my'` | Monthly or yearly dataset |
| `size` | `256 \| 512` | Image dimension in pixels | | `size` | `256 \| 512` | Image dimension in pixels |
| `quality` | `75 \| 85` | WebP compression quality | | `quality` | `75 \| 85` | WebP compression quality |
**Returns:** A string like `"mm-256-75"`. **Returns:** A string like `"mm-256-75"`.
@ -88,12 +88,12 @@ Directory names follow the pattern `{set}-{size}-{quality}`, matching the layout
```ts ```ts
import { imageFolder } from 'moon-cycle'; import { imageFolder } from 'moon-cycle';
imageFolder('mm', 256, 75) // => 'mm-256-75' imageFolder('mm', 256, 75); // => 'mm-256-75'
imageFolder('my', 512, 85) // => 'my-512-85' imageFolder('my', 512, 85); // => 'my-512-85'
// Use with a local public directory: // Use with a local public directory:
const filename = cycleMonth(); const filename = cycleMonth();
const folder = imageFolder('mm', 512, 85); const folder = imageFolder('mm', 512, 85);
const localUrl = `/public/${folder}/${filename}`; const localUrl = `/public/${folder}/${filename}`;
``` ```
@ -107,21 +107,21 @@ function cdnUrl(
set: ImageSet, set: ImageSet,
size: ImageSize, size: ImageSize,
quality: ImageQuality, quality: ImageQuality,
ref?: string ref?: string,
): 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. 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:** **Parameters:**
| Name | Type | Default | Description | | Name | Type | Default | Description |
| --- | --- | --- | --- | | ---------- | -------------- | -------- | --------------------------------------------- |
| `filename` | `string` |: | Filename from `cycleMonth()` or `cycleYear()` | | `filename` | `string` | : | Filename from `cycleMonth()` or `cycleYear()` |
| `set` | `'mm' \| 'my'` |: | Monthly or yearly dataset | | `set` | `'mm' \| 'my'` | : | Monthly or yearly dataset |
| `size` | `256 \| 512` |: | Image dimension in pixels | | `size` | `256 \| 512` | : | Image dimension in pixels |
| `quality` | `75 \| 85` |: | WebP compression quality | | `quality` | `75 \| 85` | : | WebP compression quality |
| `ref` | `string` | `'main'` | Branch name, git tag, or commit SHA | | `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"`. **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 ## Constants
| Export | Type | Value | Description | | Export | Type | Value | Description |
| --- | --- | --- | --- | | --------------- | -------- | ---------------------- | ------------------------------------ |
| `SYNODIC_MONTH` | `number` | `29.53058821398858` | IAU mean synodic month in days | | `SYNODIC_MONTH` | `number` | `29.53058821398858` | IAU mean synodic month in days |
| `MONTH_IMAGES` | `number` | `708` | Image count in the monthly dataset | | `MONTH_IMAGES` | `number` | `708` | Image count in the monthly dataset |
| `YEAR_IMAGES` | `number` | `8760` | Image count in the yearly dataset | | `YEAR_IMAGES` | `number` | `8760` | Image count in the yearly dataset |
| `MONTH_ANCHOR` | `Date` | `2023-11-13T09:27:00Z` | New moon reference for `cycleMonth` | | `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` | | `YEAR_ANCHOR` | `Date` | `2023-01-01T00:00:00Z` | Year start reference for `cycleYear` |
**Example:** **Example:**
@ -164,7 +164,7 @@ import { SYNODIC_MONTH, MONTH_ANCHOR } from 'moon-cycle';
// Compute the next new moon after a given date // Compute the next new moon after a given date
function nextNewMoon(after: Date): Date { function nextNewMoon(after: Date): Date {
const elapsed = (after.getTime() - MONTH_ANCHOR.getTime()) / (1000 * 60 * 60 * 24); 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); return new Date(MONTH_ANCHOR.getTime() + cycles * SYNODIC_MONTH * 86400000);
} }
``` ```
@ -189,19 +189,19 @@ type ImageQuality = 75 | 85;
## Image Dataset Reference ## Image Dataset Reference
| Folder | Set | Images | Resolution | Quality | Approx. Size | | Folder | Set | Images | Resolution | Quality | Approx. Size |
| --- | --- | --- | --- | --- | --- | | ----------- | ------- | ------ | ---------- | ------- | ------------ |
| `mm-256-75` | monthly | 708 | 256x256 | 75 | ~4 MB | | `mm-256-75` | monthly | 708 | 256x256 | 75 | ~4 MB |
| `mm-256-85` | monthly | 708 | 256x256 | 85 | ~5 MB | | `mm-256-85` | monthly | 708 | 256x256 | 85 | ~5 MB |
| `mm-512-75` | monthly | 708 | 512x512 | 75 | ~9 MB | | `mm-512-75` | monthly | 708 | 512x512 | 75 | ~9 MB |
| `mm-512-85` | monthly | 708 | 512x512 | 85 | ~14 MB | | `mm-512-85` | monthly | 708 | 512x512 | 85 | ~14 MB |
| `my-256-75` | yearly | 8,760 | 256x256 | 75 | ~51 MB | | `my-256-75` | yearly | 8,760 | 256x256 | 75 | ~51 MB |
| `my-256-85` | yearly | 8,760 | 256x256 | 85 | ~66 MB | | `my-256-85` | yearly | 8,760 | 256x256 | 85 | ~66 MB |
| `my-512-75` | yearly | 8,760 | 512x512 | 75 | ~113 MB | | `my-512-75` | yearly | 8,760 | 512x512 | 75 | ~113 MB |
| `my-512-85` | yearly | 8,760 | 512x512 | 85 | ~176 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). 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 ### 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`) ## 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 ## Choosing Between the Two
| Scenario | Recommendation | | Scenario | Recommendation |
| --- | --- | | -------------------------------------------------------- | --------------------------------------------------- |
| Show the actual current moon phase | `cycleMonth` | | Show the actual current moon phase | `cycleMonth` |
| Animate through a year of moon phases for a calendar app | `cycleYear` | | Animate through a year of moon phases for a calendar app | `cycleYear` |
| Show a consistent seasonal moon appearance | `cycleYear` | | Show a consistent seasonal moon appearance | `cycleYear` |
| Compute when the next full moon occurs | `cycleMonth` + `SYNODIC_MONTH` | | Compute when the next full moon occurs | `cycleMonth` + `SYNODIC_MONTH` |
| Display a decorative moon that changes daily | Either: `cycleYear` has smoother hourly progression | | Display a decorative moon that changes daily | Either: `cycleYear` has smoother hourly progression |
## Package Structure ## 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: 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 | | `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. See [Architecture](Architecture) for a full explanation of each approach.
@ -28,7 +28,7 @@ pnpm add moon-cycle
import { cycleMonth, cdnUrl } from 'moon-cycle'; import { cycleMonth, cdnUrl } from 'moon-cycle';
const file = cycleMonth(); // e.g. "354.webp": current lunar phase 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' // => '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: Pick the folder that fits your use case:
| Folder | Images | Size | | Folder | Images | Size |
| --- | --- | --- | | ----------- | -------------- | ------- |
| `mm-256-75` | 708 (monthly) | ~4 MB | | `mm-256-75` | 708 (monthly) | ~4 MB |
| `mm-512-85` | 708 (monthly) | ~14 MB | | `mm-512-85` | 708 (monthly) | ~14 MB |
| `my-256-75` | 8,760 (yearly) | ~51 MB | | `my-256-75` | 8,760 (yearly) | ~51 MB |
| `my-512-85` | 8,760 (yearly) | ~176 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. 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 ```ts
// v1: incorrect // v1: incorrect
export function cycleMonth(date: Date): MonthResult; 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: 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)_