@alpnpmrepo/json-yaml-processors

Generic JSON and YAML file processors for extracting and applying changes from git diffs.

Features

• Extract property-level changes from git diffs
• Support for both JSON and YAML files
• Format-preserving change application
• TypeScript strict mode enabled
• MIT licensed

Installation

npm install @alpnpmrepo/json-yaml-processors

Usage

Basic Example

import { FileProcessorFactory } from '@alpnpmrepo/json-yaml-processors';

// Create a processor for your file
const processor = FileProcessorFactory.createProcessor('config.json');

// Extract changes from a git diff
const result = processor.extractChanges(
  'config.json',       // source file path
  sourceContent,       // source file content
  targetContent,       // target file content
  gitDiff              // git diff output
);

// Process the extracted changes
result.changes.forEach(change => {
  console.log(`Property: ${change.propertyPath.join('.')}`);
  console.log(`Change type: ${change.changeType}`);
  console.log(`Old value: ${change.oldValue}`);
  console.log(`New value: ${change.newValue}`);
});

// Apply changes to target content
const updatedContent = processor.applyChanges(targetContent, result.changes);

JSON Processing

import { JsonProcessor } from '@alpnpmrepo/json-yaml-processors';

const jsonProcessor = new JsonProcessor();

// Extract changes
const result = jsonProcessor.extractChanges(
  'package.json',
  sourceJson,
  targetJson,
  gitDiff
);

// Changes include full property paths
result.changes.forEach(change => {
  console.log(change.propertyPath); // e.g., ["dependencies", "typescript"]
  console.log(change.newValue);     // e.g., "^5.0.0"
});

YAML Processing

import { YamlProcessor } from '@alpnpmrepo/json-yaml-processors';

const yamlProcessor = new YamlProcessor();

// Extract changes (preserves YAML formatting)
const result = yamlProcessor.extractChanges(
  'config.yaml',
  sourceYaml,
  targetYaml,
  gitDiff
);

// Supports multi-line blocks
result.changes.forEach(change => {
  if (change.sourceBlockContent) {
    console.log('Multi-line block change detected');
  }
});

API

FileProcessorFactory

Factory for creating the appropriate processor based on file extension.

static createProcessor(filePath: string): IFileProcessor

IFileProcessor

Common interface implemented by all processors.

Methods

• canProcess(filePath: string): boolean - Check if processor can handle file
• getFileType(): 'json' | 'yaml' | 'text' | 'binary' - Get file type identifier
• parseContent(content: string): unknown - Parse file content
• serializeContent(data: unknown, originalContent?: string): string - Serialize data
• extractChanges(sourceFilePath: string, sourceContent: string, targetContent: string, gitDiff: string): IExtractChangesResult - Extract changes from git diff
• applyChanges(targetContent: string, changes: IFileChange[]): string - Apply changes to content

IFileChange

Represents a single property change.

interface IFileChange {
  id: string;                  // Unique identifier
  file: string;                // File path
  fileType: 'json' | 'yaml';   // File type
  changeType: 'add' | 'modify' | 'delete';
  propertyPath: string[];      // Hierarchical path (e.g., ["server", "port"])
  lineNumber: number;          // Line number in file
  oldValue?: unknown;          // Previous value (for modify/delete)
  newValue: unknown;           // New value (for add/modify)
  sourceBlockContent?: string; // For YAML multi-line blocks
}

Architecture

This package provides pure file processing

It focuses solely on: ✅ Parsing JSON/YAML files ✅ Extracting changes from git diffs ✅ Applying changes while preserving formatting

License

MIT