mini-obj-diff

Lightweight, configurable object diffing utility for TypeScript/JavaScript. Analyze changes between objects using configurable path rules with wildcard support, nested ID tracking, and optional value change tracking.

Features

• 🎯 Configurable Path Rules: Define exactly which paths to track
• 🌟 Wildcard Support: Use [*] to match arrays and objects
• 🔍 ID-Based Array Tracking: Track array changes using nested ID fields
• 📊 Value Change Tracking: Optional tracking of old/new values
• 🚀 Zero Dependencies: Lightweight and fast
• 📝 Full TypeScript Support: Complete type definitions included
• ✨ Type-Safe: Built with strict TypeScript

Installation

npm install mini-obj-diff

Quick Start

import { analyzeChanges } from 'mini-obj-diff';

const oldObj = {
  status: 'active',
  users: [{ id: 1, name: 'Alice' }],
};

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

const result = analyzeChanges(oldObj, newObj, {
  pathConfigs: [
    { path: 'status', name: 'status', trackValues: true },
    { path: 'users.[*]', name: 'user', idField: 'id' },
  ],
});

console.log(result.updatedItems); // ['status']
console.log(result.addedItems);   // ['user']
console.log(result.valueChanges.status); // [{ oldValue: 'active', newValue: 'inactive', ... }]

Usage

Basic Example

import { analyzeChanges, type PathConfig } from 'mini-obj-diff';

const config: PathConfig[] = [
  { path: 'status', name: 'status', trackValues: true },
  { path: 'count', name: 'count' },
];

const oldState = { status: 'active', count: 5 };
const newState = { status: 'inactive', count: 10 };

const result = analyzeChanges(oldState, newState, { pathConfigs: config });

// result.addedItems = []
// result.updatedItems = ['status', 'count']
// result.removedItems = []
// result.valueChanges.status = [{ oldValue: 'active', newValue: 'inactive', ... }]

Wildcard Paths

Use [*] to match arrays and objects:

const config: PathConfig[] = [
  { path: 'users.[*].name', name: 'userName' },
  { path: 'users.[*].email', name: 'userEmail', trackValues: true },
];

const oldObj = {
  users: [
    { name: 'Alice', email: '[email protected]' },
    { name: 'Bob', email: '[email protected]' },
  ],
};

const newObj = {
  users: [
    { name: 'Alice', email: '[email protected]' },
    { name: 'Bob', email: '[email protected]' },
    { name: 'Charlie', email: '[email protected]' },
  ],
};

const result = analyzeChanges(oldObj, newObj, { pathConfigs: config });
// Detects changes in user names and emails across all users

Array Tracking with ID Fields

Track array changes using ID fields:

const config: PathConfig[] = [
  {
    path: 'products.[*]',
    name: 'product',
    idField: 'id', // Track by product.id
    trackValues: true,
  },
];

const oldProducts = [
  { id: 1, name: 'Widget', price: 10 },
  { id: 2, name: 'Gadget', price: 20 },
];

const newProducts = [
  { id: 1, name: 'Widget', price: 15 }, // price updated
  { id: 3, name: 'Tool', price: 30 },   // new product
  // id: 2 removed
];

const result = analyzeChanges(
  { products: oldProducts },
  { products: newProducts },
  { pathConfigs: config },
);

// result.updatedItems = ['product'] (price changed for id: 1)
// result.addedItems = ['product'] (id: 3 added)
// result.removedItems = ['product'] (id: 2 removed)

API Reference

analyzeChanges(oldObject, newObject, options)

Analyzes changes between two objects according to provided path configurations.

Parameters

• oldObject (unknown): The previous state of the object
• newObject (unknown): The new state of the object
• options (AnalyzeChangesOptions): Configuration options
  • pathConfigs (PathConfig[]): Array of path configurations to track
  • optimizeCache (boolean, optional): Cache resolved wildcard paths (default: true)

Returns

AnalyzeChangesResult:

• addedItems: Array of logical names that were added
• updatedItems: Array of logical names that were updated
• removedItems: Array of logical names that were removed
• valueChanges: Map of property names to their value change entries (if trackValues: true)

PathConfig

interface PathConfig {
  path: string;           // Dot-separated path (supports `[*]` wildcards)
  name: string;          // Logical name for this path (used in results)
  idField?: string;       // Optional nested path to ID field (for array tracking)
  trackValues?: boolean;  // Whether to track old/new values
}

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import {
  analyzeChanges,
  type PathConfig,
  type AnalyzeChangesResult,
  type ValueChangeEntry,
} from 'mini-obj-diff';

// All types are fully typed and exported

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (if using TypeScript)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint

# Format code
npm run format

License

MIT © Akarshit Batra

Changelog

See CHANGELOG.md for details.