@finnair/diff

Diff & VersionInfo

@finnair/diff library offers paths and values (Map<Path, any>) based configurable object difference utility. Use Diff class to analyze differences of two objects, or Versioninfo to compare and transform two versions of the same object.

Diff supports only primitive, array and plain object values.

JSON serialization of VersionInfo offers nice representation of the new version (current) with changedPaths and configurable set of old values (previous). Old values are useful for example in cases where natural identifier of an object changes and the old identifier is needed for targeting an update. VersionInfo is great for change based triggers configurable by a PathMatcher.

Getting Started

Install v-validation using yarn:

yarn add @finnair/diff

Or npm:

npm install @finnair/diff

Features

Changeset

Diff.changeset<T>(a:T, b: T) analyzes changes between a and b and returns a Map<string, Change> of changed paths to Change objects. A Change object contains a path (as Path), oldValue and newValue. Changeset can be used to patch/revert changes with Path.set:

const diff = new Diff();
const a = {...};
const b = {...};
// patch a into b - for revert, use set change.oldValue
diff.changeset(a, b).forEach((change) => change.path.set(a, change.newValue));

Change Triggering

VersionInfo.matches and matchesAny can be used to trigger functionality based on what has changed. Use PathMatcher to specify paths of interest.

Filtering

Diff has a configurable filter that can be used to include/exclude properties/values. This can be used to for example exclude metadata fields from changeset. The default filter excludes undefined values.

Mapping/Transforming

VersionInfo supports both sync and async transformations. Both old and new values are transformed and the resulting VersionInfo reflects the changes of transformed objects. This helps in conversions from internal to external model.

Nice JSON

VersionInfo is designed to be serialized as JSON. It contains the current value, changedPaths and configurable old values as previous. Only matching previous values are included and only if they have changed.

Changelog

7.0.0-alpha.4 (2024-11-14)

Features

• type guards to verify validator and existing type equality (#119) (92699e7)