js-json

A library for manipulating dynamic, JSON-like data structures in JavaScript. It provides tools for traversing, modifying, validating, and converting deeply nested objects (maps, sets, arrays, classes) using JSONPath.

Features

• Dynamic Object Manipulation: Get, Set, Delete, and Iterate over values in deeply nested structures using JSONPath.
• Schema Validation: Define schemas for your data and validate dynamic objects against them at runtime.
• Type Conversion: Convert loosely typed data (e.g., Record<string, any>) into strongly typed structures (classes, maps, sets) based on schema definitions.
• Deserialization: Helpers for loading JSON and YAML data directly into schema-validated structures.
• JSONPath Support: Supports dot notation, recursive descent (..), wildcards (*), unions (['a','b']), and array slicing ([start:end:step]).

Prerequisites

Tool	Description	Link
Node.js	JavaScript runtime.	Official Website
Task	Task runner / build tool. You can use the provided shell script taskw that automatically downloads the binary and installs it in the .task folder.	Official Website
Docker / Podman	Optional container engine for isolated development environment.	Docker / Podman

Installation

npm install @rogonion/js-json

Environment Setup

This project uses Taskfile to manage the development environment and tasks.

The below command lists all tasks available in the project:

TASK="./taskw"

$TASK --list

Task	Description	Usage
env:build	Build the dev container image. Image runs an ssh server one can connect to with vscode.	task env:build
env:info	Show current environment configuration.	task env:info
deps	Download and tidy dependencies.	task deps
test	Run tests.	task test
format	Format code.	task format
build	Compile into dist folder.	task build

Modules

1. Object

The object module is the core of the library, allowing you to manipulate data structures.

Key Capabilities:

• Get: Retrieve values.
• Set: Update or insert values (auto-creates nested structures if schema is provided).
• Delete: Remove values.
• ForEach: Iterate over matches.
• AreEqual: Deep comparison.

Example:

import { JSObject } from 'js-json';

const data = {
    users: [
        { name: 'Alice', id: 1 },
        { name: 'Bob', id: 2 }
    ]
};

const obj = new JSObject();
obj.Source = data;

// Get
const noOfResults = obj.Get('$.users[0].name');
if (noOfResults > 0) {
    console.log(obj.ValueFound); // Output: Alice
}

// Set
obj.Set('$.users[1].active', true);

// Delete
obj.Delete('$.users[0]');

2. Schema

The schema module allows you to define the expected structure of your data. This is useful for validation and conversion of dynamic data.

Example: Validation

import { DynamicSchemaNode, DataKind, Validation } from 'js-json';

// Define a schema
const userSchema = new DynamicSchemaNode({
    Kind: DataKind.Object,
    ChildNodes: {
        Name: new DynamicSchemaNode({ Kind: DataKind.String }),
        Age: new DynamicSchemaNode({ Kind: DataKind.Number })
    }
});

const validator = new Validation();
const data = { Name: 'Alice', Age: 30 };

// Validate
const ok = validator.ValidateData(data, userSchema);

Example: Conversion

import { DynamicSchemaNode, DataKind, Conversion } from 'js-json';

// Define schema (same as above)
// ...

const source = { Name: 'Alice', Age: '30' }; // Age is string in source

const converter = new Conversion();
// Converts and coerces types (string "30" -> number 30)
const dest = converter.Convert(source, userSchema);

3. Path

The path module handles parsing of JSONPath strings. It is primarily used internally by the object module but can be used directly to inspect paths.

import { Parse } from 'js-json';

const segments = Parse('$.store.book[*].author');

Supported Data Types

The library supports manipulation of:

• Primitives: string, number, boolean, bigint, symbol.
• Collections: Map, Set, Array, Object (classes).
• Any: any.