@crewhaus/tool-data 0.7.0

package/dist/lib/json.js

@@ -0,0 +1,133 @@
+/**
+ * The JSON primitives everything else in this package is built on: a value
+ * model, structural equality, a stable (key-sorted) serializer, and a
+ * content hash.
+ *
+ * Stability is the point. Two harness runs that produce the same data must
+ * produce the same bytes, or every downstream diff is noise.
+ */
+/** A plain object, as distinct from an array or a primitive. */
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Structural equality over JSON values. Key order is irrelevant; NaN never appears in JSON. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEqual(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        for (const k of ak) {
+            if (!Object.hasOwn(b, k))
+                return false;
+            if (!deepEqual(a[k], b[k]))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}
+/** A structured clone that only has to handle JSON shapes, so no cycles exist. */
+export function deepClone(value) {
+    if (Array.isArray(value))
+        return value.map((v) => deepClone(v));
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const k of Object.keys(value))
+            out[k] = deepClone(value[k]);
+        return out;
+    }
+    return value;
+}
+/**
+ * Serialize with object keys in sorted order at every depth, so that two
+ * equal values always produce identical bytes. Array order is data and is
+ * never touched.
+ *
+ * One caveat worth knowing rather than discovering: `JSON.stringify` emits
+ * an object's integer-like keys first, in ascending numeric order, whatever
+ * order they sit in. So `{"10":a,"2":b,"x":c}` serializes as `2, 10, x`, not
+ * the code-unit order `10, 2, x` that `sortKeysDeep` puts them in. The
+ * result is still canonical — two equal values still produce identical bytes
+ * — but it is not literally sorted for those keys.
+ *
+ * `indent` of 0 gives the compact form.
+ */
+export function canonicalStringify(value, indent = 0) {
+    return JSON.stringify(sortKeysDeep(value), null, indent);
+}
+/** Recursively rebuild objects with their keys in code-unit sorted order. */
+export function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const k of Object.keys(value).sort())
+            out[k] = sortKeysDeep(value[k]);
+        return out;
+    }
+    return value;
+}
+const UTF8 = new TextEncoder();
+/**
+ * FNV-1a, 64 bits, over the UTF-8 bytes of `text` — the algorithm exactly as
+ * Fowler/Noll/Vo define it, so the reference vectors hold: `""` hashes to
+ * `cbf29ce484222325`, `"a"` to `af63dc4c8601ec8c` and `"foobar"` to
+ * `85944171f73967e8`. `lib.test.ts` pins all three.
+ *
+ * It is a content fingerprint, not a cryptographic digest — never use it
+ * where collision resistance against an adversary matters.
+ */
+export function fnv1a64(text) {
+    const prime = 1099511628211n;
+    const mask = 0xffffffffffffffffn;
+    let hash = 14695981039346656037n;
+    // UTF-8 bytes, so the hash is over the encoding the vectors are defined on
+    // rather than over JavaScript's UTF-16 code units.
+    for (const byte of UTF8.encode(text)) {
+        hash ^= BigInt(byte);
+        hash = (hash * prime) & mask;
+    }
+    return hash.toString(16).padStart(16, "0");
+}
+/**
+ * A 64-bit FNV-1a hash of the canonical serialization, rendered as 16 hex
+ * characters. Two values that are `deepEqual` always hash the same, because
+ * the serialization sorts keys first.
+ *
+ * Use it as a fingerprint a caller can compare or record. Do not use it as
+ * an identity key inside this package: 64 bits collide, and the canonical
+ * string it is computed from is right there and is exact, which is what
+ * `totalCompare`, `aggregate`, `joinRecords` and `dedupeRecords` key on.
+ */
+export function stableHash(value) {
+    return fnv1a64(canonicalStringify(value));
+}
+/** Parse JSON, converting the engine's error into a caller-readable message. */
+export function parseJson(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+/** A short, human-readable type name used in diffs and error messages. */
+export function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

package/dist/lib/jsonl.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Line-delimited JSON. One value per line, which is what log shippers,
+ * dataset files and streaming APIs emit.
+ *
+ * Reading is tolerant where tolerance is safe — a trailing newline, blank
+ * lines, CRLF endings, and a byte-order mark are all fine — and strict where
+ * it is not: a line that does not parse is reported with its 1-based line
+ * number and the parser's message, never dropped in silence.
+ */
+export type JsonlRecord = {
+    line: number;
+    value: unknown;
+};
+export type JsonlFailure = {
+    line: number;
+    error: string;
+    preview: string;
+};
+export type JsonlParseResult = {
+    records: JsonlRecord[];
+    failures: JsonlFailure[];
+    truncated: boolean;
+};
+/**
+ * Parse JSONL. `maxRecords` bounds the result; `stopOnError` makes the first
+ * bad line end the parse, which is what a caller wants when the file is a
+ * transaction log rather than a best-effort sample.
+ */
+export declare function parseJsonl(text: string, maxRecords: number, stopOnError: boolean): JsonlParseResult;
+/**
+ * Serialize values as JSONL. A value containing a literal newline is still
+ * safe, because `JSON.stringify` escapes it — that is the property the
+ * format relies on. `undefined` entries are skipped and counted, since
+ * `JSON.stringify(undefined)` is not a value at all.
+ */
+export declare function writeJsonl(values: ReadonlyArray<unknown>, trailingNewline: boolean): {
+    text: string;
+    skipped: number;
+};

package/dist/lib/jsonl.js

@@ -0,0 +1,63 @@
+/**
+ * Line-delimited JSON. One value per line, which is what log shippers,
+ * dataset files and streaming APIs emit.
+ *
+ * Reading is tolerant where tolerance is safe — a trailing newline, blank
+ * lines, CRLF endings, and a byte-order mark are all fine — and strict where
+ * it is not: a line that does not parse is reported with its 1-based line
+ * number and the parser's message, never dropped in silence.
+ */
+/**
+ * Parse JSONL. `maxRecords` bounds the result; `stopOnError` makes the first
+ * bad line end the parse, which is what a caller wants when the file is a
+ * transaction log rather than a best-effort sample.
+ */
+export function parseJsonl(text, maxRecords, stopOnError) {
+    const src = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const lines = src.split("\n");
+    const records = [];
+    const failures = [];
+    let truncated = false;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i].replace(/\r$/, "");
+        if (raw.trim() === "")
+            continue;
+        if (records.length >= maxRecords) {
+            truncated = true;
+            break;
+        }
+        try {
+            records.push({ line: i + 1, value: JSON.parse(raw) });
+        }
+        catch (err) {
+            failures.push({
+                line: i + 1,
+                error: err.message,
+                preview: raw.length > 120 ? `${raw.slice(0, 120)}…` : raw,
+            });
+            if (stopOnError)
+                break;
+        }
+    }
+    return { records, failures, truncated };
+}
+/**
+ * Serialize values as JSONL. A value containing a literal newline is still
+ * safe, because `JSON.stringify` escapes it — that is the property the
+ * format relies on. `undefined` entries are skipped and counted, since
+ * `JSON.stringify(undefined)` is not a value at all.
+ */
+export function writeJsonl(values, trailingNewline) {
+    const lines = [];
+    let skipped = 0;
+    for (const value of values) {
+        const text = JSON.stringify(value);
+        if (text === undefined) {
+            skipped += 1;
+            continue;
+        }
+        lines.push(text);
+    }
+    const body = lines.join("\n");
+    return { text: trailingNewline && body !== "" ? `${body}\n` : body, skipped };
+}

package/dist/lib/jsonpath.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A small JSONPath-like query language, implemented here rather than taken
+ * from a dependency so its grammar is exactly what is documented and nothing
+ * more.
+ *
+ * ## Supported grammar
+ *
+ * ```
+ * path      := "$"? step*
+ * step      := "." name
+ *            | ".." name            recursive descent to every `name` at any depth
+ *            | ".." "*"             every node at any depth
+ *            | "." "*"  |  "[*]"    every element of an array / every value of an object
+ *            | "[" index "]"        integer, negative counts from the end
+ *            | "[" slice "]"        start:end  or  start:end:step  (Python semantics)
+ *            | "[" quoted "]"       'key' or "key" — for keys with dots or spaces
+ *            | "[?(" filter ")]"    keep array elements / object values matching filter
+ * filter    := "@" ("." name)*  (op literal)?
+ * op        := == | != | < | <= | > | >= | =~
+ * literal   := number | 'string' | "string" | true | false | null
+ * ```
+ *
+ * A filter with no operator is an existence test: `[?(@.email)]` keeps
+ * elements whose `email` is defined and neither null nor false. `=~` matches
+ * the string form of the field against a JavaScript regular expression
+ * source (no flags).
+ *
+ * ## Deliberately not supported
+ *
+ * Unions (`['a','b']`), script expressions beyond the filter grammar above,
+ * `length()` and other functions, parent axes, and boolean combinators
+ * (`&&`, `||`) inside a filter. Chain two filter steps instead of using
+ * `&&`. Anything unsupported raises a parse error naming the offending
+ * position, never a silent empty result.
+ */
+export type PathStep = {
+    kind: "child";
+    name: string;
+} | {
+    kind: "descend";
+    name: string | null;
+} | {
+    kind: "wildcard";
+} | {
+    kind: "index";
+    index: number;
+} | {
+    kind: "slice";
+    start: number | null;
+    end: number | null;
+    step: number;
+} | {
+    kind: "filter";
+    field: string[];
+    op: FilterOp | null;
+    literal: unknown;
+};
+export type FilterOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "=~";
+export declare class PathError extends Error {
+}
+/** Parse a path expression into steps, or throw a `PathError` saying where it broke. */
+export declare function parsePath(expr: string): PathStep[];
+/** One result of a query: the value, plus the normalized path that reaches it. */
+export type PathMatch = {
+    path: string;
+    value: unknown;
+};
+/**
+ * One step of a match's location. A number is an array index, a string is an
+ * object key — the distinction has to be carried, because an object may have
+ * the key `"0"` and rendering that as `[0]` would produce a path that reads
+ * back as an array index and matches nothing.
+ */
+export type PathSegment = string | number;
+/** Run a parsed path over a value, returning matches in document order. */
+export declare function queryPath(root: unknown, steps: ReadonlyArray<PathStep>, limit: number): {
+    matches: PathMatch[];
+    truncated: boolean;
+};
+/** Python slice semantics, including negative bounds and a negative step. */
+export declare function sliceIndices(length: number, start: number | null, end: number | null, step: number): number[];
+/**
+ * Render a path as `$.a[0]["odd key"]` — readable, and re-parseable by
+ * `parsePath` into a path that reaches the same node in the same document.
+ *
+ * A numeric *segment* is only written as `[0]` when it really is an array
+ * index. An object key that happens to look numeric is written `["0"]`,
+ * because `[0]` only ever matches an array and the round trip would
+ * otherwise silently return nothing.
+ */
+export declare function renderPath(segments: ReadonlyArray<PathSegment>): string;