### Complete Solar Tracking Example in TypeScript

Source: https://context7.com/semanticist21/solar-time/llms.txt

This example demonstrates a practical application of the solar-time library for a solar panel tracking system. It calculates the current sun's position based on a given latitude and longitude, then determines the optimal orientation angles for a solar panel. The code includes handling for nighttime and calculates daylight duration.

```typescript
import {getSolarTime, getSunPosition} from "solar-time";
import type {SunPositionResult} from "solar-time";

// Solar panel location: Phoenix, Arizona
const LATITUDE = 33.4484;
const LONGITUDE = -112.0740;
const TIMEZONE = "-07:00"; // MST

// Get current sun position
function getCurrentSunPosition(): SunPositionResult {
  const now = new Date();
  const isoString = now.toISOString().replace('Z', TIMEZONE);

  return getSunPosition(isoString, LATITUDE, LONGITUDE);
}

// Calculate optimal panel angles
function calculatePanelOrientation() {
  const position = getCurrentSunPosition();

  console.log(`Solar Panel Tracking System - ${new Date().toLocaleString()}`);
  console.log('─'.repeat(60));

  if (position.elevation < 0) {
    console.log('Status: Sun is below horizon (nighttime)');
    console.log('Action: Panel in rest position');
    return;
  }

  console.log(`Sun Azimuth: ${position.azimuth.toFixed(2)}°`);
  console.log(`Sun Elevation: ${position.elevation.toFixed(2)}°`);
  console.log(`Panel should face: ${position.azimuth.toFixed(2)}° from North`);
  console.log(`Panel tilt angle: ${position.elevation.toFixed(2)}° from horizontal`);
  console.log('');
  console.log(`Sunrise: ${position.sunrise}`);
  console.log(`Solar Noon: ${position.solarNoon}`);
  console.log(`Sunset: ${position.sunset}`);

  // Calculate daylight hours
  if (position.sunrise && position.sunset) {
    const sunrise = new Date(position.sunrise);
    const sunset = new Date(position.sunset);
    const daylightHours = (sunset.getTime() - sunrise.getTime()) / (1000 * 60 * 60);
    console.log(`Daylight Duration: ${daylightHours.toFixed(2)} hours`);
  }
}

// Track sun position every 15 minutes
calculatePanelOrientation();

// Example output:
// Solar Panel Tracking System - 11/1/2025, 2:30:00 PM
// ────────────────────────────────────────────────────────────
// Sun Azimuth: 214.73°
// Sun Elevation: 35.21°
// Panel should face: 214.73° from North
// Panel tilt angle: 35.21° from horizontal
//
// Sunrise: 2025-11-01T07:12:34-07:00
// Solar Noon: 2025-11-01T12:38:45-07:00
// Sunset: 2025-11-01T18:04:56-07:00
// Daylight Duration: 10.87 hours

```

--------------------------------

### Running Project Commands with pnpm

Source: https://github.com/semanticist21/solar-time/blob/main/CLAUDE.md

This section outlines the development commands for the project using the pnpm package manager. It covers testing, building, linting, formatting, and publishing workflows. Ensure pnpm version 10.20.0+ is installed.

```bash
pnpm test
pnpm test:watch
pnpm build
pnpm run format
pnpm run format:check
pnpm run lint
pnpm run lint:fix
pnpm run check
pnpm run check:fix
pnpm run publish-prod
```

--------------------------------

### Timezone Handling with ISO 8601 Strings in TypeScript

Source: https://context7.com/semanticist21/solar-time/llms.txt

Demonstrates how to correctly handle timezones using ISO 8601 strings with the solar-time library. It shows how to specify timezones for different locations and how the library preserves timezone information in its outputs. This is crucial for accurate solar event timing across the globe.

```typescript
import {getSolarTime, getSunPosition} from "solar-time";

// CORRECT: ISO 8601 string with explicit timezone
const tokyo = getSunPosition(
  "2025-11-01T09:00:00+09:00",  // JST (UTC+9)
  35.6762,
  139.6503
);
console.log(tokyo.sunrise); // "2025-11-01T06:07:23+09:00" (preserves timezone)

// Multiple timezones for same location
const newYork = {lat: 40.7128, lon: -74.0060};

// Eastern Standard Time (winter)
const winter = getSunPosition(
  "2025-11-01T12:00:00-05:00",  // EST (UTC-5)
  newYork.lat,
  newYork.lon
);
console.log(winter.sunset); // "2025-11-01T17:42:13-05:00"

// Eastern Daylight Time (summer)
const summer = getSunPosition(
  "2025-06-21T12:00:00-04:00",  // EDT (UTC-4)
  newYork.lat,
  newYork.lon
);
console.log(summer.sunset); // "2025-06-21T20:31:07-04:00"

// UTC timezone
const utc = getSolarTime("2025-11-01T12:00:00Z", 0);
console.log(utc.LST); // "2025-11-01T12:00:01Z" (preserves UTC)

// Calculate solar time for different timezones
function compareSolarTime(dateUTC: string, locations: Array<{name: string, lat: number, lon: number, offset: string}>) {
  console.log('Solar Time Comparison');
  console.log('─'.repeat(70));

  locations.forEach(loc => {
    const localTime = dateUTC.replace('Z', loc.offset);
    const solar = getSolarTime(localTime, loc.lon);

    console.log(`${loc.name.padEnd(15)} | Local: ${localTime} | Solar: ${solar.LST}`);
    console.log(`${' '.repeat(15)} | TC: ${solar.TC.toFixed(2)} min | EoT: ${solar.EoT.toFixed(2)} min`);
    console.log('');
  });
}

compareSolarTime("2025-11-01T12:00:00Z", [
  {name: "New York", lat: 40.71, lon: -74.01, offset: "-05:00"},
  {name: "London", lat: 51.51, lon: -0.13, offset: "+00:00"},
  {name: "Tokyo", lat: 35.68, lon: 139.65, offset: "+09:00"},
  {name: "Sydney", lat: -33.87, lon: 151.21, offset: "+11:00"}
]);

// Example output:
// Solar Time Comparison
// ──────────────────────────────────────────────────────────────────────
// New York        | Local: 2025-11-01T12:00:00-05:00 | Solar: 2025-11-01T12:20:34-05:00
//                 | TC: 20.57 min | EoT: 16.47 min
//
// London          | Local: 2025-11-01T12:00:00+00:00 | Solar: 2025-11-01T12:16:95+00:00
//                 | TC: 16.95 min | EoT: 16.47 min
//
// Tokyo           | Local: 2025-11-01T12:00:00+09:00 | Solar: 2025-11-01T12:15:07+09:00
//                 | TC: 15.07 min | EoT: 16.47 min
//
// Sydney          | Local: 2025-11-01T12:00:00+11:00 | Solar: 2025-11-01T12:21:31+11:00
//                 | TC: 21.31 min | EoT: 16.47 min

```

--------------------------------

### Core Sun Position Calculation Logic (TypeScript)

Source: https://github.com/semanticist21/solar-time/blob/main/CLAUDE.md

Illustrates the core logic for calculating sun position. It utilizes solar time data (TC, EoT, declination) to compute sunrise/sunset times, solar noon, and the current azimuth and elevation. Outputs are ISO 8601 strings, with null values for polar regions where sunrise/sunset may not occur.

```typescript
// Example placeholder for the sun position calculation logic
function calculateSunPosition(dateInput: Date | string | number, options?: { utcOffset?: number }): { sunrise: string | null, sunset: string | null, solarNoon: string, azimuth: number, elevation: number } {
  // ... implementation details ...
  return { sunrise: null, sunset: null, solarNoon: "", azimuth: 0, elevation: 0 };
}
```

--------------------------------

### Calculate Local Solar Time and Sun Position with JavaScript

Source: https://github.com/semanticist21/solar-time/blob/main/README.md

Demonstrates how to use the `getSolarTime` and `getSunPosition` functions from the solar-time library. `getSolarTime` calculates local solar time, time correction, and solar declination. `getSunPosition` calculates sunrise, sunset, solar noon, azimuth, and elevation. Both functions accept ISO 8601 formatted date-time strings with timezone information and return results preserving the input timezone.

```typescript
import {getSolarTime, getSunPosition} from "solar-time";

// Solar time calculation with UTC
const solar = getSolarTime("2024-06-21T12:00:00Z", 127.5);
console.log(solar.LST);         // "2024-06-21T12:08:30.123Z"
console.log(solar.TC);          // Time correction (minutes)
console.log(solar.declination); // Solar declination (degrees)

// Sun position with timezone (EST) - Note: latitude, longitude order
const sun = getSunPosition("2025-11-01T00:00:00-05:00", 39.833, -98.583);
console.log(sun.sunrise);   // "2025-11-01T08:04:12-05:00" (EST timezone preserved)
console.log(sun.sunset);    // "2025-11-01T18:32:45-05:00"
console.log(sun.solarNoon); // "2025-11-01T13:17:52-05:00"
console.log(sun.azimuth);   // 180 (degrees, south at noon)
console.log(sun.elevation); // Angle above horizon (degrees)
```

--------------------------------

### Calculate Sun Position (TypeScript)

Source: https://context7.com/semanticist21/solar-time/llms.txt

Calculates sunrise, sunset, solar noon, and current sun position (azimuth, elevation, zenith) using NOAA formulas with atmospheric refraction. It requires an ISO 8601 datetime string, latitude, and longitude as input. The function returns an object with sunrise, sunset, solarNoon, azimuth, elevation, and zenith times/values. Handles polar regions and includes error handling for invalid coordinates.

```typescript
import {getSunPosition} from "solar-time";

// Kansas, USA - November 1, 2025, 12:15 PM EST
const position = getSunPosition(
  "2025-11-01T12:15:43-05:00",
  39.833,    // Latitude (North)
  -98.583    // Longitude (West)
);

console.log(position);
// { 
//   sunrise: "2025-11-01T07:25:17-05:00",   // ISO 8601 with timezone
//   sunset: "2025-11-01T18:10:27-05:00",
//   solarNoon: "2025-11-01T12:47:52-05:00",
//   azimuth: 169.42,                        // 0° = North, 90° = East
//   elevation: 38.76,                       // Degrees above horizon
//   zenith: 51.24                           // Degrees from vertical
// }

// Summer solstice in Dubai
const dubai = getSunPosition(
  "2024-06-21T12:00:00+04:00",
  25.2048,   // Dubai latitude
  55.2708    // Dubai longitude
);
console.log(dubai);
// { 
//   sunrise: "2024-06-21T05:35:12+04:00",
//   sunset: "2024-06-21T19:13:24+04:00",
//   solarNoon: "2024-06-21T12:24:18+04:00",
//   azimuth: 182.34,
//   elevation: 88.21,   // Almost directly overhead
//   zenith: 1.79
// }

// Polar region - Arctic Circle winter (no sunrise)
const arctic = getSunPosition(
  "2024-12-21T12:00:00+02:00",
  70.0,      // North of Arctic Circle
  20.0
);
console.log(arctic);
// { 
//   sunrise: null,     // Polar night - sun doesn't rise
//   sunset: null,      // Sun doesn't set (already below horizon)
//   solarNoon: "2024-12-21T11:17:34+02:00",
//   azimuth: 180.45,
//   elevation: -3.42,  // Below horizon
//   zenith: 93.42
// }

// Error handling for invalid coordinates
try {
  getSunPosition("2024-06-21T12:00:00Z", 100, 0);
} catch (error) {
  console.error(error.message); // "Latitude must be between -90 and 90 degrees"
}

```

--------------------------------

### Core Solar Time Calculation Logic (TypeScript)

Source: https://github.com/semanticist21/solar-time/blob/main/CLAUDE.md

Demonstrates the core logic for calculating local solar time. It accepts various date inputs, determines the LSTM, computes day-of-year, and applies Spencer's Equation to find the Equation of Time (EoT) and declination. The output is a Time Correction (TC) and Local Solar Time (LST) as an ISO 8601 string.

```typescript
// Example placeholder for the solar time calculation logic
function calculateSolarTime(dateInput: Date | string | number, options?: { utcOffset?: number }): { tc: number, lst: string } {
  // ... implementation details ...
  return { tc: 0, lst: "" };
}
```

--------------------------------

### Valid ISO 8601 Timezone Handling in JavaScript

Source: https://github.com/semanticist21/solar-time/blob/main/README.md

Illustrates the correct way to provide ISO 8601 formatted date-time strings with timezone information to the solar-time library. The library strictly accepts strings with timezone offsets (e.g., +09:00, Z for UTC, or -05:00) to ensure accurate time calculations across different timezones. All returned times will preserve the timezone specified in the input.

```typescript
// ✅ ISO string with timezone
getSolarTime("2025-11-01T09:00:00+09:00", longitude);  // JST
getSolarTime("2025-11-01T09:00:00Z", longitude);       // UTC
getSolarTime("2025-11-01T09:00:00-05:00", longitude);  // EST
```

--------------------------------

### Calculate Sun Position

Source: https://context7.com/semanticist21/solar-time/llms.txt

Calculates sunrise, sunset, solar noon, and current sun position (azimuth, elevation, zenith) for a given datetime and location using NOAA formulas.

```APIDOC
## Calculate Sun Position

### Description
Calculates sunrise, sunset, solar noon, and current sun position (azimuth, elevation, zenith) for a given datetime and location using NOAA formulas with 0.833° atmospheric refraction.

### Method
`getSunPosition(datetime: string, latitude: number, longitude: number)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters
- **datetime** (string) - Required - An ISO 8601 formatted datetime string with timezone information.
- **latitude** (number) - Required - The latitude in degrees (-90 to 90).
- **longitude** (number) - Required - The longitude in degrees (-180 to 180).

### Request Example
```javascript
import {getSunPosition} from "solar-time";

const position = getSunPosition("2025-11-01T12:15:43-05:00", 39.833, -98.583);
console.log(position);
```

### Response
#### Success Response (200)
- **sunrise** (string | null) - Sunrise time in ISO 8601 format with timezone, or null if sun does not rise.
- **sunset** (string | null) - Sunset time in ISO 8601 format with timezone, or null if sun does not set.
- **solarNoon** (string) - Solar noon time in ISO 8601 format with timezone.
- **azimuth** (number) - Azimuth angle in degrees (0° = North, 90° = East).
- **elevation** (number) - Elevation angle in degrees (above horizon).
- **zenith** (number) - Zenith angle in degrees (from vertical).

#### Response Example
```json
{
  "sunrise": "2025-11-01T07:25:17-05:00",
  "sunset": "2025-11-01T18:10:27-05:00",
  "solarNoon": "2025-11-01T12:47:52-05:00",
  "azimuth": 169.42,
  "elevation": 38.76,
  "zenith": 51.24
}
```

#### Error Handling
- **Invalid ISO 8601 datetime string**: Thrown if the datetime string is invalid.
- **Latitude must be between -90 and 90 degrees**: Thrown if the latitude is out of range.
- **Longitude must be between -180 and 180 degrees**: Thrown if the longitude is out of range.
```

--------------------------------

### Date Utility Functions (TypeScript)

Source: https://github.com/semanticist21/solar-time/blob/main/CLAUDE.md

Provides essential utility functions for date manipulation, all supporting Date objects, ISO strings, and timestamps. These functions are crucial for handling timezones and formatting outputs correctly, adhering to native JavaScript Date API.

```typescript
// Placeholder for date utility functions
// import { getDayOfYear, getUTCOffset, getUTCMidnight, getLocalTimeInMinutes, addMinutes, toDate, formatWithTimezone } from './utils/date';

// Example usage:
const date = new Date();
const dayOfYear = getDayOfYear(date);
const utcOffset = getUTCOffset(date);
const utcMidnight = getUTCMidnight(date);
const localMinutes = getLocalTimeInMinutes(date);
const futureDate = addMinutes(date, 60);
const dateObject = toDate(date);
const formattedDate = formatWithTimezone(date, 9);

console.log({ dayOfYear, utcOffset, utcMidnight, localMinutes, futureDate, dateObject, formattedDate });
```

--------------------------------

### TypeScript Types for Solar Time and Sun Position

Source: https://context7.com/semanticist21/solar-time/llms.txt

This snippet defines the TypeScript interfaces for `SolarTimeResult` and `SunPositionResult`. These types are exported by the library to ensure type safety for users. They detail the expected structure and data types for solar time calculations and sun position data, including specific units and formats.

```typescript
import type {SolarTimeResult, SunPositionResult} from "solar-time";

// SolarTimeResult interface
const solarTime: SolarTimeResult = {
  LST: "2025-11-01T09:17:52+09:00",  // ISO 8601 string with timezone
  TC: 17.86,                          // Time Correction (minutes)
  EoT: 16.47,                         // Equation of Time (minutes)
  B: 304.93,                          // Day angle (degrees)
  LSTM: 135,                          // Local Standard Time Meridian
  declination: -14.51                 // Solar declination (degrees, -23.45 to +23.45)
};

// SunPositionResult interface
const sunPosition: SunPositionResult = {
  sunrise: "2025-11-01T07:25:17-05:00" | null,  // null in polar regions
  sunset: "2025-11-01T18:10:27-05:00" | null,   // null in polar regions
  solarNoon: "2025-11-01T12:47:52-05:00",       // Always present
  azimuth: 169.42,                               // 0-360° (0° = North)
  elevation: 38.76,                              // -90° to +90° (negative = below horizon)
  zenith: 51.24                                  // 0-180° (complement of elevation)
};

```

--------------------------------

### Calculate Local Solar Time (TypeScript)

Source: https://context7.com/semanticist21/solar-time/llms.txt

Calculates local solar time (LST), equation of time (EoT), time correction (TC), and solar declination using Spencer's Equation. It takes an ISO 8601 datetime string and longitude as input. The function returns an object containing LST, TC, EoT, B, LSTM, and declination. Error handling is included for invalid date strings or out-of-range longitudes.

```typescript
import {getSolarTime} from "solar-time";

// Tokyo, Japan - November 1, 2025, 9:00 AM JST
const result = getSolarTime("2025-11-01T09:00:00+09:00", 139.6917);

console.log(result);
// { 
//   LST: "2025-11-01T09:17:52+09:00",  // Local Solar Time (ISO 8601 with timezone)
//   TC: 17.86,                          // Time Correction in minutes
//   EoT: 16.47,                         // Equation of Time in minutes
//   B: 304.93,                          // Day angle in degrees
//   LSTM: 135,                          // Local Standard Time Meridian (15 * 9)
//   declination: -14.51                 // Solar declination in degrees
// }

// New York, USA - June 21, 2024, 3:30 PM EDT
const summer = getSolarTime("2024-06-21T15:30:00-04:00", -74.0060);
console.log(summer);
// { 
//   LST: "2024-06-21T15:30:00-04:00",
//   TC: -0.18,
//   EoT: -1.34,
//   LSTM: -60,
//   declination: 23.44
// }

// Error handling
try {
  getSolarTime("invalid-date", 0);
} catch (error) {
  console.error(error.message); // "Invalid ISO 8601 datetime string"
}

try {
  getSolarTime("2024-06-21T12:00:00Z", 200);
} catch (error) {
  console.error(error.message); // "Longitude must be between -180 and 180 degrees"
}

```

--------------------------------

### Calculate Solar Time

Source: https://context7.com/semanticist21/solar-time/llms.txt

Calculates local solar time (LST), equation of time (EoT), time correction (TC), and solar declination for a given datetime and longitude using Spencer's Equation.

```APIDOC
## Calculate Solar Time

### Description
Calculates local solar time (LST), equation of time (EoT), time correction (TC), and solar declination for a given datetime and longitude using Spencer's Equation.

### Method
`getSolarTime(datetime: string, longitude: number)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters
- **datetime** (string) - Required - An ISO 8601 formatted datetime string with timezone information.
- **longitude** (number) - Required - The longitude in degrees (-180 to 180).

### Request Example
```javascript
import {getSolarTime} from "solar-time";

const result = getSolarTime("2025-11-01T09:00:00+09:00", 139.6917);
console.log(result);
```

### Response
#### Success Response (200)
- **LST** (string) - Local Solar Time in ISO 8601 format with timezone.
- **TC** (number) - Time Correction in minutes.
- **EoT** (number) - Equation of Time in minutes.
- **B** (number) - Day angle in degrees.
- **LSTM** (number) - Local Standard Time Meridian.
- **declination** (number) - Solar declination in degrees.

#### Response Example
```json
{
  "LST": "2025-11-01T09:17:52+09:00",
  "TC": 17.86,
  "EoT": 16.47,
  "B": 304.93,
  "LSTM": 135,
  "declination": -14.51
}
```

#### Error Handling
- **Invalid ISO 8601 datetime string**: Thrown if the datetime string is invalid.
- **Longitude must be between -180 and 180 degrees**: Thrown if the longitude is out of range.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.