feat: support for asynchronous initialization

[duyhungtnn]

Add Asynchronous Initialization Support to Bucketeer SDK Client

This pull request introduces asynchronous initialization support for the Bucketeer SDK client, solving a critical reliability issue during startup.

Problem Solved

Previously, when creating a Bucketeer client with initializeBKTClient() and enabling the local cache, we had no way to determine when the SDK was actually ready to serve accurate feature flag evaluations. The client would return immediately, but feature flag and segment data might still be loading from the server in the background, leading to:

• Inconsistent evaluation results during startup
• No way to handle initialization failures gracefully
• Race conditions between client usage and data loading

Solution

Added a new waitForInitialization() method to the Bucketeer client interface that allows applications to:

• Wait for readiness: Ensure all cache processors have completed their initial data sync before proceeding
• Handle timeouts gracefully: Set maximum wait times and handle cases where initialization takes longer than expected
• Catch initialization failures: Detect and respond to network or server errors during startup

Usage Pattern

const client = initializeBKTClient(config);

try {
  // Wait up to 5 seconds for SDK to be ready
  await client.waitForInitialization({ timeoutMs: 5000 });
  // Now safe to perform feature flag evaluations
  const result = await client.booleanVariation(user, 'feature-flag', false);
} catch (error) {
  if (error.message.includes('timeout')) {
    console.warn('SDK initialization is taking longer than expected, but may still succeed');
    // SDK can still be used, but initial cache sync is not yet complete
  } else {
    console.error('SDK initialization failed:', error.message);
  }
}

[duyhungtnn]

Why a new method waitForInitialization() Instead of Promise<Bucketeer> with the method initializeBKTClient()?

1. Non-Singleton Design in Server SDK
   In server environments, we typically need multiple client instances because:

   • Multi-tenancy: Different tenants/customers need isolated feature flag contexts
   • Different configurations: Different services or modules might need different API keys, endpoints, or feature tags
   • Environment isolation: Dev/staging/prod environments running on the same server
   • User segmentation: Different client instances for different user groups or regions

   // Multiple clients for different contexts
   const clientA = initializeBKTClient(configForTenantA);
   const clientB = initializeBKTClient(configForTenantB);
   const clientC = initializeBKTClient(configForDifferentRegion);

2. Error Handling Problem with Promise
   If initializeBKTClient() returned Promise, what happens when initialization fails?

  // This would be problematic:
  try {
    const client = await initializeBKTClient(config); // What if this fails?
  } catch (error) {
    // Now you have NO client instance at all!
    // You can't:
    // - Use default values
    // - Retry initialization later
    // - Fall back to cached data
    // - Continue with degraded functionality
  }

3. Graceful Degradation
   This design allows for graceful degradation:

const client = initializeBKTClient(config); // Always succeeds, gives you a client

  try {
    await client.waitForInitialization({ timeoutMs: 5000 });
    // Great! Use real feature flags
  } catch (error) {
    // Still have a working client that can:
    // - Return default values
    // - Log the error
    // - Retry later
    // - Use fallback logic
  }
  
  // Client is always usable regardless of initialization success
  const result = client.booleanVariation(user, 'feature', false);

[Copilot]

Pull Request Overview

This pull request adds asynchronous initialization support to the Bucketeer SDK client, enabling applications to wait for cache processors to complete their initial data synchronization before proceeding with feature flag evaluations. This improves reliability during startup by preventing race conditions between client usage and data loading.

• Add new waitForInitialization() method to the client interface with configurable timeout
• Refactor cache processors to support async start() and stop() methods for initialization control
• Introduce comprehensive error handling system with structured error types and conversion utilities

Reviewed Changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/index.ts	Adds waitForInitialization method to Bucketeer interface with comprehensive documentation
src/client.ts	Implements waitForInitialization method and updates client initialization to track async processor startup
src/objects/errors.ts	Introduces structured error hierarchy with BKTBaseError and specific error types for different status codes
src/objects/metricsEvent.ts	Refactors error handling to use structured error types and moves helper functions
src/cache/processor/*.ts	Updates cache processors to async start/stop methods for proper initialization control
src/tests/**/*.ts	Adds comprehensive test coverage for new initialization functionality and error handling
e2e/**/*.ts	Updates end-to-end tests to use waitForInitialization instead of manual delays

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[duyhungtnn]

@cre8ivejp please help me to take a look

[cre8ivejp]

Nice work!