lacspace-json 0.1.0

package/dist/lib.d.cts

@@ -0,0 +1,151 @@
+/** Compile a query string into a reusable evaluator (throws on parse error). */
+declare function compileQuery(expr: string): (data: unknown) => unknown[];
+/**
+ * Run `expr` against `data`. Returns the single result when the query yields
+ * exactly one value, otherwise an array of all results (jq's stream semantics).
+ */
+declare function query(data: unknown, expr: string): unknown;
+/** Run `expr` and always return the full result stream as an array. */
+declare function queryAll(data: unknown, expr: string): unknown[];
+/** True if `expr` parses. */
+declare function isValidQuery(expr: string): boolean;
+
+/**
+ * Shared helpers: JSON value types, deep equality, safe object construction
+ * (prototype-pollution guarded) and type classification.
+ */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** True for a non-null, non-array object. */
+declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/** jq-style type name for a JSON value. */
+declare function typeOf(v: unknown): "null" | "boolean" | "number" | "string" | "array" | "object";
+/** Structural deep equality for JSON values. */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+/** Deep clone of a JSON value (safe against prototype pollution). */
+declare function deepClone<T>(v: T): T;
+/**
+ * A stable ordering for JSON values, used by `sort_by`, `unique`, `min`/`max`.
+ * Ordering mirrors jq: null < false < true < numbers < strings < arrays < objects.
+ */
+declare function compareValues(a: unknown, b: unknown): number;
+/** Recursively sort object keys (used by `--sort-keys`). */
+declare function sortKeysDeep(v: unknown): unknown;
+/** A rendering-safe error carrying an optional path for CLI display. */
+declare class JsonToolError extends Error {
+    path?: string;
+    constructor(message: string, path?: string);
+}
+
+type Format = "json" | "yaml" | "toml" | "csv" | "ndjson";
+/** Guess a format from a filename extension, else undefined. */
+declare function formatFromExt(filename: string): Format | undefined;
+/** Best-effort format detection from the content itself. */
+declare function detectFormat(src: string): Format;
+/** Parse `src` in the given format into a JSON value. */
+declare function parseFormat(src: string, format: Format): JsonValue;
+/** Serialize a JSON value into the given format. */
+declare function stringifyFormat(value: JsonValue, format: Format, opts?: {
+    indent?: number;
+    sortKeys?: boolean;
+    minify?: boolean;
+}): string;
+/** Convert text from one format to another. */
+declare function convert(src: string, from: Format, to: Format, opts?: {
+    indent?: number;
+    minify?: boolean;
+}): string;
+/**
+ * Recursively rebuild a parsed JSON value dropping prototype-pollution keys.
+ * `JSON.parse` itself is safe, but downstream merges/writes should never carry a
+ * literal `__proto__` own key, so we strip them at the boundary.
+ */
+declare function sanitizeJson(v: unknown): JsonValue;
+
+/** Parse a YAML document into a JSON value. */
+declare function parseYaml(src: string): JsonValue;
+/** Serialize a JSON value to YAML. */
+declare function stringifyYaml(value: JsonValue): string;
+
+/** Parse a TOML document into a JSON value (object). */
+declare function parseToml(src: string): JsonValue;
+/** Serialize a JSON object to TOML. Throws if the top level is not an object. */
+declare function stringifyToml(value: JsonValue): string;
+
+interface CsvParseOptions {
+    delimiter?: string;
+    parseTypes?: boolean;
+}
+/** Parse CSV text into an array of objects (or arrays if no header wanted). */
+declare function parseCsv(src: string, opts?: CsvParseOptions): JsonValue;
+interface CsvStringifyOptions {
+    delimiter?: string;
+    columns?: string[];
+}
+/** Serialize an array of flat objects to CSV. */
+declare function stringifyCsv(value: JsonValue, opts?: CsvStringifyOptions): string;
+/** Parse NDJSON (one JSON value per line) into an array. */
+declare function parseNdjson(src: string): JsonValue;
+/** Serialize an array to NDJSON (one compact JSON value per line). */
+declare function stringifyNdjson(value: JsonValue): string;
+
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/** Validate `data` against a JSON Schema. Returns `{ valid, errors[] }`. */
+declare function validateSchema(data: JsonValue, schema: JsonValue): ValidationResult;
+
+type DiffKind = "added" | "removed" | "changed";
+interface DiffEntry {
+    kind: DiffKind;
+    path: string;
+    before?: JsonValue;
+    after?: JsonValue;
+}
+/** Compute a flat list of differences turning `a` into `b`. */
+declare function diff(a: JsonValue, b: JsonValue): DiffEntry[];
+/** True if the two values are structurally identical. */
+declare function isEqual(a: JsonValue, b: JsonValue): boolean;
+
+type ArrayStrategy = {
+    mode: "concat";
+} | {
+    mode: "replace";
+} | {
+    mode: "by-key";
+    key: string;
+};
+interface MergeOptions {
+    array?: ArrayStrategy;
+}
+/** Deep-merge two or more JSON values left-to-right. */
+declare function merge(values: JsonValue[], opts?: MergeOptions): JsonValue;
+/** Parse a CLI `--array` flag into a strategy. */
+declare function parseArrayStrategy(spec: string | undefined, byKey?: string): ArrayStrategy;
+
+interface FormatOptions {
+    indent?: number;
+    sortKeys?: boolean;
+    minify?: boolean;
+}
+/** Pretty-print (or minify) a JSON value. */
+declare function formatJson(value: JsonValue, opts?: FormatOptions): string;
+/**
+ * Resolve a dotted / bracketed path (`.a.b[0].c`, `a.b`, `users[2].name`) to a
+ * single value. Returns `undefined` if any segment is missing.
+ */
+declare function getPath(data: JsonValue, path: string): JsonValue | undefined;
+/** Tokenize a path string into key/index segments. */
+declare function parsePath(path: string): Array<string | number>;
+
+export { type ArrayStrategy, type CsvParseOptions, type CsvStringifyOptions, type DiffEntry, type DiffKind, type Format, type FormatOptions, type JsonObject, type JsonPrimitive, JsonToolError, type JsonValue, type MergeOptions, type ValidationError, type ValidationResult, compareValues, compileQuery, convert, deepClone, deepEqual, detectFormat, diff, formatFromExt, formatJson, getPath, isEqual, isPlainObject, isValidQuery, merge, parseArrayStrategy, parseCsv, parseFormat, parseNdjson, parsePath, parseToml, parseYaml, query, queryAll, sanitizeJson, sortKeysDeep, stringifyCsv, stringifyFormat, stringifyNdjson, stringifyToml, stringifyYaml, typeOf, validateSchema };

package/dist/lib.d.ts

@@ -0,0 +1,151 @@
+/** Compile a query string into a reusable evaluator (throws on parse error). */
+declare function compileQuery(expr: string): (data: unknown) => unknown[];
+/**
+ * Run `expr` against `data`. Returns the single result when the query yields
+ * exactly one value, otherwise an array of all results (jq's stream semantics).
+ */
+declare function query(data: unknown, expr: string): unknown;
+/** Run `expr` and always return the full result stream as an array. */
+declare function queryAll(data: unknown, expr: string): unknown[];
+/** True if `expr` parses. */
+declare function isValidQuery(expr: string): boolean;
+
+/**
+ * Shared helpers: JSON value types, deep equality, safe object construction
+ * (prototype-pollution guarded) and type classification.
+ */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** True for a non-null, non-array object. */
+declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/** jq-style type name for a JSON value. */
+declare function typeOf(v: unknown): "null" | "boolean" | "number" | "string" | "array" | "object";
+/** Structural deep equality for JSON values. */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+/** Deep clone of a JSON value (safe against prototype pollution). */
+declare function deepClone<T>(v: T): T;
+/**
+ * A stable ordering for JSON values, used by `sort_by`, `unique`, `min`/`max`.
+ * Ordering mirrors jq: null < false < true < numbers < strings < arrays < objects.
+ */
+declare function compareValues(a: unknown, b: unknown): number;
+/** Recursively sort object keys (used by `--sort-keys`). */
+declare function sortKeysDeep(v: unknown): unknown;
+/** A rendering-safe error carrying an optional path for CLI display. */
+declare class JsonToolError extends Error {
+    path?: string;
+    constructor(message: string, path?: string);
+}
+
+type Format = "json" | "yaml" | "toml" | "csv" | "ndjson";
+/** Guess a format from a filename extension, else undefined. */
+declare function formatFromExt(filename: string): Format | undefined;
+/** Best-effort format detection from the content itself. */
+declare function detectFormat(src: string): Format;
+/** Parse `src` in the given format into a JSON value. */
+declare function parseFormat(src: string, format: Format): JsonValue;
+/** Serialize a JSON value into the given format. */
+declare function stringifyFormat(value: JsonValue, format: Format, opts?: {
+    indent?: number;
+    sortKeys?: boolean;
+    minify?: boolean;
+}): string;
+/** Convert text from one format to another. */
+declare function convert(src: string, from: Format, to: Format, opts?: {
+    indent?: number;
+    minify?: boolean;
+}): string;
+/**
+ * Recursively rebuild a parsed JSON value dropping prototype-pollution keys.
+ * `JSON.parse` itself is safe, but downstream merges/writes should never carry a
+ * literal `__proto__` own key, so we strip them at the boundary.
+ */
+declare function sanitizeJson(v: unknown): JsonValue;
+
+/** Parse a YAML document into a JSON value. */
+declare function parseYaml(src: string): JsonValue;
+/** Serialize a JSON value to YAML. */
+declare function stringifyYaml(value: JsonValue): string;
+
+/** Parse a TOML document into a JSON value (object). */
+declare function parseToml(src: string): JsonValue;
+/** Serialize a JSON object to TOML. Throws if the top level is not an object. */
+declare function stringifyToml(value: JsonValue): string;
+
+interface CsvParseOptions {
+    delimiter?: string;
+    parseTypes?: boolean;
+}
+/** Parse CSV text into an array of objects (or arrays if no header wanted). */
+declare function parseCsv(src: string, opts?: CsvParseOptions): JsonValue;
+interface CsvStringifyOptions {
+    delimiter?: string;
+    columns?: string[];
+}
+/** Serialize an array of flat objects to CSV. */
+declare function stringifyCsv(value: JsonValue, opts?: CsvStringifyOptions): string;
+/** Parse NDJSON (one JSON value per line) into an array. */
+declare function parseNdjson(src: string): JsonValue;
+/** Serialize an array to NDJSON (one compact JSON value per line). */
+declare function stringifyNdjson(value: JsonValue): string;
+
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/** Validate `data` against a JSON Schema. Returns `{ valid, errors[] }`. */
+declare function validateSchema(data: JsonValue, schema: JsonValue): ValidationResult;
+
+type DiffKind = "added" | "removed" | "changed";
+interface DiffEntry {
+    kind: DiffKind;
+    path: string;
+    before?: JsonValue;
+    after?: JsonValue;
+}
+/** Compute a flat list of differences turning `a` into `b`. */
+declare function diff(a: JsonValue, b: JsonValue): DiffEntry[];
+/** True if the two values are structurally identical. */
+declare function isEqual(a: JsonValue, b: JsonValue): boolean;
+
+type ArrayStrategy = {
+    mode: "concat";
+} | {
+    mode: "replace";
+} | {
+    mode: "by-key";
+    key: string;
+};
+interface MergeOptions {
+    array?: ArrayStrategy;
+}
+/** Deep-merge two or more JSON values left-to-right. */
+declare function merge(values: JsonValue[], opts?: MergeOptions): JsonValue;
+/** Parse a CLI `--array` flag into a strategy. */
+declare function parseArrayStrategy(spec: string | undefined, byKey?: string): ArrayStrategy;
+
+interface FormatOptions {
+    indent?: number;
+    sortKeys?: boolean;
+    minify?: boolean;
+}
+/** Pretty-print (or minify) a JSON value. */
+declare function formatJson(value: JsonValue, opts?: FormatOptions): string;
+/**
+ * Resolve a dotted / bracketed path (`.a.b[0].c`, `a.b`, `users[2].name`) to a
+ * single value. Returns `undefined` if any segment is missing.
+ */
+declare function getPath(data: JsonValue, path: string): JsonValue | undefined;
+/** Tokenize a path string into key/index segments. */
+declare function parsePath(path: string): Array<string | number>;
+
+export { type ArrayStrategy, type CsvParseOptions, type CsvStringifyOptions, type DiffEntry, type DiffKind, type Format, type FormatOptions, type JsonObject, type JsonPrimitive, JsonToolError, type JsonValue, type MergeOptions, type ValidationError, type ValidationResult, compareValues, compileQuery, convert, deepClone, deepEqual, detectFormat, diff, formatFromExt, formatJson, getPath, isEqual, isPlainObject, isValidQuery, merge, parseArrayStrategy, parseCsv, parseFormat, parseNdjson, parsePath, parseToml, parseYaml, query, queryAll, sanitizeJson, sortKeysDeep, stringifyCsv, stringifyFormat, stringifyNdjson, stringifyToml, stringifyYaml, typeOf, validateSchema };