d-core.temporal — org.clojars.cinguilherme/d-core-std 0.4.0

The temporal contract (roadmap 02, B1/B4/B5).

Two vocabularies, deliberately separate:

• Domains are the internal representation. Everything internal is UTC: a point in time is a java.time.Instant, a span is a java.time.Duration, and :local-date is a civil date that is deliberately not a point in time. Zone-bearing and wall-clock types (:local-date-time, :zoned-date-time, :offset-date-time) are ingress formats only — they are resolved to an Instant at the boundary and never travel internally (D10).

• Dialects are the encodings used at a boundary. A dialect is a named value (or explicit ingress map), chosen explicitly, never inferred (D6). :epoch-ms is the platform default for :instant (D3b) and :millis for :duration.

->duration clj

(->duration value)

(->duration value opts)

Decodes a boundary value into a java.time.Duration.

Supported dialects:

• :millis (exact integer milliseconds)
• :seconds (exact integer seconds, or fractional with {:dialect :seconds :fractional? true})
• :iso8601 / :rfc3339 ("PT15M")
• :literal ("15m", "2h30m")

->instant clj

(->instant value)

(->instant value opts)

Decodes a boundary value into an Instant (the internal UTC representation).

(->instant 1704067200000 :epoch-ms)
(->instant "2024-01-01T00:00:00Z" :rfc3339)
(->instant "2024-01-01T00:00:00" {:dialect :iso-local :zone "America/Sao_Paulo"})
(->instant "2024-01-01 00:00:00" {:pattern "yyyy-MM-dd HH:mm:ss" :zone "UTC"})

->local-date clj

(->local-date value)

(->local-date value opts)

Decodes a boundary value into a java.time.LocalDate.

->temporal clj

(->temporal domain value dialect-or-opts)

Domain-dispatched ingress coercion: decodes value into the internal java.time type for domain (:instant, :duration, or :local-date) using dialect-or-opts.

->wire clj

(->wire value dialect-or-opts)

(->wire value dialect-or-opts extra-opts)

Encodes an internal java.time value (Instant, Duration, LocalDate) into the given dialect-or-opts.

Refuses lossy encodings by default (D5/D13); pass {:truncating? true} to accept a documented narrowing.

boundary-only-domains clj

Domains that exist only as ingress/egress representations, never internally.

default-dialect clj

The platform's de-facto wire encoding for points in time (D3b).

default-dialect-for clj

(default-dialect-for domain)

The default encoding for an internal domain.

• :instant -> :epoch-ms (D3b)
• :duration -> :millis
• :local-date -> :local-date

detect-dialect clj

(detect-dialect value)

Inspects a raw wire value and reports its dialect status without guessing (B4). Numbers always return :ambiguous with :candidates; zone-less datetimes return :zone-required with :dialect :iso-local.

dialect-spec clj

(dialect-spec dialect-or-opts)

Returns the specification map for dialect (or normalized options map).

dialect-supports? clj

(dialect-supports? dialect-or-opts domain)

True when dialect-or-opts can carry domain without losing semantic information (§4.1 lattice).

dialects clj

Named boundary encodings. A dialect is data, never inferred from a value.

domain-of clj

(domain-of value)

Returns the internal domain of a value, or nil if it is not an internal representation. Boundary-only java.time types return nil by design (D10).

domains clj

The internal domain vocabulary (D10). Everything internal is UTC.

explain clj

(explain value)

(explain value opts)

Diagnostic helper (B5): inspects value, detects its dialect, resolves it when unambiguous (or when :dialect / :zone is provided in opts), and renders all standard representations plus any precision loss.

normalize-opts clj

(normalize-opts opts)

Normalizes a dialect keyword or options map into a canonical options map. (normalize-opts :epoch-ms) => {:dialect :epoch-ms} (normalize-opts {:pattern "yyyy-MM-dd HH:mm" :zone "UTC"}) => {:dialect :pattern ...}