@crewhaus/tool-data 0.7.0

package/dist/lib/patch.js

@@ -0,0 +1,272 @@
+/**
+ * JSON Pointer (RFC 6901), JSON Patch (RFC 6902) and JSON Merge Patch
+ * (RFC 7386).
+ *
+ * All three are implemented in full. Patching is transactional: the document
+ * is cloned, every operation is applied in order, and a failure anywhere
+ * leaves the caller's input untouched and reports which operation index
+ * failed — which is the behaviour RFC 6902 §5 requires.
+ */
+import { deepClone, deepEqual, isPlainObject } from "./json";
+export class PatchError extends Error {
+    opIndex;
+    constructor(message, opIndex) {
+        super(message);
+        this.opIndex = opIndex;
+    }
+}
+/** Decode one JSON Pointer reference token: `~1` is `/`, `~0` is `~`. */
+export function unescapeToken(token) {
+    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/** Encode one reference token for embedding in a pointer. */
+export function escapeToken(token) {
+    return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/** Split a JSON Pointer into its decoded tokens. `""` is the whole document. */
+export function parsePointer(pointer) {
+    if (pointer === "")
+        return [];
+    if (!pointer.startsWith("/")) {
+        throw new Error(`JSON Pointer must be empty or start with '/', got ${JSON.stringify(pointer)}`);
+    }
+    return pointer.slice(1).split("/").map(unescapeToken);
+}
+/** Build a pointer from already-decoded tokens. */
+export function formatPointer(tokens) {
+    return tokens.map((t) => `/${escapeToken(t)}`).join("");
+}
+/** Resolve a pointer, returning `{ found: false }` rather than throwing when it misses. */
+export function resolvePointer(doc, pointer) {
+    let tokens;
+    try {
+        tokens = parsePointer(pointer);
+    }
+    catch (err) {
+        return { found: false, reason: err.message };
+    }
+    let cur = doc;
+    for (const token of tokens) {
+        if (Array.isArray(cur)) {
+            if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+                return { found: false, reason: `"${token}" is not an array index` };
+            }
+            const i = Number(token);
+            if (i >= cur.length)
+                return { found: false, reason: `index ${i} is past the end` };
+            cur = cur[i];
+            continue;
+        }
+        if (isPlainObject(cur)) {
+            if (!Object.hasOwn(cur, token))
+                return { found: false, reason: `no member "${token}"` };
+            cur = cur[token];
+            continue;
+        }
+        return { found: false, reason: `cannot descend into a ${cur === null ? "null" : typeof cur}` };
+    }
+    return { found: true, value: cur };
+}
+/**
+ * The container that holds a pointer's final token, plus that token.
+ *
+ * A syntactically invalid pointer is the caller's mistake, so it comes back
+ * as a `PatchError` carrying the operation index — the same shape every
+ * other failure here has — rather than as the bare `Error` `parsePointer`
+ * raises, which would escape the tool as a crash.
+ */
+function locateParent(doc, pointer, opIndex) {
+    let tokens;
+    try {
+        tokens = parsePointer(pointer);
+    }
+    catch (err) {
+        throw new PatchError(err.message, opIndex);
+    }
+    if (tokens.length === 0)
+        throw new PatchError("cannot address the root's parent", opIndex);
+    const parentPointer = formatPointer(tokens.slice(0, -1));
+    const found = resolvePointer(doc, parentPointer);
+    if (!found.found) {
+        throw new PatchError(`path "${pointer}" does not exist: ${found.reason}`, opIndex);
+    }
+    return { parent: found.value, token: tokens[tokens.length - 1] };
+}
+function addAt(parent, token, value, pointer, i) {
+    if (Array.isArray(parent)) {
+        if (token === "-") {
+            parent.push(value);
+            return;
+        }
+        if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+            throw new PatchError(`"${token}" is not an array index in "${pointer}"`, i);
+        }
+        const idx = Number(token);
+        if (idx > parent.length) {
+            throw new PatchError(`index ${idx} is past the end of the array in "${pointer}"`, i);
+        }
+        parent.splice(idx, 0, value);
+        return;
+    }
+    if (isPlainObject(parent)) {
+        parent[token] = value;
+        return;
+    }
+    throw new PatchError(`cannot add to a ${typeof parent} at "${pointer}"`, i);
+}
+function removeAt(parent, token, pointer, i) {
+    if (Array.isArray(parent)) {
+        if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+            throw new PatchError(`"${token}" is not an array index in "${pointer}"`, i);
+        }
+        const idx = Number(token);
+        if (idx >= parent.length) {
+            throw new PatchError(`index ${idx} is past the end of the array in "${pointer}"`, i);
+        }
+        return parent.splice(idx, 1)[0];
+    }
+    if (isPlainObject(parent)) {
+        if (!Object.hasOwn(parent, token)) {
+            throw new PatchError(`no member "${token}" to remove at "${pointer}"`, i);
+        }
+        const old = parent[token];
+        delete parent[token];
+        return old;
+    }
+    throw new PatchError(`cannot remove from a ${typeof parent} at "${pointer}"`, i);
+}
+/**
+ * Apply an RFC 6902 patch. Returns the new document; the input is never
+ * mutated. Throws `PatchError` (carrying the failing operation's index) if
+ * any operation cannot be applied, leaving nothing half-done.
+ */
+export function applyJsonPatch(doc, ops) {
+    let working = deepClone(doc);
+    ops.forEach((op, i) => {
+        switch (op.op) {
+            case "test": {
+                const found = resolvePointer(working, op.path);
+                if (!found.found)
+                    throw new PatchError(`test failed: "${op.path}" ${found.reason}`, i);
+                if (!deepEqual(found.value, op.value)) {
+                    throw new PatchError(`test failed: "${op.path}" is not the expected value`, i);
+                }
+                return;
+            }
+            case "add": {
+                if (op.path === "") {
+                    working = deepClone(op.value);
+                    return;
+                }
+                const { parent, token } = locateParent(working, op.path, i);
+                addAt(parent, token, deepClone(op.value), op.path, i);
+                return;
+            }
+            case "remove": {
+                if (op.path === "")
+                    throw new PatchError("cannot remove the whole document", i);
+                const { parent, token } = locateParent(working, op.path, i);
+                removeAt(parent, token, op.path, i);
+                return;
+            }
+            case "replace": {
+                if (op.path === "") {
+                    working = deepClone(op.value);
+                    return;
+                }
+                const existing = resolvePointer(working, op.path);
+                if (!existing.found) {
+                    throw new PatchError(`cannot replace "${op.path}": ${existing.reason}`, i);
+                }
+                const { parent, token } = locateParent(working, op.path, i);
+                removeAt(parent, token, op.path, i);
+                addAt(parent, token, deepClone(op.value), op.path, i);
+                return;
+            }
+            case "move": {
+                if (op.path.startsWith(`${op.from}/`)) {
+                    throw new PatchError(`cannot move "${op.from}" into its own child "${op.path}"`, i);
+                }
+                // RFC 6902 §4.4: the "from" location MUST exist, and that holds even
+                // when it equals "path". Taking the no-op shortcut first would let a
+                // move of something that is not there report success.
+                const src = resolvePointer(working, op.from);
+                if (!src.found)
+                    throw new PatchError(`cannot move from "${op.from}": ${src.reason}`, i);
+                if (op.path === op.from)
+                    return;
+                const from = locateParent(working, op.from, i);
+                const moved = removeAt(from.parent, from.token, op.from, i);
+                if (op.path === "") {
+                    working = moved;
+                    return;
+                }
+                const dst = locateParent(working, op.path, i);
+                addAt(dst.parent, dst.token, moved, op.path, i);
+                return;
+            }
+            case "copy": {
+                const src = resolvePointer(working, op.from);
+                if (!src.found)
+                    throw new PatchError(`cannot copy from "${op.from}": ${src.reason}`, i);
+                if (op.path === "") {
+                    working = deepClone(src.value);
+                    return;
+                }
+                const dst = locateParent(working, op.path, i);
+                addAt(dst.parent, dst.token, deepClone(src.value), op.path, i);
+                return;
+            }
+            default: {
+                const bad = op;
+                throw new PatchError(`unknown operation ${JSON.stringify(bad.op)}`, i);
+            }
+        }
+    });
+    return working;
+}
+/**
+ * Apply an RFC 7386 merge patch: an object merges key by key, `null` deletes
+ * a key, and any non-object patch replaces the target outright. Arrays are
+ * replaced whole — that is the RFC's behaviour, not a shortcut here.
+ */
+export function applyMergePatch(target, patch) {
+    if (!isPlainObject(patch))
+        return deepClone(patch);
+    const base = isPlainObject(target)
+        ? deepClone(target)
+        : {};
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === null)
+            delete base[key];
+        else
+            base[key] = applyMergePatch(base[key], value);
+    }
+    return base;
+}
+/**
+ * Derive the RFC 7386 merge patch that turns `from` into `to`. Returns the
+ * smallest object that does so; `null` entries mark deletions. Where either
+ * side is not an object the result is `to` itself, since a merge patch
+ * cannot express a partial array or scalar change.
+ */
+export function diffMergePatch(from, to) {
+    if (!isPlainObject(from) || !isPlainObject(to))
+        return deepClone(to);
+    const out = {};
+    for (const key of Object.keys(to)) {
+        if (!Object.hasOwn(from, key)) {
+            out[key] = deepClone(to[key]);
+            continue;
+        }
+        if (deepEqual(from[key], to[key]))
+            continue;
+        out[key] = diffMergePatch(from[key], to[key]);
+    }
+    for (const key of Object.keys(from)) {
+        if (!Object.hasOwn(to, key))
+            out[key] = null;
+    }
+    return out;
+}

package/dist/lib/table.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Operations over an array of records — the shape almost every API response,
+ * CSV file and query result arrives in.
+ *
+ * Field references are dotted paths (`user.name`), so nested records work
+ * without flattening them first. Ordering is always total and stable: where
+ * two rows compare equal the original order is kept, so the same input gives
+ * the same output every time.
+ */
+export type Record_ = Record<string, unknown>;
+/** Read a dotted path out of a record. Returns undefined for any miss. */
+export declare function getPath(record: unknown, path: string): unknown;
+/** Write a dotted path into a record, creating intermediate objects. */
+export declare function setPath(target: Record_, path: string, value: unknown): void;
+export type Comparison = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "in" | "matches" | "exists" | "empty";
+export type Condition = {
+    field: string;
+    op: Comparison;
+    value?: unknown;
+};
+/** All conditions must hold ("and"), or any one ("or"). */
+export type Predicate = {
+    all?: Condition[];
+    any?: Condition[];
+    none?: Condition[];
+};
+export declare class PredicateError extends Error {
+}
+/** Evaluate one condition against a record. */
+export declare function testCondition(record: unknown, cond: Condition): boolean;
+/**
+ * Order two scalars, or null when they are not comparable. Numbers compare
+ * numerically, strings by code unit, booleans false-before-true; a
+ * number/string pair is not comparable, which is what stops `"10" < 9`
+ * quietly being true.
+ */
+export declare function compareValues(a: unknown, b: unknown): number | null;
+/** Evaluate a whole predicate. An empty predicate matches everything. */
+export declare function testPredicate(record: unknown, predicate: Predicate): boolean;
+export type SortKey = {
+    field: string;
+    direction?: "asc" | "desc";
+    /** Compare strings case-insensitively. Has no effect on other types. */
+    caseInsensitive?: boolean;
+    /** Where undefined and null go. Default "last", whatever the direction. */
+    nulls?: "first" | "last";
+};
+/**
+ * Sort records by one or more keys. The sort is stable and total: values of
+ * different types are ordered by a fixed type rank (null < boolean < number
+ * < string < array < object) so the result never depends on the input order
+ * of incomparable rows.
+ */
+export declare function sortRecords<T>(records: ReadonlyArray<T>, keys: ReadonlyArray<SortKey>): T[];
+/**
+ * The type-rank order. `TYPE_ORDER[rankOf(v)]` is the name of `v`'s rank, so
+ * the documented order and the code that implements it cannot drift.
+ * `undefined` ranks with `null`, since neither is a JSON value a comparison
+ * can say anything else about.
+ */
+export declare const TYPE_ORDER: ReadonlyArray<string>;
+/**
+ * A total order over JSON values, used so a sort is never arbitrary.
+ *
+ * Within a rank, scalars compare naturally. Arrays and objects compare by
+ * their canonical text, which is lexicographic and therefore *not*
+ * element-wise numeric: `[1, 10]` sorts before `[1, 2]`, because `"1"`
+ * precedes `"2"` at the fourth character. That is the price of an order that
+ * is total and never has to invent a comparison between a number and an
+ * object; sort by a scalar field when the order has to mean something.
+ */
+export declare function totalCompare(a: unknown, b: unknown): number;
+/** Keep only the named fields (dotted paths), preserving the requested order. */
+export declare function selectFields(record: unknown, fields: ReadonlyArray<string>): Record_;
+/** Drop the named fields (dotted paths) from a shallow copy. */
+export declare function omitFields(record: Record_, fields: ReadonlyArray<string>): Record_;
+export type AggregateFn = "count" | "sum" | "min" | "max" | "avg" | "first" | "last" | "distinct";
+export type Aggregation = {
+    as: string;
+    fn: AggregateFn;
+    field?: string;
+};
+export type GroupResult = {
+    key: Record_;
+    count: number;
+} & Record_;
+/**
+ * Group records by one or more fields and reduce each group.
+ *
+ * `sum` and `avg` ignore non-numeric values and report how many were skipped
+ * via the `_skipped` count, rather than producing NaN. `min`/`max` use the
+ * same total order as `sortRecords`. `distinct` counts distinct values by
+ * their canonical form, so `{a:1,b:2}` and `{b:2,a:1}` are one value.
+ */
+export declare function aggregate(records: ReadonlyArray<Record_>, groupBy: ReadonlyArray<string>, aggregations: ReadonlyArray<Aggregation>): {
+    groups: Record_[];
+    skipped: number;
+};
+export type JoinKind = "inner" | "left" | "right" | "full";
+export type JoinOptions = {
+    kind: JoinKind;
+    leftKey: string;
+    rightKey: string;
+    /** Prefix applied to right-hand fields whose name collides with a left one. */
+    rightPrefix: string;
+    maxRows: number;
+};
+/**
+ * Join two record arrays on a key. Matching is by the canonical form of the
+ * key value, so `1` and `"1"` are different keys — a silent coercion here is
+ * how a join quietly loses rows.
+ *
+ * Every right-hand match is emitted, so a one-to-many join multiplies rows,
+ * as SQL does. `maxRows` bounds that.
+ */
+export declare function joinRecords(left: ReadonlyArray<Record_>, right: ReadonlyArray<Record_>, options: JoinOptions): {
+    rows: Record_[];
+    truncated: boolean;
+    unmatchedLeft: number;
+    unmatchedRight: number;
+};
+/** Records to a column-oriented object: `[{a:1},{a:2}]` becomes `{a:[1,2]}`. */
+export declare function recordsToColumns(records: ReadonlyArray<Record_>): Record<string, unknown[]>;
+/**
+ * Columns back to records. Columns of differing length are padded with null
+ * up to the longest, and the caller is told how many were short.
+ */
+export declare function columnsToRecords(columns: Record<string, ReadonlyArray<unknown>>): {
+    records: Record_[];
+    ragged: string[];
+};
+/** Flatten nested objects into dotted keys. Arrays become `a.0`, `a.1` when expanded. */
+export declare function flattenObject(value: unknown, separator: string, expandArrays: boolean, maxDepth: number): Record<string, unknown>;
+/**
+ * Rebuild nested objects from dotted keys. A numeric segment becomes an
+ * array index when `arraysFromNumericKeys` is on and the keys under that
+ * prefix are a contiguous run from 0; otherwise it stays an object key, so
+ * `{"a.2": 1}` does not silently produce two nulls.
+ */
+export declare function unflattenObject(flat: Record<string, unknown>, separator: string, arraysFromNumericKeys: boolean): unknown;
+/**
+ * De-duplicate records by a key path, or by the whole value when no key is
+ * given. Identity is the canonical (key-sorted) serialization, so two
+ * records that differ only in key order are one record.
+ */
+export declare function dedupeRecords<T>(records: ReadonlyArray<T>, keyFields: ReadonlyArray<string>, keep: "first" | "last"): {
+    records: T[];
+    removed: number;
+};
+export type SampleMode = "head" | "tail" | "everyNth" | "evenly";
+/**
+ * Take a deterministic sample. There is no random mode on purpose: a tool
+ * that returned a different subset on each call could not be cached, retried
+ * or compared between runs. `evenly` spreads picks across the whole array.
+ */
+export declare function sampleRecords<T>(records: ReadonlyArray<T>, mode: SampleMode, count: number, step: number): T[];