@pith-hash/pith-unicode 0.0.0 → 0.1.0

package/index.js

@@ -1 +1,288 @@
-module.exports = {};
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 pith-hash
+"use strict";
+
+/**
+ * pith-unicode SDK: Unicode NFC/NFD normalisation through koffi.
+ *
+ * Every function validates its input as UTF-8 inside the Rust core and
+ * returns a fresh Buffer — the handed-out cdylib buffer is copied and
+ * released before returning. Invalid UTF-8 throws an `FfiError` with
+ * `status === -2`; it is never a crash.
+ */
+
+const koffi = require("koffi");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const STATUS_OK = 0;
+const STATUS_INVALID = -1;
+const STATUS_REJECTED = -2;
+
+/** Normalization form codes (UAX #15), the FFI `form` argument encoding. */
+const FORM_NFC = 1;
+const FORM_NFD = 2;
+const FORM_NFKC = 3;
+const FORM_NFKD = 4;
+
+/** Accepted spellings of a normalization form: the codes above or their names. */
+const NORMALIZATION_FORMS = { NFC: FORM_NFC, NFD: FORM_NFD, NFKC: FORM_NFKC, NFKD: FORM_NFKD };
+
+/** Every cdylib file name cargo may drop into the build directory, per platform. */
+const CDYLIB_NAMES = ["pith_unicode.dll", "libpith_unicode.so", "libpith_unicode.dylib"];
+
+const PKG_ROOT = path.join(__dirname);
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+
+/** Backs the data pointer for empty inputs: the FFI contract treats a
+ * NULL data pointer as a caller bug (status -1), so an empty Buffer
+ * must hand over a valid non-null pointer that reads as zero bytes. */
+const EMPTY_SCRATCH = Buffer.alloc(1);
+
+/** FfiError: a non-zero status code came back from the cdylib. */
+class FfiError extends Error {
+  /**
+   * @param {string} op the FFI operation name
+   * @param {number} status the raw status code
+   */
+  constructor(op, status) {
+    const kind = { [STATUS_INVALID]: "invalid argument", [STATUS_REJECTED]: "input rejected" }[status] ?? "unknown failure";
+    super(`${op} failed: ${kind} (status ${status})`);
+    this.name = "FfiError";
+    /** The raw status code the FFI returned. */
+    this.status = status;
+  }
+}
+
+/**
+ * Locates the cdylib through the suite's discovery chain.
+ * @returns {string} an absolute path to the cdylib file
+ * @throws {Error} when nothing is found
+ */
+function findCdylib() {
+  const explicit = process.env.PITH_CDYLIB;
+  if (explicit && fs.statSync(explicit, { throwIfNoEntry: false })?.isFile()) {
+    return path.resolve(explicit);
+  }
+  /** @type {string[]} */
+  const dirs = [];
+  const envDir = process.env.PITH_CDYLIB_DIR;
+  if (envDir) {
+    dirs.push(envDir);
+    if (!path.isAbsolute(envDir)) {
+      dirs.push(path.join(REPO_ROOT, envDir));
+    }
+  }
+  const osArch = `${process.platform}-${process.arch}`;
+  dirs.push(path.join(PKG_ROOT, "prebuilds", osArch));
+  dirs.push(path.join(PKG_ROOT, "prebuilds"));
+  dirs.push(path.join(REPO_ROOT, "target", "release"));
+  for (const dir of dirs) {
+    for (const name of CDYLIB_NAMES) {
+      const p = path.join(dir, name);
+      if (fs.statSync(p, { throwIfNoEntry: false })?.isFile()) return p;
+    }
+  }
+  throw new Error(
+    "no pith-unicode cdylib found (searched PITH_CDYLIB, PITH_CDYLIB_DIR, prebuilds/ and <repo>/target/release); " +
+      "run `cargo build --release` first",
+  );
+}
+
+let cached = undefined;
+
+/**
+ * Loads the cdylib and binds the exported symbols (lazily, once).
+ * Exported so the null-pointer refusal tests can drive the raw
+ * binding with a null data pointer.
+ *
+ * @returns {{nfc: Function, nfd: Function, free: Function}}
+ */
+function loadLibrary() {
+  if (cached) return cached;
+  const lib = koffi.load(findCdylib());
+  // One shared prototype shape: nfc, nfd, nfkc, nfkd and both folds have
+  // identical C signatures.
+  const bind = (name) =>
+    lib.func(name, "int32_t", [
+      "const uint8_t *",
+      "size_t",
+      koffi.out(koffi.pointer("void *")),
+      koffi.out(koffi.pointer("size_t")),
+    ]);
+  const nfc = bind("pith_unicode_nfc");
+  const nfd = bind("pith_unicode_nfd");
+  const nfkc = bind("pith_unicode_nfkc");
+  const nfkd = bind("pith_unicode_nfkd");
+  const casefold = bind("pith_unicode_casefold");
+  const casefoldSimple = bind("pith_unicode_casefold_simple");
+  const free = lib.func("void pith_unicode_free(void *ptr, size_t len)");
+  const isNormalized = lib.func("pith_unicode_is_normalized", "int32_t", [
+    "uint32_t", // normalization form code
+    "const uint8_t *", // data
+    "size_t", // len
+    koffi.out(koffi.pointer("uint8_t")), // the 0/1 answer
+  ]);
+  cached = { nfc, nfd, nfkc, nfkd, casefold, casefoldSimple, free, isNormalized };
+  return cached;
+}
+
+/** Resolves a normalization form given as a code or name.
+ *
+ * @param {number|string} form the form code (FORM_NFC…) or name ("NFC"…)
+ * @returns {number} the FFI form code
+ */
+function formCode(form) {
+  if (typeof form === "string") {
+    const code = NORMALIZATION_FORMS[form.toUpperCase()];
+    if (code === undefined) {
+      throw new TypeError(`unknown normalization form ${form}`);
+    }
+    return code;
+  }
+  if (Object.values(NORMALIZATION_FORMS).includes(form)) {
+    return form;
+  }
+  throw new TypeError(`unknown normalization form code ${form}`);
+}
+
+/** The loadLibrary() key of each form's buffer op. */
+const FORM_KEYS = { [FORM_NFC]: "nfc", [FORM_NFD]: "nfd", [FORM_NFKC]: "nfkc", [FORM_NFKD]: "nfkd" };
+
+/** Runs one buffer-handed-out op and copies the handed-out cdylib buffer
+ * into a fresh Buffer before releasing it.
+ *
+ * @param {string} key the loadLibrary() binding key (for errors)
+ * @param {Buffer} data the UTF-8 bytes to transform
+ * @returns {Buffer} the transformed UTF-8 bytes
+ * @throws {FfiError} with `status === -2` for bytes that are not valid UTF-8
+ */
+function bufferOp(key, data) {
+  if (!Buffer.isBuffer(data)) {
+    throw new TypeError("data must be a Buffer");
+  }
+  const lib = loadLibrary();
+  const op = lib[key];
+  const out = [null];
+  const outLen = [0];
+  // koffi hands a NULL pointer for a zero-length Buffer, but the FFI
+  // contract treats NULL as a caller bug (status -1); empty input must
+  // read as zero bytes off a valid non-null pointer instead.
+  const ptr = data.length > 0 ? data : EMPTY_SCRATCH;
+  const status = op(ptr, data.length, out, outLen);
+  if (status !== STATUS_OK) {
+    throw new FfiError(key, status);
+  }
+  try {
+    // koffi.decode hands back a Uint8Array view over the external
+    // buffer; copy it into a Buffer before the cdylib buffer is freed.
+    return Buffer.from(koffi.decode(out[0], "uint8_t", Number(outLen[0])));
+  } finally {
+    lib.free(out[0], Number(outLen[0]));
+  }
+}
+
+/**
+ * Normalizes `data` to Unicode Normalization Form C (canonical
+ * composition) and returns the UTF-8 result as a fresh Buffer.
+ *
+ * @param {Buffer} data the UTF-8 bytes to normalize
+ * @returns {Buffer} the NFC-normalized bytes (empty in → empty out)
+ * @throws {FfiError} with `status === -2` for invalid UTF-8
+ */
+function nfc(data) {
+  return bufferOp("nfc", data);
+}
+
+/**
+ * Normalizes `data` to Unicode Normalization Form D (canonical
+ * decomposition), with the same contract as `nfc`.
+ */
+function nfd(data) {
+  return bufferOp("nfd", data);
+}
+
+/**
+ * Normalizes `data` to Unicode Normalization Form KC (compatibility
+ * composition), with the same contract as `nfc`.
+ */
+function nfkc(data) {
+  return bufferOp("nfkc", data);
+}
+
+/**
+ * Normalizes `data` to Unicode Normalization Form KD (compatibility
+ * decomposition), with the same contract as `nfc`.
+ */
+function nfkd(data) {
+  return bufferOp("nfkd", data);
+}
+
+/**
+ * Normalizes `data` to `form` — a NORMALIZATION_FORMS name ("NFC", "NFD",
+ * "NFKC", "NFKD", any case) or one of the FORM_NFC…FORM_NFKD codes — with
+ * the same contract as `nfc`.
+ */
+function normalize(form, data) {
+  return bufferOp(FORM_KEYS[formCode(form)], data);
+}
+
+/**
+ * Answers whether `data` is already in normalization `form` — the exact
+ * UAX #15 quick-check answer, never a pessimistic approximation.
+ *
+ * @throws {TypeError} for an unknown form
+ * @throws {FfiError} with `status === -2` for invalid UTF-8
+ */
+function isNormalized(form, data) {
+  if (!Buffer.isBuffer(data)) {
+    throw new TypeError("data must be a Buffer");
+  }
+  const lib = loadLibrary();
+  const out = [0xff];
+  const status = lib.isNormalized(formCode(form), data.length > 0 ? data : EMPTY_SCRATCH, data.length, out);
+  if (status !== STATUS_OK) {
+    throw new FfiError("pith_unicode_is_normalized", status);
+  }
+  return out[0] === 1;
+}
+
+/**
+ * Folds `data` to its full case folding (UAX #44 statuses `C` and `F`;
+ * mappings may expand, e.g. ß → ss). The Turkic `T` entries are locale
+ * data and are not applied. Same contract as `nfc`.
+ */
+function casefold(data) {
+  return bufferOp("casefold", data);
+}
+
+/**
+ * Folds `data` to its simple case folding (statuses `C` and `S`): a
+ * strict one-to-one mapping (ẞ → ß, ß → itself).
+ */
+function casefoldSimple(data) {
+  return bufferOp("casefoldSimple", data);
+}
+
+module.exports = {
+  STATUS_OK,
+  STATUS_INVALID,
+  STATUS_REJECTED,
+  CDYLIB_NAMES,
+  FORM_NFC,
+  FORM_NFD,
+  FORM_NFKC,
+  FORM_NFKD,
+  NORMALIZATION_FORMS,
+  FfiError,
+  findCdylib,
+  loadLibrary,
+  nfc,
+  nfd,
+  nfkc,
+  nfkd,
+  normalize,
+  isNormalized,
+  casefold,
+  casefoldSimple,
+};

package/package.json

@@ -1,14 +1,33 @@
-{
-  "name": "@pith-hash/pith-unicode",
-  "version": "0.0.0",
-  "description": "pith SDK placeholder - real artifacts published by CI",
-  "license": "MIT",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/pith-hash/pith-unicode.git"
-  }
-}
+{
+  "name": "@pith-hash/pith-unicode",
+  "version": "0.1.0",
+  "description": "Unicode NFC/NFD normalisation SDK via the pith-unicode Rust cdylib (koffi, prebuilt)",
+  "license": "MIT",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "prebuilds/",
+    "reference.json"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "koffi": "^2.12.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pith-hash/pith-unicode.git",
+    "directory": "sdk/node"
+  },
+  "keywords": [
+    "unicode",
+    "nfc",
+    "nfd",
+    "normalization",
+    "hashing"
+  ]
+}