@futdevpro/nts-dynamo 1.15.23 → 1.15.29

package/src/_modules/local-vector-search/_services/lvs-bm25.util.ts

@@ -0,0 +1,206 @@
+/**
+ * BM25 text-search ranking util a LVS hybrid search-hez (FR-004).
+ *
+ * Pure TypeScript, dependency-free. In-memory corpus alapjan szamol score-okat,
+ * NEM perzisztal indexet (a hybrid hivasonkent ujraepiti a corpus-t a candidate
+ * dokumentumokon — kis (~100..10000 dokumentum) LVS-corpus eseten ez gyors es
+ * egyszeru).
+ *
+ * Canonical params: k1=1.2, b=0.75 (industry standard a "lucene-szeru"
+ * implementaciokban). NEM expose-oltak — ha kell, FR-002 kovetkezo iteracioban
+ * tehetjuk parameterizalhatova.
+ *
+ * Tokenizer: `text.toLowerCase().match(/\w+/g) || []`. Case-insensitive,
+ * alphanumeric+underscore boundary-k. `UserController` egy token marad (jo az
+ * identifier match-re), `auth-flow` ket tokenre esik (auth + flow).
+ *
+ * IDF formula (BM25+): `log((N - df + 0.5) / (df + 0.5) + 1)`. A +1 a logon
+ * belul garantalja, hogy a kozos szavak is pozitiv (kicsi) IDF-et kapjanak,
+ * NEM negativ-t — fontos a hybrid score-merge-nel hogy ne huzzon le dokumentumot
+ * ahol kozos szo szerepel.
+ */
+
+
+/** BM25 k1 parameter (term saturation control). Canonical default. */
+const BM25_K1: number = 1.2;
+
+/** BM25 b parameter (length normalization weight, 0=off, 1=full). Canonical default. */
+const BM25_B: number = 0.75;
+
+/** Token regex — alphanumeric + underscore. */
+const TOKEN_REGEX: RegExp = /\w+/g;
+
+
+/**
+ * Egy dokumentum BM25-score-ja egy query ellen, egy elore-felepitett corpus
+ * konteztusaban.
+ */
+export interface DyNTS_LVS_BM25_DocScore {
+  /** Dokumentum azonosito (mint az LVS_SearchResult `id`-jaben). */
+  id: string;
+  /** Nyers BM25 score (0..∞). NEM normalizalt. */
+  score: number;
+}
+
+
+/**
+ * Felepitett BM25 corpus — egy adott dokumentumhalmaz indexe. A `score()` az
+ * indexen kerdez le egy query-t es minden dokumentumra ad egy score-t.
+ *
+ * Egy corpus egyszer-hasznalatos a hybrid search hivasban — NEM kell cache-elni,
+ * a felepites O(N * |doc|) ami pici N-re elhanyagolhato.
+ */
+export class DyNTS_LVS_BM25_Corpus {
+
+  /** Tokenizalt dokumentumok: id -> tokens. */
+  private readonly docTokens: Map<string, string[]> = new Map<string, string[]>();
+  /** Doc-length: id -> token count. */
+  private readonly docLengths: Map<string, number> = new Map<string, number>();
+  /** Term -> doc-frequency (hany docban szerepel az adott term, legalabb 1x). */
+  private readonly termDocFreq: Map<string, number> = new Map<string, number>();
+  /** Term -> id -> term-frequency a docban. */
+  private readonly termFreqByDoc: Map<string, Map<string, number>> = new Map<string, Map<string, number>>();
+  /** Atlagos dokumentum-hossz (token count). */
+  private avgDocLength: number = 0;
+  /** Total doc count. */
+  private docCount: number = 0;
+
+  /**
+   * Letrehoz egy uj corpus-t a megadott id->text parok-bol.
+   * NEM dob hibat ures input-ra — ures corpus ervenyes (minden score = 0).
+   */
+  constructor(docs: { id: string; text: string }[]) {
+    if (!Array.isArray(docs) || docs.length === 0) { return; }
+
+    let totalLength: number = 0;
+    for (const doc of docs) {
+      if (!doc || typeof doc.id !== 'string' || typeof doc.text !== 'string') { continue; }
+      const tokens: string[] = DyNTS_LVS_BM25_Corpus.tokenize(doc.text);
+      this.docTokens.set(doc.id, tokens);
+      this.docLengths.set(doc.id, tokens.length);
+      totalLength += tokens.length;
+
+      // Term-frequency a docban
+      const localTf: Map<string, number> = new Map<string, number>();
+      for (const tok of tokens) {
+        localTf.set(tok, (localTf.get(tok) ?? 0) + 1);
+      }
+
+      for (const [term, tf] of localTf) {
+        // Doc-frequency: +1 per term, per doc
+        this.termDocFreq.set(term, (this.termDocFreq.get(term) ?? 0) + 1);
+        // Term-freq-by-doc reverse index
+        let perDoc: Map<string, number> | undefined = this.termFreqByDoc.get(term);
+        if (!perDoc) {
+          perDoc = new Map<string, number>();
+          this.termFreqByDoc.set(term, perDoc);
+        }
+        perDoc.set(doc.id, tf);
+      }
+    }
+
+    this.docCount = this.docTokens.size;
+    this.avgDocLength = this.docCount > 0 ? totalLength / this.docCount : 0;
+  }
+
+
+  /**
+   * Public tokenizer — exportalt, hogy spec-ek + hivok ugyanazt a normalizalast
+   * tudjak hasznalni mint a corpus.
+   */
+  static tokenize(text: string): string[] {
+    if (typeof text !== 'string' || text.length === 0) { return []; }
+    return text.toLowerCase().match(TOKEN_REGEX) ?? [];
+  }
+
+
+  /**
+   * Visszaadja a corpus dokumentum-szamat (NEM-ures docok).
+   */
+  size(): number {
+    return this.docCount;
+  }
+
+
+  /**
+   * BM25 score minden dokumentumra a query-re.
+   *
+   * Ures query → minden score 0 (degenerate case; a hivo kezelje ha kell).
+   * Ures corpus → ures array.
+   */
+  score(query: string): DyNTS_LVS_BM25_DocScore[] {
+    if (this.docCount === 0) { return []; }
+    const queryTokens: string[] = DyNTS_LVS_BM25_Corpus.tokenize(query);
+    if (queryTokens.length === 0) {
+      // Minden doc 0 score-t kap
+      const results: DyNTS_LVS_BM25_DocScore[] = [];
+      for (const id of this.docTokens.keys()) {
+        results.push({ id: id, score: 0 });
+      }
+      return results;
+    }
+
+    // Egyedi query-termek halmaza (ismetlodes nem ad nagyobb IDF-et)
+    const uniqueTerms: string[] = Array.from(new Set<string>(queryTokens));
+
+    // Pre-compute IDF a query-termekre
+    const idfMap: Map<string, number> = new Map<string, number>();
+    for (const term of uniqueTerms) {
+      const df: number = this.termDocFreq.get(term) ?? 0;
+      // BM25+ IDF: log((N - df + 0.5) / (df + 0.5) + 1)
+      const idf: number = Math.log((this.docCount - df + 0.5) / (df + 0.5) + 1);
+      idfMap.set(term, idf);
+    }
+
+    // Per-doc BM25 score
+    const results: DyNTS_LVS_BM25_DocScore[] = [];
+    for (const [docId, docLen] of this.docLengths) {
+      let score: number = 0;
+      for (const term of uniqueTerms) {
+        const tf: number = this.termFreqByDoc.get(term)?.get(docId) ?? 0;
+        if (tf === 0) { continue; }
+        const idf: number = idfMap.get(term) ?? 0;
+        const norm: number = 1 - BM25_B + BM25_B * (docLen / (this.avgDocLength || 1));
+        score += idf * (tf * (BM25_K1 + 1)) / (tf + BM25_K1 * norm);
+      }
+      results.push({ id: docId, score: score });
+    }
+
+    return results;
+  }
+}
+
+
+/**
+ * Min-max normalizalas [0,1] tartomanyra. A hybrid score-merge-hez kell a BM25
+ * score-okat a candidate-szetten 0..1 sav-ba hozni (a cosine mar 0..1).
+ *
+ * Edge case-ek:
+ *  - Ures array → [].
+ *  - Minden score azonos (max-min === 0) → minden 0.0 (NEM 0.5 vagy 1.0; ha
+ *    nincs diszkriminacio, ne tegyunk hozza signal-t).
+ *  - Negativ score-ok (BM25+IDF garantal pozitivat, de defensive): a min-max
+ *    ugyanugy mukodik.
+ */
+export function dyNTS_LVS_BM25_minMaxNormalize(
+  scores: DyNTS_LVS_BM25_DocScore[],
+): DyNTS_LVS_BM25_DocScore[] {
+  if (!Array.isArray(scores) || scores.length === 0) { return []; }
+  let min: number = Infinity;
+  let max: number = -Infinity;
+  for (const s of scores) {
+    if (s.score < min) { min = s.score; }
+    if (s.score > max) { max = s.score; }
+  }
+  const range: number = max - min;
+  if (range === 0) {
+    // Nincs diszkriminacio — minden 0.0 (NEM huzzon le, NEM huzzon fel)
+    return scores.map((s: DyNTS_LVS_BM25_DocScore): DyNTS_LVS_BM25_DocScore => ({
+      id: s.id, score: 0,
+    }));
+  }
+  return scores.map((s: DyNTS_LVS_BM25_DocScore): DyNTS_LVS_BM25_DocScore => ({
+    id: s.id,
+    score: (s.score - min) / range,
+  }));
+}

package/src/_modules/local-vector-search/_services/lvs-local-vector-search.data-service.spec.ts

@@ -341,5 +341,140 @@ describe('| DyNTS_LVS_VectorDataService', () => {
       expect(result[1]._id).toBe('data-1');
     });
   });
+
+  describe('| vectorSearch hybrid (FR-004)', () => {
+    const buildHybridCorpus = (): TestDataModel[] => {
+      const d1: TestDataModel = new TestDataModel();
+      d1._id = 'doc-user';
+      d1.content = 'the UserController handles authentication flow';
+      d1.contentVectorized = [0.4, 0.5, 0.6];
+      const d2: TestDataModel = new TestDataModel();
+      d2._id = 'doc-recipe';
+      d2.content = 'cooking recipes for desserts and cakes';
+      d2.contentVectorized = [0.45, 0.55, 0.65];
+      const d3: TestDataModel = new TestDataModel();
+      d3._id = 'doc-db';
+      d3.content = 'database setup guide for MongoDB';
+      d3.contentVectorized = [0.42, 0.52, 0.62];
+      return [d1, d2, d3];
+    };
+
+    it('| throws ha textSearchKey hianyzik hybrid modban (VS4)', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.4, 0.5, 0.6]));
+      try {
+        await service.vectorSearch({
+          input: 'UserController',
+          searchInKey: 'contentVectorized',
+          searchMode: LVS_Search_Mode.hybrid,
+        });
+        fail('Should have thrown an error');
+      } catch (err) {
+        expect(err).toBeInstanceOf(DyFM_Error);
+        expect((err as DyFM_Error)._errorCode).toContain('DyNTS-LVS-VS4');
+      }
+    });
+
+    it('| throws ha hybridWeight invalid (negativ) (VS5)', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.4, 0.5, 0.6]));
+      try {
+        await service.vectorSearch({
+          input: 'UserController',
+          searchInKey: 'contentVectorized',
+          searchMode: LVS_Search_Mode.hybrid,
+          textSearchKey: 'content',
+          hybridWeight: { vector: -0.5, text: 1.5 },
+        });
+        fail('Should have thrown an error');
+      } catch (err) {
+        expect(err).toBeInstanceOf(DyFM_Error);
+        expect((err as DyFM_Error)._errorCode).toContain('DyNTS-LVS-VS5');
+      }
+    });
+
+    it('| basic hybrid: text-relevant doc top-en', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.4, 0.5, 0.6]));
+      const result: TestDataModel[] = await service.vectorSearch({
+        input: 'UserController',
+        searchInKey: 'contentVectorized',
+        searchMode: LVS_Search_Mode.hybrid,
+        textSearchKey: 'content',
+        limit: 3,
+      });
+      expect(result.length).toBe(3);
+      expect(result[0]._id).toBe('doc-user');
+    });
+
+    it('| weight {vector:1, text:0} → effektivan pure cosine', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.42, 0.52, 0.62]));
+      const result: TestDataModel[] = await service.vectorSearch({
+        input: 'UserController',
+        searchInKey: 'contentVectorized',
+        searchMode: LVS_Search_Mode.hybrid,
+        textSearchKey: 'content',
+        hybridWeight: { vector: 1, text: 0 },
+        limit: 3,
+      });
+      expect(result.length).toBe(3);
+      expect(result[0]._id).toBe('doc-db');
+    });
+
+    it('| weight {vector:0, text:1} → effektivan pure BM25', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.45, 0.55, 0.65]));
+      const result: TestDataModel[] = await service.vectorSearch({
+        input: 'authentication',
+        searchInKey: 'contentVectorized',
+        searchMode: LVS_Search_Mode.hybrid,
+        textSearchKey: 'content',
+        hybridWeight: { vector: 0, text: 1 },
+        limit: 3,
+      });
+      expect(result.length).toBe(3);
+      expect(result[0]._id).toBe('doc-user');
+    });
+
+    it('| all-zero BM25 fallback → cosine-rendezes marad', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.45, 0.55, 0.65]));
+      const result: TestDataModel[] = await service.vectorSearch({
+        input: 'xyzzy-nonexistent-token',
+        searchInKey: 'contentVectorized',
+        searchMode: LVS_Search_Mode.hybrid,
+        textSearchKey: 'content',
+        limit: 3,
+      });
+      expect(result.length).toBe(3);
+      expect(result[0]._id).toBe('doc-recipe');
+    });
+
+    it('| limit honored hybrid modban', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve(buildHybridCorpus()));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.4, 0.5, 0.6]));
+      const result: TestDataModel[] = await service.vectorSearch({
+        input: 'UserController',
+        searchInKey: 'contentVectorized',
+        searchMode: LVS_Search_Mode.hybrid,
+        textSearchKey: 'content',
+        limit: 1,
+      });
+      expect(result.length).toBe(1);
+    });
+
+    it('| ures candidate-szet → ures eredmeny', async () => {
+      spyOn(service, 'getAll').and.returnValue(Promise.resolve([]));
+      spyOn(service, 'vectorize').and.returnValue(Promise.resolve([0.4, 0.5, 0.6]));
+      const result: TestDataModel[] = await service.vectorSearch({
+        input: 'UserController',
+        searchInKey: 'contentVectorized',
+        searchMode: LVS_Search_Mode.hybrid,
+        textSearchKey: 'content',
+      });
+      expect(result.length).toBe(0);
+    });
+  });
 });
 

package/src/_modules/local-vector-search/_services/lvs-local-vector-search.data-service.ts

@@ -10,6 +10,11 @@ import { DyFM_OAI_Settings } from '@futdevpro/fsm-dynamo/ai/open-ai';
 import { LVS_Search_Mode } from '../_enums/lvs-search-mode.enum';
 import { LVS_SearchResult } from '../_models/lvs-search-result.interface';
 import { LVS_VectorPool_ControlService } from './lvs-vector-pool.control-service';
+import {
+  DyNTS_LVS_BM25_Corpus,
+  DyNTS_LVS_BM25_DocScore,
+  dyNTS_LVS_BM25_minMaxNormalize,
+} from './lvs-bm25.util';
 import { DyNTS_OAI_VectorDataService } from '../../ai/_modules/open-ai/_services/data-services/oai-vector-data.service';
 import { DyNTS_global_settings } from '../../../_collections/global-settings.const';
 
@@ -109,10 +114,23 @@ export class DyNTS_LVS_VectorDataService<T extends DyFM_Metadata> extends DyNTS_
        */
       filterBy?: DyFM_DBFilter<T>;
       /**
-       * Search mode (cosine similarity or L2 distance)
-       * Defaults to this.defaultSearchMode
+       * Search mode (cosine similarity, L2 distance, or hybrid).
+       * Defaults to this.defaultSearchMode.
+       *
+       * `hybrid` mode combines cosine similarity (vector half) with BM25
+       * text scoring (text half) — `textSearchKey` is REQUIRED in hybrid mode.
        */
       searchMode?: LVS_Search_Mode;
+      /**
+       * Csak `hybrid` modban — weighted score-merge a cosine es a BM25 kozott.
+       * Default: { vector: 0.5, text: 0.5 }. Mindkettonek 0..1 tartomany javasolt.
+       */
+      hybridWeight?: { vector: number; text: number };
+      /**
+       * Csak `hybrid` modban — KOTELEZO; melyik string property-n fut a BM25
+       * text-search. NEM kell hogy a vectorized property legyen.
+       */
+      textSearchKey?: keyof T;
     },
   ): Promise<T[]> {
     try {
@@ -127,7 +145,33 @@ export class DyNTS_LVS_VectorDataService<T extends DyFM_Metadata> extends DyNTS_
       }
 
       set.limit ??= 3;
-      const { input, searchInKey, limit, filterBy, searchMode } = set;
+      const { input, searchInKey, limit, filterBy, searchMode, hybridWeight, textSearchKey } = set;
+      const effectiveMode: LVS_Search_Mode = searchMode ?? this.defaultSearchMode;
+
+      // Hybrid mode korai validacio
+      if (effectiveMode === LVS_Search_Mode.hybrid) {
+        if (!textSearchKey) {
+          throw new DyFM_Error({
+            ...this.getDefaultErrorSettings(
+              'vectorSearch',
+              new Error('textSearchKey is required when searchMode is hybrid'),
+            ),
+            errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-LVS-VS4`,
+          });
+        }
+        if (hybridWeight) {
+          const w: { vector: number; text: number } = hybridWeight;
+          if (!Number.isFinite(w.vector) || !Number.isFinite(w.text) || w.vector < 0 || w.text < 0) {
+            throw new DyFM_Error({
+              ...this.getDefaultErrorSettings(
+                'vectorSearch',
+                new Error('hybridWeight.vector and .text must be non-negative finite numbers'),
+              ),
+              errorCode: `${DyNTS_global_settings.systemShortCodeName}|DyNTS-LVS-VS5`,
+            });
+          }
+        }
+      }
 
       // Validáljuk, hogy a searchInKey létezik-e
       const property: DyFM_DataProperty_Params<any, T> = 
@@ -250,7 +294,7 @@ export class DyNTS_LVS_VectorDataService<T extends DyFM_Metadata> extends DyNTS_
       );
 
       // 4. Végrehajtjuk a local vector search-t
-      const mode: LVS_Search_Mode = searchMode ?? this.defaultSearchMode;
+      const mode: LVS_Search_Mode = effectiveMode;
 
       if (this.debugLog) {
         DyFM_Log.log(
@@ -258,11 +302,53 @@ export class DyNTS_LVS_VectorDataService<T extends DyFM_Metadata> extends DyNTS_
         );
       }
 
-      const searchResults: LVS_SearchResult[] = this.vectorPool.search(
-        queryVector,
-        limit,
-        mode
-      );
+      let searchResults: LVS_SearchResult[];
+
+      if (mode === LVS_Search_Mode.hybrid) {
+        // Hybrid: cosine ALL candidate-re + BM25 ALL candidate-re + min-max norm + weighted sum
+        const allCandidatesCosine: LVS_SearchResult[] = this.vectorPool.search(
+          queryVector,
+          dataMap.size,
+          LVS_Search_Mode.cosineSimilarity,
+        );
+
+        // BM25 corpus epitese a `textSearchKey` property-bol
+        const docs: { id: string; text: string }[] = [];
+        for (const [docId, dataItem] of dataMap) {
+          const textValue: unknown = dataItem[textSearchKey as keyof T];
+          docs.push({
+            id: docId,
+            text: typeof textValue === 'string' ? textValue : '',
+          });
+        }
+        const bm25Corpus: DyNTS_LVS_BM25_Corpus = new DyNTS_LVS_BM25_Corpus(docs);
+        const bm25Raw: DyNTS_LVS_BM25_DocScore[] = bm25Corpus.score(input);
+        const bm25Normalized: DyNTS_LVS_BM25_DocScore[] = dyNTS_LVS_BM25_minMaxNormalize(bm25Raw);
+
+        const bm25ScoreById: Map<string, number> = new Map<string, number>();
+        for (const s of bm25Normalized) {
+          bm25ScoreById.set(s.id, s.score);
+        }
+
+        const wVector: number = hybridWeight?.vector ?? 0.5;
+        const wText: number = hybridWeight?.text ?? 0.5;
+
+        const merged: LVS_SearchResult[] = allCandidatesCosine.map((c: LVS_SearchResult): LVS_SearchResult => {
+          const bm25Score: number = bm25ScoreById.get(c.id) ?? 0;
+          return {
+            id: c.id,
+            score: wVector * c.score + wText * bm25Score,
+          };
+        });
+        merged.sort((a: LVS_SearchResult, b: LVS_SearchResult) => b.score - a.score);
+        searchResults = merged.slice(0, limit);
+      } else {
+        searchResults = this.vectorPool.search(
+          queryVector,
+          limit,
+          mode,
+        );
+      }
 
       if (this.debugLog) {
         DyFM_Log.log(

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']);
+    });
+  });
 });