@futdevpro/nts-dynamo 1.15.23 → 1.15.29

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;
+  }
 }