multi platform

Author: raju-opti

docs/PLATFORM_ISOLATION.md

@@ -6,47 +6,116 @@ This project supports multiple runtime platforms (Browser, Node.js, React Native
 
 ## Naming Convention
 
-Platform-specific files use a suffix pattern:
+Platform-specific files can be identified in two ways:
+
+### 1. File Naming Convention (Single Platform)
+
+For files specific to a single platform, use a suffix pattern:
 - `.browser.ts` - Browser-specific implementation
 - `.node.ts` - Node.js-specific implementation
 - `.react_native.ts` - React Native-specific implementation
 - `.ts` (no suffix) - Universal code (works across all platforms)
 
+### 2. Export Declaration (Multiple Platforms)
+
+For files that support multiple platforms but not all (e.g., Browser + React Native, but not Node.js), export a `__supportedPlatforms` array:
+
+```typescript
+// lib/utils/web-features.ts
+export const __supportedPlatforms = ['browser', 'react_native'];
+
+// Your code that works on both browser and react_native
+export function getWindowSize() {
+  // Implementation that works on both platforms
+}
+```
+
+Valid platform identifiers: `'browser'`, `'node'`, `'react_native'`
+
+### Priority
+
+If a file has both a platform suffix in its name AND a `__supportedPlatforms` export, the `__supportedPlatforms` export **takes priority**. This allows you to keep the `.browser.ts` naming convention while expanding support to additional platforms like React Native.
+
 ## Import Rules
 
 Each platform-specific file can **only** import from:
 
-1. **Universal files** (no platform suffix)
-2. **Same-platform files** (matching platform suffix)
+1. **Universal files** (no platform restrictions)
+2. **Compatible platform files** (files that support ALL the required platforms)
 3. **External packages** (node_modules)
 
+A file is compatible if:
+- It's universal (no platform restrictions)
+- For single-platform files: The import supports at least that platform
+- For multi-platform files: The import supports ALL of those platforms
+
+### Compatibility Examples
+
+**Single Platform File (`.browser.ts` or `__supportedPlatforms = ['browser']`)**
+- ✅ Can import from: universal files, `.browser.ts` files, files with `['browser']` or `['browser', 'react_native']`
+- ❌ Cannot import from: `.node.ts` files, files with `['node']` or `['react_native']` only
+
+**Multi-Platform File (`__supportedPlatforms = ['browser', 'react_native']`)**
+- ✅ Can import from: universal files, files with exactly `['browser', 'react_native']`
+- ❌ Cannot import from: `.browser.ts` (browser only), `.react_native.ts` (react_native only), `.node.ts`
+- **Why?** A file supporting both platforms needs imports that work in BOTH environments
+
 ### Examples
 
 ✅ **Valid Imports**
 
 ```typescript
-// In lib/index.browser.ts
+// In lib/index.browser.ts (Browser platform only)
 import { Config } from './shared_types';  // ✅ Universal file
-import { BrowserRequestHandler } from './utils/http_request_handler/request_handler.browser'; // ✅ Same platform
+import { BrowserRequestHandler } from './utils/http_request_handler/request_handler.browser'; // ✅ browser + react_native (supports browser)
 import { uuid } from 'uuid'; // ✅ External package
 ```
 
 ```typescript
-// In lib/index.node.ts
+// In lib/index.node.ts (Node platform only)
 import { Config } from './shared_types';  // ✅ Universal file
 import { NodeRequestHandler } from './utils/http_request_handler/request_handler.node'; // ✅ Same platform
 ```
 
+```typescript
+// In lib/index.react_native.ts (React Native platform only)
+import { Config } from './shared_types';  // ✅ Universal file
+
+// If web-features.ts has: __supportedPlatforms = ['browser', 'react_native']
+import { getWindowSize } from './utils/web-features'; // ✅ Compatible (supports react_native)
+```
+
+```typescript
+// In lib/utils/web-api.ts
+// export const __supportedPlatforms = ['browser', 'react_native'];
+
+import { Config } from './shared_types';  // ✅ Universal file
+
+// If dom-helpers.ts has: __supportedPlatforms = ['browser', 'react_native']
+import { helpers } from './dom-helpers'; // ✅ Compatible (supports BOTH browser and react_native)
+```
+
 ❌ **Invalid Imports**
 
 ```typescript
-// In lib/index.browser.ts
-import { NodeRequestHandler } from './utils/http_request_handler/request_handler.node'; // ❌ Different platform
+// In lib/index.browser.ts (Browser platform only)
+import { NodeRequestHandler } from './utils/http_request_handler/request_handler.node'; // ❌ Node-only file
+```
+
+```typescript
+// In lib/index.node.ts (Node platform only)
+// If web-features.ts has: __supportedPlatforms = ['browser', 'react_native']
+import { getWindowSize } from './utils/web-features'; // ❌ Not compatible with Node
 ```
 
 ```typescript
-// In lib/index.node.ts
-import { BrowserRequestHandler } from './utils/http_request_handler/request_handler.browser'; // ❌ Different platform
+// In lib/utils/web-api.ts  
+// export const __supportedPlatforms = ['browser', 'react_native'];
+
+// If helper.browser.ts is browser-only (no __supportedPlatforms export)
+import { helper } from './helper.browser'; // ❌ Browser-only, doesn't support react_native
+
+// This file needs imports that work in BOTH browser AND react_native
 ```
 
 ## Automatic Validation
@@ -95,11 +164,13 @@ If platform isolation is violated, the build will fail with a detailed error mes
 
 When creating new platform-specific implementations:
 
+### Single Platform
+
 1. Name the file with the appropriate platform suffix (e.g., `my-feature.browser.ts`)
 2. Only import from universal or same-platform files
 3. Create a universal factory or interface if multiple platforms need different implementations
 
-### Example: Creating a Platform-Specific Feature
+**Example:**
 
 ```typescript
 // lib/features/my-feature.ts (universal interface)
@@ -130,6 +201,39 @@ import { NodeMyFeature } from './my-feature.node';
 export const createMyFeature = () => new NodeMyFeature();
 ```
 
+### Multiple Platforms (But Not All)
+
+For code that works on multiple platforms but not all, use the `__supportedPlatforms` export:
+
+**Example: Browser + React Native only**
+
+```typescript
+// lib/utils/dom-helpers.ts
+export const __supportedPlatforms = ['browser', 'react_native'];
+
+// This code works on both browser and react_native, but not node
+export function getElementById(id: string): Element | null {
+  if (typeof document !== 'undefined') {
+    return document.getElementById(id);
+  }
+  // React Native polyfill or alternative
+  return null;
+}
+```
+
+**Example: Node + React Native only**
+
+```typescript
+// lib/utils/native-crypto.ts
+export const __supportedPlatforms = ['node', 'react_native'];
+
+import crypto from 'crypto'; // Available in both Node and React Native
+
+export function generateHash(data: string): string {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+```
+
 ## Troubleshooting
 
 If you encounter a platform isolation error:

lib/event_processor/event_dispatcher/default_dispatcher.browser.ts

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+// This implementation works in both browser and react_native environments
+export const __supportedPlatforms = ['browser', 'react_native'];
+
 import { BrowserRequestHandler } from "../../utils/http_request_handler/request_handler.browser";
 import { EventDispatcher } from './event_dispatcher';
 import { DefaultEventDispatcher } from './default_dispatcher';

lib/utils/http_request_handler/request_handler.browser.ts

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+// This implementation works in both browser and react_native environments
+export const __supportedPlatforms = ['browser', 'react_native'];
+
 import { AbortableRequest, Headers, RequestHandler, Response } from './http';
 import { LoggerFacade, LogLevel } from '../../logging/logger';
 import { REQUEST_TIMEOUT_MS } from '../enums';

package.json

@@ -58,6 +58,7 @@
     "clean:win": "(if exist dist rd /s/q dist)",
     "lint": "tsc --noEmit && eslint 'lib/**/*.js' 'lib/**/*.ts'",
     "validate-platform-isolation": "node scripts/validate-platform-isolation.js",
+    "test-platform-isolation": "node scripts/test-validator.js",
     "test-vitest": "vitest run",
     "test-mocha": "TS_NODE_COMPILER_OPTIONS='{\"module\": \"commonjs\" }' mocha -r ts-node/register -r tsconfig-paths/register -r lib/tests/exit_on_unhandled_rejection.js 'lib/**/*.tests.ts' 'lib/**/*.tests.js'",
     "test": "npm run test-mocha && npm run test-vitest",

scripts/README.md

@@ -0,0 +1,61 @@
+# Scripts
+
+This directory contains build and validation scripts for the JavaScript SDK.
+
+## validate-platform-isolation.js
+
+Validates that platform-specific code is properly isolated to prevent runtime errors when building for different platforms (Browser, Node.js, React Native).
+
+### Usage
+
+```bash
+# Run manually
+node scripts/validate-platform-isolation.js
+
+# Run via npm script
+npm run validate-platform-isolation
+
+# Runs automatically during build
+npm run build
+```
+
+### How It Works
+
+The script:
+1. Scans all TypeScript/JavaScript files in the `lib/` directory
+2. Identifies platform-specific files by:
+   - Naming convention (`.browser.ts`, `.node.ts`, `.react_native.ts`)
+   - `__supportedPlatforms` export for multi-platform files
+3. Parses import statements (ES6 imports, require(), dynamic imports)
+4. Validates that each import is compatible with the file's platform
+5. Fails with exit code 1 if any violations are found
+
+### Exit Codes
+
+- `0`: All platform-specific files are properly isolated
+- `1`: Violations found or script error
+
+## test-validator.js
+
+Comprehensive test suite for the platform isolation validator. Documents and validates all compatibility rules.
+
+### Usage
+
+```bash
+# Run via npm script
+npm run test-platform-isolation
+
+# Or run directly
+node scripts/test-validator.js
+```
+
+Tests cover:
+- Universal imports (always compatible)
+- Single platform file imports
+- Single platform importing from multi-platform files
+- Multi-platform file imports (strictest rules)
+- `__supportedPlatforms` extraction
+
+---
+
+See [../docs/PLATFORM_ISOLATION.md](../docs/PLATFORM_ISOLATION.md) for detailed documentation on platform isolation rules.

scripts/test-validator.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * Comprehensive test suite for platform isolation validator
+ * 
+ * This test documents and validates all the compatibility rules
+ */
+
+const assert = require('assert');
+const validator = require('./validate-platform-isolation.js');
+
+let passed = 0;
+let failed = 0;
+
+function test(description, actual, expected) {
+  try {
+    assert.strictEqual(actual, expected);
+    console.log(`✅ ${description}`);
+    passed++;
+  } catch (e) {
+    console.log(`❌ ${description}`);
+    console.log(`   Expected: ${expected}, Got: ${actual}`);
+    failed++;
+  }
+}
+
+console.log('Platform Isolation Validator - Comprehensive Test Suite\n');
+console.log('=' .repeat(70));
+
+console.log('\n1. UNIVERSAL IMPORTS (always compatible)');
+console.log('-'.repeat(70));
+test('Browser file can import universal', 
+  validator.isPlatformCompatible('browser', null), true);
+test('Node file can import universal', 
+  validator.isPlatformCompatible('node', null), true);
+test('Multi-platform file can import universal', 
+  validator.isPlatformCompatible(['browser', 'react_native'], null), true);
+
+console.log('\n2. SINGLE PLATFORM FILES');
+console.log('-'.repeat(70));
+test('Browser file can import from browser file', 
+  validator.isPlatformCompatible('browser', 'browser'), true);
+test('Browser file CANNOT import from node file', 
+  validator.isPlatformCompatible('browser', 'node'), false);
+test('Node file can import from node file', 
+  validator.isPlatformCompatible('node', 'node'), true);
+test('React Native file can import from react_native file', 
+  validator.isPlatformCompatible('react_native', 'react_native'), true);
+
+console.log('\n3. SINGLE PLATFORM IMPORTING FROM MULTI-PLATFORM');
+console.log('-'.repeat(70));
+test('Browser file CAN import from [browser, react_native] file', 
+  validator.isPlatformCompatible('browser', ['browser', 'react_native']), true);
+test('React Native file CAN import from [browser, react_native] file', 
+  validator.isPlatformCompatible('react_native', ['browser', 'react_native']), true);
+test('Node file CANNOT import from [browser, react_native] file', 
+  validator.isPlatformCompatible('node', ['browser', 'react_native']), false);
+
+console.log('\n4. MULTI-PLATFORM FILES (strictest rules)');
+console.log('-'.repeat(70));
+test('[browser, react_native] file CAN import from [browser, react_native] file', 
+  validator.isPlatformCompatible(['browser', 'react_native'], ['browser', 'react_native']), true);
+test('[browser, react_native] file CANNOT import from browser-only file', 
+  validator.isPlatformCompatible(['browser', 'react_native'], 'browser'), false);
+test('[browser, react_native] file CANNOT import from react_native-only file', 
+  validator.isPlatformCompatible(['browser', 'react_native'], 'react_native'), false);
+test('[browser, react_native] file CANNOT import from node file', 
+  validator.isPlatformCompatible(['browser', 'react_native'], 'node'), false);
+
+console.log('\n5. SUPPORTED PLATFORMS EXTRACTION');
+console.log('-'.repeat(70));
+const testExport1 = `export const __supportedPlatforms = ['browser', 'react_native'];`;
+const platforms1 = validator.extractSupportedPlatforms(testExport1);
+test('Extract __supportedPlatforms array', 
+  JSON.stringify(platforms1), JSON.stringify(['browser', 'react_native']));
+
+const testExport2 = `export const __supportedPlatforms: string[] = ["browser", "node"];`;
+const platforms2 = validator.extractSupportedPlatforms(testExport2);
+test('Extract __supportedPlatforms with type annotation', 
+  JSON.stringify(platforms2), JSON.stringify(['browser', 'node']));
+
+console.log('\n' + '='.repeat(70));
+console.log(`\nResults: ${passed} passed, ${failed} failed`);
+
+if (failed > 0) {
+  process.exit(1);
+}
+
+console.log('\n✅ All tests passed!');