Address code review feedback: fix division by zero, improve error tracking, clarify documentation

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/data-objectstack/README.md

@@ -83,9 +83,10 @@ dataSource.clearCache();
 ### Cache Configuration
 
 - **LRU Eviction**: Automatically evicts least recently used entries when cache is full
-- **TTL Expiration**: Entries expire after the configured time-to-live (default: 5 minutes)
+- **TTL Expiration**: Entries expire after the configured time-to-live from creation (default: 5 minutes)
+  - Note: TTL is fixed from creation time, not sliding based on access
 - **Memory Limits**: Configurable maximum cache size (default: 100 entries)
-- **Thread-Safe**: Handles concurrent access patterns safely
+- **Concurrent Access**: Handles async operations safely. Note that concurrent requests for the same uncached key may result in multiple fetcher calls.
 
 ## Error Handling
 

packages/data-objectstack/src/cache/MetadataCache.ts

@@ -33,11 +33,15 @@ export interface CacheStats {
  * 
  * Features:
  * - LRU (Least Recently Used) eviction policy
- * - TTL (Time To Live) based expiration
+ * - TTL (Time To Live) based expiration (fixed from creation, not sliding)
  * - Memory limit controls
- * - Thread-safe operations (async/await)
+ * - Async-safe operations
  * - Performance statistics tracking
  * 
+ * Note: Concurrent requests for the same uncached key may result in multiple
+ * fetcher calls. For production use cases requiring request deduplication,
+ * consider wrapping the cache with a promise-based deduplication layer.
+ * 
  * @example
  * ```typescript
  * const cache = new MetadataCache({ maxSize: 100, ttl: 300000 });

packages/data-objectstack/src/errors.ts

@@ -105,12 +105,15 @@ export class BulkOperationError extends ObjectStackError {
    * Get a summary of the bulk operation failure
    */
   getSummary() {
+    const total = this.successCount + this.failureCount;
+    const failureRate = total > 0 ? this.failureCount / total : 0;
+    
     return {
       operation: this.details.operation,
-      total: this.successCount + this.failureCount,
+      total: total,
       successful: this.successCount,
       failed: this.failureCount,
-      failureRate: this.failureCount / (this.successCount + this.failureCount),
+      failureRate: failureRate,
       errors: this.errors,
     };
   }

packages/data-objectstack/src/index.ts

@@ -175,9 +175,13 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
           const ids = data.map(item => (item as any).id).filter(Boolean);
 
           if (ids.length === 0) {
-            throw new BulkOperationError('delete', 0, data.length, 
-              data.map((_, index) => ({ index, error: 'Missing ID' }))
-            );
+            // Track which items are missing IDs
+            const errors = data.map((_, index) => ({
+              index,
+              error: `Missing ID for item at index ${index}`
+            }));
+            
+            throw new BulkOperationError('delete', 0, data.length, errors);
           }
 
           await this.client.data.deleteMany(resource, ids);
@@ -249,12 +253,17 @@ export class ObjectStackAdapter<T = any> implements DataSource<T> {
         throw error;
       }
 
-      // Wrap other errors in BulkOperationError
+      // Wrap other errors in BulkOperationError with proper error tracking
+      const errors = data.map((_, index) => ({
+        index,
+        error: error.message || String(error)
+      }));
+      
       throw new BulkOperationError(
         operation,
         0,
         data.length,
-        [{ index: 0, error: error.message || error }],
+        errors,
         { resource, originalError: error }
       );
     }