Utility Functions

The Open Electricity client provides several utility functions to help you work with dates, timezones, and other common operations. These utilities are designed to handle the complexities of working with different electricity networks and their specific timezone requirements.

Date and Time Utilities

Network Timezones

The client handles data from different electricity networks in Australia, each with their own timezone:

• NEM (National Electricity Market): AEST/UTC+10
• WEM (Western Australia): AWST/UTC+8
• AU (Australia): AEST/UTC+10 (default)

Timezone Functions

getNetworkTimezone

Get the timezone offset in hours for a specific network.

function getNetworkTimezone(network: NetworkCode): number

Parameters:

• network: Network code ("NEM" | "WEM" | "AU")

Returns:

• Number representing timezone offset in hours (e.g., 10 for AEST/UTC+10)

Example:

import { getNetworkTimezone } from 'openelectricity'

const nemOffset = getNetworkTimezone("NEM") // Returns 10 (AEST/UTC+10)
const wemOffset = getNetworkTimezone("WEM") // Returns 8 (AWST/UTC+8)

getNetworkTimezoneOffset

Get timezone offset in milliseconds for a network.

function getNetworkTimezoneOffset(network: NetworkCode): number

Parameters:

• network: Network code ("NEM" | "WEM" | "AU")

Returns:

• Number representing timezone offset in milliseconds

Example:

import { getNetworkTimezoneOffset } from 'openelectricity'

const nemOffsetMs = getNetworkTimezoneOffset("NEM") // Returns 36000000 (10 hours in ms)

Date Handling Functions

isAware

Check if a date string contains timezone information.

function isAware(dateStr: string | Date): boolean

Parameters:

• dateStr: Date string or Date object to check

Returns:

• Boolean indicating if the date string contains timezone information

Example:

import { isAware } from 'openelectricity'

isAware("2024-03-15T10:00:00Z")           // Returns true
isAware("2024-03-15T10:00:00+10:00")      // Returns true
isAware("2024-03-15T10:00:00")            // Returns false
isAware(new Date())                        // Returns false

makeAware

Make a date timezone aware by adding the network’s timezone offset.

function makeAware(date: string | Date, network: NetworkCode): string

Parameters:

• date: Date string or Date object to make timezone aware
• network: Network code to get timezone from

Returns:

• ISO string with timezone information

Example:

import { makeAware } from 'openelectricity'

const awareDate = makeAware("2024-03-15T10:00:00", "NEM")
// Returns "2024-03-15T10:00:00+10:00"

stripTimezone

Remove timezone information from a date string.

function stripTimezone(dateStr: string): string

Parameters:

• dateStr: Date string to strip timezone from

Returns:

• Date string without timezone information

Example:

import { stripTimezone } from 'openelectricity'

const naiveDate = stripTimezone("2024-03-15T10:00:00+10:00")
// Returns "2024-03-15T10:00:00"

Interval Functions

getLastCompleteInterval

Get the last complete 5-minute interval for a network.

function getLastCompleteInterval(network: NetworkCode): string

Parameters:

• network: Network code to get timezone from

Returns:

• ISO string of the last complete 5-minute interval in network time (without timezone information)

Example:

import { getLastCompleteInterval } from 'openelectricity'

// If current time is 2024-03-15T10:07:30+10:00
const lastInterval = getLastCompleteInterval("NEM")
// Returns "2024-03-15T10:00:00"

Best Practices

Working with Timezones

1. Network-Specific Times: Always use the appropriate network timezone when working with dates:

   const networkAwareDate = makeAware(localDate, "NEM")

2. API Submissions: The API expects timezone-naive dates in network time:

   const apiReadyDate = stripTimezone(networkAwareDate)

3. Interval Data: Use getLastCompleteInterval for real-time data:

   const lastInterval = getLastCompleteInterval("NEM")

Date Validation

1. Check Timezone Information:

   if (isAware(dateStr)) {
     // Handle timezone-aware date
   } else {
     // Handle naive date
   }

2. Network-Specific Processing:

   const offset = getNetworkTimezone(network)
   const offsetMs = getNetworkTimezoneOffset(network)

Common Patterns

Real-time Data Retrieval

import { getLastCompleteInterval } from '@openelectricity/client'

async function getLatestData() {
  const lastInterval = getLastCompleteInterval("NEM")
  const { datatable } = await client.getNetworkData("NEM", ["power"], {
    dateStart: lastInterval,
    interval: "5m"
  })
  return datatable
}

Date Conversion Pipeline

import { makeAware, stripTimezone } from 'openelectricity'

function prepareDateForAPI(date: Date, network: NetworkCode) {
  // Add network timezone
  const networkAware = makeAware(date, network)
  // Strip for API submission
  return stripTimezone(networkAware)
}

Timezone Validation

import { isAware, makeAware } from 'openelectricity'

function ensureNetworkAware(date: string | Date, network: NetworkCode) {
  if (!isAware(date)) {
    return makeAware(date, network)
  }
  return date.toString()
}