{"_id":"@astacinco/rn-performance","name":"@astacinco/rn-performance","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@astacinco/rn-performance","version":"0.1.0","description":"Performance monitoring with adapter pattern - memory leak detection and metrics reporting","main":"src/index.ts","types":"src/index.ts","repository":{"type":"git","url":"git+https://github.com/jrudydev/rn-toolkit.git","directory":"packages/performance"},"publishConfig":{"access":"public"},"author":{"name":"Spark Labs","email":"hello@sparklabs.dev"},"homepage":"https://github.com/jrudydev/rn-toolkit#readme","scripts":{"typecheck":"tsc --noEmit","test":"jest"},"peerDependencies":{"react":">=17.0.0","react-native":">=0.64.0"},"optionalDependencies":{"@react-native-firebase/perf":">=18.0.0"},"devDependencies":{"@types/react":"^18.0.0","react":"^18.2.0","react-native":"^0.72.0","typescript":"^5.0.0"},"keywords":["react-native","performance","memory-leak","monitoring","adapter-pattern","profiling","metrics"],"license":"MIT","_id":"@astacinco/rn-performance@0.1.0","gitHead":"6fa965625ad344ec91902e42e12b2000624373ea","bugs":{"url":"https://github.com/jrudydev/rn-toolkit/issues"},"_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Ii1u1d0Kxcl3EpC2VG8DEd3trcN84dOlmqMhwiGRpnjb0KVKu2DRRnALaF3UBkcUbRqH7VYO0JS7IHYauA/8kw==","shasum":"1ea664798028142eff05941a8cb645b7d84435fc","tarball":"https://registry.npmjs.org/@astacinco/rn-performance/-/rn-performance-0.1.0.tgz","fileCount":18,"unpackedSize":87258,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHbC+UZfKK0eerPuwlB7uMhZcaeeDxY6RLEmhQPhZsESAiAGM5kZCgAPnvi0j3kUYuNC0qYEpCdNQYHEQXQ+D+eXOw=="}]},"_npmUser":{"name":"sparklabs343","email":"gomez.rudy@gmail.com"},"directories":{},"maintainers":[{"name":"sparklabs343","email":"gomez.rudy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rn-performance_0.1.0_1772793182098_0.765047731031608"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-06T10:33:01.982Z","0.1.0":"2026-03-06T10:33:02.250Z","modified":"2026-03-06T10:33:02.407Z"},"maintainers":[{"name":"sparklabs343","email":"gomez.rudy@gmail.com"}],"description":"Performance monitoring with adapter pattern - memory leak detection and metrics reporting","homepage":"https://github.com/jrudydev/rn-toolkit#readme","keywords":["react-native","performance","memory-leak","monitoring","adapter-pattern","profiling","metrics"],"repository":{"type":"git","url":"git+https://github.com/jrudydev/rn-toolkit.git","directory":"packages/performance"},"author":{"name":"Spark Labs","email":"hello@sparklabs.dev"},"bugs":{"url":"https://github.com/jrudydev/rn-toolkit/issues"},"license":"MIT","readme":"# @astacinco/rn-performance\n\nPerformance monitoring with **adapter pattern** for React Native - swap monitoring backends without code changes.\n\n## Features\n\n- **Adapter Pattern** - Swap monitoring backends (Firebase Performance, Sentry, etc.) without changing app code\n- **Built-in Adapters** - Firebase, Console (debug), NoOp (testing)\n- **Performance Traces** - Track operation durations with attributes and metrics\n- **Memory Leak Detection** - Track subscriptions, timers, and listeners for cleanup verification\n- **Render Tracking** - Monitor component renders and detect excessive re-renders\n- **Network Tracing** - Track API request performance\n- **TypeScript** - Full type safety with comprehensive interfaces\n\n## Installation\n\n```bash\nnpm install @astacinco/rn-performance\n```\n\n### For Firebase Performance (production)\n\n```bash\nnpm install @react-native-firebase/perf\n```\n\n## Quick Start\n\n### 1. Choose your adapter\n\n```tsx\nimport {\n  PerformanceProvider,\n  FirebaseAdapter,\n  ConsoleAdapter,\n  NoOpAdapter,\n} from '@astacinco/rn-performance';\n\n// Production: Firebase Performance\nconst adapter = new FirebaseAdapter();\n\n// Development: Console logging\nconst adapter = new ConsoleAdapter({ prefix: '[Perf]' });\n\n// Testing: No-op (silent)\nconst adapter = new NoOpAdapter();\n```\n\n### 2. Wrap your app\n\n```tsx\nfunction App() {\n  const adapter = __DEV__\n    ? new ConsoleAdapter({ prefix: '[Perf]' })\n    : new FirebaseAdapter();\n\n  return (\n    <PerformanceProvider\n      adapter={adapter}\n      config={{\n        debug: __DEV__,\n        trackRenders: __DEV__,\n        renderCountThreshold: 10,\n      }}\n    >\n      <MyApp />\n    </PerformanceProvider>\n  );\n}\n```\n\n### 3. Use in components\n\n```tsx\nimport {\n  usePerformance,\n  useLeakDetector,\n  useRenderTracker,\n} from '@astacinco/rn-performance';\n\nfunction DataLoader() {\n  // Performance monitoring\n  const { measure, startTrace, recordMetric } = usePerformance();\n\n  // Memory leak detection\n  const { trackSubscription, trackTimer } = useLeakDetector({\n    componentName: 'DataLoader',\n  });\n\n  // Render tracking\n  const { renderCount } = useRenderTracker({\n    componentName: 'DataLoader',\n    threshold: 5,\n  });\n\n  useEffect(() => {\n    // Measure async operations\n    const loadData = async () => {\n      const data = await measure('load_data', async () => {\n        return api.fetchData();\n      }, 'network');\n\n      setData(data);\n    };\n\n    loadData();\n\n    // Track subscription for leak detection\n    const unsubscribe = api.subscribe(handleUpdate);\n    trackSubscription('data_updates', unsubscribe);\n\n    // Track timer\n    const timerId = setInterval(refresh, 5000);\n    trackTimer('refresh_interval', timerId);\n\n    // Cleanup happens automatically on unmount!\n  }, []);\n\n  return <View>...</View>;\n}\n```\n\n## API Reference\n\n### PerformanceProvider\n\nProvider component that wraps your app with performance context.\n\n```tsx\n<PerformanceProvider\n  adapter={adapter}        // Required: Performance adapter\n  config={{\n    enabled: true,         // Enable monitoring\n    debug: false,          // Debug logging\n    trackRenders: false,   // Track component renders\n    renderCountThreshold: 10,      // Re-render warning threshold\n    renderDurationThreshold: 16,   // Slow render threshold (ms)\n    traceNetwork: false,   // Auto-trace network requests\n    sampleRate: 1.0,       // Metric sampling rate (0-1)\n  }}\n>\n  {children}\n</PerformanceProvider>\n```\n\n### Built-in Adapters\n\n#### ConsoleAdapter (Development)\n\n```typescript\nimport { ConsoleAdapter } from '@astacinco/rn-performance';\n\nconst adapter = new ConsoleAdapter({\n  prefix: '[Perf]',       // Log prefix\n  timestamps: true,       // Include timestamps\n  minSeverity: 'info',    // Minimum log level\n  colorize: true,         // Use emoji indicators\n});\n```\n\n#### NoOpAdapter (Testing)\n\n```typescript\nimport { NoOpAdapter } from '@astacinco/rn-performance';\n\nconst adapter = new NoOpAdapter();\n// Silent - does nothing (useful for testing)\n```\n\n#### FirebaseAdapter (Production)\n\n```typescript\nimport { FirebaseAdapter } from '@astacinco/rn-performance';\n\nconst adapter = new FirebaseAdapter();\n// Requires @react-native-firebase/perf\n```\n\n### Creating Custom Adapters\n\nImplement the `PerformanceAdapter` interface:\n\n```typescript\nimport type { PerformanceAdapter } from '@astacinco/rn-performance';\n\nclass SentryAdapter implements PerformanceAdapter {\n  readonly name = 'sentry';\n\n  async initialize() {\n    // Initialize Sentry\n  }\n\n  async startTrace(traceName: string): Promise<TraceHandle> {\n    const transaction = Sentry.startTransaction({ name: traceName });\n    return {\n      stop: () => transaction.finish(),\n      putAttribute: (name, value) => transaction.setTag(name, value),\n      putMetric: (name, value) => transaction.setMeasurement(name, value),\n    };\n  }\n\n  // ... implement all other methods\n}\n```\n\n### Hooks\n\n#### usePerformance\n\nMain hook for performance monitoring.\n\n```typescript\nconst {\n  isInitialized,  // Provider ready\n  isEnabled,      // Monitoring enabled\n  adapterName,    // Current adapter name\n  startTrace,     // Start a trace\n  recordMetric,   // Record a metric\n  measure,        // Measure function execution\n  setEnabled,     // Enable/disable monitoring\n} = usePerformance();\n```\n\n#### useLeakDetector\n\nMemory leak detection hook.\n\n```typescript\nconst {\n  trackSubscription,  // Track subscription cleanup\n  trackTimer,         // Track timer cleanup\n  trackListener,      // Track listener cleanup\n  verifyCleanup,      // Manual cleanup verification\n  getTrackedCount,    // Get tracked resource counts\n} = useLeakDetector({\n  componentName: 'MyComponent',\n  checkSubscriptions: true,\n  checkTimers: true,\n  checkListeners: true,\n  verifyCleanup: () => customVerification(),\n});\n```\n\n#### useRenderTracker\n\nComponent render tracking.\n\n```typescript\nconst {\n  renderCount,          // Number of renders\n  lastRenderDuration,   // Last render time (ms)\n  averageRenderDuration, // Average render time (ms)\n  getRenderInfo,        // Get full render info\n} = useRenderTracker({\n  componentName: 'MyComponent',\n  threshold: 10,                    // Warn after this many renders\n  trackedProps: { data, filter },   // Track which props changed\n  logToConsole: __DEV__,            // Log to console\n});\n```\n\n## Measuring Performance\n\n### Traces\n\n```typescript\nconst { startTrace } = usePerformance();\n\n// Manual trace control\nconst trace = await startTrace('process_data');\ntrace.putAttribute('count', data.length.toString());\n\n// ... do work ...\n\ntrace.putMetric('items_processed', data.length);\ntrace.stop();\n```\n\n### Measure Function\n\n```typescript\nconst { measure } = usePerformance();\n\n// Measure sync operations\nconst result = await measure('compute', () => {\n  return expensiveComputation();\n}, 'custom');\n\n// Measure async operations\nconst data = await measure('fetch_users', async () => {\n  return api.getUsers();\n}, 'network');\n\n// Errors are automatically marked as anomalies\n```\n\n### Custom Metrics\n\n```typescript\nconst { recordMetric } = usePerformance();\n\nawait recordMetric('button_press', 'custom', undefined, {\n  button_name: 'submit',\n  screen: 'checkout',\n});\n\nawait recordMetric('list_scroll', 'render', 16.5, {\n  item_count: 100,\n});\n```\n\n## Leak Detection\n\n```tsx\nfunction SubscriptionComponent() {\n  const { trackSubscription, trackTimer, trackListener } = useLeakDetector({\n    componentName: 'SubscriptionComponent',\n  });\n\n  useEffect(() => {\n    // Track subscription\n    const unsubscribe = store.subscribe(handleChange);\n    trackSubscription('store', unsubscribe);\n\n    // Track interval\n    const timerId = setInterval(refresh, 5000);\n    trackTimer('refresh', timerId);\n\n    // Track event listener\n    const handler = () => handleResize();\n    window.addEventListener('resize', handler);\n    trackListener('resize', () => window.removeEventListener('resize', handler));\n\n    // On unmount:\n    // 1. Leak detector calls all cleanup functions\n    // 2. Reports any uncleared resources as potential leaks\n  }, []);\n\n  return <View>...</View>;\n}\n```\n\n## Render Tracking\n\n```tsx\nfunction ExpensiveList({ data, filter }) {\n  const { renderCount, averageRenderDuration } = useRenderTracker({\n    componentName: 'ExpensiveList',\n    threshold: 5,\n    trackedProps: { data, filter },\n    logToConsole: __DEV__,\n  });\n\n  // Console output (in dev):\n  // [Render] ExpensiveList #1 (5.23ms)\n  // [Render] ExpensiveList #2 (3.12ms) Changed: filter\n  // [Render] ExpensiveList #3 (2.87ms) Changed: data\n  // ⚠️ [Performance] ExpensiveList has rendered 6 times (threshold: 5)\n\n  return <FlatList data={data} ... />;\n}\n```\n\n## Adapter Pattern Benefits\n\nThe adapter pattern allows you to:\n\n1. **Swap backends easily** - Change from Console to Firebase with one line\n2. **Test without real monitoring** - Use `NoOpAdapter`\n3. **Debug with visibility** - Use `ConsoleAdapter` to see all events\n4. **Create custom adapters** - Build adapters for Sentry, New Relic, etc.\n\n```typescript\n// Switch providers without changing any component code:\n\n// Development\n<PerformanceProvider adapter={new ConsoleAdapter()}>\n\n// Production\n<PerformanceProvider adapter={new FirebaseAdapter()}>\n\n// Testing\n<PerformanceProvider adapter={new NoOpAdapter()}>\n\n// Custom (Sentry)\n<PerformanceProvider adapter={new SentryAdapter()}>\n```\n\n## TypeScript\n\nFull TypeScript support with exported types:\n\n```typescript\nimport type {\n  PerformanceAdapter,\n  PerformanceConfig,\n  PerformanceMetric,\n  MetricType,\n  Severity,\n  TraceHandle,\n  MemorySnapshot,\n  LeakDetectionResult,\n  RenderInfo,\n  LeakDetectorOptions,\n} from '@astacinco/rn-performance';\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-9bec0511a818eb01f2ce276d1e6e53a6"}