mirror of
https://github.com/acamarata/nrel-spa.git
synced 2026-06-30 19:04:25 +00:00
b44d9a958b
Complete modernization of the package. The core SPA algorithm is unchanged and validated; everything else is rebuilt to match current JavaScript ecosystem standards. Changes: - TypeScript wrapper in src/ with full type definitions - Dual CJS/ESM build via tsup (dist/index.cjs, dist/index.mjs) - Core algorithm moved from dist/spa.js to lib/spa.js (same code) - Input validation with descriptive TypeError/RangeError messages - formatTime() and SPA function code constants as named exports - getSpa() / calcSpa() accept null for optional args (tz, options) - Test suite: 61 ESM assertions and 17 CJS assertions - GitHub Actions CI: Node 20/22/24 matrix, typecheck, pack-check - GitHub Wiki: Home, API Reference, Architecture, Twilight, NREL SPA - NREL attribution in LICENSE and README per their license terms - package.json: exports map, files, engines >=20, sideEffects: false - Author corrected to Aric Camarata; repository.url uses git+https:// - LICENSE year corrected to 2023-2026 - Removed: index.js, test.js, dist/spa.js (superseded by above)
131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# API Reference
|
|
|
|
## Functions
|
|
|
|
### `getSpa(date, latitude, longitude, timezone?, options?, angles?)`
|
|
|
|
Computes solar position for the given date and location. Returns raw numerical values.
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| --- | --- | --- | --- |
|
|
| `date` | `Date` | Yes | UTC date and time. Uses UTC components internally. |
|
|
| `latitude` | `number` | Yes | Observer latitude, -90 to 90. Negative = south. |
|
|
| `longitude` | `number` | Yes | Observer longitude, -180 to 180. Negative = west. |
|
|
| `timezone` | `number \| null` | No | Hours from UTC (e.g., -4 for EDT). Default: `0`. |
|
|
| `options` | `SpaOptions \| null` | No | Atmospheric and calculation parameters. |
|
|
| `angles` | `number[]` | No | Custom zenith angles in degrees. See [Twilight Calculations](Twilight-Calculations). |
|
|
|
|
**Returns:** `SpaResult`
|
|
|
|
```typescript
|
|
interface SpaResult {
|
|
zenith: number; // topocentric zenith angle (degrees)
|
|
azimuth: number; // topocentric azimuth, eastward from north (degrees)
|
|
sunrise: number; // local sunrise (fractional hours, e.g. 5.417 = 05:25)
|
|
solarNoon: number; // local solar noon (fractional hours)
|
|
sunset: number; // local sunset (fractional hours)
|
|
}
|
|
```
|
|
|
|
When `angles` is provided, returns `SpaResultWithAngles`:
|
|
|
|
```typescript
|
|
interface SpaResultWithAngles extends SpaResult {
|
|
angles: Array<{ sunrise: number; sunset: number }>;
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
- `TypeError` if `date` is not a valid Date, or `latitude`/`longitude` are not finite numbers
|
|
- `RangeError` if `latitude` is outside [-90, 90] or `longitude` outside [-180, 180]
|
|
- `Error` if the internal SPA calculation returns a non-zero error code
|
|
|
|
---
|
|
|
|
### `calcSpa(date, latitude, longitude, timezone?, options?, angles?)`
|
|
|
|
Same parameters as `getSpa()`. Formats `sunrise`, `solarNoon`, and `sunset` as `HH:MM:SS` strings.
|
|
|
|
**Returns:** `SpaFormattedResult`
|
|
|
|
```typescript
|
|
interface SpaFormattedResult {
|
|
zenith: number; // same as SpaResult
|
|
azimuth: number; // same as SpaResult
|
|
sunrise: string; // "HH:MM:SS" or "N/A" during polar day/night
|
|
solarNoon: string; // "HH:MM:SS" or "N/A"
|
|
sunset: string; // "HH:MM:SS" or "N/A"
|
|
}
|
|
```
|
|
|
|
When `angles` is provided, returns `SpaFormattedResultWithAngles`:
|
|
|
|
```typescript
|
|
interface SpaFormattedResultWithAngles extends SpaFormattedResult {
|
|
angles: Array<{ sunrise: string; sunset: string }>;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `formatTime(hours)`
|
|
|
|
Converts a fractional hour value to `HH:MM:SS` format.
|
|
|
|
```javascript
|
|
formatTime(5.417489) // "05:25:03"
|
|
formatTime(12) // "12:00:00"
|
|
formatTime(23.9997) // "23:59:59"
|
|
formatTime(-1) // "N/A"
|
|
formatTime(NaN) // "N/A"
|
|
formatTime(Infinity) // "N/A"
|
|
```
|
|
|
|
---
|
|
|
|
## SpaOptions
|
|
|
|
All options are optional. Defaults match the NREL C reference implementation.
|
|
|
|
| Option | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `elevation` | `number` | `0` | Observer elevation above sea level in meters. |
|
|
| `pressure` | `number` | `1013` | Annual average atmospheric pressure in millibars. |
|
|
| `temperature` | `number` | `15` | Annual average temperature in degrees Celsius. |
|
|
| `delta_ut1` | `number` | `0` | Fractional second difference between UTC and UT1. Valid range: (-1, 1). |
|
|
| `delta_t` | `number` | `67` | Difference between Terrestrial Time and UTC in seconds. |
|
|
| `slope` | `number` | `0` | Surface slope from horizontal in degrees. Used for incidence angle (SPA_ZA_INC, SPA_ALL). |
|
|
| `azm_rotation` | `number` | `0` | Surface azimuth rotation from south in degrees. |
|
|
| `atmos_refract` | `number` | `0.5667` | Atmospheric refraction at sunrise/sunset in degrees. |
|
|
| `function` | `SpaFunctionCode` | `SPA_ZA_RTS` | Which outputs to compute. |
|
|
|
|
---
|
|
|
|
## Function Codes
|
|
|
|
```javascript
|
|
import { SPA_ZA, SPA_ZA_INC, SPA_ZA_RTS, SPA_ALL } from 'nrel-spa';
|
|
```
|
|
|
|
| Constant | Value | Outputs Computed |
|
|
| --- | --- | --- |
|
|
| `SPA_ZA` | `0` | `zenith`, `azimuth` |
|
|
| `SPA_ZA_INC` | `1` | `zenith`, `azimuth`, incidence angle (for solar panels on sloped surfaces) |
|
|
| `SPA_ZA_RTS` | `2` | `zenith`, `azimuth`, `sunrise`, `solarNoon`, `sunset` |
|
|
| `SPA_ALL` | `3` | All outputs from SPA_ZA_INC and SPA_ZA_RTS combined |
|
|
|
|
The default is `SPA_ZA_RTS`. Use `SPA_ZA` for zenith/azimuth-only calculations if you do not need rise/set times; it skips the three-day calculation that rise/set requires and is slightly faster.
|
|
|
|
---
|
|
|
|
## SpaFunctionCode Type
|
|
|
|
```typescript
|
|
type SpaFunctionCode = 0 | 1 | 2 | 3;
|
|
```
|
|
|
|
---
|
|
|
|
[Home](Home) . [Architecture](Architecture) . [Twilight Calculations](Twilight-Calculations) . [NREL SPA Algorithm](NREL-SPA-Algorithm)
|