laterite 0.1.0

package/index.d.ts

@@ -0,0 +1,168 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * AGS spec type code → canonical category label (`"string"`, `"integer"`,
+ * `"decimal"`, `"datetime"`, `"date"`, `"time"`, `"bool"`, `"enum"`), or `null`
+ * for unknown codes (the TS wrapper re-raises as an error).
+ */
+export declare function canonicalType(agsType: string): string | null
+/**
+ * Presentation hint for a numeric AGS type: `"2DP"` → `"%.2f"`, `"3SF"` →
+ * `"%.3g"`, `"1SCI"` → `"%.1e"`; `null` for non-numeric / unknown codes.
+ */
+export declare function displayHint(agsType: string): string | null
+/**
+ * Parse an AGS4-shaped raw string into its canonical value — the same engine
+ * the read path uses. Permissive: empty / unparseable → `null`. Returns native
+ * JS: integer/decimal → number, bool → boolean, string/enum → string,
+ * **datetime/date/time → the canonical string** (`"YYYY-MM-DD HH:MM:SS"` /
+ * `"YYYY-MM-DD"` / `"HH:MM:SS"`), unknown code → the trimmed input.
+ */
+export declare function parseValue(raw: string | undefined | null, agsType: string): any
+/**
+ * Result of `transportPack` / `transportLock`: output size, ratio vs source,
+ * elapsed seconds.
+ */
+export interface PackStats {
+  bytes: bigint
+  ratio: number
+  elapsedS: number
+}
+/** Result of `transportUnpack` / `transportUnlock`: output size, elapsed seconds. */
+export interface UnpackStats {
+  bytes: bigint
+  elapsedS: number
+}
+/** zstd-compress `src` → `dest`. `level` is 1–22 (default 9, the AGS sweet spot). */
+export declare function transportPack(src: string, dest: string, level?: number | undefined | null): PackStats
+/** zstd-decompress `src` → `dest`. */
+export declare function transportUnpack(src: string, dest: string): UnpackStats
+/**
+ * zstd-compress, then age-encrypt with `password` → `dest`. Compress-then-
+ * encrypt is load-bearing: zstd needs low-entropy input; ciphertext is random.
+ */
+export declare function transportLock(src: string, dest: string, password: string, level?: number | undefined | null): PackStats
+/**
+ * age-decrypt with `password`, then zstd-decompress → `dest`. Wrong passphrase
+ * / non-passphrase envelopes surface as an error.
+ */
+export declare function transportUnlock(src: string, dest: string, password: string): UnpackStats
+/** The crate version. */
+export declare function version(): string
+/** Per-group schema — parallel arrays, one entry per heading. */
+export interface GroupMeta {
+  headings: Array<string>
+  units: Array<string>
+  /** AGS TYPE codes from the file's TYPE row (e.g. "2DP", "DT", "ID"). */
+  types: Array<string>
+  /**
+   * The SQL/DuckDB column type each heading lands as ("DOUBLE", "BIGINT",
+   * "TIMESTAMP", "VARCHAR", …).
+   */
+  sqlTypes: Array<string>
+  /** 1-indexed source line of each DATA row (parallel to the group's rows). */
+  lineNumbers: Array<number>
+}
+/**
+ * Parse an AGS4 file (`path`) or in-memory `text` into a `Reading` handle.
+ * `encoding`: `"utf-8"` (default) / `"windows-1252"` / a label. Throws the
+ * classified `kind␟code␟message` (see the error-protocol note) on bad input.
+ */
+export declare function parseArrow(path?: string | undefined | null, text?: string | undefined | null, encoding?: string | undefined | null): Reading
+/** One rule violation (omitting `severity` ⇒ error, matching the engine). */
+export interface Finding {
+  rule: string
+  line?: number
+  group: string
+  desc: string
+  severity?: string
+}
+/**
+ * The validation report — the Node mirror of laterite-py's `run_check` dict.
+ * `ok` is **false only for un-validatable input** (the TS `raiseFor` raises
+ * then); rule *violations* come back in `findings` with `ok:true`. `Report`'s
+ * `isValid` is the separate `count == 0`. `json`/`ndjson` are byte-identical
+ * to `ags4-check --json` / `--ndjson`.
+ */
+export interface ValidationReport {
+  ok: boolean
+  /**
+   * Set (with `error`) only when `ok` is false — the failure kind the TS
+   * `raiseFor` maps to an exception (`not_ags4`, `unsupported_edition`, …).
+   */
+  errorKind?: string
+  error?: string
+  /**
+   * Mirrors the `ags4-check` binary: 0 valid / 1 findings on success;
+   * 3 not-found/io, 4 not-utf8/not-ags4/bad-edition, 5 bad-dict on failure.
+   */
+  exitCode: number
+  file: string
+  dictVersion: string
+  resolution: string
+  count: number
+  findings: Array<Finding>
+  json: string
+  ndjson: string
+}
+/**
+ * Validate an AGS4 file (`path`) or `text` against the AGS4 rules. `dict_version`
+ * `None`/`"auto"` auto-detects from `TRAN_AGS`, else forces an edition. Returns
+ * the `{ok:false}` failure report (not a throw) for un-validatable input.
+ */
+export declare function runCheck(path?: string | undefined | null, text?: string | undefined | null, dictVersion?: string | undefined | null, includeWarnings?: boolean | undefined | null, includeFyi?: boolean | undefined | null, checkFiles?: boolean | undefined | null, encoding?: string | undefined | null): ValidationReport
+/**
+ * One group of columnar input — its code + an Arrow IPC stream (`Buffer`)
+ * whose column names are the AGS headings.
+ */
+export interface GroupIpc {
+  code: string
+  ipc: Buffer
+}
+/**
+ * The emit result. `bytes` is the AGS4 document; `findingsJson` is the
+ * validator's `{rule:[…]}` map on the output; `fixesApplied` counts safe fixes.
+ */
+export interface EmitResult {
+  bytes: Buffer
+  findingsJson: string
+  fixesApplied: number
+}
+/**
+ * Build valid AGS4 from per-group **Arrow IPC** streams (the columnar
+ * producer; the read boundary reversed). = `ags4-wasm`'s `to_ags4_ipc`.
+ */
+export declare function emitAgs4FromIpc(groups: Array<GroupIpc>, edition?: string | undefined | null, mode?: string | undefined | null): EmitResult
+/**
+ * A parsed AGS4 file held native-side — the Node analog of laterite-py's
+ * `Reading` handle (and `ags4-wasm`'s `ParsedDataset`). Each group's typed
+ * `RecordBatch` is built lazily on `tableIpc(code)` and dropped after the
+ * bytes are returned, so peak residency is one batch.
+ */
+export declare class Reading {
+  /** Group codes in file order (the order to load tables in). */
+  groupCodes(): Array<string>
+  /** The file's `TRAN_AGS` edition string, if present. */
+  get tranAgs(): string | null
+  /**
+   * `{headings, units, types, sqlTypes}` for one group, or `null` if the
+   * code isn't present. No Arrow built — cheap metadata only.
+   */
+  meta(code: string): GroupMeta | null
+  /**
+   * One group's rows as an Arrow **IPC stream** (`Buffer`), columns already
+   * correctly typed. The Node analog of the pyo3-arrow capsule: the typed
+   * columns come from the one shared emitter (`ags5_types::arrow_cols`), the
+   * SAME casting Python/wasm use — so a file types byte-identically across
+   * hosts. Returns `null` if the code isn't in the file.
+   */
+  tableIpc(code: string): Buffer | null
+  /**
+   * Re-emit byte-faithful AGS4 text from the retained parse (the raw DATA
+   * values, unchanged). = laterite-py's `Reading::emit`.
+   */
+  emit(): string
+}

package/index.js

@@ -0,0 +1,326 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'laterite-node.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.android-arm64.node')
+          } else {
+            nativeBinding = require('@laterite/native-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'laterite-node.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@laterite/native-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'laterite-node.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@laterite/native-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'laterite-node.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@laterite/native-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'laterite-node.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@laterite/native-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'laterite-node.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./laterite-node.darwin-universal.node')
+      } else {
+        nativeBinding = require('@laterite/native-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'laterite-node.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.darwin-x64.node')
+          } else {
+            nativeBinding = require('@laterite/native-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'laterite-node.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@laterite/native-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'laterite-node.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./laterite-node.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@laterite/native-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'laterite-node.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./laterite-node.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@laterite/native-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'laterite-node.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./laterite-node.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@laterite/native-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { canonicalType, displayHint, parseValue, transportPack, transportUnpack, transportLock, transportUnlock, version, Reading, parseArrow, runCheck, emitAgs4FromIpc } = nativeBinding
+
+module.exports.canonicalType = canonicalType
+module.exports.displayHint = displayHint
+module.exports.parseValue = parseValue
+module.exports.transportPack = transportPack
+module.exports.transportUnpack = transportUnpack
+module.exports.transportLock = transportLock
+module.exports.transportUnlock = transportUnlock
+module.exports.version = version
+module.exports.Reading = Reading
+module.exports.parseArrow = parseArrow
+module.exports.runCheck = runCheck
+module.exports.emitAgs4FromIpc = emitAgs4FromIpc

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "laterite",
+  "version": "0.1.0",
+  "description": "AGS4 geotechnical data for Node.js — read, validate, produce, and query (the Node port of the laterite Python toolkit, Rust-backed).",
+  "license": "MIT",
+  "author": "niko86",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niko86/laterite.git",
+    "directory": "rust-packages/laterite-node"
+  },
+  "homepage": "https://github.com/niko86/laterite#readme",
+  "keywords": [
+    "ags4",
+    "ags",
+    "geotechnical",
+    "validator",
+    "arrow",
+    "napi",
+    "rust"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#native": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "napi": {
+    "name": "laterite-node",
+    "package": {
+      "name": "@laterite/native"
+    },
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-apple-darwin",
+        "x86_64-pc-windows-msvc"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "napi build --platform --release && npm run build:ts",
+    "build:debug": "napi build --platform && npm run build:ts",
+    "build:ts": "tsup",
+    "artifacts": "napi artifacts",
+    "smoke:pack": "node tools/pack-smoke.mjs",
+    "prepublish:napi": "napi prepublish -t npm --skip-gh-release",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "apache-arrow": "^21.1.0"
+  },
+  "optionalDependencies": {
+    "@laterite/native-linux-x64-gnu": "0.1.0",
+    "@laterite/native-darwin-arm64": "0.1.0",
+    "@laterite/native-win32-x64-msvc": "0.1.0"
+  },
+  "peerDependencies": {
+    "@duckdb/node-api": ">=1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@duckdb/node-api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@duckdb/node-api": "^1.5.3-r.3",
+    "@napi-rs/cli": "^2.18.4",
+    "@types/node": "^25.9.3",
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}