feat: Improve delete API with clear hard delete option

- Single clear way to hard delete: { hard: true }
- Removed confusing soft: false option
- Soft delete remains the default behavior
- Clean, intuitive API: delete() for soft, delete(id, { hard: true }) for hard
- All delete features working: soft, hard, cascade

brainy-data/_system/statistics.json

@@ -1,18 +0,0 @@
-{
-  "nounCount": {
-    "default": 0
-  },
-  "verbCount": {},
-  "metadataCount": {
-    "default": 0
-  },
-  "hnswIndexSize": 1,
-  "lastUpdated": "2025-08-19T01:13:31.471Z",
-  "serviceActivity": {
-    "default": {
-      "firstActivity": "2025-08-19T01:13:26.462Z",
-      "lastActivity": "2025-08-19T01:13:26.467Z",
-      "totalOperations": 4
-    }
-  }
-}

brainy-data/metadata/__metadata_index__deletedAt_2025-08-19t01_chunk0.json

@@ -1 +0,0 @@
-null

brainy-data/metadata/__metadata_index__deletedBy_user_chunk0.json

@@ -1 +0,0 @@
-null

brainy-data/metadata/__metadata_index__deleted___true___chunk0.json

@@ -1 +0,0 @@
-null

brainy-data/metadata/d5478378-9e6c-4c8f-b642-1f2358b0d082.json

@@ -1 +0,0 @@
-null

dist/brainyData.d.ts

@@ -785,7 +785,7 @@ export declare class BrainyData<T = any> implements BrainyDataInterface<T> {
      */
     delete(id: string, options?: {
         service?: string;
-        soft?: boolean;
+        hard?: boolean;
         cascade?: boolean;
         force?: boolean;
     }): Promise<boolean>;

dist/brainyData.js

@@ -2300,12 +2300,13 @@ export class BrainyData {
      * @returns Promise that resolves to true if the vector was deleted, false otherwise
      */
     async delete(id, options = {}) {
+        // Clear API: use 'hard: true' for hard delete, otherwise soft delete
+        const isHardDelete = options.hard === true;
         const opts = {
-            service: undefined,
-            soft: true, // Soft delete is default - preserves indexes
-            cascade: false,
-            force: false,
-            ...options
+            service: options.service,
+            soft: !isHardDelete, // Soft delete is default unless hard: true is specified
+            cascade: options.cascade || false,
+            force: options.force || false
         };
         // Validate id parameter first, before any other logic
         if (id === null || id === undefined) {

src/brainyData.ts

@@ -3376,17 +3376,19 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
     id: string,
     options: {
       service?: string // The service that is deleting the data
-      soft?: boolean // Soft delete (mark as deleted, default: true)
+      hard?: boolean // Hard delete - completely removes from storage (default: false, soft delete is default)
       cascade?: boolean // Delete related verbs (default: false)
       force?: boolean // Force delete even if has relationships (default: false)
     } = {}
   ): Promise<boolean> {
+    // Clear API: use 'hard: true' for hard delete, otherwise soft delete
+    const isHardDelete = options.hard === true
+    
     const opts = {
-      service: undefined,
-      soft: true, // Soft delete is default - preserves indexes
-      cascade: false,
-      force: false,
-      ...options
+      service: options.service,
+      soft: !isHardDelete, // Soft delete is default unless hard: true is specified
+      cascade: options.cascade || false,
+      force: options.force || false
     }
     // Validate id parameter first, before any other logic
     if (id === null || id === undefined) {

tests/unified-api.test.ts

@@ -187,7 +187,7 @@ describe('Brainy 1.0 Unified API', () => {
 
     it('should hard delete when specified', async () => {
       const id = await brainy.add("Data to hard delete")
-      const success = await brainy.delete(id, { soft: false })
+      const success = await brainy.delete(id, { hard: true })
       expect(success).toBe(true)
     })