fix(collection): improve duplicate key error reporting on insert

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-04-05 - 7.1.6 - fix(collection)
+improve duplicate key error reporting on insert
+
+- Wrap insertOne() in error handling to detect MongoDB duplicate key conflicts
+- Log a clearer message with the collection name and identifiable object when unique indexes are involved
+- Guide callers to use getInstance() or save() on a db-retrieved instance when a duplicate already exists
+
 ## 2026-04-05 - 7.1.5 - fix(collection)
 ensure unique indexes are marked before upsert operations
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdata',
-  version: '7.1.5',
+  version: '7.1.6',
   description: 'An advanced library for NoSQL data organization and manipulation using TypeScript with support for MongoDB, data validation, collections, and custom data types.'
 }

ts/classes.collection.ts

@@ -447,8 +447,22 @@ export class SmartdataCollection<T> {
     }
     
     const saveableObject = await dbDocArg.createSavableObject() as any;
+    try {
       const result = await this.mongoDbCollection.insertOne(saveableObject, { session: opts?.session });
       return result;
+    } catch (err: any) {
+      const isDuplicateKey = err?.code === 11000 || err?.codeName === 'DuplicateKey';
+      if (isDuplicateKey && dbDocArg.uniqueIndexes && dbDocArg.uniqueIndexes.length > 0) {
+        const identifiableObject = await dbDocArg.createIdentifiableObject();
+        logger.log(
+          'error',
+          `Duplicate key conflict in "${this.collectionName}" on insert. ` +
+          `A document with ${JSON.stringify(identifiableObject)} already exists. ` +
+          `Use getInstance() to retrieve the existing document, or update it via save() on a db-retrieved instance.`
+        );
+      }
+      throw err;
+    }
   }
 
   /**