@vailix/mask 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @vailix/mask
 
+## 0.2.3
+
+### Patch Changes
+
+- c1ca263: fix: prevent race condition in SDK initialization
+  - Implement singleton pattern for `VailixSDK.create()` to prevent concurrent database connections
+  - Ensure database is properly closed before deletion on key mismatch errors
+  - Add missing internal BLE types (`InternalNearbyUser`, `PendingPairRequest`, `BleServiceConfig`)
+  - Add `VailixSDK.destroy()` for cleanup and `VailixSDK.isInitialized()` for status checking
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -62,6 +62,16 @@ const unsubscribe = sdk.onNearbyUsersChanged((users) => {
 });
 ```
 
+> **Note:** `VailixSDK.create()` returns a singleton instance. Multiple calls return the same instance, and the config is only used on the first call. Use `VailixSDK.destroy()` to reset the SDK if needed.
+
+### Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `VailixSDK.create(config)` | Create or return the singleton SDK instance |
+| `VailixSDK.destroy()` | Release resources and reset the singleton |
+| `VailixSDK.isInitialized()` | Check if the SDK has been initialized |
+
 ## Compatibility
 
 - **Expo**: SDK 52+ (Development Build required, **Expo Go not supported**)

package/dist/index.d.mts

@@ -227,6 +227,8 @@ interface ParsedQR {
 }
 
 declare class VailixSDK {
+    private static instance;
+    private static initPromise;
     identity: IdentityManager;
     storage: StorageService;
     matcher: MatcherService;
@@ -237,11 +239,27 @@ declare class VailixSDK {
     private rpiDurationMs;
     private constructor();
     /**
-     * Create and initialize the VailixSDK.
+     * Create or return the singleton SDK instance.
      *
-     * @param config - Unified configuration object
+     * Thread-safe: concurrent calls will wait for the first initialization to complete
+     * and return the same instance. Config is only used on first initialization.
+     *
+     * @param config - Unified configuration object (used only on first call)
      */
     static create(config: VailixConfig): Promise<VailixSDK>;
+    /**
+     * Internal initialization logic (extracted for singleton pattern).
+     */
+    private static doCreate;
+    /**
+     * Destroy the singleton instance and release all resources.
+     * Use for testing or when the app needs to fully reset the SDK.
+     */
+    static destroy(): Promise<void>;
+    /**
+     * Check if the SDK has been initialized.
+     */
+    static isInitialized(): boolean;
     /** Get current QR code data */
     getQRCode(): string;
     /**

package/dist/index.d.ts

@@ -227,6 +227,8 @@ interface ParsedQR {
 }
 
 declare class VailixSDK {
+    private static instance;
+    private static initPromise;
     identity: IdentityManager;
     storage: StorageService;
     matcher: MatcherService;
@@ -237,11 +239,27 @@ declare class VailixSDK {
     private rpiDurationMs;
     private constructor();
     /**
-     * Create and initialize the VailixSDK.
+     * Create or return the singleton SDK instance.
      *
-     * @param config - Unified configuration object
+     * Thread-safe: concurrent calls will wait for the first initialization to complete
+     * and return the same instance. Config is only used on first initialization.
+     *
+     * @param config - Unified configuration object (used only on first call)
      */
     static create(config: VailixConfig): Promise<VailixSDK>;
+    /**
+     * Internal initialization logic (extracted for singleton pattern).
+     */
+    private static doCreate;
+    /**
+     * Destroy the singleton instance and release all resources.
+     * Use for testing or when the app needs to fully reset the SDK.
+     */
+    static destroy(): Promise<void>;
+    /**
+     * Check if the SDK has been initialized.
+     */
+    static isInitialized(): boolean;
     /** Get current QR code data */
     getQRCode(): string;
     /**

package/dist/index.js

@@ -826,6 +826,9 @@ async function tryOpenEncryptedDatabase(masterKey) {
 
 // src/index.ts
 var VailixSDK = class _VailixSDK {
+  // Singleton instance and initialization promise for thread-safety
+  static instance = null;
+  static initPromise = null;
   identity;
   storage;
   matcher;
@@ -845,11 +848,33 @@ var VailixSDK = class _VailixSDK {
     this.rpiDurationMs = rpiDurationMs;
   }
   /**
-   * Create and initialize the VailixSDK.
+   * Create or return the singleton SDK instance.
    * 
-   * @param config - Unified configuration object
+   * Thread-safe: concurrent calls will wait for the first initialization to complete
+   * and return the same instance. Config is only used on first initialization.
+   * 
+   * @param config - Unified configuration object (used only on first call)
    */
   static async create(config) {
+    if (_VailixSDK.instance) {
+      return _VailixSDK.instance;
+    }
+    if (_VailixSDK.initPromise) {
+      return _VailixSDK.initPromise;
+    }
+    _VailixSDK.initPromise = _VailixSDK.doCreate(config);
+    try {
+      _VailixSDK.instance = await _VailixSDK.initPromise;
+      return _VailixSDK.instance;
+    } catch (error) {
+      _VailixSDK.initPromise = null;
+      throw error;
+    }
+  }
+  /**
+   * Internal initialization logic (extracted for singleton pattern).
+   */
+  static async doCreate(config) {
     const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1e3;
     if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
       throw new Error(`rescanIntervalMs (${config.rescanIntervalMs}) cannot exceed rpiDurationMs (${rpiDuration})`);
@@ -885,6 +910,23 @@ var VailixSDK = class _VailixSDK {
       rpiDuration
     );
   }
+  /**
+   * Destroy the singleton instance and release all resources.
+   * Use for testing or when the app needs to fully reset the SDK.
+   */
+  static async destroy() {
+    if (_VailixSDK.instance) {
+      _VailixSDK.instance.ble.destroy();
+      _VailixSDK.instance = null;
+    }
+    _VailixSDK.initPromise = null;
+  }
+  /**
+   * Check if the SDK has been initialized.
+   */
+  static isInitialized() {
+    return _VailixSDK.instance !== null;
+  }
   // ========================================================================
   // QR Code Methods
   // ========================================================================

package/dist/index.mjs

@@ -790,6 +790,9 @@ async function tryOpenEncryptedDatabase(masterKey) {
 
 // src/index.ts
 var VailixSDK = class _VailixSDK {
+  // Singleton instance and initialization promise for thread-safety
+  static instance = null;
+  static initPromise = null;
   identity;
   storage;
   matcher;
@@ -809,11 +812,33 @@ var VailixSDK = class _VailixSDK {
     this.rpiDurationMs = rpiDurationMs;
   }
   /**
-   * Create and initialize the VailixSDK.
+   * Create or return the singleton SDK instance.
    * 
-   * @param config - Unified configuration object
+   * Thread-safe: concurrent calls will wait for the first initialization to complete
+   * and return the same instance. Config is only used on first initialization.
+   * 
+   * @param config - Unified configuration object (used only on first call)
    */
   static async create(config) {
+    if (_VailixSDK.instance) {
+      return _VailixSDK.instance;
+    }
+    if (_VailixSDK.initPromise) {
+      return _VailixSDK.initPromise;
+    }
+    _VailixSDK.initPromise = _VailixSDK.doCreate(config);
+    try {
+      _VailixSDK.instance = await _VailixSDK.initPromise;
+      return _VailixSDK.instance;
+    } catch (error) {
+      _VailixSDK.initPromise = null;
+      throw error;
+    }
+  }
+  /**
+   * Internal initialization logic (extracted for singleton pattern).
+   */
+  static async doCreate(config) {
     const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1e3;
     if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
       throw new Error(`rescanIntervalMs (${config.rescanIntervalMs}) cannot exceed rpiDurationMs (${rpiDuration})`);
@@ -849,6 +874,23 @@ var VailixSDK = class _VailixSDK {
       rpiDuration
     );
   }
+  /**
+   * Destroy the singleton instance and release all resources.
+   * Use for testing or when the app needs to fully reset the SDK.
+   */
+  static async destroy() {
+    if (_VailixSDK.instance) {
+      _VailixSDK.instance.ble.destroy();
+      _VailixSDK.instance = null;
+    }
+    _VailixSDK.initPromise = null;
+  }
+  /**
+   * Check if the SDK has been initialized.
+   */
+  static isInitialized() {
+    return _VailixSDK.instance !== null;
+  }
   // ========================================================================
   // QR Code Methods
   // ========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vailix/mask",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Privacy-preserving proximity tracing SDK for React Native & Expo",
   "author": "Gil Eyni",
   "keywords": [

package/src/index.ts

@@ -16,6 +16,10 @@ import type {
 } from './types';
 
 export class VailixSDK {
+    // Singleton instance and initialization promise for thread-safety
+    private static instance: VailixSDK | null = null;
+    private static initPromise: Promise<VailixSDK> | null = null;
+
     public identity: IdentityManager;
     public storage: StorageService;
     public matcher: MatcherService;
@@ -46,11 +50,41 @@ export class VailixSDK {
     }
 
     /**
-     * Create and initialize the VailixSDK.
+     * Create or return the singleton SDK instance.
+     * 
+     * Thread-safe: concurrent calls will wait for the first initialization to complete
+     * and return the same instance. Config is only used on first initialization.
      * 
-     * @param config - Unified configuration object
+     * @param config - Unified configuration object (used only on first call)
      */
     static async create(config: VailixConfig): Promise<VailixSDK> {
+        // Already initialized - return existing instance
+        if (VailixSDK.instance) {
+            return VailixSDK.instance;
+        }
+
+        // Initialization in progress - wait for it (prevents race condition)
+        if (VailixSDK.initPromise) {
+            return VailixSDK.initPromise;
+        }
+
+        // First call - start initialization
+        VailixSDK.initPromise = VailixSDK.doCreate(config);
+
+        try {
+            VailixSDK.instance = await VailixSDK.initPromise;
+            return VailixSDK.instance;
+        } catch (error) {
+            // Clear promise on failure so retry is possible
+            VailixSDK.initPromise = null;
+            throw error;
+        }
+    }
+
+    /**
+     * Internal initialization logic (extracted for singleton pattern).
+     */
+    private static async doCreate(config: VailixConfig): Promise<VailixSDK> {
         // Validate: rescanInterval cannot exceed rpiDuration
         const rpiDuration = config.rpiDurationMs ?? 15 * 60 * 1000; // Default 15 min
         if (config.rescanIntervalMs && config.rescanIntervalMs > rpiDuration) {
@@ -99,6 +133,27 @@ export class VailixSDK {
         );
     }
 
+    /**
+     * Destroy the singleton instance and release all resources.
+     * Use for testing or when the app needs to fully reset the SDK.
+     */
+    static async destroy(): Promise<void> {
+        if (VailixSDK.instance) {
+            // Cleanup BLE resources
+            VailixSDK.instance.ble.destroy();
+            // Note: Database connection cleanup is handled by expo-sqlite
+            VailixSDK.instance = null;
+        }
+        VailixSDK.initPromise = null;
+    }
+
+    /**
+     * Check if the SDK has been initialized.
+     */
+    static isInitialized(): boolean {
+        return VailixSDK.instance !== null;
+    }
+
     // ========================================================================
     // QR Code Methods
     // ========================================================================