midas.entities — energy.grid-coordination/clj-midas 0.5.1

MIDAS entity coercion: raw API responses → idiomatic Clojure maps.

Two-layer data model: Raw layer — direct JSON→EDN, PascalCase keys, string values Coerced layer — namespaced keywords, native types (java.time, BigDecimal)

Time handling: every coerced timestamp is a ZonedDateTime in the zone configured on the client (per-instance via :zone, default America/Los_Angeles). MIDAS mixes Z-suffixed UTC fields with bare wall-clock fields on the wire; both are normalised to ZonedDateTime in the configured zone — the instant is preserved for Z-suffixed values and assumed-zone-local for bare values. See https://github.com/grid-coordination/midas-api-specs/blob/main/doc/datetime-and-timezone.md

All coerced entities carry the original raw data as :midas/raw metadata.

->holiday clj

(->holiday raw)

Coerce a raw HolidayEntry.

Raw shape: {:EnergyCode "PG" :EnergyDescription "Pacific Gas and Electric" :DateOfHoliday "2023-12-25T00:00:00" :HolidayDescription "Christmas 2023"}

Coerced shape: {:midas.holiday/energy-code "PG" :midas.holiday/energy-name "Pacific Gas and Electric" :midas.holiday/date #local-date 2023-12-25 :midas.holiday/description "Christmas 2023"}

->lookup-entry clj

(->lookup-entry raw)

Coerce a raw LookupEntry.

Raw shape: {:UploadCode "PG" :Description "Pacific Gas and Electric"}

Coerced shape: {:midas.lookup/code "PG" :midas.lookup/description "Pacific Gas and Electric"}

->rate-info clj

(->rate-info raw zone)

Coerce a raw RateInfo response to an idiomatic Clojure map.

zone is the ZoneId for ZonedDateTime composition. Z-suffixed fields (SystemTime_UTC, SignupCloseDate) preserve their UTC instant and are re-expressed in zone; bare wall-clock fields are attached to zone.

Raw shape: {:RateID "USCA-TSTS-TTOU-TEST" :RateName "CEC TEST24HTOU" :ValueInformation [...] ...}

Coerced shape: {:midas.rate/id "USCA-TSTS-TTOU-TEST" :midas.rate/name "CEC TEST24HTOU" :midas.rate/system-time #zoned-date-time ... :midas.rate/values [<ValueData> ...] ...}

->rin-list-entry clj

(->rin-list-entry raw zone)

Coerce a raw RIN list entry.

zone is the ZoneId for ZonedDateTime composition. The bare LastUpdated wire field is interpreted as wall-clock in zone.

Raw shape: {:RateID "USCA-TSTS-TTOU-TEST" :SignalType "Rates" :Description "..." :LastUpdated "2023-06-07T15:57:48.023"}

Coerced shape: {:midas.rin/id "USCA-TSTS-TTOU-TEST" :midas.rin/signal-type :midas.signal-type/rates :midas.rin/description "..." :midas.rin/last-updated #zoned-date-time ...}

->value-data clj

(->value-data raw zone)

Coerce a raw ValueData interval to an idiomatic Clojure map.

zone is the ZoneId to attach to wall-clock fields when composing ZonedDateTime tick boundaries. Pass the zone configured on the client (typically America/Los_Angeles — MIDAS's native zone).

Raw shape: {:ValueName "winter off peak" :DateStart "2023-05-01" ...}

Coerced shape: {:midas.value/name "winter off peak" :midas.value/date-start #local-date ... :midas.value/price 0.1006M :tick/beginning #zoned-date-time ... :tick/end #zoned-date-time ... ...}

When both date and time are present for a boundary, the map also carries :tick/beginning and :tick/end keys (ZonedDateTime in zone), making it directly usable as a tick interval. The bare :date-start / :time-start / :date-end / :time-end fields remain LocalDate / LocalTime — they are zone-naive boundary descriptors (e.g. "the rate boundary is at PT-clock- time 07:00"), distinct from the moment-in-time tick keys.

annotate-rin clj

(annotate-rin parsed-rin lookup-tables)

Add human-readable labels to a parsed RIN map.

lookup-tables is a map of lookup table name to a sequence of coerced LookupEntry maps (as returned by (entities/lookup-table response)). Recognized keys: "Distribution" and "Energy".

Example: (annotate-rin (parse-rin "USCA-PGPG-TOU4-0000") {"Distribution" dist-entries "Energy" energy-entries}) ;=> {:midas.rin/country "US" ; :midas.rin/state "CA" ; :midas.rin/distribution "PG" ; :midas.rin/distribution-name "Pacific Gas and Electric" ; :midas.rin/energy "PG" ; :midas.rin/energy-name "Pacific Gas and Electric" ; :midas.rin/rate "TOU4" ; :midas.rin/location "0000"}

day-type-kw clj

flex-alert-active? clj

(flex-alert-active? rate)

True if the Flex Alert rate-info indicates an active alert. Active when any value interval has a non-zero value.

flex-alert? clj

(flex-alert? rate)

True if rate-info represents a Flex Alert signal.

ghg? clj

(ghg? rate)

True if rate-info represents a GHG (greenhouse gas emissions) signal.

historical-data clj

(historical-data response)

Extract and coerce historical rate data from a get-historical-data response.

historical-list clj

(historical-list response)

Extract and coerce historical RIN list from a get-historical-list response. Deduplicates by RIN ID (the live API returns duplicates).

holidays clj

(holidays response)

Extract and coerce holidays from a get-holidays response.

lookup-table clj

(lookup-table response)

Extract and coerce lookup table entries from a get-lookup-table response.

parse-rin clj

(parse-rin rin)

Parse a RIN string into its component fields.

Example: (parse-rin "USCA-PGPG-TOU4-0000") ;=> {:midas.rin/country "US" ; :midas.rin/state "CA" ; :midas.rin/distribution "PG" ; :midas.rin/energy "PG" ; :midas.rin/rate "TOU4" ; :midas.rin/location "0000"}

Returns nil if the string does not match the RIN format.

rate-info clj

(rate-info response)

Extract and coerce rate info from a get-rate-values response.

rate-type-kw clj

rin-list clj

(rin-list response)

Extract and coerce RIN list entries from a get-rin-list response.

signal-type-kw clj

unit-type-kw clj