**feat: implement robust error-handling and operation utilities for storage adapters**

- Added `BrainyError` class to classify and handle errors with types like `TIMEOUT`, `NETWORK`, `STORAGE`, `NOT_FOUND`, and `RETRY_EXHAUSTED`. Includes static helper methods for error creation and retry determination.
- Introduced `operationUtils` with utility functions for timeout, retry logic, and exponential backoff. Implements features like `withTimeout`, `withRetry`, and a combined `withTimeoutAndRetry`.
- Updated `S3CompatibleStorage` to leverage new operation utilities for timeout and retry handling, including `StorageOperationExecutors` for clean operation execution.
- Enhanced `storageFactory` to pass `OperationConfig` for configurable timeout and retry behavior.
- Extended `BrainyData` to include timeout and retry policy configuration at initialization.

**Purpose**: Improve storage reliability by introducing configurable and reusable error-handling and operation utilities, reducing code duplication and enhancing maintainability.

src/brainyData.ts

@@ -135,6 +135,60 @@ export interface BrainyDataConfig {
         verbose?: boolean
     }
 
+    /**
+     * Timeout configuration for async operations
+     * Controls how long operations wait before timing out
+     */
+    timeouts?: {
+        /**
+         * Timeout for get operations in milliseconds
+         * Default: 30000 (30 seconds)
+         */
+        get?: number
+
+        /**
+         * Timeout for add operations in milliseconds
+         * Default: 60000 (60 seconds)
+         */
+        add?: number
+
+        /**
+         * Timeout for delete operations in milliseconds
+         * Default: 30000 (30 seconds)
+         */
+        delete?: number
+    }
+
+    /**
+     * Retry policy configuration for failed operations
+     * Controls how operations are retried on failure
+     */
+    retryPolicy?: {
+        /**
+         * Maximum number of retry attempts
+         * Default: 3
+         */
+        maxRetries?: number
+
+        /**
+         * Initial delay between retries in milliseconds
+         * Default: 1000 (1 second)
+         */
+        initialDelay?: number
+
+        /**
+         * Maximum delay between retries in milliseconds
+         * Default: 10000 (10 seconds)
+         */
+        maxDelay?: number
+
+        /**
+         * Multiplier for exponential backoff
+         * Default: 2
+         */
+        backoffMultiplier?: number
+    }
+
     /**
      * Real-time update configuration
      * Controls how the database handles updates when data is added by external processes
@@ -181,6 +235,10 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
     private _dimensions: number
     private loggingConfig: BrainyDataConfig['logging'] = {verbose: true}
     
+    // Timeout and retry configuration
+    private timeoutConfig: BrainyDataConfig['timeouts'] = {}
+    private retryConfig: BrainyDataConfig['retryPolicy'] = {}
+    
     // Real-time update properties
     private realtimeUpdateConfig: Required<NonNullable<BrainyDataConfig['realtimeUpdates']>> = {
         enabled: false,
@@ -268,6 +326,10 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
         // Store storage configuration for later use in init()
         this.storageConfig = config.storage || {}
 
+        // Store timeout and retry configuration
+        this.timeoutConfig = config.timeouts || {}
+        this.retryConfig = config.retryPolicy || {}
+
         // Store remote server configuration if provided
         if (config.remoteServer) {
             this.remoteServerConfig = config.remoteServer

src/errors/brainyError.ts

@@ -0,0 +1,179 @@
+/**
+ * Custom error types for Brainy operations
+ * Provides better error classification and handling
+ */
+
+export type BrainyErrorType = 'TIMEOUT' | 'NETWORK' | 'STORAGE' | 'NOT_FOUND' | 'RETRY_EXHAUSTED'
+
+/**
+ * Custom error class for Brainy operations
+ * Provides error type classification and retry information
+ */
+export class BrainyError extends Error {
+    public readonly type: BrainyErrorType
+    public readonly retryable: boolean
+    public readonly originalError?: Error
+    public readonly attemptNumber?: number
+    public readonly maxRetries?: number
+
+    constructor(
+        message: string,
+        type: BrainyErrorType,
+        retryable: boolean = false,
+        originalError?: Error,
+        attemptNumber?: number,
+        maxRetries?: number
+    ) {
+        super(message)
+        this.name = 'BrainyError'
+        this.type = type
+        this.retryable = retryable
+        this.originalError = originalError
+        this.attemptNumber = attemptNumber
+        this.maxRetries = maxRetries
+
+        // Maintain proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, BrainyError)
+        }
+    }
+
+    /**
+     * Create a timeout error
+     */
+    static timeout(operation: string, timeoutMs: number, originalError?: Error): BrainyError {
+        return new BrainyError(
+            `Operation '${operation}' timed out after ${timeoutMs}ms`,
+            'TIMEOUT',
+            true,
+            originalError
+        )
+    }
+
+    /**
+     * Create a network error
+     */
+    static network(message: string, originalError?: Error): BrainyError {
+        return new BrainyError(
+            `Network error: ${message}`,
+            'NETWORK',
+            true,
+            originalError
+        )
+    }
+
+    /**
+     * Create a storage error
+     */
+    static storage(message: string, originalError?: Error): BrainyError {
+        return new BrainyError(
+            `Storage error: ${message}`,
+            'STORAGE',
+            true,
+            originalError
+        )
+    }
+
+    /**
+     * Create a not found error
+     */
+    static notFound(resource: string): BrainyError {
+        return new BrainyError(
+            `Resource not found: ${resource}`,
+            'NOT_FOUND',
+            false
+        )
+    }
+
+    /**
+     * Create a retry exhausted error
+     */
+    static retryExhausted(operation: string, maxRetries: number, lastError?: Error): BrainyError {
+        return new BrainyError(
+            `Operation '${operation}' failed after ${maxRetries} retry attempts`,
+            'RETRY_EXHAUSTED',
+            false,
+            lastError,
+            maxRetries,
+            maxRetries
+        )
+    }
+
+    /**
+     * Check if an error is retryable
+     */
+    static isRetryable(error: Error): boolean {
+        if (error instanceof BrainyError) {
+            return error.retryable
+        }
+
+        // Check for common retryable error patterns
+        const message = error.message.toLowerCase()
+        const name = error.name.toLowerCase()
+
+        // Network-related errors that are typically retryable
+        if (
+            message.includes('timeout') ||
+            message.includes('network') ||
+            message.includes('connection') ||
+            message.includes('econnreset') ||
+            message.includes('enotfound') ||
+            message.includes('etimedout') ||
+            name.includes('timeout')
+        ) {
+            return true
+        }
+
+        // AWS SDK specific retryable errors
+        if (
+            message.includes('throttling') ||
+            message.includes('rate limit') ||
+            message.includes('service unavailable') ||
+            message.includes('internal server error') ||
+            message.includes('bad gateway') ||
+            message.includes('gateway timeout')
+        ) {
+            return true
+        }
+
+        return false
+    }
+
+    /**
+     * Convert a generic error to a BrainyError with appropriate classification
+     */
+    static fromError(error: Error, operation?: string): BrainyError {
+        if (error instanceof BrainyError) {
+            return error
+        }
+
+        const message = error.message.toLowerCase()
+        const name = error.name.toLowerCase()
+
+        // Classify the error based on common patterns
+        if (message.includes('timeout') || name.includes('timeout')) {
+            return BrainyError.timeout(operation || 'unknown', 0, error)
+        }
+
+        if (
+            message.includes('network') ||
+            message.includes('connection') ||
+            message.includes('econnreset') ||
+            message.includes('enotfound') ||
+            message.includes('etimedout')
+        ) {
+            return BrainyError.network(error.message, error)
+        }
+
+        if (
+            message.includes('nosuchkey') ||
+            message.includes('not found') ||
+            message.includes('does not exist')
+        ) {
+            return BrainyError.notFound(operation || 'resource')
+        }
+
+        // Default to storage error for unclassified errors
+        return BrainyError.storage(error.message, error)
+    }
+}

src/storage/adapters/s3CompatibleStorage.ts

@@ -6,6 +6,8 @@
 
 import {GraphVerb, HNSWNoun, StatisticsData} from '../../coreTypes.js'
 import {BaseStorage, NOUNS_DIR, VERBS_DIR, METADATA_DIR, INDEX_DIR, STATISTICS_KEY} from '../baseStorage.js'
+import {StorageOperationExecutors, OperationConfig} from '../../utils/operationUtils.js'
+import {BrainyError} from '../../errors/brainyError.js'
 
 // Type aliases for better readability
 type HNSWNode = HNSWNoun
@@ -76,6 +78,9 @@ export class S3CompatibleStorage extends BaseStorage {
     
     // Change log for efficient synchronization
     private changeLogPrefix: string = 'change-log/'
+    
+    // Operation executors for timeout and retry handling
+    private operationExecutors: StorageOperationExecutors
 
     /**
      * Initialize the storage adapter
@@ -90,6 +95,7 @@ export class S3CompatibleStorage extends BaseStorage {
         secretAccessKey: string
         sessionToken?: string
         serviceType?: string
+        operationConfig?: OperationConfig
     }) {
         super()
         this.bucketName = options.bucketName
@@ -101,6 +107,9 @@ export class S3CompatibleStorage extends BaseStorage {
         this.sessionToken = options.sessionToken
         this.serviceType = options.serviceType || 's3'
 
+        // Initialize operation executors with timeout and retry configuration
+        this.operationExecutors = new StorageOperationExecutors(options.operationConfig)
+
         // Set up prefixes for different types of data
         this.nounPrefix = `${NOUNS_DIR}/`
         this.verbPrefix = `${VERBS_DIR}/`
@@ -938,61 +947,62 @@ export class S3CompatibleStorage extends BaseStorage {
     public async getMetadata(id: string): Promise<any | null> {
         await this.ensureInitialized()
 
-        try {
+        return this.operationExecutors.executeGet(async () => {
-            // Import the GetObjectCommand only when needed
-            const {GetObjectCommand} = await import('@aws-sdk/client-s3')
-
-            console.log(`Getting metadata for ${id} from bucket ${this.bucketName}`)
-            const key = `${this.metadataPrefix}${id}.json`
-            console.log(`Looking for metadata at key: ${key}`)
-
-            // Try to get the metadata from the metadata directory
-            const response = await this.s3Client!.send(
-                new GetObjectCommand({
-                    Bucket: this.bucketName,
-                    Key: key
-                })
-            )
-
-            // Check if response is null or undefined (can happen in mock implementations)
-            if (!response || !response.Body) {
-                console.log(`No metadata found for ${id}`)
-                return null
-            }
-
-            // Convert the response body to a string
-            const bodyContents = await response.Body.transformToString()
-            console.log(`Retrieved metadata body: ${bodyContents}`)
-
-            // Parse the JSON string
             try {
-                const parsedMetadata = JSON.parse(bodyContents)
+                // Import the GetObjectCommand only when needed
-                console.log(`Successfully retrieved metadata for ${id}:`, parsedMetadata)
+                const {GetObjectCommand} = await import('@aws-sdk/client-s3')
-                return parsedMetadata
-            } catch (parseError) {
-                console.error(`Failed to parse metadata for ${id}:`, parseError)
-                return null
-            }
-        } catch (error: any) {
-            // Check if this is a "NoSuchKey" error (object doesn't exist)
-            // In AWS SDK, this would be error.name === 'NoSuchKey'
-            // In our mock, we might get different error types
-            if (
-                error.name === 'NoSuchKey' ||
-                (error.message && (
-                    error.message.includes('NoSuchKey') ||
-                    error.message.includes('not found') ||
-                    error.message.includes('does not exist')
-                ))
-            ) {
-                console.log(`Metadata not found for ${id}`)
-                return null
-            }
 
-            // For other types of errors, log and re-throw
+                console.log(`Getting metadata for ${id} from bucket ${this.bucketName}`)
-            console.error(`Error getting metadata for ${id}:`, error)
+                const key = `${this.metadataPrefix}${id}.json`
-            throw error
+                console.log(`Looking for metadata at key: ${key}`)
-        }
+
+                // Try to get the metadata from the metadata directory
+                const response = await this.s3Client!.send(
+                    new GetObjectCommand({
+                        Bucket: this.bucketName,
+                        Key: key
+                    })
+                )
+
+                // Check if response is null or undefined (can happen in mock implementations)
+                if (!response || !response.Body) {
+                    console.log(`No metadata found for ${id}`)
+                    return null
+                }
+
+                // Convert the response body to a string
+                const bodyContents = await response.Body.transformToString()
+                console.log(`Retrieved metadata body: ${bodyContents}`)
+
+                // Parse the JSON string
+                try {
+                    const parsedMetadata = JSON.parse(bodyContents)
+                    console.log(`Successfully retrieved metadata for ${id}:`, parsedMetadata)
+                    return parsedMetadata
+                } catch (parseError) {
+                    console.error(`Failed to parse metadata for ${id}:`, parseError)
+                    return null
+                }
+            } catch (error: any) {
+                // Check if this is a "NoSuchKey" error (object doesn't exist)
+                // In AWS SDK, this would be error.name === 'NoSuchKey'
+                // In our mock, we might get different error types
+                if (
+                    error.name === 'NoSuchKey' ||
+                    (error.message && (
+                        error.message.includes('NoSuchKey') ||
+                        error.message.includes('not found') ||
+                        error.message.includes('does not exist')
+                    ))
+                ) {
+                    console.log(`Metadata not found for ${id}`)
+                    return null
+                }
+
+                // For other types of errors, convert to BrainyError for better classification
+                throw BrainyError.fromError(error, `getMetadata(${id})`)
+            }
+        }, `getMetadata(${id})`)
     }
 
     /**

src/storage/storageFactory.ts

@@ -9,6 +9,7 @@ import {OPFSStorage} from './adapters/opfsStorage.js'
 import {S3CompatibleStorage, R2Storage} from './adapters/s3CompatibleStorage.js'
 import {FileSystemStorage} from './adapters/fileSystemStorage.js'
 import {isBrowser} from '../utils/environment.js'
+import {OperationConfig} from '../utils/operationUtils.js'
 
 /**
  * Options for creating a storage adapter
@@ -165,6 +166,11 @@ export interface StorageOptions {
          */
         serviceType?: string
     }
+
+    /**
+     * Operation configuration for timeout and retry behavior
+     */
+    operationConfig?: OperationConfig
 }
 
 /**
@@ -238,7 +244,8 @@ export async function createStorage(
                         accessKeyId: options.s3Storage.accessKeyId,
                         secretAccessKey: options.s3Storage.secretAccessKey,
                         sessionToken: options.s3Storage.sessionToken,
-                        serviceType: 's3'
+                        serviceType: 's3',
+                        operationConfig: options.operationConfig
                     })
                 } else {
                     console.warn('S3 storage configuration is missing, falling back to memory storage')

src/utils/operationUtils.ts

@@ -0,0 +1,204 @@
+/**
+ * Utility functions for timeout and retry logic
+ * Used by storage adapters to handle network operations reliably
+ */
+
+import { BrainyError } from '../errors/brainyError.js'
+
+export interface TimeoutConfig {
+    get?: number
+    add?: number
+    delete?: number
+}
+
+export interface RetryConfig {
+    maxRetries?: number
+    initialDelay?: number
+    maxDelay?: number
+    backoffMultiplier?: number
+}
+
+export interface OperationConfig {
+    timeouts?: TimeoutConfig
+    retryPolicy?: RetryConfig
+}
+
+// Default configuration values
+export const DEFAULT_TIMEOUTS: Required<TimeoutConfig> = {
+    get: 30000,      // 30 seconds
+    add: 60000,      // 1 minute
+    delete: 30000    // 30 seconds
+}
+
+export const DEFAULT_RETRY_POLICY: Required<RetryConfig> = {
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 10000,
+    backoffMultiplier: 2
+}
+
+/**
+ * Wraps a promise with a timeout
+ */
+export function withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    operation: string
+): Promise<T> {
+    return new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            reject(BrainyError.timeout(operation, timeoutMs))
+        }, timeoutMs)
+
+        promise
+            .then((result) => {
+                clearTimeout(timeoutId)
+                resolve(result)
+            })
+            .catch((error) => {
+                clearTimeout(timeoutId)
+                reject(error)
+            })
+    })
+}
+
+/**
+ * Calculates the delay for exponential backoff
+ */
+function calculateBackoffDelay(
+    attemptNumber: number,
+    initialDelay: number,
+    maxDelay: number,
+    backoffMultiplier: number
+): number {
+    const delay = initialDelay * Math.pow(backoffMultiplier, attemptNumber - 1)
+    return Math.min(delay, maxDelay)
+}
+
+/**
+ * Sleeps for the specified number of milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Executes an operation with retry logic and exponential backoff
+ */
+export async function withRetry<T>(
+    operation: () => Promise<T>,
+    operationName: string,
+    config: RetryConfig = {}
+): Promise<T> {
+    const {
+        maxRetries = DEFAULT_RETRY_POLICY.maxRetries,
+        initialDelay = DEFAULT_RETRY_POLICY.initialDelay,
+        maxDelay = DEFAULT_RETRY_POLICY.maxDelay,
+        backoffMultiplier = DEFAULT_RETRY_POLICY.backoffMultiplier
+    } = config
+
+    let lastError: Error | undefined
+
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        try {
+            return await operation()
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error))
+
+            // If this is the last attempt, don't retry
+            if (attempt > maxRetries) {
+                break
+            }
+
+            // Check if the error is retryable
+            if (!BrainyError.isRetryable(lastError)) {
+                throw BrainyError.fromError(lastError, operationName)
+            }
+
+            // Calculate delay for exponential backoff
+            const delay = calculateBackoffDelay(attempt, initialDelay, maxDelay, backoffMultiplier)
+            
+            console.warn(
+                `Operation '${operationName}' failed on attempt ${attempt}/${maxRetries + 1}. ` +
+                `Retrying in ${delay}ms. Error: ${lastError.message}`
+            )
+
+            // Wait before retrying
+            await sleep(delay)
+        }
+    }
+
+    // All retries exhausted
+    throw BrainyError.retryExhausted(operationName, maxRetries, lastError)
+}
+
+/**
+ * Executes an operation with both timeout and retry logic
+ */
+export async function withTimeoutAndRetry<T>(
+    operation: () => Promise<T>,
+    operationName: string,
+    timeoutMs: number,
+    retryConfig: RetryConfig = {}
+): Promise<T> {
+    return withRetry(
+        () => withTimeout(operation(), timeoutMs, operationName),
+        operationName,
+        retryConfig
+    )
+}
+
+/**
+ * Creates a configured operation executor for a specific operation type
+ */
+export function createOperationExecutor(
+    operationType: keyof TimeoutConfig,
+    config: OperationConfig = {}
+) {
+    const timeouts = { ...DEFAULT_TIMEOUTS, ...config.timeouts }
+    const retryPolicy = { ...DEFAULT_RETRY_POLICY, ...config.retryPolicy }
+    const timeoutMs = timeouts[operationType]
+
+    return async function executeOperation<T>(
+        operation: () => Promise<T>,
+        operationName: string
+    ): Promise<T> {
+        return withTimeoutAndRetry(operation, operationName, timeoutMs, retryPolicy)
+    }
+}
+
+/**
+ * Storage operation executors for different operation types
+ */
+export class StorageOperationExecutors {
+    private getExecutor: ReturnType<typeof createOperationExecutor>
+    private addExecutor: ReturnType<typeof createOperationExecutor>
+    private deleteExecutor: ReturnType<typeof createOperationExecutor>
+
+    constructor(config: OperationConfig = {}) {
+        this.getExecutor = createOperationExecutor('get', config)
+        this.addExecutor = createOperationExecutor('add', config)
+        this.deleteExecutor = createOperationExecutor('delete', config)
+    }
+
+    /**
+     * Execute a get operation with timeout and retry
+     */
+    async executeGet<T>(operation: () => Promise<T>, operationName: string): Promise<T> {
+        return this.getExecutor(operation, operationName)
+    }
+
+    /**
+     * Execute an add operation with timeout and retry
+     */
+    async executeAdd<T>(operation: () => Promise<T>, operationName: string): Promise<T> {
+        return this.addExecutor(operation, operationName)
+    }
+
+    /**
+     * Execute a delete operation with timeout and retry
+     */
+    async executeDelete<T>(operation: () => Promise<T>, operationName: string): Promise<T> {
+        return this.deleteExecutor(operation, operationName)
+    }
+}