Versions and time zones
The version this library writes
import { WELL_FORMAT_VERSION } from '@welldot/core';
WELL_FORMAT_VERSION; // '2.4'
serializeWell always writes this version. parseWell reads 1, 2 and any "2.x" (Versions and deprecation).
Parsing and comparing versions
Since 2.4 the version is the string "M.m", compared as two integers (Versioning). Never compare version strings as text: "2.10" sorts before "2.9" as text but is the later revision.
import { compareFormatVersions, parseFormatVersion } from '@welldot/core';
parseFormatVersion('2.4'); // { major: 2, minor: 4 }
parseFormatVersion(2); // { major: 2, minor: undefined }, a v2.0–v2.3 file
parseFormatVersion(2.4); // undefined: a JSON number is malformed
parseFormatVersion('2.4.1'); // undefined: patch levels are not allowed
compareFormatVersions('2.10', '2.9'); // 1 (positive: the first is later)
parseFormatVersion returns undefined for every malformed form, so you can report the value to the user as the spec requires (parser version handling). compareFormatVersions throws on malformed input.
A typical check before writing to a shared archive:
import { WELL_FORMAT_VERSION, compareFormatVersions } from '@welldot/core';
const archiveReads = '2.3'; // the newest revision your readers support
if (compareFormatVersions(WELL_FORMAT_VERSION, archiveReads) > 0) {
console.warn(
`This tool writes ${WELL_FORMAT_VERSION}; update the readers first.`,
);
}
The well site time zone
Permit deadlines and validity are judged on the local calendar date at the well. Since 2.4, location.properties.timezone stores the site's IANA time zone, and the local date of an instant is that instant converted to the zone (datetime conventions).
"location": {
"lat": -1.4558,
"lng": -48.5039,
"properties": { "timezone": "America/Belem" }
}
A value that is not an IANA name is malformed. Check it before writing:
import { isIanaTimeZone } from '@welldot/core';
isIanaTimeZone('America/Belem'); // true
isIanaTimeZone('-03:00'); // false: offsets are not time zones
isIanaTimeZone('BRT'); // false
@welldot/utils uses the zone for local dates (instantLocalDate, getWellTimeZone) and warns with missing_timezone when a file has permit condition fulfillments but no zone (Permits).