[{"data":1,"prerenderedAt":1560},["ShallowReactive",2],{"page-\u002Fcore\u002Fgetting-started\u002Ffirst-use":3,"navigation":1186},{"collection":4,"page":5},"docs_en",{"id":6,"title":7,"body":8,"description":1178,"extension":1179,"meta":1180,"navigation":112,"path":1181,"rawbody":1182,"seo":1183,"stem":1184,"__hash__":1185},"docs_en\u002Fcore\u002F1.getting-started\u002F2.first-use.md","First use",{"type":9,"value":10,"toc":1171},"minimark",[11,24,29,181,195,224,525,539,547,551,554,826,838,847,851,973,992,996,999,1145,1149,1167],[12,13,14,15,19,20,23],"p",{},"This page reads a well, looks at a few fields, changes one and writes the file back. It runs in Node 18 or later; in a browser, replace the file system calls with a ",[16,17,18],"code",{},"File"," or ",[16,21,22],{},"fetch",".",[25,26,28],"h2",{"id":27},"read-and-validate","Read and validate",[30,31,37],"pre",{"className":32,"code":33,"filename":34,"language":35,"meta":36,"style":36},"language-ts shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","import { readFile } from 'node:fs\u002Fpromises';\nimport { parseWell, type Well } from '@welldot\u002Fcore';\n\nconst text = await readFile('PT-01.well', 'utf8');\nconst well: Well = parseWell(text);\n","read.ts","ts","",[16,38,39,75,107,114,157],{"__ignoreMap":36},[40,41,44,48,52,56,59,62,65,69,72],"span",{"class":42,"line":43},"line",1,[40,45,47],{"class":46},"s7zQu","import",[40,49,51],{"class":50},"sMK4o"," {",[40,53,55],{"class":54},"sTEyZ"," readFile",[40,57,58],{"class":50}," }",[40,60,61],{"class":46}," from",[40,63,64],{"class":50}," '",[40,66,68],{"class":67},"sfazB","node:fs\u002Fpromises",[40,70,71],{"class":50},"'",[40,73,74],{"class":50},";\n",[40,76,78,80,82,85,88,91,94,96,98,100,103,105],{"class":42,"line":77},2,[40,79,47],{"class":46},[40,81,51],{"class":50},[40,83,84],{"class":54}," parseWell",[40,86,87],{"class":50},",",[40,89,90],{"class":46}," type",[40,92,93],{"class":54}," Well",[40,95,58],{"class":50},[40,97,61],{"class":46},[40,99,64],{"class":50},[40,101,102],{"class":67},"@welldot\u002Fcore",[40,104,71],{"class":50},[40,106,74],{"class":50},[40,108,110],{"class":42,"line":109},3,[40,111,113],{"emptyLinePlaceholder":112},true,"\n",[40,115,117,121,124,127,130,133,136,138,141,143,145,147,150,152,155],{"class":42,"line":116},4,[40,118,120],{"class":119},"spNyl","const",[40,122,123],{"class":54}," text ",[40,125,126],{"class":50},"=",[40,128,129],{"class":46}," await",[40,131,55],{"class":132},"s2Zo4",[40,134,135],{"class":54},"(",[40,137,71],{"class":50},[40,139,140],{"class":67},"PT-01.well",[40,142,71],{"class":50},[40,144,87],{"class":50},[40,146,64],{"class":50},[40,148,149],{"class":67},"utf8",[40,151,71],{"class":50},[40,153,154],{"class":54},")",[40,156,74],{"class":50},[40,158,160,162,165,168,171,174,176,179],{"class":42,"line":159},5,[40,161,120],{"class":119},[40,163,164],{"class":54}," well",[40,166,167],{"class":50},":",[40,169,93],{"class":170},"sBMFI",[40,172,173],{"class":50}," =",[40,175,84],{"class":132},[40,177,178],{"class":54},"(text)",[40,180,74],{"class":50},[12,182,183,186,187,190,191,194],{},[16,184,185],{},"parseWell"," takes the JSON text (not an already parsed object), validates it against the schema and returns a typed ",[16,188,189],{},"Well",". A file with ",[16,192,193],{},"\"version\": 1"," is upgraded to v2 first. It throws when:",[196,197,198,210,217],"ul",{},[199,200,201,202,205,206,209],"li",{},"the text is not JSON (a ",[16,203,204],{},"SyntaxError"," from ",[16,207,208],{},"JSON.parse",");",[199,211,212,213,216],{},"the version is malformed or unsupported (an ",[16,214,215],{},"Error"," naming the value);",[199,218,219,220,223],{},"the document does not match the schema (a ",[16,221,222],{},"ZodError"," listing every problem).",[30,225,227],{"className":32,"code":226,"language":35,"meta":36,"style":36},"type Issue = { path: (string | number)[]; message: string };\n\ntry {\n  parseWell(text);\n} catch (error) {\n  if (error instanceof Error && error.name === 'ZodError') {\n    for (const issue of (error as Error & { issues: Issue[] }).issues) {\n      console.log(issue.path.join('.'), issue.message);\n      \u002F\u002F well_screen.0.screen_slot Required\n    }\n  } else {\n    console.log((error as Error).message);\n  }\n}\n",[16,228,229,276,280,288,302,316,358,411,460,467,473,484,513,519],{"__ignoreMap":36},[40,230,231,234,237,239,241,245,247,250,253,256,259,262,265,268,270,273],{"class":42,"line":43},[40,232,233],{"class":119},"type",[40,235,236],{"class":170}," Issue",[40,238,173],{"class":50},[40,240,51],{"class":50},[40,242,244],{"class":243},"swJcz"," path",[40,246,167],{"class":50},[40,248,249],{"class":54}," (",[40,251,252],{"class":170},"string",[40,254,255],{"class":50}," |",[40,257,258],{"class":170}," number",[40,260,261],{"class":54},")[]",[40,263,264],{"class":50},";",[40,266,267],{"class":243}," message",[40,269,167],{"class":50},[40,271,272],{"class":170}," string",[40,274,275],{"class":50}," };\n",[40,277,278],{"class":42,"line":77},[40,279,113],{"emptyLinePlaceholder":112},[40,281,282,285],{"class":42,"line":109},[40,283,284],{"class":46},"try",[40,286,287],{"class":50}," {\n",[40,289,290,293,295,298,300],{"class":42,"line":116},[40,291,292],{"class":132},"  parseWell",[40,294,135],{"class":243},[40,296,297],{"class":54},"text",[40,299,154],{"class":243},[40,301,74],{"class":50},[40,303,304,307,310,313],{"class":42,"line":159},[40,305,306],{"class":50},"}",[40,308,309],{"class":46}," catch",[40,311,312],{"class":54}," (error) ",[40,314,315],{"class":50},"{\n",[40,317,319,322,324,327,330,333,336,339,341,344,347,349,351,353,356],{"class":42,"line":318},6,[40,320,321],{"class":46},"  if",[40,323,249],{"class":243},[40,325,326],{"class":54},"error",[40,328,329],{"class":50}," instanceof",[40,331,332],{"class":170}," Error",[40,334,335],{"class":50}," &&",[40,337,338],{"class":54}," error",[40,340,23],{"class":50},[40,342,343],{"class":54},"name",[40,345,346],{"class":50}," ===",[40,348,64],{"class":50},[40,350,222],{"class":67},[40,352,71],{"class":50},[40,354,355],{"class":243},") ",[40,357,315],{"class":50},[40,359,361,364,366,368,371,374,376,378,381,383,386,388,391,393,395,398,400,402,404,407,409],{"class":42,"line":360},7,[40,362,363],{"class":46},"    for",[40,365,249],{"class":243},[40,367,120],{"class":119},[40,369,370],{"class":54}," issue",[40,372,373],{"class":50}," of",[40,375,249],{"class":243},[40,377,326],{"class":54},[40,379,380],{"class":46}," as",[40,382,332],{"class":170},[40,384,385],{"class":50}," &",[40,387,51],{"class":50},[40,389,390],{"class":243}," issues",[40,392,167],{"class":50},[40,394,236],{"class":170},[40,396,397],{"class":243},"[] ",[40,399,306],{"class":50},[40,401,154],{"class":243},[40,403,23],{"class":50},[40,405,406],{"class":54},"issues",[40,408,355],{"class":243},[40,410,315],{"class":50},[40,412,414,417,419,422,424,427,429,432,434,437,439,441,443,445,447,449,451,453,456,458],{"class":42,"line":413},8,[40,415,416],{"class":54},"      console",[40,418,23],{"class":50},[40,420,421],{"class":132},"log",[40,423,135],{"class":243},[40,425,426],{"class":54},"issue",[40,428,23],{"class":50},[40,430,431],{"class":54},"path",[40,433,23],{"class":50},[40,435,436],{"class":132},"join",[40,438,135],{"class":243},[40,440,71],{"class":50},[40,442,23],{"class":67},[40,444,71],{"class":50},[40,446,154],{"class":243},[40,448,87],{"class":50},[40,450,370],{"class":54},[40,452,23],{"class":50},[40,454,455],{"class":54},"message",[40,457,154],{"class":243},[40,459,74],{"class":50},[40,461,463],{"class":42,"line":462},9,[40,464,466],{"class":465},"sHwdD","      \u002F\u002F well_screen.0.screen_slot Required\n",[40,468,470],{"class":42,"line":469},10,[40,471,472],{"class":50},"    }\n",[40,474,476,479,482],{"class":42,"line":475},11,[40,477,478],{"class":50},"  }",[40,480,481],{"class":46}," else",[40,483,287],{"class":50},[40,485,487,490,492,494,497,499,501,503,505,507,509,511],{"class":42,"line":486},12,[40,488,489],{"class":54},"    console",[40,491,23],{"class":50},[40,493,421],{"class":132},[40,495,496],{"class":243},"((",[40,498,326],{"class":54},[40,500,380],{"class":46},[40,502,332],{"class":170},[40,504,154],{"class":243},[40,506,23],{"class":50},[40,508,455],{"class":54},[40,510,154],{"class":243},[40,512,74],{"class":50},[40,514,516],{"class":42,"line":515},13,[40,517,518],{"class":50},"  }\n",[40,520,522],{"class":42,"line":521},14,[40,523,524],{"class":50},"}\n",[12,526,527,528,530,531,534,535,538],{},"Checking ",[16,529,343],{}," rather than ",[16,532,533],{},"instanceof ZodError"," avoids importing ",[16,536,537],{},"zod"," yourself and keeps working if your project resolves a different copy of it.",[12,540,541,546],{},[542,543,545],"a",{"href":544},"\u002Fcore\u002Fguides\u002Fparsing-and-validating","Parsing and validating"," shows how to turn these into readable messages.",[25,548,550],{"id":549},"inspect-the-data","Inspect the data",[12,552,553],{},"Every block is typed. The construction and geology arrays are always present; the other blocks are optional.",[30,555,557],{"className":32,"code":556,"language":35,"meta":36,"style":36},"console.log(well.name, well.well_type);\n\nfor (const layer of well.lithology) {\n  console.log(`${layer.from}–${layer.to} m  ${layer.description}`);\n}\n\nconst screens = well.well_screen.map(s => `${s.from}–${s.to} m`);\nconst tests = (well.hydrodynamic_events ?? []).filter(\n  e => e.type === 'constant_rate' || e.type === 'step_drawdown',\n);\n",[16,558,559,586,590,614,672,676,680,743,774,820],{"__ignoreMap":36},[40,560,561,564,566,568,571,573,575,577,579,581,584],{"class":42,"line":43},[40,562,563],{"class":54},"console",[40,565,23],{"class":50},[40,567,421],{"class":132},[40,569,570],{"class":54},"(well",[40,572,23],{"class":50},[40,574,343],{"class":54},[40,576,87],{"class":50},[40,578,164],{"class":54},[40,580,23],{"class":50},[40,582,583],{"class":54},"well_type)",[40,585,74],{"class":50},[40,587,588],{"class":42,"line":77},[40,589,113],{"emptyLinePlaceholder":112},[40,591,592,595,597,599,602,605,607,609,612],{"class":42,"line":109},[40,593,594],{"class":46},"for",[40,596,249],{"class":54},[40,598,120],{"class":119},[40,600,601],{"class":54}," layer ",[40,603,604],{"class":50},"of",[40,606,164],{"class":54},[40,608,23],{"class":50},[40,610,611],{"class":54},"lithology) ",[40,613,315],{"class":50},[40,615,616,619,621,623,625,628,631,633,636,638,641,644,646,648,651,653,656,658,660,662,665,668,670],{"class":42,"line":116},[40,617,618],{"class":54},"  console",[40,620,23],{"class":50},[40,622,421],{"class":132},[40,624,135],{"class":243},[40,626,627],{"class":50},"`${",[40,629,630],{"class":54},"layer",[40,632,23],{"class":50},[40,634,635],{"class":54},"from",[40,637,306],{"class":50},[40,639,640],{"class":67},"–",[40,642,643],{"class":50},"${",[40,645,630],{"class":54},[40,647,23],{"class":50},[40,649,650],{"class":54},"to",[40,652,306],{"class":50},[40,654,655],{"class":67}," m  ",[40,657,643],{"class":50},[40,659,630],{"class":54},[40,661,23],{"class":50},[40,663,664],{"class":54},"description",[40,666,667],{"class":50},"}`",[40,669,154],{"class":243},[40,671,74],{"class":50},[40,673,674],{"class":42,"line":159},[40,675,524],{"class":50},[40,677,678],{"class":42,"line":318},[40,679,113],{"emptyLinePlaceholder":112},[40,681,682,684,687,689,691,693,696,698,701,703,707,710,713,715,717,719,721,723,725,727,729,731,733,736,739,741],{"class":42,"line":360},[40,683,120],{"class":119},[40,685,686],{"class":54}," screens ",[40,688,126],{"class":50},[40,690,164],{"class":54},[40,692,23],{"class":50},[40,694,695],{"class":54},"well_screen",[40,697,23],{"class":50},[40,699,700],{"class":132},"map",[40,702,135],{"class":54},[40,704,706],{"class":705},"sHdIc","s",[40,708,709],{"class":119}," =>",[40,711,712],{"class":50}," `${",[40,714,706],{"class":54},[40,716,23],{"class":50},[40,718,635],{"class":54},[40,720,306],{"class":50},[40,722,640],{"class":67},[40,724,643],{"class":50},[40,726,706],{"class":54},[40,728,23],{"class":50},[40,730,650],{"class":54},[40,732,306],{"class":50},[40,734,735],{"class":67}," m",[40,737,738],{"class":50},"`",[40,740,154],{"class":54},[40,742,74],{"class":50},[40,744,745,747,750,752,755,757,760,763,766,768,771],{"class":42,"line":413},[40,746,120],{"class":119},[40,748,749],{"class":54}," tests ",[40,751,126],{"class":50},[40,753,754],{"class":54}," (well",[40,756,23],{"class":50},[40,758,759],{"class":54},"hydrodynamic_events ",[40,761,762],{"class":50},"??",[40,764,765],{"class":54}," [])",[40,767,23],{"class":50},[40,769,770],{"class":132},"filter",[40,772,773],{"class":54},"(\n",[40,775,776,779,781,784,786,789,792,794,797,799,802,804,806,808,810,812,815,817],{"class":42,"line":462},[40,777,778],{"class":705},"  e",[40,780,709],{"class":119},[40,782,783],{"class":54}," e",[40,785,23],{"class":50},[40,787,788],{"class":54},"type ",[40,790,791],{"class":50},"===",[40,793,64],{"class":50},[40,795,796],{"class":67},"constant_rate",[40,798,71],{"class":50},[40,800,801],{"class":50}," ||",[40,803,783],{"class":54},[40,805,23],{"class":50},[40,807,788],{"class":54},[40,809,791],{"class":50},[40,811,64],{"class":50},[40,813,814],{"class":67},"step_drawdown",[40,816,71],{"class":50},[40,818,819],{"class":50},",\n",[40,821,822,824],{"class":42,"line":469},[40,823,154],{"class":54},[40,825,74],{"class":50},[12,827,828,831,832,834,835,837],{},[16,829,830],{},"HydrodynamicEvent"," is a union discriminated by ",[16,833,233],{},", so narrowing on ",[16,836,233],{}," gives you the fields of that event kind.",[12,839,840,841,23],{},"For derived values, such as the latest static level, gravel pack volume or permit status, use ",[542,842,844],{"href":843},"\u002Futils",[16,845,846],{},"@welldot\u002Futils",[25,848,850],{"id":849},"change-and-save","Change and save",[30,852,855],{"className":32,"code":853,"filename":854,"language":35,"meta":36,"style":36},"import { writeFile } from 'node:fs\u002Fpromises';\nimport { serializeWell } from '@welldot\u002Fcore';\n\nwell.well_purpose = ['production', 'monitoring'];\nawait writeFile('PT-01.well', serializeWell(well), 'utf8');\n","save.ts",[16,856,857,878,899,903,939],{"__ignoreMap":36},[40,858,859,861,863,866,868,870,872,874,876],{"class":42,"line":43},[40,860,47],{"class":46},[40,862,51],{"class":50},[40,864,865],{"class":54}," writeFile",[40,867,58],{"class":50},[40,869,61],{"class":46},[40,871,64],{"class":50},[40,873,68],{"class":67},[40,875,71],{"class":50},[40,877,74],{"class":50},[40,879,880,882,884,887,889,891,893,895,897],{"class":42,"line":77},[40,881,47],{"class":46},[40,883,51],{"class":50},[40,885,886],{"class":54}," serializeWell",[40,888,58],{"class":50},[40,890,61],{"class":46},[40,892,64],{"class":50},[40,894,102],{"class":67},[40,896,71],{"class":50},[40,898,74],{"class":50},[40,900,901],{"class":42,"line":109},[40,902,113],{"emptyLinePlaceholder":112},[40,904,905,908,910,913,915,918,920,923,925,927,929,932,934,937],{"class":42,"line":116},[40,906,907],{"class":54},"well",[40,909,23],{"class":50},[40,911,912],{"class":54},"well_purpose ",[40,914,126],{"class":50},[40,916,917],{"class":54}," [",[40,919,71],{"class":50},[40,921,922],{"class":67},"production",[40,924,71],{"class":50},[40,926,87],{"class":50},[40,928,64],{"class":50},[40,930,931],{"class":67},"monitoring",[40,933,71],{"class":50},[40,935,936],{"class":54},"]",[40,938,74],{"class":50},[40,940,941,944,946,948,950,952,954,956,958,961,963,965,967,969,971],{"class":42,"line":159},[40,942,943],{"class":46},"await",[40,945,865],{"class":132},[40,947,135],{"class":54},[40,949,71],{"class":50},[40,951,140],{"class":67},[40,953,71],{"class":50},[40,955,87],{"class":50},[40,957,886],{"class":132},[40,959,960],{"class":54},"(well)",[40,962,87],{"class":50},[40,964,64],{"class":50},[40,966,149],{"class":67},[40,968,71],{"class":50},[40,970,154],{"class":54},[40,972,74],{"class":50},[12,974,975,978,979,982,983,986,987,991],{},[16,976,977],{},"serializeWell"," writes ",[16,980,981],{},"\"version\": \"2.4\"",", leaves out empty optional fields and keeps every member it does not know, including ",[16,984,985],{},"x-"," extensions, as the spec requires (",[542,988,990],{"href":989},"\u002Fcore\u002Fguides\u002Fserializing-and-sharing","Serializing and sharing",").",[25,993,995],{"id":994},"show-labels-and-convert-units","Show labels and convert units",[12,997,998],{},"Values are stored as keys and in SI units. Convert for display:",[30,1000,1002],{"className":32,"code":1001,"language":35,"meta":36,"style":36},"import {\n  CONSTRUCTION_MATERIALS,\n  getVocabLabel,\n  metersToFeet,\n  mmToInches,\n} from '@welldot\u002Fcore';\n\nconst casing = well.well_case[0];\ngetVocabLabel(CONSTRUCTION_MATERIALS, casing.type, 'pt'); \u002F\u002F 'Aço carbono'\nmmToInches(casing.diameter); \u002F\u002F 8.62… for 219 mm\nmetersToFeet(casing.to);\n",[16,1003,1004,1010,1017,1024,1031,1038,1052,1056,1080,1113,1131],{"__ignoreMap":36},[40,1005,1006,1008],{"class":42,"line":43},[40,1007,47],{"class":46},[40,1009,287],{"class":50},[40,1011,1012,1015],{"class":42,"line":77},[40,1013,1014],{"class":54},"  CONSTRUCTION_MATERIALS",[40,1016,819],{"class":50},[40,1018,1019,1022],{"class":42,"line":109},[40,1020,1021],{"class":54},"  getVocabLabel",[40,1023,819],{"class":50},[40,1025,1026,1029],{"class":42,"line":116},[40,1027,1028],{"class":54},"  metersToFeet",[40,1030,819],{"class":50},[40,1032,1033,1036],{"class":42,"line":159},[40,1034,1035],{"class":54},"  mmToInches",[40,1037,819],{"class":50},[40,1039,1040,1042,1044,1046,1048,1050],{"class":42,"line":318},[40,1041,306],{"class":50},[40,1043,61],{"class":46},[40,1045,64],{"class":50},[40,1047,102],{"class":67},[40,1049,71],{"class":50},[40,1051,74],{"class":50},[40,1053,1054],{"class":42,"line":360},[40,1055,113],{"emptyLinePlaceholder":112},[40,1057,1058,1060,1063,1065,1067,1069,1072,1076,1078],{"class":42,"line":413},[40,1059,120],{"class":119},[40,1061,1062],{"class":54}," casing ",[40,1064,126],{"class":50},[40,1066,164],{"class":54},[40,1068,23],{"class":50},[40,1070,1071],{"class":54},"well_case[",[40,1073,1075],{"class":1074},"sbssI","0",[40,1077,936],{"class":54},[40,1079,74],{"class":50},[40,1081,1082,1085,1088,1090,1093,1095,1097,1099,1101,1104,1106,1108,1110],{"class":42,"line":462},[40,1083,1084],{"class":132},"getVocabLabel",[40,1086,1087],{"class":54},"(CONSTRUCTION_MATERIALS",[40,1089,87],{"class":50},[40,1091,1092],{"class":54}," casing",[40,1094,23],{"class":50},[40,1096,233],{"class":54},[40,1098,87],{"class":50},[40,1100,64],{"class":50},[40,1102,1103],{"class":67},"pt",[40,1105,71],{"class":50},[40,1107,154],{"class":54},[40,1109,264],{"class":50},[40,1111,1112],{"class":465}," \u002F\u002F 'Aço carbono'\n",[40,1114,1115,1118,1121,1123,1126,1128],{"class":42,"line":469},[40,1116,1117],{"class":132},"mmToInches",[40,1119,1120],{"class":54},"(casing",[40,1122,23],{"class":50},[40,1124,1125],{"class":54},"diameter)",[40,1127,264],{"class":50},[40,1129,1130],{"class":465}," \u002F\u002F 8.62… for 219 mm\n",[40,1132,1133,1136,1138,1140,1143],{"class":42,"line":475},[40,1134,1135],{"class":132},"metersToFeet",[40,1137,1120],{"class":54},[40,1139,23],{"class":50},[40,1141,1142],{"class":54},"to)",[40,1144,74],{"class":50},[25,1146,1148],{"id":1147},"next","Next",[196,1150,1151,1155,1161],{},[199,1152,1153],{},[542,1154,545],{"href":544},[199,1156,1157],{},[542,1158,1160],{"href":1159},"\u002Fcore\u002Fguides\u002Fvocabularies-and-textures","Vocabularies and textures",[199,1162,1163],{},[542,1164,1166],{"href":1165},"\u002Fcore\u002Fapi","API reference",[1168,1169,1170],"style",{},"html pre.shiki code .s7zQu, html code.shiki .s7zQu{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .s2Zo4, html code.shiki .s2Zo4{--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF}html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .swJcz, html code.shiki .swJcz{--shiki-light:#E53935;--shiki-default:#F07178;--shiki-dark:#F07178}html pre.shiki code .sHwdD, html code.shiki .sHwdD{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic}html pre.shiki code .sHdIc, html code.shiki .sHdIc{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#EEFFFF;--shiki-default-font-style:italic;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .sbssI, html code.shiki .sbssI{--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C}",{"title":36,"searchDepth":77,"depth":77,"links":1172},[1173,1174,1175,1176,1177],{"id":27,"depth":77,"text":28},{"id":549,"depth":77,"text":550},{"id":849,"depth":77,"text":850},{"id":994,"depth":77,"text":995},{"id":1147,"depth":77,"text":1148},"Read a .well file with @welldot\u002Fcore, handle validation errors, inspect the typed data, change it and save it again.","md",{},"\u002Fcore\u002Fgetting-started\u002Ffirst-use","---\ntitle: First use\ndescription: Read a .well file with @welldot\u002Fcore, handle validation errors, inspect the typed data, change it and save it again.\n---\n\nThis page reads a well, looks at a few fields, changes one and writes the file back. It runs in Node 18 or later; in a browser, replace the file system calls with a `File` or `fetch`.\n\n## Read and validate\n\n```ts [read.ts]\nimport { readFile } from 'node:fs\u002Fpromises';\nimport { parseWell, type Well } from '@welldot\u002Fcore';\n\nconst text = await readFile('PT-01.well', 'utf8');\nconst well: Well = parseWell(text);\n```\n\n`parseWell` takes the JSON text (not an already parsed object), validates it against the schema and returns a typed `Well`. A file with `\"version\": 1` is upgraded to v2 first. It throws when:\n\n- the text is not JSON (a `SyntaxError` from `JSON.parse`);\n- the version is malformed or unsupported (an `Error` naming the value);\n- the document does not match the schema (a `ZodError` listing every problem).\n\n```ts\ntype Issue = { path: (string | number)[]; message: string };\n\ntry {\n  parseWell(text);\n} catch (error) {\n  if (error instanceof Error && error.name === 'ZodError') {\n    for (const issue of (error as Error & { issues: Issue[] }).issues) {\n      console.log(issue.path.join('.'), issue.message);\n      \u002F\u002F well_screen.0.screen_slot Required\n    }\n  } else {\n    console.log((error as Error).message);\n  }\n}\n```\n\nChecking `name` rather than `instanceof ZodError` avoids importing `zod` yourself and keeps working if your project resolves a different copy of it.\n\n[Parsing and validating](\u002Fcore\u002Fguides\u002Fparsing-and-validating) shows how to turn these into readable messages.\n\n## Inspect the data\n\nEvery block is typed. The construction and geology arrays are always present; the other blocks are optional.\n\n```ts\nconsole.log(well.name, well.well_type);\n\nfor (const layer of well.lithology) {\n  console.log(`${layer.from}–${layer.to} m  ${layer.description}`);\n}\n\nconst screens = well.well_screen.map(s => `${s.from}–${s.to} m`);\nconst tests = (well.hydrodynamic_events ?? []).filter(\n  e => e.type === 'constant_rate' || e.type === 'step_drawdown',\n);\n```\n\n`HydrodynamicEvent` is a union discriminated by `type`, so narrowing on `type` gives you the fields of that event kind.\n\nFor derived values, such as the latest static level, gravel pack volume or permit status, use [`@welldot\u002Futils`](\u002Futils).\n\n## Change and save\n\n```ts [save.ts]\nimport { writeFile } from 'node:fs\u002Fpromises';\nimport { serializeWell } from '@welldot\u002Fcore';\n\nwell.well_purpose = ['production', 'monitoring'];\nawait writeFile('PT-01.well', serializeWell(well), 'utf8');\n```\n\n`serializeWell` writes `\"version\": \"2.4\"`, leaves out empty optional fields and keeps every member it does not know, including `x-` extensions, as the spec requires ([Serializing and sharing](\u002Fcore\u002Fguides\u002Fserializing-and-sharing)).\n\n## Show labels and convert units\n\nValues are stored as keys and in SI units. Convert for display:\n\n```ts\nimport {\n  CONSTRUCTION_MATERIALS,\n  getVocabLabel,\n  metersToFeet,\n  mmToInches,\n} from '@welldot\u002Fcore';\n\nconst casing = well.well_case[0];\ngetVocabLabel(CONSTRUCTION_MATERIALS, casing.type, 'pt'); \u002F\u002F 'Aço carbono'\nmmToInches(casing.diameter); \u002F\u002F 8.62… for 219 mm\nmetersToFeet(casing.to);\n```\n\n## Next\n\n- [Parsing and validating](\u002Fcore\u002Fguides\u002Fparsing-and-validating)\n- [Vocabularies and textures](\u002Fcore\u002Fguides\u002Fvocabularies-and-textures)\n- [API reference](\u002Fcore\u002Fapi)\n",{"title":7,"description":1178},"core\u002F1.getting-started\u002F2.first-use","JpjOd9tMNdnbSVxUsHjdu6KCpjdWbbd6xsaTxqkrnMY",{"docs_en":1187,"spec":1493,"changelogs":1543},[1188,1208,1227,1272,1382,1436],{"title":1189,"path":1190,"stem":1191,"children":1192},"Ai","\u002Fai","ai",[1193,1196,1200,1204],{"title":1194,"path":1190,"stem":1195},"Introduction","ai\u002Findex",{"title":1197,"path":1198,"stem":1199},"Converting reports with an assistant","\u002Fai\u002Fconversion-skill","ai\u002Fconversion-skill",{"title":1201,"path":1202,"stem":1203},"llms.txt and Markdown pages","\u002Fai\u002Fllms","ai\u002Fllms",{"title":1205,"path":1206,"stem":1207},"MCP server","\u002Fai\u002Fmcp","ai\u002Fmcp",{"title":1209,"path":1210,"stem":1211,"children":1212},"Contributing","\u002Fcontributing","contributing",[1213,1215,1219,1223],{"title":1194,"path":1210,"stem":1214},"contributing\u002Findex",{"title":1216,"path":1217,"stem":1218},"Writing docs","\u002Fcontributing\u002Fwriting-docs","contributing\u002F1.writing-docs",{"title":1220,"path":1221,"stem":1222},"Update rules","\u002Fcontributing\u002Fupdate-rules","contributing\u002F2.update-rules",{"title":1224,"path":1225,"stem":1226},"Content components","\u002Fcontributing\u002Fcomponents","contributing\u002Fcomponents",{"title":1228,"path":1229,"stem":1230,"children":1231},"Core","\u002Fcore","core",[1232,1234,1245,1268],{"title":1194,"path":1229,"stem":1233},"core\u002Findex",{"title":1235,"path":1236,"stem":1237,"children":1238,"page":1244},"Getting Started","\u002Fcore\u002Fgetting-started","core\u002F1.getting-started",[1239,1243],{"title":1240,"path":1241,"stem":1242},"Installation","\u002Fcore\u002Fgetting-started\u002Finstallation","core\u002F1.getting-started\u002F1.installation",{"title":7,"path":1181,"stem":1184},false,{"title":1246,"path":1247,"stem":1248,"children":1249,"page":1244},"Guides","\u002Fcore\u002Fguides","core\u002F2.guides",[1250,1252,1254,1258,1260,1264],{"title":545,"path":544,"stem":1251},"core\u002F2.guides\u002F1.parsing-and-validating",{"title":990,"path":989,"stem":1253},"core\u002F2.guides\u002F2.serializing-and-sharing",{"title":1255,"path":1256,"stem":1257},"Unit conversion","\u002Fcore\u002Fguides\u002Funit-conversion","core\u002F2.guides\u002F3.unit-conversion",{"title":1160,"path":1159,"stem":1259},"core\u002F2.guides\u002F4.vocabularies-and-textures",{"title":1261,"path":1262,"stem":1263},"Water quality vocabulary","\u002Fcore\u002Fguides\u002Fwater-quality-vocabulary","core\u002F2.guides\u002F5.water-quality-vocabulary",{"title":1265,"path":1266,"stem":1267},"Versions and time zones","\u002Fcore\u002Fguides\u002Fversions-and-time-zones","core\u002F2.guides\u002F6.versions-and-time-zones",{"title":1166,"path":1165,"stem":1269,"children":1270},"core\u002Fapi\u002Findex",[1271],{"title":1166,"path":1165,"stem":1269},{"title":1273,"path":1274,"stem":1275,"children":1276},"Format","\u002Fformat","format",[1277,1279,1299,1328,1352,1372,1378],{"title":1194,"path":1274,"stem":1278},"format\u002Findex",{"title":1235,"path":1280,"stem":1281,"children":1282,"page":1244},"\u002Fformat\u002Fgetting-started","format\u002F1.getting-started",[1283,1287,1291,1295],{"title":1284,"path":1285,"stem":1286},"What is .well?","\u002Fformat\u002Fgetting-started\u002Fwhat-is-well","format\u002F1.getting-started\u002F1.what-is-well",{"title":1288,"path":1289,"stem":1290},"For geologists","\u002Fformat\u002Fgetting-started\u002Ffor-geologists","format\u002F1.getting-started\u002F2.for-geologists",{"title":1292,"path":1293,"stem":1294},"For developers","\u002Fformat\u002Fgetting-started\u002Ffor-developers","format\u002F1.getting-started\u002F3.for-developers",{"title":1296,"path":1297,"stem":1298},"Your first .well file","\u002Fformat\u002Fgetting-started\u002Ffirst-well-file","format\u002F1.getting-started\u002F4.first-well-file",{"title":1300,"path":1301,"stem":1302,"children":1303,"page":1244},"Concepts","\u002Fformat\u002Fconcepts","format\u002F2.concepts",[1304,1308,1312,1316,1320,1324],{"title":1305,"path":1306,"stem":1307},"Depths and intervals","\u002Fformat\u002Fconcepts\u002Fdepths-and-intervals","format\u002F2.concepts\u002F1.depths-and-intervals",{"title":1309,"path":1310,"stem":1311},"Units and precision","\u002Fformat\u002Fconcepts\u002Funits-and-precision","format\u002F2.concepts\u002F2.units-and-precision",{"title":1313,"path":1314,"stem":1315},"Vocabularies","\u002Fformat\u002Fconcepts\u002Fvocabularies","format\u002F2.concepts\u002F3.vocabularies",{"title":1317,"path":1318,"stem":1319},"Profiles","\u002Fformat\u002Fconcepts\u002Fprofiles","format\u002F2.concepts\u002F4.profiles",{"title":1321,"path":1322,"stem":1323},"Versions and deprecation","\u002Fformat\u002Fconcepts\u002Fversions-and-deprecation","format\u002F2.concepts\u002F5.versions-and-deprecation",{"title":1325,"path":1326,"stem":1327},"Extensibility","\u002Fformat\u002Fconcepts\u002Fextensibility","format\u002F2.concepts\u002F6.extensibility",{"title":1246,"path":1329,"stem":1330,"children":1331,"page":1244},"\u002Fformat\u002Fguides","format\u002F3.guides",[1332,1336,1340,1344,1348],{"title":1333,"path":1334,"stem":1335},"Writing a .well by hand","\u002Fformat\u002Fguides\u002Fwriting-by-hand","format\u002F3.guides\u002F1.writing-by-hand",{"title":1337,"path":1338,"stem":1339},"Converting a report","\u002Fformat\u002Fguides\u002Fconverting-a-report","format\u002F3.guides\u002F2.converting-a-report",{"title":1341,"path":1342,"stem":1343},"Validating","\u002Fformat\u002Fguides\u002Fvalidating","format\u002F3.guides\u002F3.validating",{"title":1345,"path":1346,"stem":1347},"Extending for your own needs","\u002Fformat\u002Fguides\u002Fextending","format\u002F3.guides\u002F4.extending",{"title":1349,"path":1350,"stem":1351},"Building an editor or database on .well","\u002Fformat\u002Fguides\u002Fbuilding-on-well","format\u002F3.guides\u002F5.building-on-well",{"title":1353,"path":1354,"stem":1355,"children":1356},"Overview","\u002Fformat\u002Freference","format\u002F4.reference\u002Findex",[1357,1358,1362,1366],{"title":1353,"path":1354,"stem":1355},{"title":1359,"path":1360,"stem":1361},"JSON Schema","\u002Fformat\u002Freference\u002Fjson-schema","format\u002F4.reference\u002F1.json-schema",{"title":1363,"path":1364,"stem":1365},"Example wells","\u002Fformat\u002Freference\u002Fexamples","format\u002F4.reference\u002F2.examples",{"title":1367,"path":1368,"stem":1369,"children":1370},"Object reference","\u002Fformat\u002Freference\u002Fobjects","format\u002Freference\u002Fobjects\u002Findex",[1371],{"title":1367,"path":1368,"stem":1369},{"title":1373,"path":1374,"stem":1375,"children":1376},"About the spec","\u002Fformat\u002Fspec","format\u002F5.spec\u002Findex",[1377],{"title":1373,"path":1374,"stem":1375},{"title":1379,"path":1380,"stem":1381},"Changelog","\u002Fformat\u002Fchangelog","format\u002F6.changelog",{"title":1383,"path":1384,"stem":1385,"children":1386},"Render","\u002Frender","render",[1387,1389,1399,1431],{"title":1194,"path":1384,"stem":1388},"render\u002Findex",{"title":1235,"path":1390,"stem":1391,"children":1392,"page":1244},"\u002Frender\u002Fgetting-started","render\u002F1.getting-started",[1393,1396],{"title":1240,"path":1394,"stem":1395},"\u002Frender\u002Fgetting-started\u002Finstallation","render\u002F1.getting-started\u002F1.installation",{"title":7,"path":1397,"stem":1398},"\u002Frender\u002Fgetting-started\u002Ffirst-use","render\u002F1.getting-started\u002F2.first-use",{"title":1246,"path":1400,"stem":1401,"children":1402,"page":1244},"\u002Frender\u002Fguides","render\u002F2.guides",[1403,1407,1411,1415,1419,1423,1427],{"title":1404,"path":1405,"stem":1406},"Panels and layout","\u002Frender\u002Fguides\u002Fpanels-and-layout","render\u002F2.guides\u002F1.panels-and-layout",{"title":1408,"path":1409,"stem":1410},"Layers and labels","\u002Frender\u002Fguides\u002Flayers-and-labels","render\u002F2.guides\u002F2.layers-and-labels",{"title":1412,"path":1413,"stem":1414},"Theming","\u002Frender\u002Fguides\u002Ftheming","render\u002F2.guides\u002F3.theming",{"title":1416,"path":1417,"stem":1418},"Locale and units","\u002Frender\u002Fguides\u002Flocale-and-units","render\u002F2.guides\u002F4.locale-and-units",{"title":1420,"path":1421,"stem":1422},"Legends","\u002Frender\u002Fguides\u002Flegends","render\u002F2.guides\u002F5.legends",{"title":1424,"path":1425,"stem":1426},"Zoom, pan and highlights","\u002Frender\u002Fguides\u002Finteraction","render\u002F2.guides\u002F6.interaction",{"title":1428,"path":1429,"stem":1430},"Using it in a framework","\u002Frender\u002Fguides\u002Fframeworks","render\u002F2.guides\u002F7.frameworks",{"title":1166,"path":1432,"stem":1433,"children":1434},"\u002Frender\u002Fapi","render\u002Fapi\u002Findex",[1435],{"title":1166,"path":1432,"stem":1433},{"title":1437,"path":843,"stem":1438,"children":1439},"Utils","utils",[1440,1442,1452,1488],{"title":1194,"path":843,"stem":1441},"utils\u002Findex",{"title":1235,"path":1443,"stem":1444,"children":1445,"page":1244},"\u002Futils\u002Fgetting-started","utils\u002F1.getting-started",[1446,1449],{"title":1240,"path":1447,"stem":1448},"\u002Futils\u002Fgetting-started\u002Finstallation","utils\u002F1.getting-started\u002F1.installation",{"title":7,"path":1450,"stem":1451},"\u002Futils\u002Fgetting-started\u002Ffirst-use","utils\u002F1.getting-started\u002F2.first-use",{"title":1246,"path":1453,"stem":1454,"children":1455,"page":1244},"\u002Futils\u002Fguides","utils\u002F2.guides",[1456,1460,1464,1468,1472,1476,1480,1484],{"title":1457,"path":1458,"stem":1459},"Geometry and volumes","\u002Futils\u002Fguides\u002Fgeometry-and-volumes","utils\u002F2.guides\u002F1.geometry-and-volumes",{"title":1461,"path":1462,"stem":1463},"Water levels and pumping tests","\u002Futils\u002Fguides\u002Fpumping-tests","utils\u002F2.guides\u002F2.pumping-tests",{"title":1465,"path":1466,"stem":1467},"Permits","\u002Futils\u002Fguides\u002Fpermits","utils\u002F2.guides\u002F3.permits",{"title":1469,"path":1470,"stem":1471},"Operation and production","\u002Futils\u002Fguides\u002Foperation","utils\u002F2.guides\u002F4.operation",{"title":1473,"path":1474,"stem":1475},"Water quality","\u002Futils\u002Fguides\u002Fwater-quality","utils\u002F2.guides\u002F5.water-quality",{"title":1477,"path":1478,"stem":1479},"Logger import","\u002Futils\u002Fguides\u002Flogger-import","utils\u002F2.guides\u002F6.logger-import",{"title":1481,"path":1482,"stem":1483},"SIAGAS import","\u002Futils\u002Fguides\u002Fsiagas-import","utils\u002F2.guides\u002F7.siagas-import",{"title":1485,"path":1486,"stem":1487},"Formatting","\u002Futils\u002Fguides\u002Fformatting","utils\u002F2.guides\u002F8.formatting",{"title":1166,"path":1489,"stem":1490,"children":1491},"\u002Futils\u002Fapi","utils\u002Fapi\u002Findex",[1492],{"title":1166,"path":1489,"stem":1490},[1494],{"title":1273,"path":1274,"stem":1275,"children":1495,"page":1244},[1496],{"title":1497,"path":1374,"stem":1498,"children":1499,"page":1244},"Spec","format\u002Fspec",[1500,1509,1518],{"title":1501,"path":1502,"stem":1503,"children":1504,"page":1244},"Reference","\u002Fformat\u002Fspec\u002Freference","format\u002Fspec\u002Freference",[1505],{"title":1506,"path":1507,"stem":1508},"FGDC Texture Patterns Reference","\u002Fformat\u002Fspec\u002Freference\u002Ffgdc-textures","format\u002Fspec\u002Freference\u002Ffgdc-textures",{"title":1510,"path":1511,"stem":1512,"children":1513,"page":1244},"V1","\u002Fformat\u002Fspec\u002Fv1","format\u002Fspec\u002Fv1",[1514],{"title":1515,"path":1516,"stem":1517},".well File Format Specification","\u002Fformat\u002Fspec\u002Fv1\u002Fwell-format","format\u002Fspec\u002Fv1\u002Fwell-format",{"title":1519,"path":1520,"stem":1521,"children":1522,"page":1244},"V2","\u002Fformat\u002Fspec\u002Fv2","format\u002Fspec\u002Fv2",[1523,1527,1531,1535,1539],{"title":1524,"path":1525,"stem":1526},".well File Format Specification — Version 2.4: Format Reference","\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference","format\u002Fspec\u002Fv2\u002Fformat-reference",{"title":1528,"path":1529,"stem":1530},".well File Format Specification — Version 2.4: Interoperability","\u002Fformat\u002Fspec\u002Fv2\u002Finteroperability","format\u002Fspec\u002Fv2\u002Finteroperability",{"title":1532,"path":1533,"stem":1534},".well File Format Specification — Version 2.4: Object Schemas","\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas","format\u002Fspec\u002Fv2\u002Fobject-schemas",{"title":1536,"path":1537,"stem":1538},".well File Format Specification — Version 2.4: Overview","\u002Fformat\u002Fspec\u002Fv2\u002Foverview","format\u002Fspec\u002Fv2\u002Foverview",{"title":1540,"path":1541,"stem":1542},".well File Format Specification — Version 2.4: Water Quality","\u002Fformat\u002Fspec\u002Fv2\u002Fwater-quality","format\u002Fspec\u002Fv2\u002Fwater-quality",[1544,1549,1555],{"title":1228,"path":1229,"stem":1230,"children":1545,"page":1244},[1546],{"title":102,"path":1547,"stem":1548},"\u002Fcore\u002Fchangelog","core\u002FCHANGELOG",{"title":1383,"path":1384,"stem":1385,"children":1550,"page":1244},[1551],{"title":1552,"path":1553,"stem":1554},"@welldot\u002Frender","\u002Frender\u002Fchangelog","render\u002FCHANGELOG",{"title":1437,"path":843,"stem":1438,"children":1556,"page":1244},[1557],{"title":846,"path":1558,"stem":1559},"\u002Futils\u002Fchangelog","utils\u002FCHANGELOG",1793050497021]