react-native-demo-library-by-rinkal 1.2.7 → 1.3.0

package/QUICK_REFERENCE.md

@@ -0,0 +1,298 @@
+# Quick Reference Guide - MiniApp-Container Communication
+
+## 🚀 Quick Start (30 seconds)
+
+### MiniApp
+```typescript
+import MiniAppCommunication from 'react-native-demo-library-by-rinkal';
+
+MiniAppCommunication.initialize();
+MiniAppCommunication.sendEvent('hello', { message: 'Hi!' });
+```
+
+### Container
+```typescript
+import ContainerCommunication from 'react-native-demo-library-by-rinkal';
+
+ContainerCommunication.initialize();
+ContainerCommunication.onEvent('hello', (data) => console.log(data));
+```
+
+---
+
+## 📚 6 Communication Patterns
+
+### 1️⃣ Event Emitter (Fire & Forget)
+**MiniApp → Container**
+```typescript
+MiniAppCommunication.sendEvent('buttonClicked', { id: 123 });
+```
+**Container**
+```typescript
+ContainerCommunication.onEvent('buttonClicked', (data) => {
+  console.log('Button:', data.id);
+});
+```
+**📖 Reference**: https://reactnative.dev/docs/native-modules-ios#sending-events-to-javascript
+
+---
+
+### 2️⃣ Callback (Direct Invocation)
+**MiniApp**
+```typescript
+MiniAppCommunication.registerCallback('onSuccess', (result) => {
+  console.log('Success:', result);
+});
+```
+**📖 Reference**: https://reactnative.dev/docs/native-modules-ios#callbacks
+
+---
+
+### 3️⃣ Promise (Async Request-Response)
+**MiniApp**
+```typescript
+const data = await MiniAppCommunication.request('getUser', { id: 123 });
+console.log(data); // { name: 'John', email: 'john@example.com' }
+```
+**Container**
+```typescript
+ContainerCommunication.registerHandler('getUser', async (params) => {
+  return { name: 'John', email: 'john@example.com' };
+});
+```
+**📖 Reference**: https://reactnative.dev/docs/native-modules-ios#promises
+
+---
+
+### 4️⃣ Shared State (Bidirectional Sync)
+**MiniApp**
+```typescript
+MiniAppCommunication.setState('theme', 'dark');
+MiniAppCommunication.subscribeToState('theme', (newTheme) => {
+  console.log('Theme changed:', newTheme);
+});
+```
+**Container**
+```typescript
+ContainerCommunication.setState('theme', 'light');
+const theme = ContainerCommunication.getState('theme');
+```
+**📖 Reference**: https://redux.js.org/introduction/getting-started
+
+---
+
+### 5️⃣ Native Bridge (Native Module Calls)
+**MiniApp**
+```typescript
+const info = await MiniAppCommunication.callNative(
+  'DeviceInfo',
+  'getBatteryLevel'
+);
+console.log('Battery:', info);
+```
+**📖 Reference**: https://reactnative.dev/docs/native-modules-intro
+
+---
+
+### 6️⃣ Message Queue (Reliable Delivery)
+**MiniApp**
+```typescript
+MiniAppCommunication.queueMessage('analytics', {
+  event: 'page_view',
+  page: 'home'
+});
+```
+**Container**
+```typescript
+ContainerCommunication.registerMessageHandler('analytics', (msg) => {
+  console.log('Analytics:', msg.payload);
+});
+```
+**📖 Reference**: https://en.wikipedia.org/wiki/Message_queue
+
+---
+
+## 🎯 When to Use Each Pattern
+
+| Pattern | Use When |
+|---------|----------|
+| **Event Emitter** | Notifying about user actions, UI updates |
+| **Callback** | Simple function calls, synchronous operations |
+| **Promise** | Fetching data, waiting for results |
+| **Shared State** | Syncing settings, user preferences |
+| **Native Bridge** | Accessing device features (camera, GPS) |
+| **Message Queue** | Analytics, logging, offline support |
+
+---
+
+## 🔧 Common Operations
+
+### Initialize (Required)
+```typescript
+// In MiniApp
+MiniAppCommunication.initialize();
+
+// In Container
+ContainerCommunication.initialize();
+```
+
+### Cleanup (Recommended)
+```typescript
+useEffect(() => {
+  return () => {
+    MiniAppCommunication.cleanup();
+  };
+}, []);
+```
+
+### Error Handling
+```typescript
+try {
+  const result = await MiniAppCommunication.request('getData', {});
+} catch (error) {
+  console.error('Request failed:', error);
+}
+```
+
+---
+
+## 📱 Complete React Component Example
+
+### MiniApp Component
+```typescript
+import React, { useEffect, useState } from 'react';
+import { View, Button, Text } from 'react-native';
+import MiniAppCommunication from 'react-native-demo-library-by-rinkal';
+
+export const MyMiniApp = () => {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    MiniAppCommunication.initialize();
+    
+    const sub = MiniAppCommunication.onEvent('update', setData);
+    
+    return () => {
+      sub.remove();
+      MiniAppCommunication.cleanup();
+    };
+  }, []);
+
+  const fetchData = async () => {
+    const result = await MiniAppCommunication.request('getData', {});
+    setData(result);
+  };
+
+  return (
+    <View>
+      <Button title="Fetch Data" onPress={fetchData} />
+      <Text>{JSON.stringify(data)}</Text>
+    </View>
+  );
+};
+```
+
+### Container Component
+```typescript
+import React, { useEffect } from 'react';
+import { View, Button } from 'react-native';
+import ContainerCommunication from 'react-native-demo-library-by-rinkal';
+
+export const MyContainer = () => {
+  useEffect(() => {
+    ContainerCommunication.initialize();
+    
+    ContainerCommunication.registerHandler('getData', async () => {
+      return { message: 'Hello from container!' };
+    });
+
+    const sub = ContainerCommunication.onEvent('buttonClicked', (data) => {
+      console.log('MiniApp button clicked:', data);
+    });
+
+    return () => {
+      sub.remove();
+      ContainerCommunication.cleanup();
+    };
+  }, []);
+
+  const sendUpdate = () => {
+    ContainerCommunication.sendEvent('update', {
+      timestamp: Date.now()
+    });
+  };
+
+  return (
+    <View>
+      <Button title="Send Update" onPress={sendUpdate} />
+    </View>
+  );
+};
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Events Not Received?
+✅ Both sides initialized?
+✅ Correct event names?
+✅ Listener registered before sending?
+
+### Promise Timeout?
+✅ Handler registered in container?
+✅ Network/processing time < 30s?
+✅ Check console logs for errors?
+
+### State Not Syncing?
+✅ SharedState initialized?
+✅ Same key names used?
+✅ Subscriptions active?
+
+---
+
+## 📖 Full Documentation
+
+- **Complete Guide**: [COMMUNICATION_DOCS.md](./COMMUNICATION_DOCS.md)
+- **Official References**: [OFFICIAL_REFERENCES.md](./OFFICIAL_REFERENCES.md)
+- **Examples**: [CommunicationExample.tsx](./CommunicationExample.tsx)
+
+---
+
+## 🔗 Key Official Links
+
+1. React Native Events: https://reactnative.dev/docs/native-modules-ios#sending-events-to-javascript
+2. React Native Callbacks: https://reactnative.dev/docs/native-modules-ios#callbacks
+3. React Native Promises: https://reactnative.dev/docs/native-modules-ios#promises
+4. Native Modules: https://reactnative.dev/docs/native-modules-intro
+5. Node.js Events: https://nodejs.org/api/events.html
+6. JavaScript Promises: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+---
+
+## ⚡ Performance Tips
+
+1. **Batch Events**: Use message queue for multiple events
+2. **Debounce**: Limit frequent state updates
+3. **Cleanup**: Always cleanup listeners in useEffect
+4. **Error Handling**: Wrap all async calls in try-catch
+5. **Logging**: Use console logs during development
+
+---
+
+## 📦 Installation
+
+```bash
+npm install react-native-demo-library-by-rinkal
+```
+
+---
+
+## 📄 License
+ISC
+
+## 👨‍💻 Author
+Rinkal
+
+## 📌 Version
+1.3.0