@diffson/core 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,264 @@
+# @diffson/core
+
+A powerful TypeScript library for comparing JSON objects with multiple comparison strategies.
+
+## Installation
+
+```bash
+npm install @diffson/core
+```
+
+## Quick Start
+
+```typescript
+import { DiffService, PresetName } from '@diffson/core';
+
+// Create a diff service
+const diffService = new DiffService();
+
+// Compare two JSON objects
+const left = { name: 'John', age: 30 };
+const right = { name: 'John', age: 31 };
+
+const results = diffService.diffElement(left, right);
+
+console.log(results);
+// [
+//   {
+//     leftPath: 'age',
+//     rightPath: 'age',
+//     left: '30',
+//     right: '31',
+//     diffType: 'MODIFY'
+//   }
+// ]
+```
+
+## API Reference
+
+### DiffService
+
+The main class for comparing JSON objects.
+
+#### Constructor
+
+```typescript
+new DiffService(preset?: PresetName)
+```
+
+**Parameters:**
+- `preset` (optional): Comparison strategy preset. Default: `PresetName.FullSmart`
+
+**Presets:**
+- `PresetName.FullSmart` - Smart comparison of all fields (default)
+- `PresetName.FullOrdered` - Order-sensitive comparison
+- `PresetName.LeftSmart` - Compare only fields in left object, smart mode
+- `PresetName.LeftOrdered` - Compare only fields in left object, order-sensitive
+
+#### Methods
+
+##### `diffElement(left, right, options?)`
+
+Compare two JSON values directly.
+
+```typescript
+diffElement(
+  left: JsonValue,
+  right: JsonValue,
+  options?: {
+    noisePath?: string[];
+    specialPath?: string[];
+    parseNestedJson?: boolean;
+  }
+): Result[]
+```
+
+**Parameters:**
+- `left`: First JSON value
+- `right`: Second JSON value
+- `options` (optional):
+  - `noisePath`: Array of paths to ignore during comparison
+  - `specialPath`: Array of paths to mark as special even if values match
+  - `parseNestedJson`: Parse nested JSON strings recursively
+
+**Returns:** Array of `Result` objects representing differences.
+
+##### `diffJson(leftJson, rightJson, options?)`
+
+Compare two JSON strings.
+
+```typescript
+diffJson(
+  leftJson: string,
+  rightJson: string,
+  options?: {
+    noisePath?: string[];
+    specialPath?: string[];
+    parseNestedJson?: boolean;
+  }
+): Result[]
+```
+
+**Parameters:**
+- `leftJson`: First JSON string
+- `rightJson`: Second JSON string
+- `options`: Same as `diffElement`
+
+**Returns:** Array of `Result` objects representing differences.
+
+### Result Object
+
+Each difference is represented by a `Result` object:
+
+```typescript
+{
+  leftPath: string | null;   // Path in left object
+  rightPath: string | null;  // Path in right object
+  left: unknown;             // Value in left object
+  right: unknown;            // Value in right object
+  diffType: string;          // 'ADD' | 'DELETE' | 'MODIFY'
+}
+```
+
+**Diff Types:**
+- `ADD`: Field exists in right but not in left
+- `DELETE`: Field exists in left but not in right
+- `MODIFY`: Field exists in both but with different values
+
+## Usage Examples
+
+### Basic Comparison
+
+```typescript
+import { DiffService } from '@diffson/core';
+
+const diffService = new DiffService();
+
+const left = { a: 1, b: 2 };
+const right = { a: 1, b: 3, c: 4 };
+
+const results = diffService.diffElement(left, right);
+// Results: [
+//   { leftPath: 'b', rightPath: 'b', left: '2', right: '3', diffType: 'MODIFY' },
+//   { leftPath: null, rightPath: 'c', left: null, right: '4', diffType: 'ADD' }
+// ]
+```
+
+### Using Presets
+
+```typescript
+import { DiffService, PresetName } from '@diffson/core';
+
+// Order-sensitive comparison
+const orderedDiff = new DiffService(PresetName.FullOrdered);
+const results1 = orderedDiff.diffElement([1, 2, 3], [1, 3, 2]);
+// Detects order changes
+
+// Left-only comparison (ignore fields only in right)
+const leftDiff = new DiffService(PresetName.LeftSmart);
+const left = { a: 1, b: 2 };
+const right = { a: 1, b: 2, c: 3 };
+const results2 = leftDiff.diffElement(left, right);
+// Results: [] (ignores 'c' since it's not in left)
+```
+
+### Ignoring Paths (Noise Paths)
+
+```typescript
+const diffService = new DiffService();
+
+const left = { name: 'John', timestamp: 1000 };
+const right = { name: 'John', timestamp: 2000 };
+
+// Ignore timestamp field
+const results = diffService.diffElement(left, right, {
+  noisePath: ['timestamp']
+});
+// Results: [] (timestamp is ignored)
+```
+
+### Nested Objects
+
+```typescript
+const left = {
+  user: { name: 'Alice', age: 30 },
+  items: [{ id: 1, name: 'Item 1' }]
+};
+
+const right = {
+  user: { name: 'Bob', age: 30 },
+  items: [{ id: 1, name: 'Item 1' }]
+};
+
+const results = diffService.diffElement(left, right);
+// Results: [
+//   { leftPath: 'user.name', rightPath: 'user.name', left: 'Alice', right: 'Bob', diffType: 'MODIFY' }
+// ]
+```
+
+### Parsing Nested JSON Strings
+
+```typescript
+const left = { data: '{"nested":"value1"}' };
+const right = { data: '{"nested":"value2"}' };
+
+// Without parseNestedJson
+const results1 = diffService.diffElement(left, right);
+// Compares strings: '{"nested":"value1"}' vs '{"nested":"value2"}'
+
+// With parseNestedJson
+const results2 = diffService.diffElement(left, right, {
+  parseNestedJson: true
+});
+// Parses and compares: { nested: 'value1' } vs { nested: 'value2' }
+// Results: [{ leftPath: 'data.nested', rightPath: 'data.nested', ... }]
+```
+
+### Comparing JSON Strings
+
+```typescript
+const leftJson = '{"name":"John","age":30}';
+const rightJson = '{"name":"John","age":31}';
+
+const results = diffService.diffJson(leftJson, rightJson);
+// Same as diffElement but accepts JSON strings
+```
+
+### Fluent API (Advanced)
+
+```typescript
+import { DiffService, SequentialArrayComparator, LeftJoinObjectComparator } from '@diffson/core';
+
+const diffService = new DiffService()
+  .withArrayComparator(SequentialArrayComparator)
+  .withObjectComparator(LeftJoinObjectComparator);
+
+const results = diffService.diffElement(left, right);
+// Uses custom comparators
+```
+
+## Path Format
+
+Paths use dot notation to reference nested fields:
+
+- `field` - Object field
+- `array.[0]` - Array element at index 0
+- `parent.child` - Nested object field
+- `items.[0].name` - Field in array element
+
+When using `noisePath`, array indices are auto-filtered:
+- `items.name` matches `items.[0].name`, `items.[1].name`, etc.
+
+## TypeScript Support
+
+This library is written in TypeScript and includes full type definitions.
+
+```typescript
+import type { JsonValue, Result, PresetName } from '@diffson/core';
+```
+
+## License
+
+MIT
+
+

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@diffson/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "imports": {
     "#contract": "./src/contract/index.ts",
     "#service": "./src/service/index.ts"

package/.turbo/turbo-build.log

@@ -1 +0,0 @@
-$ tsc

package/.turbo/turbo-test.log

@@ -1,96 +0,0 @@
-
-$ bun test
-bun test v1.3.5 (1e86cebd)
-
-src/util/TypeGuards.test.ts:
-✓ TypeGuards > isJsonObject > should return true for objects [0.92ms]
-✓ TypeGuards > isJsonObject > should return false for non-objects [0.05ms]
-✓ TypeGuards > isJsonArray > should return true for arrays [0.02ms]
-✓ TypeGuards > isJsonArray > should return false for non-arrays [0.02ms]
-✓ TypeGuards > isJsonPrimitive > should return true for primitives [0.01ms]
-✓ TypeGuards > isJsonPrimitive > should return false for non-primitives [0.02ms]
-✓ TypeGuards > isJsonNull > should return true for null [0.02ms]
-✓ TypeGuards > isJsonNull > should return false for non-null [0.01ms]
-✓ TypeGuards > jsonElement2Str > should convert primitives to strings [0.03ms]
-✓ TypeGuards > jsonElement2Str > should return null for undefined
-✓ TypeGuards > jsonElement2Str > should return 'null' for null
-✓ TypeGuards > jsonElement2Str > should return placeholder for objects
-✓ TypeGuards > jsonElement2Str > should return placeholder for arrays
-
-src/service/diff/Diff.test.ts:
-✓ DiffService > diffElement > should return empty array for identical objects [1.15ms]
-✓ DiffService > diffElement > should detect modified values [0.12ms]
-✓ DiffService > diffElement > should detect added fields [0.06ms]
-✓ DiffService > diffElement > should detect deleted fields [0.13ms]
-✓ DiffService > diffJson > should parse JSON strings and diff them [0.10ms]
-✓ DiffService > diffJson > should return empty array for identical JSON strings [0.09ms]
-✓ DiffService > diffJson > should throw error for invalid left JSON string [0.31ms]
-✓ DiffService > diffJson > should throw error for invalid right JSON string [0.02ms]
-✓ DiffService > nested objects > should handle nested objects [0.09ms]
-
-src/service/diff/DiffService.test.ts:
-✓ DiffService > basic comparison > should return empty array for identical objects [0.10ms]
-✓ DiffService > basic comparison > should detect modified values [0.06ms]
-[
-  Result {
-    leftPath: "items.[1]",
-    rightPath: "items.[1]",
-    left: "2",
-    right: "4",
-    diffType: "MODIFY",
-  }
-]
-✓ DiffService > withArrayComparator > should use sequential array comparator when configured [0.85ms]
-✓ DiffService > withArrayComparator > should reuse injector when configuration changes [0.40ms]
-✓ DiffService > preset > should use FullOrdered preset [0.04ms]
-✓ DiffService > preset > should use LeftSmart preset [0.03ms]
-✓ DiffService > preset > should use LeftOrdered preset [0.05ms]
-✓ DiffService > compareWithOptions > should ignore noise paths [0.06ms]
-✓ DiffService > compareWithOptions > should handle special paths [0.13ms]
-✓ DiffService > fluent API > should support method chaining [0.34ms]
-✓ DiffService - parseNestedJson > should parse nested JSON strings when parseNestedJson option is true [0.61ms]
-✓ DiffService - parseNestedJson > should not parse nested JSON strings when parseNestedJson option is false or undefined [0.07ms]
-✓ DiffService - parseNestedJson > should handle deeply nested JSON strings [0.09ms]
-✓ DiffService - parseNestedJson > should handle arrays containing JSON strings [0.11ms]
-✓ DiffService - parseNestedJson > should handle mixed content with both JSON strings and regular strings [0.07ms]
-✓ DiffService - parseNestedJson > should not fail on invalid JSON strings [0.07ms]
-
-src/service/comparator/array/SequentialArrayComparator.test.ts:
-✓ SequentialArrayComparator > should compare arrays by index [0.13ms]
-✓ SequentialArrayComparator > should detect added elements [0.03ms]
-✓ SequentialArrayComparator > should detect deleted elements [0.04ms]
-
-src/service/comparator/array/SimilarArrayComparator.test.ts:
-✓ SimilarArrayComparator > should match similar elements [0.04ms]
-✓ SimilarArrayComparator > should detect modifications in matched elements [0.10ms]
-✓ SimilarArrayComparator > should detect added elements [0.05ms]
-
-src/service/comparator/primitive/DefaultPrimitiveComparator.test.ts:
-✓ DefaultPrimitiveComparator > should detect string changes
-✓ DefaultPrimitiveComparator > should detect number changes [0.12ms]
-✓ DefaultPrimitiveComparator > should detect boolean changes [0.02ms]
-✓ DefaultPrimitiveComparator > should not report identical primitives [0.03ms]
-
-src/service/comparator/other/DefaultOtherComparator.test.ts:
-✓ DefaultOtherComparator > should detect type changes from object to array
-✓ DefaultOtherComparator > should detect type changes from array to primitive [0.22ms]
-✓ DefaultOtherComparator > should detect undefined to value [0.02ms]
-✓ DefaultOtherComparator > should detect value to undefined [0.04ms]
-
-src/service/comparator/nulls/DefaultNullComparator.test.ts:
-✓ DefaultNullComparator > should not report differences for null vs null [0.23ms]
-✓ DefaultNullComparator > should detect null to value changes [0.16ms]
-✓ DefaultNullComparator > should detect value to null changes [0.03ms]
-
-src/service/comparator/object/UnionKeyObjectComparator.test.ts:
-✓ UnionKeyObjectComparator > should compare all keys from both objects [0.12ms]
-
-src/service/comparator/object/LeftJoinObjectComparator.test.ts:
-✓ LeftJoinObjectComparator > should only compare keys from left object [0.15ms]
-✓ LeftJoinObjectComparator > should detect changes in left keys [0.04ms]
-✓ LeftJoinObjectComparator > should detect missing keys in right object [0.03ms]
-
- 59 pass
- 0 fail
- 154 expect() calls
-Ran 59 tests across 10 files. [27.00ms]

package/.turbo/turbo-typecheck.log

@@ -1,2 +0,0 @@
-
-$ tsc --noEmit

package/src/contract/constant/DiffConstants.ts

@@ -1,10 +0,0 @@
-export const DIFFERENT = false;
-export const SAME = true;
-export const SPLIT_PATH = "\\.";
-export const MERGE_PATH = ".";
-
-export const OBJECT_NULL = null;
-export const TYPE_MODIFY = "MODIFY";
-export const TYPE_ADD = "ADD";
-export const TYPE_DELETE = "DELETE";
-

package/src/contract/constant/PresetName.ts

@@ -1,6 +0,0 @@
-export enum PresetName {
-  FullSmart = "fullSmart",
-  FullOrdered = "fullOrdered",
-  LeftSmart = "leftSmart",
-  LeftOrdered = "leftOrdered",
-}

package/src/contract/constant/index.ts

@@ -1,2 +0,0 @@
-export * from "./DiffConstants";
-export * from "./PresetName";

package/src/contract/index.ts

@@ -1,2 +0,0 @@
-export * from "./type";
-export * from "./constant";

package/src/contract/type/ArrayComparator.ts

@@ -1,15 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { JsonArray, JsonValue } from "./JsonTypes";
-import type { DiffContext } from "../../service/diff/DiffContext";
-import type { PathTracker } from "../../service/diff/PathTracker";
-
-export interface IArrayComparator {
-  diffArray(a: JsonArray, b: JsonArray, pathTracker: PathTracker): DiffContext;
-  diffElement(
-    a: JsonValue | undefined,
-    b: JsonValue | undefined,
-    pathTracker: PathTracker
-  ): DiffContext;
-}
-
-export const IArrayComparator = createIdentifier<IArrayComparator>("IArrayComparator");

package/src/contract/type/ComparatorOrchestrator.ts

@@ -1,16 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { JsonValue } from "./JsonTypes";
-import type { DiffContext } from "../../service/diff/DiffContext";
-import type { PathTracker } from "../../service/diff/PathTracker";
-import type { IArrayComparator } from "./ArrayComparator";
-
-export interface IComparatorOrchestrator {
-  diffElement(
-    a: JsonValue | undefined,
-    b: JsonValue | undefined,
-    pathTracker: PathTracker
-  ): DiffContext;
-  getArrayComparator(): IArrayComparator;
-}
-
-export const IComparatorOrchestrator = createIdentifier<IComparatorOrchestrator>("IComparatorOrchestrator");

package/src/contract/type/DiffService.ts

@@ -1,31 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { JsonValue } from "./JsonTypes";
-import type { Result } from "./Result";
-
-export interface IDiffService {
-  /**
-   * Diff two JSON strings
-   * @param leftJson - Left JSON string
-   * @param rightJson - Right JSON string
-   * @returns Array of differences
-   */
-  diffJson(leftJson: string, rightJson: string, options?: {
-    noisePath?: string[];
-    specialPath?: string[];
-    parseNestedJson?: boolean;
-  }): Result[];
-
-  /**
-   * Diff two JSON objects directly
-   * @param left - Left JSON value
-   * @param right - Right JSON value
-   * @returns Array of differences
-   */
-  diffElement(left: JsonValue, right: JsonValue, options?: {
-    noisePath?: string[];
-    specialPath?: string[];
-    parseNestedJson?: boolean;
-  }): Result[];
-}
-
-export const IDiffService = createIdentifier<IDiffService>("IDiffService");

package/src/contract/type/JsonTypes.ts

@@ -1,3 +0,0 @@
-export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
-export type JsonObject = { [key: string]: JsonValue };
-export type JsonArray = JsonValue[];

package/src/contract/type/NullComparator.ts

@@ -1,9 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { DiffContext } from "../../service/diff/DiffContext";
-import type { PathTracker } from "../../service/diff/PathTracker";
-
-export interface INullComparator {
-  diff(a: null, b: null, pathTracker: PathTracker): DiffContext;
-}
-
-export const INullComparator = createIdentifier<INullComparator>("INullComparator");

package/src/contract/type/ObjectComparator.ts

@@ -1,15 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { JsonObject, JsonValue } from "./JsonTypes";
-import type { DiffContext } from "../../service/diff/DiffContext";
-import type { PathTracker } from "../../service/diff/PathTracker";
-
-export interface IObjectComparator {
-  diff(a: JsonObject, b: JsonObject, pathTracker: PathTracker): DiffContext;
-  diffElement(
-    a: JsonValue | undefined,
-    b: JsonValue | undefined,
-    pathTracker: PathTracker
-  ): DiffContext;
-}
-
-export const IObjectComparator = createIdentifier<IObjectComparator>("IObjectComparator");

package/src/contract/type/OtherComparator.ts

@@ -1,14 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { JsonValue } from "./JsonTypes";
-import type { DiffContext } from "../../service/diff/DiffContext";
-import type { PathTracker } from "../../service/diff/PathTracker";
-
-export interface IOtherComparator {
-  diff(
-    a: JsonValue | undefined,
-    b: JsonValue | undefined,
-    pathTracker: PathTracker
-  ): DiffContext;
-}
-
-export const IOtherComparator = createIdentifier<IOtherComparator>("IOtherComparator");

package/src/contract/type/PrimitiveComparator.ts

@@ -1,13 +0,0 @@
-import { createIdentifier } from "@wendellhu/redi";
-import type { DiffContext } from "../../service/diff/DiffContext";
-import type { PathTracker } from "../../service/diff/PathTracker";
-
-export interface IPrimitiveComparator {
-  diff(
-    a: string | number | boolean,
-    b: string | number | boolean,
-    pathTracker: PathTracker
-  ): DiffContext;
-}
-
-export const IPrimitiveComparator = createIdentifier<IPrimitiveComparator>("IPrimitiveComparator");

package/src/contract/type/Result.ts

@@ -1,7 +0,0 @@
-export class Result {
-  leftPath: string | null = null;
-  rightPath: string | null = null;
-  left: unknown = null;
-  right: unknown = null;
-  diffType: string = "";
-}

package/src/contract/type/SingleNodeDifference.ts

@@ -1,13 +0,0 @@
-export class SingleNodeDifference {
-  leftPath: string;
-  rightPath: string;
-  left: unknown;
-  right: unknown;
-
-  constructor(leftPath: string, rightPath: string, left: unknown, right: unknown) {
-    this.leftPath = leftPath;
-    this.rightPath = rightPath;
-    this.left = left;
-    this.right = right;
-  }
-}

package/src/contract/type/index.ts

@@ -1,10 +0,0 @@
-export * from "./JsonTypes";
-export * from "./Result";
-export * from "./SingleNodeDifference";
-export * from "./ComparatorOrchestrator";
-export * from "./ObjectComparator";
-export * from "./ArrayComparator";
-export * from "./PrimitiveComparator";
-export * from "./NullComparator";
-export * from "./OtherComparator";
-export * from "./DiffService";

package/src/index.ts

@@ -1,17 +0,0 @@
-// Public API - Types
-export type { JsonValue, JsonObject, JsonArray } from "./contract/type/JsonTypes";
-export { Result } from "./contract/type/Result";
-export * from "./contract/type/DiffService";
-
-// Public API - Constants
-export {
-  TYPE_ADD,
-  TYPE_DELETE,
-  TYPE_MODIFY,
-} from "./contract/constant";
-
-// Public API - Enums
-export { PresetName } from "./contract/constant/PresetName";
-
-// Public API - Service
-export { DiffService } from "./service";

package/src/service/comparator/ComparatorOrchestrator.ts

@@ -1,50 +0,0 @@
-import { Inject } from "@wendellhu/redi";
-import {
-  type IComparatorOrchestrator,
-  type IObjectComparator,
-  IObjectComparator as IObjectComparatorToken,
-  type IArrayComparator,
-  IArrayComparator as IArrayComparatorToken,
-  type IPrimitiveComparator,
-  IPrimitiveComparator as IPrimitiveComparatorToken,
-  type INullComparator,
-  INullComparator as INullComparatorToken,
-  type IOtherComparator,
-  IOtherComparator as IOtherComparatorToken,
-  type JsonValue,
-} from "../../contract/type";
-import { DiffContext } from "../diff/DiffContext";
-import type { PathTracker } from "../diff/PathTracker";
-import { isJsonObject, isJsonArray, isJsonPrimitive, isJsonNull } from "../../util";
-
-export class ComparatorOrchestrator implements IComparatorOrchestrator {
-  constructor(
-    @Inject(IObjectComparatorToken) protected objectComparator: IObjectComparator,
-    @Inject(IArrayComparatorToken) protected arrayComparator: IArrayComparator,
-    @Inject(IPrimitiveComparatorToken) protected primitiveComparator: IPrimitiveComparator,
-    @Inject(INullComparatorToken) protected nullComparator: INullComparator,
-    @Inject(IOtherComparatorToken) protected otherComparator: IOtherComparator
-  ) {}
-
-  diffElement(
-    a: JsonValue | undefined,
-    b: JsonValue | undefined,
-    pathTracker: PathTracker
-  ): DiffContext {
-    if (isJsonObject(a) && isJsonObject(b)) {
-      return this.objectComparator.diff(a, b, pathTracker);
-    } else if (isJsonArray(a) && isJsonArray(b)) {
-      return this.arrayComparator.diffArray(a, b, pathTracker);
-    } else if (isJsonPrimitive(a) && isJsonPrimitive(b)) {
-      return this.primitiveComparator.diff(a, b, pathTracker);
-    } else if (isJsonNull(a) && isJsonNull(b)) {
-      return this.nullComparator.diff(a, b, pathTracker);
-    } else {
-      return this.otherComparator.diff(a, b, pathTracker);
-    }
-  }
-
-  getArrayComparator(): IArrayComparator {
-    return this.arrayComparator;
-  }
-}