Contributing

Prerequisites

Node.js 18 or later
pnpm 10 or later
Emscripten (only for recompiling the WASM module)

On macOS, Emscripten is available via Homebrew:

brew install emscripten

Building from source

Clone the repository, install dependencies, and build the TypeScript:

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):

pnpm run build:wasm

Or build everything at once:

pnpm run build

Running tests

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

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. Include:

Node.js version (node --version)
The input parameters that produced the unexpected result
Expected vs actual output

Home · Architecture · API Reference

2.6 KiB Raw Blame History