@futdevpro/fsm-dynamo 1.15.18 → 1.15.20

package/src/_models/data-models/errors.data-model.ts

@@ -1,92 +1,149 @@
-import { DyFM_DataModel_Params } from '../control-models/data-model-params.control-model';
-import { DyFM_ErrorLevel } from '../../_enums/error-level.enum';
-import { DyFM_Error } from '../control-models/error.control-model';
-import { DyFM_Metadata } from './metadata.data-model';
-
-
-export const DyFM_errorsFlag = 'DyFM-ERRORS-OBJECT';
-
-/**
- * This obj is the saved version of the DyFM_Error object.
- * It is used to store the error in the database and its statistics.
- * 
- * @example
- * ```ts
- * const errors: DyFM_Errors<DyFM_Error> = new DyFM_Errors({
- *   message: 'Error message',
- *   error: new DyFM_Error({
- *     message: 'Error message',
- *   }),
- * });
- * ```
- */
-export class DyFM_Errors<T_Error extends DyFM_Error> extends DyFM_Metadata {
-  readonly flag?: string = DyFM_errorsFlag;
-
-  source?: string;
-  issuer?: string;
-  username?: string;
-  /** In which system versions this error occurred. */
-  versions?: string[] = [];
-  localTime?: string;
-  region?: string;
-
-  message?: string;
-  exception?: string;
-  exceptionObj?: any;
-
-  stackTrace?: string[] = [];
-  error?: any;
-
-  count?: number = 1;
-  
-  d_error?: T_Error;
-
-  additionalContent?: any;
-
-  level?: DyFM_ErrorLevel;
-  priority?: number;
-  duplications?: DyFM_Errors<T_Error>[] = [];
-
-  constructor(
-    set?: DyFM_Errors<T_Error>
-  ) {
-    super(set);
-    
-    if (set) {
-      Object.assign(this, set);
-    }
-  }
-}
-
-export const DyFM_errors_dataParams: DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>> = 
-  new DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>>({
-    dataName: 'errors',
-    properties: {
-      flag: { type: 'string' },
-
-      issuer: { type: 'string' },
-      username: { type: 'string' },
-      versions: { type: 'string[]' },
-
-      localTime: { type: 'string' },
-      region: { type: 'string' },
-
-      message: { type: 'string' },
-      exception: { type: 'string' },
-      exceptionObj: { type: 'any' },
-
-      stackTrace: { type: 'string[]' },
-      error: { type: 'any' },
-
-      count: { type: 'number' },
-
-      d_error: { type: 'DyFM_Error' },
-
-      additionalContent: { type: 'any' },
-
-      level: { type: 'DyFM_ErrorLevel' },
-      priority: { type: 'number' },
-      duplications: { type: 'DyNTS_Error[]' },
-    },
+import { DyFM_DataModel_Params } from '../control-models/data-model-params.control-model';
+import { DyFM_ErrorLevel } from '../../_enums/error-level.enum';
+import { DyFM_Error } from '../control-models/error.control-model';
+import { DyFM_Metadata } from './metadata.data-model';
+
+
+export const DyFM_errorsFlag = 'DyFM-ERRORS-OBJECT';
+
+
+/**
+ * Single fix-attempt entry on an error record. Append-only — every call to the
+ * `recordFixAttempt` data-service method adds a new entry to `fixAttempts[]`.
+ *
+ * Intended use: after diagnosing the root cause of an error and shipping a fix,
+ * mark the error with the hypothesis + target version. If a NEW occurrence of
+ * the same error then arrives carrying a version >= this attempt's version,
+ * the dedup branch of `recordError` flips `regressedAfterFix: true` — the
+ * dashboard can highlight it as a failed hypothesis worth re-investigating.
+ */
+export interface DyFM_Errors_FixAttempt {
+  /** When the fix was claimed. */
+  at: Date | string;
+  /** Issuer / username who claimed the fix. */
+  by: string;
+  /** The app version that contains the claimed fix (e.g. `01.15.117`). */
+  version: string;
+  /** Plain-text root-cause hypothesis that justified the fix. */
+  hypothesis: string;
+}
+
+/**
+ * This obj is the saved version of the DyFM_Error object.
+ * It is used to store the error in the database and its statistics.
+ * 
+ * @example
+ * ```ts
+ * const errors: DyFM_Errors<DyFM_Error> = new DyFM_Errors({
+ *   message: 'Error message',
+ *   error: new DyFM_Error({
+ *     message: 'Error message',
+ *   }),
+ * });
+ * ```
+ */
+export class DyFM_Errors<T_Error extends DyFM_Error> extends DyFM_Metadata {
+  readonly flag?: string = DyFM_errorsFlag;
+
+  source?: string;
+  issuer?: string;
+  username?: string;
+  /** In which system versions this error occurred. */
+  versions?: string[] = [];
+  localTime?: string;
+  region?: string;
+
+  message?: string;
+  exception?: string;
+  exceptionObj?: any;
+
+  stackTrace?: string[] = [];
+  error?: any;
+
+  count?: number = 1;
+  
+  d_error?: T_Error;
+
+  additionalContent?: any;
+
+  level?: DyFM_ErrorLevel;
+  priority?: number;
+  duplications?: DyFM_Errors<T_Error>[] = [];
+
+  // ─── Fix tracking (append-only audit + quick-access aliases) ────────────────
+
+  /**
+   * Append-only audit log of fix attempts. New entries via `recordFixAttempt`
+   * on the data-service. Never overwritten / pruned — full hypothesis history
+   * stays available even when one hypothesis turns out to be wrong and the
+   * next attempt is logged.
+   */
+  fixAttempts?: DyFM_Errors_FixAttempt[] = [];
+
+  /** Convenience alias — last entry of `fixAttempts.at`. */
+  lastFixedAt?: Date | string;
+  /** Convenience alias — last entry of `fixAttempts.by`. */
+  lastFixedBy?: string;
+  /** Convenience alias — last entry of `fixAttempts.version`. */
+  lastFixedInVersion?: string;
+  /** Convenience alias — last entry of `fixAttempts.hypothesis`. */
+  lastFixHypothesis?: string;
+
+  /**
+   * Set to `true` in the `recordError` dedup branch when a NEW occurrence
+   * arrives carrying a `versions[0]` >= `lastFixedInVersion`. Indicates the
+   * most recent fix attempt did not actually fix the root cause — surface as
+   * a flag on the dashboard so the next investigator knows to dig deeper than
+   * "already fixed in vN".
+   */
+  regressedAfterFix?: boolean;
+
+  constructor(
+    set?: DyFM_Errors<T_Error>
+  ) {
+    super(set);
+    
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}
+
+export const DyFM_errors_dataParams: DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>> = 
+  new DyFM_DataModel_Params<DyFM_Errors<DyFM_Error>>({
+    dataName: 'errors',
+    properties: {
+      flag: { type: 'string' },
+
+      issuer: { type: 'string' },
+      username: { type: 'string' },
+      versions: { type: 'string[]' },
+
+      localTime: { type: 'string' },
+      region: { type: 'string' },
+
+      message: { type: 'string' },
+      exception: { type: 'string' },
+      exceptionObj: { type: 'any' },
+
+      stackTrace: { type: 'string[]' },
+      error: { type: 'any' },
+
+      count: { type: 'number' },
+
+      d_error: { type: 'DyFM_Error' },
+
+      additionalContent: { type: 'any' },
+
+      level: { type: 'DyFM_ErrorLevel' },
+      priority: { type: 'number' },
+      duplications: { type: 'DyNTS_Error[]' },
+
+      fixAttempts: { type: 'any' },
+      lastFixedAt: { type: 'Date' },
+      lastFixedBy: { type: 'string' },
+      lastFixedInVersion: { type: 'string' },
+      lastFixHypothesis: { type: 'string' },
+      regressedAfterFix: { type: 'boolean' },
+    },
   });

package/src/_models/data-models/metadata.data-model.spec.ts

@@ -1,184 +1,184 @@
-import { DyFM_Metadata } from './metadata.data-model';
-
-describe('| DyFM_Metadata', (): void => {
-  it('| should create an instance without initial data', (): void => {
-    const instance = new DyFM_Metadata();
-    expect(instance).toBeTruthy();
-    expect(instance.__created).toBeInstanceOf(Date);
-    expect(instance.__lastModified).toBeInstanceOf(Date);
-    expect(instance.__v).toBe(0);
-  });
-
-  it('| should create an instance with initial data', (): void => {
-    const initialData: DyFM_Metadata = {
-      _id: 'test-id',
-      __created: new Date('2023-01-01'),
-      __createdBy: 'user1',
-      __lastModified: new Date('2023-01-02'),
-      __lastModifiedBy: 'user2',
-      __v: 1
-    };
-    const instance = new DyFM_Metadata(initialData);
-
-    expect(instance._id).toBe('test-id');
-    expect(instance.__created).toEqual(new Date('2023-01-01'));
-    expect(instance.__createdBy).toBe('user1');
-    expect(instance.__lastModified).toEqual(new Date('2023-01-02'));
-    expect(instance.__lastModifiedBy).toBe('user2');
-    expect(instance.__v).toBe(1);
-  });
-
-  it('| should set default values when not provided', (): void => {
-    const instance = new DyFM_Metadata({});
-
-    expect(instance.__created).toBeInstanceOf(Date);
-    expect(instance.__lastModified).toBeInstanceOf(Date);
-    expect(instance.__v).toBe(0);
-  });
-
-  it('| should handle init parameter with id and issuer', (): void => {
-    const instance = new DyFM_Metadata(undefined, {
-      id: 'init-id',
-      issuer: 'init-user'
-    });
-
-    expect(instance._id).toBe('init-id');
-    expect(instance.__createdBy).toBe('init-user');
-    expect(instance.__lastModifiedBy).toBe('init-user');
-  });
-
-  it('| should not override existing _id with init id', (): void => {
-    const instance = new DyFM_Metadata(
-      { _id: 'existing-id' },
-      { id: 'init-id', issuer: 'user' }
-    );
-
-    expect(instance._id).toBe('existing-id');
-  });
-
-  it('| should not override existing __createdBy with init issuer', (): void => {
-    const instance = new DyFM_Metadata(
-      { __createdBy: 'existing-user' },
-      { issuer: 'init-user' }
-    );
-
-    expect(instance.__createdBy).toBe('existing-user');
-  });
-
-  it('| should handle archived data', (): void => {
-    const archivedDate = new Date('2023-01-01');
-    const instance = new DyFM_Metadata({
-      _archived: archivedDate,
-      _originalId: 'original-id'
-    });
-
-    expect(instance._archived).toEqual(archivedDate);
-    expect(instance._originalId).toBe('original-id');
-  });
-
-  it('| should handle deleted data', (): void => {
-    const deletedDate = new Date('2023-01-01');
-    const instance = new DyFM_Metadata({
-      _deleted: deletedDate,
-      _deletedBy: 'deleter'
-    } as any);
-    instance._deleted = deletedDate;
-    instance._deletedBy = 'deleter';
-
-    expect(instance._deleted).toEqual(deletedDate);
-    expect(instance._deletedBy).toBe('deleter');
-  });
-
-  it('| should set _id to undefined when _id is falsy but not undefined', (): void => {
-    // Test case for line 40-42: if (!set._id && set._id !== undefined)
-    // This happens when _id is null, empty string, 0, false, etc.
-    const instance1 = new DyFM_Metadata({ _id: null as any });
-    expect(instance1._id).toBeUndefined();
-
-    const instance2 = new DyFM_Metadata({ _id: '' as any });
-    expect(instance2._id).toBeUndefined();
-
-    const instance3 = new DyFM_Metadata({ _id: 0 as any });
-    expect(instance3._id).toBeUndefined();
-  });
-
-  describe('| updateMetadata', (): void => {
-    it('| should update metadata correctly', (): void => {
-      const data = new DyFM_Metadata();
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater', 'new-id');
-
-      expect(updated._id).toBe('new-id');
-      expect(updated.__createdBy).toBe('updater');
-      expect(updated.__lastModifiedBy).toBe('updater');
-      expect(updated.__lastModified).toBeInstanceOf(Date);
-      expect(updated.__v).toBe(1);
-    });
-
-    it('| should increment version on update', (): void => {
-      const data = new DyFM_Metadata({ __v: 5 });
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
-
-      expect(updated.__v).toBe(6);
-    });
-
-    it('| should set version to 1 if not present', (): void => {
-      const data = new DyFM_Metadata({ __v: undefined });
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
-
-      expect(updated.__v).toBe(1);
-    });
-
-    it('| should not override existing _id if id not provided', (): void => {
-      const data = new DyFM_Metadata({ _id: 'existing-id' });
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
-
-      expect(updated._id).toBe('existing-id');
-    });
-
-    it('| should set _id if not present and id provided', (): void => {
-      const data = new DyFM_Metadata({ _id: undefined });
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater', 'new-id');
-
-      expect(updated._id).toBe('new-id');
-    });
-
-    it('| should throw error when updating deleted data', (): void => {
-      const data = new DyFM_Metadata({ _deleted: new Date() } as any);
-      data._deleted = new Date();
-
-      expect(() => {
-        DyFM_Metadata.updateMetadata!(data, 'updater');
-      }).toThrowError('Cannot update metadata of deleted data');
-    });
-
-    it('| should return data as-is if data is null', (): void => {
-      const result = DyFM_Metadata.updateMetadata!(null as any, 'updater');
-
-      expect(result).toBeNull();
-    });
-
-    it('| should set __created if not present', (): void => {
-      const data = new DyFM_Metadata({ __created: undefined });
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
-
-      expect(updated.__created).toBeInstanceOf(Date);
-    });
-
-    it('| should set __createdBy if not present', (): void => {
-      const data = new DyFM_Metadata({ __createdBy: undefined });
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
-
-      expect(updated.__createdBy).toBe('updater');
-    });
-
-    it('| should set __created if not present (branch coverage)', (): void => {
-      // Test case for line 114-116: if (!data.__created)
-      const data = new DyFM_Metadata();
-      data.__created = undefined as any;
-      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
-
-      expect(updated.__created).toBeInstanceOf(Date);
-    });
-  });
-});
-
+import { DyFM_Metadata } from './metadata.data-model';
+
+describe('| DyFM_Metadata', (): void => {
+  it('| should create an instance without initial data', (): void => {
+    const instance = new DyFM_Metadata();
+    expect(instance).toBeTruthy();
+    expect(instance.__created).toBeInstanceOf(Date);
+    expect(instance.__lastModified).toBeInstanceOf(Date);
+    expect(instance.__v).toBe(0);
+  });
+
+  it('| should create an instance with initial data', (): void => {
+    const initialData: DyFM_Metadata = {
+      _id: 'test-id',
+      __created: new Date('2023-01-01'),
+      __createdBy: 'user1',
+      __lastModified: new Date('2023-01-02'),
+      __lastModifiedBy: 'user2',
+      __v: 1
+    };
+    const instance = new DyFM_Metadata(initialData);
+
+    expect(instance._id).toBe('test-id');
+    expect(instance.__created).toEqual(new Date('2023-01-01'));
+    expect(instance.__createdBy).toBe('user1');
+    expect(instance.__lastModified).toEqual(new Date('2023-01-02'));
+    expect(instance.__lastModifiedBy).toBe('user2');
+    expect(instance.__v).toBe(1);
+  });
+
+  it('| should set default values when not provided', (): void => {
+    const instance = new DyFM_Metadata({});
+
+    expect(instance.__created).toBeInstanceOf(Date);
+    expect(instance.__lastModified).toBeInstanceOf(Date);
+    expect(instance.__v).toBe(0);
+  });
+
+  it('| should handle init parameter with id and issuer', (): void => {
+    const instance = new DyFM_Metadata(undefined, {
+      id: 'init-id',
+      issuer: 'init-user'
+    });
+
+    expect(instance._id).toBe('init-id');
+    expect(instance.__createdBy).toBe('init-user');
+    expect(instance.__lastModifiedBy).toBe('init-user');
+  });
+
+  it('| should not override existing _id with init id', (): void => {
+    const instance = new DyFM_Metadata(
+      { _id: 'existing-id' },
+      { id: 'init-id', issuer: 'user' }
+    );
+
+    expect(instance._id).toBe('existing-id');
+  });
+
+  it('| should not override existing __createdBy with init issuer', (): void => {
+    const instance = new DyFM_Metadata(
+      { __createdBy: 'existing-user' },
+      { issuer: 'init-user' }
+    );
+
+    expect(instance.__createdBy).toBe('existing-user');
+  });
+
+  it('| should handle archived data', (): void => {
+    const archivedDate = new Date('2023-01-01');
+    const instance = new DyFM_Metadata({
+      _archived: archivedDate,
+      _originalId: 'original-id'
+    });
+
+    expect(instance._archived).toEqual(archivedDate);
+    expect(instance._originalId).toBe('original-id');
+  });
+
+  it('| should handle deleted data', (): void => {
+    const deletedDate = new Date('2023-01-01');
+    const instance = new DyFM_Metadata({
+      _deleted: deletedDate,
+      _deletedBy: 'deleter'
+    } as any);
+    instance._deleted = deletedDate;
+    instance._deletedBy = 'deleter';
+
+    expect(instance._deleted).toEqual(deletedDate);
+    expect(instance._deletedBy).toBe('deleter');
+  });
+
+  it('| should set _id to undefined when _id is falsy but not undefined', (): void => {
+    // Test case for line 40-42: if (!set._id && set._id !== undefined)
+    // This happens when _id is null, empty string, 0, false, etc.
+    const instance1 = new DyFM_Metadata({ _id: null as any });
+    expect(instance1._id).toBeUndefined();
+
+    const instance2 = new DyFM_Metadata({ _id: '' as any });
+    expect(instance2._id).toBeUndefined();
+
+    const instance3 = new DyFM_Metadata({ _id: 0 as any });
+    expect(instance3._id).toBeUndefined();
+  });
+
+  describe('| updateMetadata', (): void => {
+    it('| should update metadata correctly', (): void => {
+      const data = new DyFM_Metadata();
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater', 'new-id');
+
+      expect(updated._id).toBe('new-id');
+      expect(updated.__createdBy).toBe('updater');
+      expect(updated.__lastModifiedBy).toBe('updater');
+      expect(updated.__lastModified).toBeInstanceOf(Date);
+      expect(updated.__v).toBe(1);
+    });
+
+    it('| should increment version on update', (): void => {
+      const data = new DyFM_Metadata({ __v: 5 });
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
+
+      expect(updated.__v).toBe(6);
+    });
+
+    it('| should set version to 1 if not present', (): void => {
+      const data = new DyFM_Metadata({ __v: undefined });
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
+
+      expect(updated.__v).toBe(1);
+    });
+
+    it('| should not override existing _id if id not provided', (): void => {
+      const data = new DyFM_Metadata({ _id: 'existing-id' });
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
+
+      expect(updated._id).toBe('existing-id');
+    });
+
+    it('| should set _id if not present and id provided', (): void => {
+      const data = new DyFM_Metadata({ _id: undefined });
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater', 'new-id');
+
+      expect(updated._id).toBe('new-id');
+    });
+
+    it('| should throw error when updating deleted data', (): void => {
+      const data = new DyFM_Metadata({ _deleted: new Date() } as any);
+      data._deleted = new Date();
+
+      expect(() => {
+        DyFM_Metadata.updateMetadata!(data, 'updater');
+      }).toThrowError('Cannot update metadata of deleted data');
+    });
+
+    it('| should return data as-is if data is null', (): void => {
+      const result = DyFM_Metadata.updateMetadata!(null as any, 'updater');
+
+      expect(result).toBeNull();
+    });
+
+    it('| should set __created if not present', (): void => {
+      const data = new DyFM_Metadata({ __created: undefined });
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
+
+      expect(updated.__created).toBeInstanceOf(Date);
+    });
+
+    it('| should set __createdBy if not present', (): void => {
+      const data = new DyFM_Metadata({ __createdBy: undefined });
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
+
+      expect(updated.__createdBy).toBe('updater');
+    });
+
+    it('| should set __created if not present (branch coverage)', (): void => {
+      // Test case for line 114-116: if (!data.__created)
+      const data = new DyFM_Metadata();
+      data.__created = undefined as any;
+      const updated = DyFM_Metadata.updateMetadata!(data, 'updater');
+
+      expect(updated.__created).toBeInstanceOf(Date);
+    });
+  });
+});
+