@welldot/core 0.4.0-next.20261014.26249fd → 0.4.0

package/README.md

@@ -26,6 +26,10 @@ The format is designed for three use cases: visualization of technical well prof
 
 See the [v2 format specification](./docs/spec/v2/overview.md) (current revision: v2.3) for the complete schema reference and design rationale. The [v1 spec](./docs/spec/v1/well-format.md) remains available for reference.
 
+### Example wells
+
+The package ships 14 complete, valid `.well` files in [`examples/`](./examples/README.md). They are built on real wells from the Brazilian SIAGAS registry, with illustrative names, permits, analyses and operating data. Together they cover crystalline, karst, sedimentary, deep, flowing, hand-dug and monitoring wells, plus incomplete and inconsistent records. Import them as `@welldot/core/examples/<file>`, or download them from `https://welldot.org/examples/<file>`.
+
 ## Installation
 
 ```bash
@@ -50,6 +54,7 @@ import {
   parseWell,
   serializeWell,
   deserializeWell,
+  hasWellData,
   isWellEmpty,
 } from '@welldot/core';
 
@@ -65,8 +70,9 @@ const jsonString = serializeWell(well);
 // Deserialize — handles versioned format and legacy formats
 const restored = deserializeWell(jsonString);
 
-// Check if a well contains any data
+// Check if a well has a profile to draw, or holds any data at all
 const empty = isWellEmpty(well);
+const hasData = hasWellData(well);
 ```
 
 ## API Reference
@@ -219,11 +225,11 @@ Each schema validates its corresponding type at runtime. All schemas are Zod obj
 
 #### `parseWell(json: string): Well`
 
-Parses a raw JSON string and validates it against `WellSchema`. Throws a `ZodError` on validation failure. Does not handle legacy formats — use `deserializeWell` for that.
+Parses a raw JSON string and validates it against `WellSchema`. Throws a `ZodError` on validation failure. Unknown members (`x-` fields and blocks) are kept at every level, including inside array items. Does not handle legacy formats — use `deserializeWell` for that.
 
 #### `serializeWell(well: Well): string`
 
-Serializes a `Well` object to a versioned `.well` JSON string (`"version": 2`). Emits `location` when set; does not emit deprecated flat `lat`/`lng`/`elevation`. Omits `undefined` optional fields.
+Serializes a `Well` object to a versioned `.well` JSON string (`"version": 2`). Emits `location` when set; does not emit deprecated flat `lat`/`lng`/`elevation` or other legacy v1 keys. Omits `undefined` optional fields. Root members the spec does not define (`x-` fields and blocks, foreign members) are written unchanged after the spec blocks, as the spec requires.
 
 #### `deserializeWell(jsonString: string): Well | null`
 
@@ -241,13 +247,17 @@ Returns `null` if the parsed data is empty. Throws on unrecognized version numbe
 
 Returns `true` when all constructive and geologic arrays are empty. Accepts `null` and `undefined` (both treated as empty).
 
+#### `hasWellData(well: Well | null | undefined): boolean`
+
+Returns `true` when the well holds any data: a profile, or any other filled root member (identification, location, events, samples, permits, `x-` members, …). A registry record without construction or geology has data although `isWellEmpty` says it has nothing to draw. Blank strings, zeros and objects holding only those do not count.
+
 #### `calculatedWellDepth(well: Well): number`
 
 Deepest `to` across the constructive arrays (bore hole, casings, screens, reductions, hole fill), ignoring geology. `0` without constructive data. Used as the fallback for a missing `well_depth`.
 
 #### `redactWell(well: Well, visibility: WellVisibility): Well`
 
-Copy of `well` with hidden parts emptied (arrays become `[]`, optional fields are removed), so the result stays schema-valid. `visibility` keys are the 7 `SECTION_KEYS` and/or the fields of `VISIBILITY_TREE` (e.g. `meters`, `permits`, `location`); `false` hides, missing keys are visible, and a hidden section hides all its fields. `VISIBILITY_LEAF_KEYS` lists the finest toggles. References from visible records to hidden ones are left as-is.
+Copy of `well` with hidden parts emptied (arrays become `[]`, optional fields are removed), so the result stays schema-valid. `visibility` keys are the 7 `SECTION_KEYS` and/or the fields of `VISIBILITY_TREE` (e.g. `meters`, `permits`, `location`); `false` hides, missing keys are visible, and a hidden section hides all its fields. `VISIBILITY_LEAF_KEYS` lists the finest toggles. References from visible records to hidden ones are left as-is. Unknown root members (`x-` fields and blocks) are kept only when nothing is hidden; nested ones follow their record.
 
 ```typescript
 redactWell(well, { operation: false }); // whole section

package/dist/index.cjs

@@ -161,6 +161,7 @@ __export(index_exports, {
   getParameterLabel: () => getParameterLabel,
   getVocabEntry: () => getVocabEntry,
   getVocabLabel: () => getVocabLabel,
+  hasWellData: () => hasWellData,
   hoursToMinutes: () => hoursToMinutes,
   hpToKilowatts: () => hpToKilowatts,
   inchesToMm: () => inchesToMm,
@@ -209,6 +210,16 @@ var mergeWell = (0, import_defu.createDefu)((obj, key, value) => {
     return true;
   }
 });
+var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var mergeParsed = (0, import_defu.createDefu)((obj, key, value) => {
+  if (Array.isArray(value)) {
+    const raw = obj[key];
+    obj[key] = Array.isArray(raw) && raw.length === value.length ? value.map(
+      (item, i) => isPlainObject(item) && isPlainObject(raw[i]) ? mergeParsed(item, raw[i]) : item
+    ) : value;
+    return true;
+  }
+});
 var RFC3339_WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 var rfc3339 = () => import_zod.z.string().regex(RFC3339_WITH_OFFSET, "datetime must be RFC 3339 with UTC offset");
 var CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
@@ -840,7 +851,7 @@ function parseWell(json) {
     }
     if (version === 1) {
       const normalized = normalizeV1Fields(raw);
-      return mergeWell(
+      return mergeParsed(
         WellSchema.parse(normalized),
         normalized
       );
@@ -850,12 +861,20 @@ function parseWell(json) {
   } else {
     raw.version = 2;
   }
-  return mergeWell(WellSchema.parse(raw), raw);
+  return mergeParsed(WellSchema.parse(raw), raw);
 }
 
 // src/utils/well.utils.ts
 var WELL_FORMAT_VERSION = 2;
 var INCHES_TO_MM = 25.4;
+var LEGACY_ROOT_KEYS = /* @__PURE__ */ new Set([
+  "lat",
+  "lng",
+  "elevation",
+  "bole_hole",
+  "constructive",
+  "geologic"
+]);
 var SECTION_KEYS = [
   "general",
   "constructive",
@@ -1100,6 +1119,11 @@ function normalizeGeologic(raw) {
     caves: raw.caves ?? []
   };
 }
+function unknownRootKeys(well) {
+  return Object.keys(well).filter(
+    (key) => !(key in WellSchema.shape) && !LEGACY_ROOT_KEYS.has(key)
+  );
+}
 function serializeWell(well) {
   const payload = {
     version: WELL_FORMAT_VERSION,
@@ -1152,6 +1176,10 @@ function serializeWell(well) {
       water_samples: well.water_samples
     }
   };
+  for (const key of unknownRootKeys(well)) {
+    const value = well[key];
+    if (value !== void 0) payload[key] = value;
+  }
   return JSON.stringify(payload);
 }
 function isWellEmpty(well) {
@@ -1160,6 +1188,22 @@ function isWellEmpty(well) {
   if (raw.constructive || raw.geologic) return false;
   return well.lithology?.length === 0 && well.fractures?.length === 0 && well.caves?.length === 0 && well.bore_hole?.length === 0 && well.hole_fill?.length === 0 && well.well_case?.length === 0 && well.well_screen?.length === 0;
 }
+function isFilled(value) {
+  if (value === void 0 || value === null) return false;
+  if (typeof value === "string") return value.trim() !== "";
+  if (typeof value === "number") return value !== 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.values(value).some(isFilled);
+  return true;
+}
+var NON_DATA_ROOT_KEYS = /* @__PURE__ */ new Set(["version", "$schema", "@context"]);
+function hasWellData(well) {
+  if (!well) return false;
+  if (!isWellEmpty(well)) return true;
+  return Object.entries(well).some(
+    ([key, value]) => !NON_DATA_ROOT_KEYS.has(key) && isFilled(value)
+  );
+}
 function redactWell(well, visibility) {
   const v = visibility;
   const redacted = { ...well };
@@ -1203,6 +1247,10 @@ function redactWell(well, visibility) {
   if (hidden("production")) delete redacted.production;
   if (hidden("permits")) delete redacted.permits;
   if (hidden("water_quality")) delete redacted.water_samples;
+  if (Object.values(v).some((shown) => shown === false)) {
+    for (const key of unknownRootKeys(redacted))
+      delete redacted[key];
+  }
   return redacted;
 }
 function deserializeWell(jsonString) {
@@ -3393,6 +3441,7 @@ function expandedToStandardUncertainty(expanded, coverageFactor = 2) {
   getParameterLabel,
   getVocabEntry,
   getVocabLabel,
+  hasWellData,
   hoursToMinutes,
   hpToKilowatts,
   inchesToMm,