json-mapper

A patterns-driven, high-performance command-line interface (CLI) tool designed to recursively map and transform JSON arrays using a schema-based dictionary.

---

60-Second Quick Start

Follow these steps to clone the repository, install dependencies, and run a sample transformation.

1. Installation

Clone the repository and install the production and development dependencies:

git clone https://github.com/your-username/json-mapper.git
cd json-mapper
npm install

2. Run Transformation

Execute the mapping process using the provided workspace samples:

node src/infrastructure/cli/bin.js -i ./sample/initial_model.json -d ./sample/dictionary.json -o ./sample/output.json

3. Verify Output

Inspect the generated file in the sample directory to view the structured results:

cat sample/output.json

---

Multi-File & Directory Processing Guide

This section explains how to run transformations across multiple files or directories using the two topological mapping modes.

1-to-1 Mapping (Directory to Directory)

In 1:1 mode, each source file maps to an individual converted output file inside a target directory.

# Create directory containing source JSON arrays
mkdir -p data/inputs
echo '[{"id": 1, "name": "Alice"}]' > data/inputs/users_us.json
echo '[{"id": 2, "name": "Bob"}]' > data/inputs/users_eu.json

# Execute the mapping. The output directory is automatically generated
node src/infrastructure/cli/bin.js -i data/inputs -d sample/dictionary.json -o data/outputs -m 1:1

# Verify output files have been generated with matching names
cat data/outputs/users_us.json
cat data/outputs/users_eu.json

Many-to-1 Mapping (Wildcard Glob to Unified File)

In many:1 mode, the mapper reads files matching a wildcard pattern, runs the transformation, and concatenates all records into a single destination JSON array.

# Execute mapping using wildcard glob pattern
node src/infrastructure/cli/bin.js -i "data/inputs/*.json" -d sample/dictionary.json -o data/merged.json -m many:1

# Verify the unified output file contains records from all matched inputs
cat data/merged.json

---

Command Line Interface (CLI) Reference

The command-line interface uses commander to parse options and enforce constraints.

Available Options

All parameter options are required for the mapping execution (except --mode which defaults to 1:1):

• -i, --input <path> - Specifies the path to the source JSON file, directory path, or wildcard glob pattern.
• -d, --dict <file> - Specifies the path to the mapping schema dictionary JSON file.
• -o, --output <path> - Specifies the output file path or directory path.
• -m, --mode <mode> - Specifies the mapping topology mode: 1:1 (default) or many:1.
• -V, --version - Outputs the version number of the tool.
• -h, --help - Renders the CLI usage instructions and options overview.

---

Logging & Telemetry Reference

Version 2 integrates structured logging and operational metrics using pino under a clean architecture abstraction layer.

Telemetry Logs Structure

All logs generated by the system output in a structured JSON format to stdout. Key logging levels include:

• Level 30 (Info) - Logs general operational checkpoints (e.g., startup checkpoints, loaded records count, successful outputs).
• Level 40 (Warn) - Logs non-fatal operational anomalies (e.g., errors handled during CLI execution boundary controller phases).
• Level 50 (Error) - Logs fatal execution halts including stack traces (e.g., file not found, bad schemas).

Operational Metrics Schema

When a transformation executes successfully, the system logs a structured telemetry event with telemetry: true.

Example Telemetry Metric Log

{
  "level": 30,
  "time": "2026-06-20T17:37:36.123Z",
  "pid": 8692,
  "hostname": "Notebook-Camilo-1",
  "telemetry": true,
  "metric": "mapping_execution_telemetry",
  "durationUs": 4260,
  "processedFileCount": 2,
  "aggregateObjectCount": 3,
  "mode": "1:1",
  "durationMs": 4.26,
  "recordCount": 3,
  "inputFile": "/absolute/path/to/inputs/file1.json",
  "outputFile": "/absolute/path/to/outputs/file1.json",
  "msg": "Telemetry Metric: mapping_execution_telemetry"
}

Metrics Properties

• metric - Identifies the telemetry event type (mapping_execution_telemetry).
• telemetry - Flags (true) that this log records operational performance metrics.
• durationUs - Records the total execution duration in microseconds.
• processedFileCount - Tracks the count of resolved input files processed in the transaction.
• aggregateObjectCount - Tracks the total number of source objects mapped across all files.
• mode - Denotes the mapping mode: 1:1 or many:1.
• durationMs - Records the high-precision execution timing calculated in milliseconds (retained for backward compatibility).
• recordCount - Tracks the total count of source JSON objects mapped (retained for backward compatibility).
• inputFile - Specifies the path to the first input JSON file processed (retained for backward compatibility).
• outputFile - Specifies the path to the written output JSON file (retained for backward compatibility).

---

Architectural Reference

This codebase adheres to Clean Architecture principles, ensuring separation of concerns and loose coupling.

Concentric Layers

• Domain Layer (src/domain/) - Houses the core business rules and AST compilation algorithms. This layer contains zero external dependencies and remains fully decoupled from network, filesystems, and databases.
• Use Cases Layer (src/usecases/) - Defines workflows and execution steps. It interfaces with outer mechanisms strictly using abstract ports (IFileRepository, ILogger).
• Adapters Layer (src/adapters/) - Connects use cases and domain models to environments, databases, and logging engines (such as the GoF PinoLoggerAdapter).
• Infrastructure Layer (src/infrastructure/) - Contains third-party CLI orchestrators (commander), config bootstrap, and dependency injection wire-up.

Design Patterns

• Composite Pattern - Models the declarative dictionary schema recursively via nested composite structures, defined in src/domain/model/MappingNode.js.
• Strategy Pattern - Determines properties and indexed array selections dynamically, defined in src/domain/services/LookupResolver.js.
• Adapter Pattern - Decouples storage inputs (src/adapters/repositories/FileRepositoryAdapter.js) and logging telemetry (src/adapters/loggers/PinoLoggerAdapter.js) from inner layers.

---

Testing Reference

Validate system logic and boundary integrations using the test suites.

Testing Strategy

The repository is validated using two testing levels:

• Unit Tests (test/unit/): Verify individual domain model computations, composite mapping tree resolutions, AST parser logic, and repository adapter operations.
• End-to-End Tests (test/e2e/): Execute black-box verification of the command-line application. The test runner spawns src/infrastructure/cli/bin.js as an independent child process via child_process.fork, passing input data and translation dictionaries. It verifies the process close transitions, asserts output JSON layout correctness, and parses stdout standard streams to intercept JSON Pino performance telemetries.

Running Automated Tests

Run the complete test suite (Unit and E2E combined) recursively using Node's native test runner:

npm test

Running Specific Test Suites

Execute only the E2E verification test suite:

node --test test/e2e/

Running Unit Test Suite

Execute only the unit testing suite:

node --test test/unit/

Running Target Test File

Execute a single target test file directly:

node --test test/e2e/cli-lifecycle.test.js

---

Further Reading

The design decisions behind this project — the shift from prompt-and-paste GenAI usage to a coordinated multi-agent engineering cell (Architect / Full-Stack / Technical Writer) under Clean Architecture and TDD — are written up in more detail here:

👉 Raise the Level of Abstraction: Del Assembler a la Inteligencia Artificial Generativa