@futdevpro/nts-dynamo 1.15.24 → 1.15.31

package/src/_services/base/data.service.spec.ts

@@ -489,5 +489,186 @@ describe('| DyNTS_DataService', () => {
       }).toThrow();
     });
   });
+
+  // ════════════════════════════════════════════════════════════════════════
+  // FR-001 — Generic compareData()
+  // ════════════════════════════════════════════════════════════════════════
+
+  describe('| compareData() — FR-001', (): void => {
+    let svc: DyNTS_DataService<TestMetadata>;
+
+    beforeEach((): void => {
+      // Re-use existing TestMetadata + testDataParams.
+      const t: TestMetadata = new TestMetadata();
+      svc = new DyNTS_DataService<TestMetadata>(t, testDataParams, 'test-issuer');
+    });
+
+    it('| equal POJO returns { result: "equal" } — sin changedFields', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'a@x' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'a@x' });
+      const r = svc.compareData(a, b);
+      expect(r.result).toBe('equal');
+      expect(r.changedFields).toBeUndefined();
+    });
+
+    it('| modified single field — changedFields tartalmazza azt', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'a@x' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'bob', email: 'a@x' });
+      const r = svc.compareData(a, b);
+      expect(r.result).toBe('modified');
+      expect(r.changedFields).toEqual(['name']);
+    });
+
+    it('| modified multi-field — changedFields TELJES listat ad (nem early-return)', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'a@x', userId: 'u1' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'bob', email: 'b@y', userId: 'u2' });
+      const r = svc.compareData(a, b);
+      expect(r.result).toBe('modified');
+      expect(r.changedFields?.sort()).toEqual(['email', 'name', 'userId'] as any);
+    });
+
+    it('| auto-discovery SKIP-eli a metadata fields-et (_id, __created, __lastModified)', (): void => {
+      const now: Date = new Date();
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', _id: 'X', __created: now, __lastModified: now });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', _id: 'Y', __created: new Date(2000, 0, 1), __lastModified: new Date(2001, 0, 1) });
+      const r = svc.compareData(a, b);
+      expect(r.result).toBe('equal');
+    });
+
+    it('| explicit fields override — KIFEJEZETT _id-val VIZSGALJA a skip-listet is', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', _id: 'X' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', _id: 'Y' });
+      const r = svc.compareData(a, b, { fields: ['_id' as keyof TestMetadata] });
+      expect(r.result).toBe('modified');
+      expect(r.changedFields).toEqual(['_id' as keyof TestMetadata]);
+    });
+
+    it('| explicit fields scope-szukit — csak a listazott fields szamit', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'a@x' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'b@y' });
+      const r = svc.compareData(a, b, { fields: ['name'] });
+      expect(r.result).toBe('equal');  // email change ignored, only 'name' checked
+    });
+
+    it('| customComparator override (case-insensitive string)', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'Alice' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice' });
+      const r = svc.compareData(a, b, {
+        customComparators: { name: (x: string, y: string) => x.toLowerCase() === y.toLowerCase() },
+      });
+      expect(r.result).toBe('equal');
+    });
+
+    it('| customComparator — array-set-equality eltero sorrendre', (): void => {
+      class WithArr extends DyFM_Metadata {
+        name?: string;
+        tags?: string[];
+      }
+      const arrSvc = new DyNTS_DataService<WithArr>(
+        new WithArr(),
+        new DyFM_DataModel_Params<WithArr>({
+          dataName: 'with_arr',
+          properties: { name: { key: 'name', type: DyFM_BasicProperty_Type.string } },
+        }),
+        'test-issuer',
+      );
+      const a: WithArr = Object.assign(new WithArr(), { name: 'x', tags: ['a', 'b', 'c'] });
+      const b: WithArr = Object.assign(new WithArr(), { name: 'x', tags: ['c', 'b', 'a'] });
+      const r = arrSvc.compareData(a, b, {
+        customComparators: {
+          tags: (x: string[], y: string[]) => {
+            const s: Set<string> = new Set<string>(x);
+            return y.length === x.length && y.every((v: string) => s.has(v));
+          },
+        },
+      });
+      expect(r.result).toBe('equal');
+    });
+
+    it('| deep-equal: Date instances ugyanazon time-stamp-pel equal-nek szamitanak', (): void => {
+      class WithDate extends DyFM_Metadata {
+        when?: Date;
+      }
+      const dateSvc = new DyNTS_DataService<WithDate>(
+        new WithDate(),
+        new DyFM_DataModel_Params<WithDate>({
+          dataName: 'with_date',
+          properties: {},
+        }),
+        'test-issuer',
+      );
+      const t: number = 1_700_000_000_000;
+      const a: WithDate = Object.assign(new WithDate(), { when: new Date(t) });
+      const b: WithDate = Object.assign(new WithDate(), { when: new Date(t) });
+      expect(dateSvc.compareData(a, b).result).toBe('equal');
+    });
+
+    it('| deep-equal: nested object', (): void => {
+      class WithNested extends DyFM_Metadata {
+        nested?: { a: number; b: { c: string } };
+      }
+      const nSvc = new DyNTS_DataService<WithNested>(
+        new WithNested(),
+        new DyFM_DataModel_Params<WithNested>({ dataName: 'with_nested', properties: {} }),
+        'test-issuer',
+      );
+      const a: WithNested = Object.assign(new WithNested(), { nested: { a: 1, b: { c: 'x' } } });
+      const b: WithNested = Object.assign(new WithNested(), { nested: { a: 1, b: { c: 'x' } } });
+      const c: WithNested = Object.assign(new WithNested(), { nested: { a: 1, b: { c: 'y' } } });
+      expect(nSvc.compareData(a, b).result).toBe('equal');
+      expect(nSvc.compareData(a, c).result).toBe('modified');
+    });
+
+    it('| deep-equal: array index-szerinti compare (eltero sorrend → modified default-ban)', (): void => {
+      class WithArr2 extends DyFM_Metadata {
+        items?: number[];
+      }
+      const aSvc = new DyNTS_DataService<WithArr2>(
+        new WithArr2(),
+        new DyFM_DataModel_Params<WithArr2>({ dataName: 'with_arr2', properties: {} }),
+        'test-issuer',
+      );
+      const a: WithArr2 = Object.assign(new WithArr2(), { items: [1, 2, 3] });
+      const b: WithArr2 = Object.assign(new WithArr2(), { items: [1, 2, 3] });
+      const c: WithArr2 = Object.assign(new WithArr2(), { items: [3, 2, 1] });
+      expect(aSvc.compareData(a, b).result).toBe('equal');
+      expect(aSvc.compareData(a, c).result).toBe('modified');
+    });
+
+    it('| throw 400 ha newData null', (): void => {
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'x' });
+      let thrown: any = null;
+      try { svc.compareData(null as any, b); } catch (e) { thrown = e; }
+      expect(thrown).not.toBeNull();
+      expect(DyFM_Error.getErrorStatus(thrown)).toBe(400);
+      expect(DyFM_Error.getErrorCode(thrown)).toContain('DyNTS-DS0-CD1');
+    });
+
+    it('| throw 400 ha oldData undefined', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'x' });
+      let thrown: any = null;
+      try { svc.compareData(a, undefined as any); } catch (e) { thrown = e; }
+      expect(thrown).not.toBeNull();
+      expect(DyFM_Error.getErrorStatus(thrown)).toBe(400);
+    });
+
+    it('| throw 400 ha options.fields ures array', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice' });
+      let thrown: any = null;
+      try { svc.compareData(a, b, { fields: [] }); } catch (e) { thrown = e; }
+      expect(thrown).not.toBeNull();
+      expect(DyFM_Error.getErrorStatus(thrown)).toBe(400);
+      expect(DyFM_Error.getErrorCode(thrown)).toContain('DyNTS-DS0-CD2');
+    });
+
+    it('| asymmetric keys: ha az egyik objektum-bol hianyzik a key, modified-nek szamit', (): void => {
+      const a: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice', email: 'a@x' });
+      const b: TestMetadata = Object.assign(new TestMetadata(), { name: 'alice' });  // no email
+      const r = svc.compareData(a, b);
+      expect(r.result).toBe('modified');
+      expect(r.changedFields).toEqual(['email']);
+    });
+  });
 });
 

package/src/_services/base/data.service.ts

@@ -29,11 +29,30 @@ import {
 
 import { DyNTS_getArchivedDBName } from '../../_collections/archive.util';
 import { DyNTS_global_settings } from '../../_collections/global-settings.const';
+import { DyNTS_CompareData_Options } from '../../_models/interfaces/compare-data-options.interface';
+import { DyNTS_CompareData_Result } from '../../_models/interfaces/compare-data-result.interface';
 import { DyNTS_DBUpdate } from '../../_models/types/db-update.type';
 import { DyNTS_GlobalService } from '../core/global.service';
 import { DyNTS_ArchiveDataService } from './archive-data.service';
 import { DyNTS_DBService } from './db.service';
 
+
+/**
+ * `DyFM_Metadata` field-ek amik auto-discovery modban (fields opcio nelkul)
+ * KI vannak hagyva a compareData()-bol. Ezek normal mukodes kozben kezelt
+ * mezok (id-allocation, audit timestamps, audit usernames) — szemantikus
+ * adatvaltozas-ellenorzeshez irrelevansak.
+ *
+ * Explicit `fields: ['_id']`-vel meg vizsgaltathato, ha valamiert kell.
+ */
+const COMPARE_DATA_METADATA_SKIP_FIELDS: ReadonlySet<string> = new Set<string>([
+  '_id',
+  '__created',
+  '__createdBy',
+  '__lastModified',
+  '__lastModifiedBy',
+]);
+
 // TODO: 2 type of archiving service system: within list, or separate db elements
 
 /**
@@ -2503,7 +2522,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
   }
 
   protected getDefaultErrorSettings(
-    fnName: string, 
+    fnName: string,
     error: DyFM_AnyError,
     /** @deprecated we wont support the separate user message in the future, use the message instead */
     useMessageAsUserMessage: boolean = true,
@@ -2514,7 +2533,7 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
         (error as DyFM_Error)?._message ??
         `${fnName} was UNSUCCESSFUL (${DyNTS_global_settings.systemShortCodeName})`,
       addECToUserMsg: !(error as DyFM_Error)?.__userMessage,
-      userMessage: (error as DyFM_Error)?.__userMessage ?? 
+      userMessage: (error as DyFM_Error)?.__userMessage ??
         (useMessageAsUserMessage ? (error as Error)?.message : this.defaultErrorUserMsg),
       issuer: this.issuer,
       issuerService: this.constructor?.name,
@@ -2522,4 +2541,179 @@ export class DyNTS_DataService<T extends DyFM_Metadata> {
       error: error,
     };
   }
+
+
+  // ════════════════════════════════════════════════════════════════════════
+  // GENERIC DATA COMPARE (FR-001)
+  // ════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Generic, field-szintu osszehasonlitas ket adat-objektum kozott.
+   *
+   * **Auto-discovery mod** (`options.fields` nelkul): a metodus mindket
+   * objektum kulcs-uniojan iter, KIVEVE a `DyFM_Metadata` skip-listet
+   * (`_id`, `__created`, `__createdBy`, `__lastModified`, `__lastModifiedBy`).
+   *
+   * **Scope-szukito mod** (`options.fields = [...]`): KIZAROLAG a felsorolt
+   * mezoket vizsgalja. A skip-list IGNORALODIK — explicit fields override.
+   *
+   * **Custom comparator** (`options.customComparators`): per-field override
+   * a default deep-equal helyett (pl. set-equality array-ekre,
+   * case-insensitive string compare-re). A custom function `true`-val signal-ozza
+   * az equality-t.
+   *
+   * **Return:** `'equal'` ha minden vizsgalt field egyezik; `'modified'` ha
+   * legalabb egy elter — ilyenkor `changedFields` tartalmazza a TELJES
+   * mismatch-listat (nem early-return).
+   *
+   * **Throws:**
+   * - `newData` vagy `oldData` null/undefined → `DyFM_Error(400, DyNTS-DS0-CD1)`
+   * - `options.fields = []` ures array → `DyFM_Error(400, DyNTS-DS0-CD2)`
+   *
+   * **Sync method** (nincs I/O szukseglet); a host wrappel-i ha async kell.
+   *
+   * @example
+   * const result = userService.compareData(newUser, oldUser);
+   * if (result.result === 'modified') {
+   *   console.log('Changed:', result.changedFields);
+   * }
+   *
+   * @example // Scope-szukites + custom comparator
+   * userService.compareData(newUser, oldUser, {
+   *   fields: ['email', 'roles'],
+   *   customComparators: {
+   *     roles: (a, b) => new Set(a).size === new Set([...a, ...b]).size,
+   *   },
+   * });
+   */
+  compareData(
+    newData: T,
+    oldData: T,
+    options?: DyNTS_CompareData_Options<T>,
+  ): DyNTS_CompareData_Result<T> {
+    // Input guard
+    if (newData === null || newData === undefined || oldData === null || oldData === undefined) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('compareData', new Error('newData/oldData required')),
+        status: 400,
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DS0-CD1`,
+        message: 'compareData: newData and oldData are required (both must be non-null/undefined)',
+      });
+    }
+
+    if (options?.fields !== undefined && options.fields.length === 0) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('compareData', new Error('options.fields must not be empty')),
+        status: 400,
+        errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-DS0-CD2`,
+        message: 'compareData: options.fields must not be an empty array',
+      });
+    }
+
+    const fieldsToCheck: (keyof T)[] = this._resolveCompareFields(newData, oldData, options);
+    const comparators: Partial<Record<keyof T, (a: any, b: any) => boolean>> =
+      options?.customComparators ?? {};
+
+    const changedFields: (keyof T)[] = [];
+    for (const field of fieldsToCheck) {
+      const a: any = (newData as any)[field];
+      const b: any = (oldData as any)[field];
+
+      const isEqual: boolean = comparators[field]
+        ? comparators[field]!(a, b)
+        : this._deepEqual(a, b);
+
+      if (!isEqual) {
+        changedFields.push(field);
+      }
+    }
+
+    if (changedFields.length === 0) {
+      return { result: 'equal' };
+    }
+    return { result: 'modified', changedFields: changedFields };
+  }
+
+  /**
+   * Eldonti az osszehasonlitando fields-listat:
+   * - explicit `options.fields` esetan annak masolata (skip-list ignoralt)
+   * - egyebkent `Object.keys(newData) UNION Object.keys(oldData)` minus skip-list
+   */
+  private _resolveCompareFields(
+    newData: T,
+    oldData: T,
+    options?: DyNTS_CompareData_Options<T>,
+  ): (keyof T)[] {
+    if (options?.fields !== undefined) {
+      // Explicit fields — copy-spread (defensive against caller mutation mid-flight)
+      return [...options.fields];
+    }
+
+    const keySet: Set<string> = new Set<string>();
+    for (const k of Object.keys(newData as object)) { keySet.add(k); }
+    for (const k of Object.keys(oldData as object)) { keySet.add(k); }
+
+    const result: (keyof T)[] = [];
+    for (const k of keySet) {
+      if (COMPARE_DATA_METADATA_SKIP_FIELDS.has(k)) { continue; }
+      result.push(k as keyof T);
+    }
+    return result;
+  }
+
+  /**
+   * Deep-equal helper.
+   *
+   * - Primitive (`string`/`number`/`boolean`/`null`/`undefined`): `===` / `Object.is`
+   *   (a `NaN === NaN` esetet `Object.is` kezeli helyesen)
+   * - `Date`: `.getTime()` egyenloseg (kulonbozo Date instance-ok same-time-mal egyenlonek)
+   * - Array: length + index-szerinti rekurziv deep-equal
+   * - POJO: keys-union + per-key rekurzio
+   * - Egyeb (RegExp / Map / Set / Buffer): `Object.is` fallback (reference compare)
+   *
+   * NEM kezelt: cyclic references — a hivo objektum-grafja flat / fa kell legyen
+   * (a tipikus FDP data-model esete; cycle eseten stack overflow lesz, ami ertelmes
+   * jelzes a programozonak).
+   */
+  private _deepEqual(a: any, b: any): boolean {
+    if (a === b) { return true; }
+    if (Object.is(a, b)) { return true; }
+
+    // Null/undefined es a masik nem ugyanaz → false
+    if (a === null || a === undefined || b === null || b === undefined) { return false; }
+
+    // Date
+    if (a instanceof Date && b instanceof Date) {
+      return a.getTime() === b.getTime();
+    }
+    if (a instanceof Date || b instanceof Date) { return false; }
+
+    // Array
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) { return false; }
+      for (let i: number = 0; i < a.length; i++) {
+        if (!this._deepEqual(a[i], b[i])) { return false; }
+      }
+      return true;
+    }
+    if (Array.isArray(a) || Array.isArray(b)) { return false; }
+
+    // POJO (Object.prototype) — keys union, per-key compare
+    if (typeof a === 'object' && typeof b === 'object') {
+      const keysA: string[] = Object.keys(a);
+      const keysB: string[] = Object.keys(b);
+      if (keysA.length !== keysB.length) { return false; }
+      const keysAset: Set<string> = new Set<string>(keysA);
+      for (const k of keysB) {
+        if (!keysAset.has(k)) { return false; }
+      }
+      for (const k of keysA) {
+        if (!this._deepEqual(a[k], b[k])) { return false; }
+      }
+      return true;
+    }
+
+    // Fallback (function, symbol, BigInt, stb.) — strict equality mar nem stimmelt
+    return false;
+  }
 }