diene_core_utils library

Pure Dart utilities shared by the Diene Dart family.

Three groups of members, all total:

Every fallible member returns Result from package:diene_result with the canonical Problem envelope from package:diene_problems as its error channel; nothing in this library throws to report an expected failure. The only members that touch the outside world do so through the INJECTED Vfs interface from package:diene_interfaces — this package imports neither dart:io nor Flutter, so it runs unchanged on the VM and on the web.

The shared, version-pinned C0 §1 temporal contract is exported separately from package:diene_core_utils/c0_temporal.dart so downstream Dart-family packages can drive their own conformance from one value.

Classes

C0Cases
Positive/negative string cases for one temporal domain.
C0InstantVector
A deterministic instant-normalization vector: input (any RFC 3339 form, including offsets) formats to canonicalUtc (RFC 3339 UTC Z). The instant is injected — no host clock is read.
C0TemporalContract
The version-pinned C0 temporal contract value.
C0TemporalProvenance
The single, version-pinned C0 §1 temporal contract for the Dart family.
ConfigLayer
One named configuration layer, lowest precedence first.
IanaTimezone
A validated IANA timezone identifier.
IsoDuration
A validated ISO 8601 duration, preserved without lossy conversion.
WireCodec
Codec facade for every C0 temporal wire form.
WireDate
A C0 YYYY-MM-DD calendar date.
WireTime
A C0 HH:mm:ss local wall-clock time.

Enums

NamespacedKeyField
Identifies the input that made a namespaced key invalid.
UtilErrorCode
How a utility surface failed.
UtilName
Which utility surface produced a failure.

Constants

c0TemporalContract → const C0TemporalContract
The shared C0 temporal contract consumed unchanged across the Dart family.
coreUtilsProblemVersion → const String
Contract version segment of every problem type URI minted here.
environmentPathSeparator → const String
The C0 §3 path separator inside an environment or --dart-define key.
ianaTimeZoneRelease → const String
The IANA release baked into isIanaTimeZone.
wireDateGrammar → const String
The C0 wire grammar for a calendar date.
wireDurationGrammar → const String
The C0 wire grammar for a duration.
wireInstantGrammar → const String
The C0 wire grammar for an instant.
wireTimeGrammar → const String
The C0 wire grammar for a wall-clock time.
wireTimezoneGrammar → const String
The C0 wire grammar for a timezone identifier.

Functions

canonicalConfigKey(String key) → String
Canonicalises a configuration key for separator- and case-insensitive matching.
coerceEnvironmentScalar(String value) → Object?
Coerces an environment scalar using the C0 §3 configuration conventions.
configKeysMatch(String left, String right) → bool
Whether two configuration keys identify the same logical key.
deepClone(Object? value) → Object?
Deeply clones a JSON-like value.
deepMerge(Map<String, Object?> base, Map<String, Object?> overlay) → JsonObject
Deep-merges overlay over base without mutating either input.
deepMergeAll(Iterable<Map<String, Object?>> layers) → JsonObject
Deep-merges layers from lowest to highest precedence.
environmentToNestedMap(Map<String, String> environment, {required String prefix}) → Result<JsonObject>
Converts the prefix-scoped entries of environment into a nested configuration object.
formatRfc3339Utc(DateTime value) → Result<String>
Formats value as a canonical RFC 3339 UTC instant ending in Z.
fuzzyIncludes(String haystack, String needle) → bool
Case-insensitive substring test.
invalidUtilInput<T>({required UtilName util, required String operation, required String field, required String message}) → Err<T>
Builds an invalid-input failure naming the offending field.
invalidWireFormat<T>({required String operation, required String expected, required String value}) → Err<T>
Builds an invalid-format failure naming the rejected value and its expected C0 wire grammar.
isIanaTimeZone(String id) → bool
Reports whether id is a valid IANA timezone identifier.
isJsonObject(Object? value) → bool
Narrows value to a plain JSON object: a Map keyed by String that is not a list.
loadConfigLayers(Vfs vfs, List<ConfigLayer> layers) → Future<Result<JsonObject>>
Loads layers through vfs and deep-merges them in order.
mapWithConcurrency<T, R>(Iterable<T> items, int concurrency, Future<Result<R>> mapper(T item)) → Future<Result<List<R>>>
Maps items through mapper with at most concurrency calls in flight.
namespacedKey(String namespace, String key) → Result<String>
Composes a namespace:key identifier from slugified parts.
normalizeRfc3339ToUtc(String value) → Result<String>
Normalises any RFC 3339 instant — including one carrying a numeric offset — into the canonical UTC Z wire form.
parseRfc3339Utc(String value) → Result<DateTime>
Parses a STRICT RFC 3339 UTC instant.
readOptionalVfsText(Vfs vfs, String path) → Future<Result<String?>>
Reads path from vfs and returns its text, or null when the path does not exist.
readVfsText(Vfs vfs, String path) → Future<Result<String>>
Reads path from vfs as UTF-8 text.
sleep(Duration duration) → Future<Result<void>>
Completes after duration has elapsed.
slugify(String input) → String
Normalises an arbitrary string into a deterministic kebab-case slug.
stableConfig(Object? value) → Result<Object?>
Produces a deterministic clone of a config-like value.
stableConfigObject(JsonObject value) → Result<JsonObject>
Deterministically projects a configuration object, preserving the JsonObject type for callers that merged it with deepMerge.
utilFailure<T>({required UtilName util, required UtilErrorCode code, required String operation, required String message, ErrorPortal portal = ErrorPortal.localError, Map<String, Object?> details = const <String, Object?>{}}) → Err<T>
Builds an Err carrying utilProblem's envelope.
utilProblem({required UtilName util, required UtilErrorCode code, required String operation, required String message, ErrorPortal portal = ErrorPortal.localError, Map<String, Object?> details = const <String, Object?>{}}) → Problem
Builds the RFC 9457 envelope for a utility failure.
writeVfsText(Vfs vfs, String path, String contents) → Future<Result<void>>
Writes contents to path through vfs as UTF-8.

Typedefs

JsonObject = Map<String, Object?>
A JSON-like configuration object.