mirror of
https://github.com/acamarata/solar-spa.git
synced 2026-07-01 11:24:28 +00:00
91 lines
2.6 KiB
Markdown
91 lines
2.6 KiB
Markdown
# Contributing
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18 or later
|
|
- pnpm 10 or later
|
|
- [Emscripten](https://emscripten.org/docs/getting_started/downloads.html) (only for recompiling the WASM module)
|
|
|
|
On macOS, Emscripten is available via Homebrew:
|
|
|
|
```sh
|
|
brew install emscripten
|
|
```
|
|
|
|
## Building from source
|
|
|
|
Clone the repository, install dependencies, and build the TypeScript:
|
|
|
|
```sh
|
|
git clone https://github.com/acamarata/solar-spa.git
|
|
cd solar-spa
|
|
pnpm install
|
|
pnpm run build:ts
|
|
```
|
|
|
|
To recompile the WASM module (requires Emscripten):
|
|
|
|
```sh
|
|
pnpm run build:wasm
|
|
```
|
|
|
|
Or build everything at once:
|
|
|
|
```sh
|
|
pnpm run build
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```sh
|
|
pnpm test
|
|
```
|
|
|
|
This runs both the ESM test suite (`test.mjs`, 66 assertions) and the CJS smoke test (`test-cjs.cjs`). Tests cover multiple geographic locations, seasons, input validation, error handling, concurrent initialization, polar regions, boundary coordinates, and all SPA function codes.
|
|
|
|
## Type checking
|
|
|
|
```sh
|
|
pnpm run typecheck
|
|
```
|
|
|
|
## Project structure
|
|
|
|
```
|
|
src/
|
|
index.ts # Main implementation (TypeScript source)
|
|
types.ts # Type definitions and constants
|
|
spa.c # NREL SPA algorithm (do not modify)
|
|
spa.h # NREL SPA header (do not modify)
|
|
spa_wrapper.c # Flat wrapper for WASM boundary
|
|
wasm/
|
|
spa-module.js # Compiled WASM output (~60KB, inlined as base64)
|
|
dist/ # Generated by tsup (CJS + ESM + declarations)
|
|
index.cjs
|
|
index.mjs
|
|
index.d.ts # CJS declarations
|
|
index.d.mts # ESM declarations
|
|
test.mjs # ESM test suite
|
|
test-cjs.cjs # CJS smoke test
|
|
tsup.config.ts # Build configuration
|
|
tsconfig.json # TypeScript configuration
|
|
```
|
|
|
|
## Guidelines
|
|
|
|
- Do not modify `spa.c` or `spa.h`. These are the original NREL source files and should remain identical to the NREL distribution.
|
|
- Changes to `spa_wrapper.c` that add new output fields require corresponding changes in `src/index.ts` (the OFFSET map and `readResult` function) and `src/types.ts` (the result interfaces).
|
|
- Run `pnpm test` and `pnpm run typecheck` before submitting. All tests and type checks should pass.
|
|
- The test suite uses approximate comparisons (`approx` with a tolerance) because floating-point results vary slightly across platforms and Emscripten versions.
|
|
|
|
## Reporting bugs
|
|
|
|
Open an issue at [github.com/acamarata/solar-spa/issues](https://github.com/acamarata/solar-spa/issues). Include:
|
|
|
|
- Node.js version (`node --version`)
|
|
- The input parameters that produced the unexpected result
|
|
- Expected vs actual output
|
|
|
|
---
|
|
|
|
[Home](Home) · [Architecture](Architecture) · [API Reference](API-Reference)
|