@welldot/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,747 @@
+import { z } from 'zod';
+
+/** A drilled interval of the borehole. Multiple entries describe a telescoping borehole. */
+type BoreHole = {
+    /** Start depth in meters from ground level (0 = surface). */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Borehole diameter in millimeters. */
+    diameter: number;
+    /** Free text description of the drilling method used (e.g. `rotary`, `percussion`, `cable_tool`). */
+    drilling_method?: string;
+};
+/** Steel or plastic casing installed inside the borehole. */
+type WellCase = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Casing material. Recommended: `steel`, `pvc`, `hdpe`, `fiberglass`. Can be free-text. */
+    type: string;
+    /** Casing outer diameter in millimeters. */
+    diameter: number;
+};
+/** Transition piece connecting two casing or screen sections of different diameters. */
+type Reduction = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Diameter at the top of the reducer in millimeters. */
+    diam_from: number;
+    /** Diameter at the bottom of the reducer in millimeters. */
+    diam_to: number;
+    /** Reducer shape (e.g. `conical`, `stepped`). Can be free-text. */
+    type: string;
+};
+/** Slotted or wire-wound screen section that allows water to enter the well. */
+type WellScreen = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Screen type. Recommended: `wire_wound`, `bridge_slot`, `louvered`, `pvc_slotted`. Can be free-text. */
+    type: string;
+    /** Screen outer diameter in millimeters. */
+    diameter: number;
+    /** Slot opening size in millimeters. */
+    screen_slot_mm: number;
+};
+/** Material placed in the annular space between the casing and the borehole wall. */
+type HoleFill = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Fill category: `gravel_pack` for filter gravel, `seal` for cement or bentonite. */
+    type: 'gravel_pack' | 'seal';
+    /** Outer diameter of the filled annulus in millimeters. */
+    diameter: number;
+    /** Material description (e.g. grain size, material name). */
+    description: string;
+};
+/** Outer protective casing installed near the surface to prevent contamination. */
+type SurfaceCase = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Casing outer diameter in millimeters. */
+    diameter: number;
+};
+/** Concrete pad installed at ground level (depth 0) around the wellhead. All dimensions in **meters**. */
+type CementPad = {
+    /** Pad shape (e.g. `square`, `rectangular`, `circular`). */
+    type: string;
+    /** Width in meters. */
+    width: number;
+    /** Thickness in meters. */
+    thickness: number;
+    /** Length in meters. */
+    length: number;
+};
+/** Geological description of a depth interval. */
+type Lithology = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Free-text geological description. */
+    description: string;
+    /** Representative color as a CSS hex value (e.g. `#f5deb3`). */
+    color: string;
+    /** Texture code per the FGDC Digital Cartographic Standard for Geologic Map Symbolization. */
+    fgdc_texture: string;
+    /** Name of the stratigraphic or geologic unit. */
+    geologic_unit: string;
+    /** Aquifer unit name (e.g. `Pirabas Aquifer`). */
+    aquifer_unit: string;
+};
+/** A discrete fracture or fracture zone intersected by the borehole. */
+type Fracture = {
+    /** Depth of the fracture in meters from ground level. */
+    depth: number;
+    /** Whether the fracture produces water. */
+    water_intake: boolean;
+    /** Free-text description. */
+    description: string;
+    /** Whether this fracture belongs to a swarm (closely spaced set of fractures). */
+    swarm: boolean;
+    /** Azimuth in degrees from geographic north (0–360). */
+    azimuth: number;
+    /** Dip angle in degrees from horizontal (0–90). */
+    dip: number;
+};
+/** A cavity or void zone intersected by the borehole. */
+type Cave = {
+    /** Start depth in meters from ground level. */
+    from: number;
+    /** End depth in meters from ground level. */
+    to: number;
+    /** Whether the cave produces water. */
+    water_intake: boolean;
+    /** Free-text description. */
+    description: string;
+};
+/** Complete static record of a water well. All depths in meters, all diameters in millimeters. */
+type Well = {
+    /** Classification of the well (e.g. `tubular`, `artesian`, `hand_dug`). */
+    well_type?: string;
+    /** Well name or local identifier. */
+    name?: string;
+    /** Name of the drilling company or individual. */
+    well_driller?: string;
+    /** ISO 8601 date of well completion (YYYY-MM-DD). */
+    construction_date?: string;
+    /** Latitude in decimal degrees (WGS84). */
+    lat?: number;
+    /** Longitude in decimal degrees (WGS84). */
+    lng?: number;
+    /** Ground elevation above sea level in meters. */
+    elevation?: number;
+    /** Free-text observations about the well. */
+    obs?: string;
+    bore_hole: BoreHole[];
+    well_case: WellCase[];
+    reduction: Reduction[];
+    well_screen: WellScreen[];
+    surface_case: SurfaceCase[];
+    hole_fill: HoleFill[];
+    cement_pad: CementPad;
+    lithology: Lithology[];
+    fractures: Fracture[];
+    caves: Cave[];
+};
+/** Geologic section of a well (lithology, fractures, caves). */
+type Geologic = {
+    lithology: Lithology[];
+    fractures: Fracture[];
+    caves: Cave[];
+};
+/** Constructive section of a well (borehole geometry, casings, screens, fills). */
+type Constructive = {
+    bore_hole: BoreHole[];
+    well_case: WellCase[];
+    reduction: Reduction[];
+    well_screen: WellScreen[];
+    surface_case: SurfaceCase[];
+    hole_fill: HoleFill[];
+    cement_pad: CementPad;
+};
+
+type UnitsTypes = 'metric' | 'imperial';
+type LengthUnits = 'm' | 'ft';
+type DiameterUnits = 'mm' | 'inches';
+type Units = {
+    length: LengthUnits;
+    diameter: DiameterUnits;
+};
+
+declare const BoreHoleSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    diameter: z.ZodNumber;
+    drilling_method: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    diameter: number;
+    drilling_method?: string | undefined;
+}, {
+    from: number;
+    to: number;
+    diameter: number;
+    drilling_method?: string | undefined;
+}>;
+declare const WellCaseSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    type: z.ZodString;
+    diameter: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    diameter: number;
+    type: string;
+}, {
+    from: number;
+    to: number;
+    diameter: number;
+    type: string;
+}>;
+declare const ReductionSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    diam_from: z.ZodNumber;
+    diam_to: z.ZodNumber;
+    type: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    type: string;
+    diam_from: number;
+    diam_to: number;
+}, {
+    from: number;
+    to: number;
+    type: string;
+    diam_from: number;
+    diam_to: number;
+}>;
+declare const WellScreenSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    type: z.ZodString;
+    diameter: z.ZodNumber;
+    screen_slot_mm: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    diameter: number;
+    type: string;
+    screen_slot_mm: number;
+}, {
+    from: number;
+    to: number;
+    diameter: number;
+    type: string;
+    screen_slot_mm: number;
+}>;
+declare const HoleFillSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    type: z.ZodEnum<["gravel_pack", "seal"]>;
+    diameter: z.ZodNumber;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    diameter: number;
+    type: "gravel_pack" | "seal";
+    description: string;
+}, {
+    from: number;
+    to: number;
+    diameter: number;
+    type: "gravel_pack" | "seal";
+    description: string;
+}>;
+declare const SurfaceCaseSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    diameter: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    diameter: number;
+}, {
+    from: number;
+    to: number;
+    diameter: number;
+}>;
+declare const CementPadSchema: z.ZodObject<{
+    type: z.ZodString;
+    width: z.ZodNumber;
+    thickness: z.ZodNumber;
+    length: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    length: number;
+    width: number;
+    thickness: number;
+}, {
+    type: string;
+    length: number;
+    width: number;
+    thickness: number;
+}>;
+declare const LithologySchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    description: z.ZodString;
+    color: z.ZodString;
+    fgdc_texture: z.ZodString;
+    geologic_unit: z.ZodString;
+    aquifer_unit: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    description: string;
+    color: string;
+    fgdc_texture: string;
+    geologic_unit: string;
+    aquifer_unit: string;
+}, {
+    from: number;
+    to: number;
+    description: string;
+    color: string;
+    fgdc_texture: string;
+    geologic_unit: string;
+    aquifer_unit: string;
+}>;
+declare const FractureSchema: z.ZodObject<{
+    depth: z.ZodNumber;
+    water_intake: z.ZodBoolean;
+    description: z.ZodString;
+    swarm: z.ZodBoolean;
+    azimuth: z.ZodNumber;
+    dip: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    depth: number;
+    water_intake: boolean;
+    swarm: boolean;
+    azimuth: number;
+    dip: number;
+}, {
+    description: string;
+    depth: number;
+    water_intake: boolean;
+    swarm: boolean;
+    azimuth: number;
+    dip: number;
+}>;
+declare const CaveSchema: z.ZodObject<{
+    from: z.ZodNumber;
+    to: z.ZodNumber;
+    water_intake: z.ZodBoolean;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: number;
+    to: number;
+    description: string;
+    water_intake: boolean;
+}, {
+    from: number;
+    to: number;
+    description: string;
+    water_intake: boolean;
+}>;
+declare const WellSchema: z.ZodObject<{
+    well_type: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    well_driller: z.ZodOptional<z.ZodString>;
+    construction_date: z.ZodOptional<z.ZodString>;
+    lat: z.ZodOptional<z.ZodNumber>;
+    lng: z.ZodOptional<z.ZodNumber>;
+    elevation: z.ZodOptional<z.ZodNumber>;
+    obs: z.ZodOptional<z.ZodString>;
+    bore_hole: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        diameter: z.ZodNumber;
+        drilling_method: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        diameter: number;
+        drilling_method?: string | undefined;
+    }, {
+        from: number;
+        to: number;
+        diameter: number;
+        drilling_method?: string | undefined;
+    }>, "many">;
+    well_case: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        type: z.ZodString;
+        diameter: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+    }, {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+    }>, "many">;
+    reduction: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        diam_from: z.ZodNumber;
+        diam_to: z.ZodNumber;
+        type: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        type: string;
+        diam_from: number;
+        diam_to: number;
+    }, {
+        from: number;
+        to: number;
+        type: string;
+        diam_from: number;
+        diam_to: number;
+    }>, "many">;
+    well_screen: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        type: z.ZodString;
+        diameter: z.ZodNumber;
+        screen_slot_mm: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+        screen_slot_mm: number;
+    }, {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+        screen_slot_mm: number;
+    }>, "many">;
+    surface_case: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        diameter: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        diameter: number;
+    }, {
+        from: number;
+        to: number;
+        diameter: number;
+    }>, "many">;
+    hole_fill: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        type: z.ZodEnum<["gravel_pack", "seal"]>;
+        diameter: z.ZodNumber;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        diameter: number;
+        type: "gravel_pack" | "seal";
+        description: string;
+    }, {
+        from: number;
+        to: number;
+        diameter: number;
+        type: "gravel_pack" | "seal";
+        description: string;
+    }>, "many">;
+    cement_pad: z.ZodObject<{
+        type: z.ZodString;
+        width: z.ZodNumber;
+        thickness: z.ZodNumber;
+        length: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        length: number;
+        width: number;
+        thickness: number;
+    }, {
+        type: string;
+        length: number;
+        width: number;
+        thickness: number;
+    }>;
+    lithology: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        description: z.ZodString;
+        color: z.ZodString;
+        fgdc_texture: z.ZodString;
+        geologic_unit: z.ZodString;
+        aquifer_unit: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        description: string;
+        color: string;
+        fgdc_texture: string;
+        geologic_unit: string;
+        aquifer_unit: string;
+    }, {
+        from: number;
+        to: number;
+        description: string;
+        color: string;
+        fgdc_texture: string;
+        geologic_unit: string;
+        aquifer_unit: string;
+    }>, "many">;
+    fractures: z.ZodArray<z.ZodObject<{
+        depth: z.ZodNumber;
+        water_intake: z.ZodBoolean;
+        description: z.ZodString;
+        swarm: z.ZodBoolean;
+        azimuth: z.ZodNumber;
+        dip: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        depth: number;
+        water_intake: boolean;
+        swarm: boolean;
+        azimuth: number;
+        dip: number;
+    }, {
+        description: string;
+        depth: number;
+        water_intake: boolean;
+        swarm: boolean;
+        azimuth: number;
+        dip: number;
+    }>, "many">;
+    caves: z.ZodArray<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+        water_intake: z.ZodBoolean;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: number;
+        to: number;
+        description: string;
+        water_intake: boolean;
+    }, {
+        from: number;
+        to: number;
+        description: string;
+        water_intake: boolean;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    bore_hole: {
+        from: number;
+        to: number;
+        diameter: number;
+        drilling_method?: string | undefined;
+    }[];
+    well_case: {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+    }[];
+    reduction: {
+        from: number;
+        to: number;
+        type: string;
+        diam_from: number;
+        diam_to: number;
+    }[];
+    well_screen: {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+        screen_slot_mm: number;
+    }[];
+    surface_case: {
+        from: number;
+        to: number;
+        diameter: number;
+    }[];
+    hole_fill: {
+        from: number;
+        to: number;
+        diameter: number;
+        type: "gravel_pack" | "seal";
+        description: string;
+    }[];
+    cement_pad: {
+        type: string;
+        length: number;
+        width: number;
+        thickness: number;
+    };
+    lithology: {
+        from: number;
+        to: number;
+        description: string;
+        color: string;
+        fgdc_texture: string;
+        geologic_unit: string;
+        aquifer_unit: string;
+    }[];
+    fractures: {
+        description: string;
+        depth: number;
+        water_intake: boolean;
+        swarm: boolean;
+        azimuth: number;
+        dip: number;
+    }[];
+    caves: {
+        from: number;
+        to: number;
+        description: string;
+        water_intake: boolean;
+    }[];
+    well_type?: string | undefined;
+    name?: string | undefined;
+    well_driller?: string | undefined;
+    construction_date?: string | undefined;
+    lat?: number | undefined;
+    lng?: number | undefined;
+    elevation?: number | undefined;
+    obs?: string | undefined;
+}, {
+    bore_hole: {
+        from: number;
+        to: number;
+        diameter: number;
+        drilling_method?: string | undefined;
+    }[];
+    well_case: {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+    }[];
+    reduction: {
+        from: number;
+        to: number;
+        type: string;
+        diam_from: number;
+        diam_to: number;
+    }[];
+    well_screen: {
+        from: number;
+        to: number;
+        diameter: number;
+        type: string;
+        screen_slot_mm: number;
+    }[];
+    surface_case: {
+        from: number;
+        to: number;
+        diameter: number;
+    }[];
+    hole_fill: {
+        from: number;
+        to: number;
+        diameter: number;
+        type: "gravel_pack" | "seal";
+        description: string;
+    }[];
+    cement_pad: {
+        type: string;
+        length: number;
+        width: number;
+        thickness: number;
+    };
+    lithology: {
+        from: number;
+        to: number;
+        description: string;
+        color: string;
+        fgdc_texture: string;
+        geologic_unit: string;
+        aquifer_unit: string;
+    }[];
+    fractures: {
+        description: string;
+        depth: number;
+        water_intake: boolean;
+        swarm: boolean;
+        azimuth: number;
+        dip: number;
+    }[];
+    caves: {
+        from: number;
+        to: number;
+        description: string;
+        water_intake: boolean;
+    }[];
+    well_type?: string | undefined;
+    name?: string | undefined;
+    well_driller?: string | undefined;
+    construction_date?: string | undefined;
+    lat?: number | undefined;
+    lng?: number | undefined;
+    elevation?: number | undefined;
+    obs?: string | undefined;
+}>;
+declare function parseWell(json: string): Well;
+
+/**
+ * Serializes a {@link Well} object into a versioned JSON string suitable for
+ * storage or transmission.
+ *
+ * @param well - The well profile to serialize.
+ * @returns A JSON string containing the versioned well payload.
+ */
+declare function serializeWell(well: Well): string;
+/**
+ * Returns `true` when the well has no meaningful data — all constructive and
+ * geologic arrays are empty and no legacy nested structure is present.
+ *
+ * @param well - The well profile to check. Accepts `null` / `undefined`
+ *   (both treated as empty).
+ * @returns `true` if the well is considered empty, `false` otherwise.
+ */
+declare function isWellEmpty(well: Well | null | undefined): boolean;
+/**
+ * Parses a JSON string produced by {@link serializeWell} (or older legacy
+ * formats) and returns a normalized {@link Well} object.
+ *
+ * Handles:
+ * - Versioned format (v1)
+ * - Legacy format with `constructive` / `geologic` sub-objects
+ * - Legacy `diam_pol` inch diameters → `diameter` mm conversion
+ * - Typo `bole_hole` → `bore_hole` compatibility
+ *
+ * @param jsonString - Raw JSON string to parse.
+ * @returns A normalized {@link Well}, or `null` if the parsed data is empty.
+ * @throws {Error} If `jsonString` is not valid JSON.
+ * @throws {Error} If the `version` field is present but not supported.
+ */
+declare function deserializeWell(jsonString: string): Well | null;
+/** @deprecated Use {@link serializeWell} */
+declare const profileToWell: typeof serializeWell;
+/** @deprecated Use {@link isWellEmpty} */
+declare const checkIfProfileIsEmpty: typeof isWellEmpty;
+/** @deprecated Use {@link deserializeWell} */
+declare const convertProfileFromJSON: typeof deserializeWell;
+
+export { type BoreHole, BoreHoleSchema, type Cave, CaveSchema, type CementPad, CementPadSchema, type Constructive, type DiameterUnits, type Fracture, FractureSchema, type Geologic, type HoleFill, HoleFillSchema, type LengthUnits, type Lithology, LithologySchema, type Well as Profile, type Reduction, ReductionSchema, type SurfaceCase, SurfaceCaseSchema, type Units, type UnitsTypes, type Well, type WellCase, WellCaseSchema, WellSchema, type WellScreen, WellScreenSchema, checkIfProfileIsEmpty, convertProfileFromJSON, parseWell, profileToWell };