mirror of
https://github.com/acamarata/nrel-spa.git
synced 2026-07-01 11:24:25 +00:00
51dcf89d63
Fixed: - calcSpa with empty angles array no longer crashes (consistent guard with getSpa) - getSpa with SPA_ZA/SPA_ZA_INC now returns NaN for sunrise/solarNoon/sunset instead of misleading 0; calcSpa returns "N/A" for those fields - lib/spa.js header comment corrected from dist/spa.js to lib/spa.js - dist/spa.js removed (file moved to lib/spa.js in v2.0.0, stale copy deleted) - wiki-sync.yml handles first-run when GitHub Wiki repo does not yet exist - CI pack-check grep uses word-boundary pattern to prevent false prefix matches - Removed package-import-method=hardlink from .npmrc (pnpm default, caused npm warn) Added: - options.function validated before calculation; invalid code throws RangeError - angles with non-RTS function code throws RangeError (requires suntransit) - TypeScript function overloads for getSpa and calcSpa; angles typed as [number, ...number[]] non-empty tuple, narrows return type automatically - SpaFormattedAnglesResult interface, consistent with SpaAnglesResult - CI jobs declare explicit permissions: contents: read - Wiki: Implementation Comparison page with accuracy table (8 locations vs C reference, max delta 0.49 s) and performance benchmarks (nrel-spa vs solar-spa vs C, both SPA_ZA_RTS and SPA_ZA modes, 200k iterations on Node v24.6.0) - Wiki: API Reference updated with named types, all throws, Named Types block - Wiki: Architecture updated with all exported interfaces
45 lines
1.8 KiB
Markdown
45 lines
1.8 KiB
Markdown
# nrel-spa
|
|
|
|
Pure JavaScript implementation of the NREL Solar Position Algorithm (SPA). Computes solar zenith angle, azimuth, sunrise, sunset, and solar noon for any location and date. Validated to produce identical output to the original NREL C reference implementation.
|
|
|
|
## Overview
|
|
|
|
**Package:** [nrel-spa on npm](https://www.npmjs.com/package/nrel-spa)
|
|
**Repository:** [acamarata/nrel-spa on GitHub](https://github.com/acamarata/nrel-spa)
|
|
**License:** MIT (wrapper). NREL SPA C source: see LICENSE for third-party notice.
|
|
|
|
## Pages
|
|
|
|
- [API Reference](API-Reference) - Full function signatures, parameters, return types
|
|
- [Architecture](Architecture) - How the algorithm is structured and validated
|
|
- [Twilight Calculations](Twilight-Calculations) - Custom zenith angles for civil, nautical, astronomical twilight
|
|
- [NREL SPA Algorithm](NREL-SPA-Algorithm) - The algorithm background, accuracy, and reference
|
|
- [Implementation Comparison](Implementation-Comparison) - Accuracy and performance: nrel-spa vs solar-spa vs C reference
|
|
|
|
## Quick Example
|
|
|
|
```javascript
|
|
import { calcSpa } from 'nrel-spa';
|
|
|
|
const result = calcSpa(
|
|
new Date('2025-06-21T00:00:00Z'),
|
|
40.7128, // New York latitude
|
|
-74.006, // New York longitude
|
|
-4, // EDT (UTC-4)
|
|
);
|
|
|
|
console.log(result.sunrise); // "05:25:03"
|
|
console.log(result.solarNoon); // "12:57:56"
|
|
console.log(result.sunset); // "20:30:35"
|
|
```
|
|
|
|
## Key Facts
|
|
|
|
- Zero runtime dependencies
|
|
- Synchronous: no async, no WASM, no loading delay
|
|
- Dual CJS and ESM, full TypeScript definitions
|
|
- Matches NREL C reference output within one second across all tested locations
|
|
|
|
---
|
|
|
|
[API Reference](API-Reference) . [Architecture](Architecture) . [Twilight Calculations](Twilight-Calculations) . [NREL SPA Algorithm](NREL-SPA-Algorithm) . [Implementation Comparison](Implementation-Comparison)
|