@vailix/mask 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @vailix/mask
 
+## 0.2.4
+
+### Patch Changes
+
+- dfda662: fix: make singleton initialization truly atomic
+  - Fix race condition where check-and-set wasn't atomic by using IIFE pattern
+  - Add comprehensive tests for singleton pattern (12 tests including stress test with 100 concurrent calls)
+
+## 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/__tests__/singleton.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Tests for VailixSDK singleton pattern.
+ * 
+ * These tests verify that the race condition fix works correctly:
+ * - Multiple concurrent calls return the same instance
+ * - The promise is set atomically (no gap between check and set)
+ * - destroy() properly resets the singleton
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// We need to test the singleton pattern in isolation.
+// Since VailixSDK.doCreate has many dependencies, we'll mock them.
+
+// Mock all the heavy dependencies using proper class constructors
+vi.mock('../src/identity', () => {
+    return {
+        IdentityManager: class MockIdentityManager {
+            initialize = vi.fn().mockResolvedValue(undefined);
+            getMasterKey = vi.fn().mockReturnValue('0123456789abcdef0123456789abcdef');
+            getCurrentRPI = vi.fn().mockReturnValue('testrpi');
+            getMetadataKey = vi.fn().mockReturnValue('testkey');
+            getHistory = vi.fn().mockReturnValue([]);
+            getDisplayName = vi.fn().mockReturnValue('Test-123');
+        },
+    };
+});
+
+vi.mock('../src/db', () => ({
+    initializeDatabase: vi.fn().mockResolvedValue({
+        run: vi.fn().mockResolvedValue(undefined),
+    }),
+}));
+
+vi.mock('../src/storage', () => {
+    return {
+        StorageService: class MockStorageService {
+            initialize = vi.fn().mockResolvedValue(undefined);
+            cleanupOldScans = vi.fn().mockResolvedValue(undefined);
+            canScan = vi.fn().mockReturnValue(true);
+            logScan = vi.fn().mockResolvedValue(undefined);
+            getRecentPairs = vi.fn().mockResolvedValue([]);
+        },
+    };
+});
+
+vi.mock('../src/matcher', () => {
+    return {
+        MatcherService: class MockMatcherService {
+            on = vi.fn();
+            off = vi.fn();
+            emit = vi.fn();
+            getMatchById = vi.fn().mockResolvedValue(null);
+        },
+    };
+});
+
+vi.mock('../src/ble', () => {
+    return {
+        BleService: class MockBleService {
+            setStorage = vi.fn();
+            destroy = vi.fn();
+            startDiscovery = vi.fn().mockResolvedValue(undefined);
+            stopDiscovery = vi.fn().mockResolvedValue(undefined);
+            getNearbyUsers = vi.fn().mockReturnValue([]);
+            onNearbyUsersChanged = vi.fn().mockReturnValue(() => { });
+            pairWithUser = vi.fn().mockResolvedValue({ success: true });
+            unpairUser = vi.fn().mockResolvedValue(undefined);
+        },
+    };
+});
+
+vi.mock('react-native-quick-crypto', () => ({
+    createCipheriv: vi.fn(),
+    randomBytes: vi.fn().mockReturnValue(Buffer.alloc(12)),
+}));
+
+// Import after mocks are set up
+import { VailixSDK } from '../src/index';
+
+const TEST_CONFIG = {
+    appSecret: 'test-secret',
+    reportUrl: 'https://test.example.com',
+    downloadUrl: 'https://test.example.com',
+};
+
+describe('VailixSDK Singleton Pattern', () => {
+    beforeEach(async () => {
+        // Reset singleton state before each test
+        await VailixSDK.destroy();
+        vi.clearAllMocks();
+    });
+
+    describe('create()', () => {
+        it('should return the same instance on multiple sequential calls', async () => {
+            const sdk1 = await VailixSDK.create(TEST_CONFIG);
+            const sdk2 = await VailixSDK.create(TEST_CONFIG);
+            const sdk3 = await VailixSDK.create(TEST_CONFIG);
+
+            expect(sdk1).toBe(sdk2);
+            expect(sdk2).toBe(sdk3);
+        });
+
+        it('should return the same instance on concurrent calls (race condition test)', async () => {
+            // Launch multiple concurrent create() calls
+            const promises = [
+                VailixSDK.create(TEST_CONFIG),
+                VailixSDK.create(TEST_CONFIG),
+                VailixSDK.create(TEST_CONFIG),
+                VailixSDK.create(TEST_CONFIG),
+                VailixSDK.create(TEST_CONFIG),
+            ];
+
+            const results = await Promise.all(promises);
+
+            // All should be the exact same instance
+            const firstInstance = results[0];
+            results.forEach((sdk) => {
+                expect(sdk).toBe(firstInstance);
+            });
+        });
+
+        it('should only initialize once even with concurrent calls', async () => {
+            const { initializeDatabase } = await import('../src/db');
+
+            // Launch concurrent calls
+            await Promise.all([
+                VailixSDK.create(TEST_CONFIG),
+                VailixSDK.create(TEST_CONFIG),
+                VailixSDK.create(TEST_CONFIG),
+            ]);
+
+            // initializeDatabase should only be called once
+            expect(initializeDatabase).toHaveBeenCalledTimes(1);
+        });
+
+        it('should use config from first call only', async () => {
+            const config1 = { ...TEST_CONFIG, reportUrl: 'https://first.com' };
+            const config2 = { ...TEST_CONFIG, reportUrl: 'https://second.com' };
+
+            const sdk1 = await VailixSDK.create(config1);
+            const sdk2 = await VailixSDK.create(config2);
+
+            // Both should be the same instance
+            expect(sdk1).toBe(sdk2);
+            // The instance should use the first config (verified indirectly by same instance)
+        });
+    });
+
+    describe('isInitialized()', () => {
+        it('should return false before create() is called', () => {
+            expect(VailixSDK.isInitialized()).toBe(false);
+        });
+
+        it('should return true after create() completes', async () => {
+            await VailixSDK.create(TEST_CONFIG);
+            expect(VailixSDK.isInitialized()).toBe(true);
+        });
+
+        it('should return false after destroy() is called', async () => {
+            await VailixSDK.create(TEST_CONFIG);
+            expect(VailixSDK.isInitialized()).toBe(true);
+
+            await VailixSDK.destroy();
+            expect(VailixSDK.isInitialized()).toBe(false);
+        });
+    });
+
+    describe('destroy()', () => {
+        it('should allow creating a new instance after destroy', async () => {
+            const sdk1 = await VailixSDK.create(TEST_CONFIG);
+            await VailixSDK.destroy();
+
+            const sdk2 = await VailixSDK.create(TEST_CONFIG);
+
+            // Should be different instances
+            expect(sdk1).not.toBe(sdk2);
+        });
+
+        it('should be safe to call destroy() multiple times', async () => {
+            await VailixSDK.create(TEST_CONFIG);
+
+            // Multiple destroy calls should not throw
+            await VailixSDK.destroy();
+            await VailixSDK.destroy();
+            await VailixSDK.destroy();
+
+            expect(VailixSDK.isInitialized()).toBe(false);
+        });
+
+        it('should be safe to call destroy() without prior create()', async () => {
+            // Should not throw
+            await VailixSDK.destroy();
+            expect(VailixSDK.isInitialized()).toBe(false);
+        });
+    });
+
+    describe('Race condition stress test', () => {
+        it('should handle many concurrent calls correctly', async () => {
+            const CONCURRENT_CALLS = 100;
+
+            const promises = Array.from({ length: CONCURRENT_CALLS }, () =>
+                VailixSDK.create(TEST_CONFIG)
+            );
+
+            const results = await Promise.all(promises);
+
+            // All should be the exact same instance
+            const firstInstance = results[0];
+            expect(results.every(sdk => sdk === firstInstance)).toBe(true);
+
+            // Verify initialization only happened once
+            const { initializeDatabase } = await import('../src/db');
+            expect(initializeDatabase).toHaveBeenCalledTimes(1);
+        });
+
+        it('should handle interleaved create and destroy calls', async () => {
+            // First creation
+            const sdk1 = await VailixSDK.create(TEST_CONFIG);
+
+            // Destroy and recreate
+            await VailixSDK.destroy();
+            const sdk2 = await VailixSDK.create(TEST_CONFIG);
+
+            // Destroy and recreate again
+            await VailixSDK.destroy();
+            const sdk3 = await VailixSDK.create(TEST_CONFIG);
+
+            // All should be different instances
+            expect(sdk1).not.toBe(sdk2);
+            expect(sdk2).not.toBe(sdk3);
+            expect(sdk1).not.toBe(sdk3);
+        });
+    });
+});

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,36 @@ 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 = (async () => {
+      try {
+        const sdk = await _VailixSDK.doCreate(config);
+        _VailixSDK.instance = sdk;
+        return sdk;
+      } catch (error) {
+        _VailixSDK.initPromise = null;
+        throw error;
+      }
+    })();
+    return _VailixSDK.initPromise;
+  }
+  /**
+   * 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 +913,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,36 @@ 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 = (async () => {
+      try {
+        const sdk = await _VailixSDK.doCreate(config);
+        _VailixSDK.instance = sdk;
+        return sdk;
+      } catch (error) {
+        _VailixSDK.initPromise = null;
+        throw error;
+      }
+    })();
+    return _VailixSDK.initPromise;
+  }
+  /**
+   * 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 +877,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.4",
   "description": "Privacy-preserving proximity tracing SDK for React Native & Expo",
   "author": "Gil Eyni",
   "keywords": [
@@ -52,7 +52,8 @@
   "devDependencies": {
     "drizzle-kit": "^0.30.0",
     "typescript": "^5.7.0",
-    "tsup": "^8.0.0"
+    "tsup": "^8.0.0",
+    "vitest": "^4.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",

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,45 @@ 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
+        if (VailixSDK.initPromise) {
+            return VailixSDK.initPromise;
+        }
+
+        // CRITICAL: Set promise SYNCHRONOUSLY before any await
+        // This makes the check-and-set atomic within the same microtask
+        VailixSDK.initPromise = (async () => {
+            try {
+                const sdk = await VailixSDK.doCreate(config);
+                VailixSDK.instance = sdk;
+                return sdk;
+            } catch (error) {
+                // Clear promise on failure so retry is possible
+                VailixSDK.initPromise = null;
+                throw error;
+            }
+        })();
+
+        return VailixSDK.initPromise;
+    }
+
+    /**
+     * 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 +137,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
     // ========================================================================

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        environment: 'node',
+        include: ['__tests__/**/*.test.ts'],
+        globals: true,
+    },
+});