Skip to content

@memberjunction/record-comparison

Framework-agnostic record comparison primitive for MemberJunction.

RecordComparisonEngine loads a set of records for a single entity and computes a structured, field-level delta between them — a survivor candidate plus its potential matches diffed column-by-column. It performs one read-only load (RunView with ResultType: 'simple' and a targeted field list) and never mutates records.

It is one piece of MJ’s duplicate management feature. The end-to-end picture — detection, LLM reasoning, review and merging — is in the Duplicate Management Guide.

The comparison logic is needed by two callers that sit on opposite sides of the dependency graph:

  • The LLM duplicate-detection reasoning path (@memberjunction/ai-vector-dupe), whose MatchedSetDeltaBuilder feeds the differing-field deltas of a matched set to the reasoning provider as context.
  • The side-by-side comparison panel in the UI (@memberjunction/ng-record-merge, used by the entity grid’s merge flow), which reaches the engine through the RecordComparison.Compare Remote Operation this package registers.

@memberjunction/core-entities-server depends on @memberjunction/ai-vector-dupe, so the dupe package sits lower in the graph and cannot reach an engine that lives in a server package without a build cycle. Hoisting the engine into this low-level package (it depends only on @memberjunction/core, @memberjunction/core-entities and @memberjunction/global) gives both sides one implementation, no cycle, and no duplicated delta logic.

import { RecordComparisonEngine } from '@memberjunction/record-comparison';
import { CompositeKey } from '@memberjunction/core';
const engine = new RecordComparisonEngine();
// By entity name — resolves the entity from the (request-scoped) provider's metadata.
const result = await engine.CompareRecords(
{ EntityName: 'Accounts', Keys: [survivorKey, candidateKey] },
contextUser,
provider // request-scoped IMetadataProvider (multi-provider safety)
);
// With an already-resolved EntityInfo and an injected RunView (the dupe path) — skips the
// by-name lookup and reuses the caller's request-scoped RunView.
const result2 = await engine.CompareRecordsForEntity(
entityInfo,
[sourceKey, ...candidateKeys],
contextUser,
{ RunViewInstance: runView, IncludeFields: ['Name', 'Email', 'Phone'] }
);
if (result.Success) {
for (const field of result.Fields.filter(f => f.Differs)) {
console.log(field.DisplayName, field.Cells.map(c => c.Value));
}
}

The engine never throws for ordinary failures: check result.Success and read result.ErrorMessage.

From any client: the RecordComparison.Compare Remote Operation

Section titled “From any client: the RecordComparison.Compare Remote Operation”

This package registers RecordComparisonCompareServerOperation under the operation key RecordComparison.Compare. The typed client base, RecordComparisonCompareOperation, is generated into @memberjunction/core-entities, so the browser calls the same contract over the generic remote-operation transport — there is no bespoke resolver or GraphQL client:

import { RecordComparisonCompareOperation } from '@memberjunction/core-entities';
const op = new RecordComparisonCompareOperation();
const result = await op.Execute(
{
EntityName: 'Accounts',
Keys: [
{ KeyValuePairs: [{ FieldName: 'ID', Value: survivorId }] },
{ KeyValuePairs: [{ FieldName: 'ID', Value: candidateId }] },
],
},
{ provider: this.ProviderToUse }
);
if (result.Success && result.Output) {
const { Records, Fields } = result.Output;
}

In Angular, RecordComparisonService.GetRecordComparison() in @memberjunction/ng-record-merge wraps exactly this call. The operation runs as the calling user, so entity permissions and row-level security apply to the records it loads. Make sure the server bootstrap loads this package (LoadRecordComparisonCompareOperation() is the tree-shaking anchor) so the registration exists.

RuleDetail
Field setThe IncludeFields list (case-insensitive) when given; otherwise every field except primary keys and __mj_* system columns.
Field orderName fields first, then DefaultInView fields, then by Sequence, then by name.
Reference columnKeys[0] is the reference (the survivor candidate). Every other record’s cell carries EqualsReference.
EqualityTrimmed, case-insensitive string comparison; null equals only null/undefined.
Empty fieldsA field whose value is empty in every record is dropped — it carries no signal.
Differstrue when any cell differs from the reference.
Record labelThe first name field’s value, falling back to the key’s values.
LoadingOne RunView that ORs every key’s WHERE clause, MaxRows = number of keys, run as the context user. Works for single-column and composite keys of any column name.
interface RecordComparisonResult {
Success: boolean;
ErrorMessage?: string;
EntityName: string;
Records: RecordComparisonRecord[]; // one per input key, ColumnIndex aligned with Keys
Fields: RecordComparisonFieldDelta[]; // one per compared, non-empty field
}
interface RecordComparisonFieldDelta {
FieldName: string;
DisplayName: string;
Category: string | null;
Cells: { ColumnIndex: number; Value: string | number | boolean | null; EqualsReference: boolean }[];
Differs: boolean;
}

Fields is a plain-data delta matrix (no BaseEntity instances), so it serializes cleanly over the wire and into a reasoning prompt.

Field-level security. The engine loads values as the context user, so a field the user may not read never reaches them. The duplicate-reasoning path additionally drops fields that any role is restricted from (GetIndexRestrictedFieldNames), because its prompt and stored reasoning are read by everyone who can see the duplicate run — see MatchedSetDeltaBuilder in @memberjunction/ai-vector-dupe.

Terminal window
pnpm run build
pnpm run test

Business Source License 1.1 — see LICENSE for details.