API Documentation

🔧 API Documentation

Complete technical reference for Arsenal Lab components and APIs.

📋 Table of Contents

• Core Components
  • PerformanceArsenal
  • BuildConfigurationArsenal
• Custom Hooks
• UI Components
• Utility Functions
• Type Definitions
• Advanced Usage
• Migration Guide
• Support

🎯 Core Components

PerformanceArsenal

Main performance testing component with real-time benchmarking.

Props

interface PerformanceArsenalProps {
  initialTab?: 'postmessage' | 'registry' | 'crypto' | 'memory';
  showHardwareWarning?: boolean;
  enableAnalytics?: boolean;
}

Usage

import { PerformanceArsenal } from '@bun/performance-arsenal';

function App() {
  return (
    <PerformanceArsenal
      initialTab="crypto"
      showHardwareWarning={true}
      enableAnalytics={true}
    />
  );
}

BuildConfigurationArsenal

Interactive Bun.build() API and CLI playground.

Props

interface BuildConfigurationArsenalProps {
  initialConfig?: Partial<BuildConfiguration>;
  showCliCommand?: boolean;
  enableCodeCopy?: boolean;
}

BuildConfiguration Interface

interface BuildConfiguration {
  // Core Options
  entrypoints: string[];
  outdir: string;
  target: 'browser' | 'bun' | 'node';
  format: 'esm' | 'cjs' | 'iife';

  // Environment
  env: 'inline' | 'disable' | string;
  define: Record<string, string>;
  conditions: string[];

  // JSX
  jsx: {
    runtime: 'automatic' | 'classic';
    factory: string;
    fragment: string;
    importSource: string;
  };

  // Optimization
  minify: boolean | {
    whitespace: boolean;
    syntax: boolean;
    identifiers: boolean;
  };
  splitting: boolean;
  external: string[];
  packages: 'bundle' | 'external';

  // Output
  sourcemap: 'none' | 'linked' | 'inline' | 'external';
  naming: string | {
    entry: string;
    chunk: string;
    asset: string;
  };
  publicPath: string;

  // Advanced
  bytecode: boolean;
  throw: boolean;
  banner: string;
  footer: string;
  drop: string[];
  ignoreDCEAnnotations: boolean;
  emitDCEAnnotations: boolean;

  // CLI-Specific (not in JS API)
  production?: boolean;
  watch?: boolean;
  noClearScreen?: boolean;
  reactFastRefresh?: boolean;
  compile?: boolean;
  compileExecArgv?: string;
}

🎣 Custom Hooks

usePerformanceArsenal

Core hook for performance benchmarking functionality.

interface PerformanceArsenalHook {
  // State
  tab: 'postmessage' | 'registry' | 'crypto' | 'memory';
  pmSize: number;
  regAction: string;
  isRunning: boolean;
  benchmarkResults: BenchmarkResult[];

  // Hardware
  hardwareInfo: HardwareInfo;

  // Actions
  setTab: (tab: TabType) => void;
  setPmSize: (size: number) => void;
  setRegAction: (action: string) => void;
  runBenchmark: () => Promise<void>;
  copyCode: (code: string) => void;
}

interface BenchmarkResult {
  name: string;
  bun: number;
  node: number;
  speedup: number;
  timestamp: Date;
}

interface HardwareInfo {
  cores: number;
  memory: number;
  platform: string;
  arch: string;
}

useBuildConfigurationArsenal

Hook for build configuration management.

interface BuildConfigurationHook {
  // State
  config: BuildConfiguration;
  activeTab: string;
  generatedCode: string;
  cliCommand: string;

  // Actions
  updateConfig: (updates: Partial<BuildConfiguration>) => void;
  updateCoreOption: (key: keyof CoreOptions, value: any) => void;
  updateEnvOption: (key: keyof EnvOptions, value: any) => void;
  updateJsxOption: (key: keyof JsxOptions, value: any) => void;
  updateOptimization: (key: keyof OptimizationOptions, value: any) => void;
  updateOutput: (key: keyof OutputOptions, value: any) => void;
  updateAdvanced: (key: keyof AdvancedOptions, value: any) => void;
  updateCliOption: (key: keyof CliOptions, value: any) => void;

  // Utilities
  generateBuildCode: () => string;
  generateCliCommand: () => string;
  resetConfig: () => void;
}

useDatabaseInfrastructureArsenal

Database testing and infrastructure management.

interface DatabaseHook {
  // SQLite
  sqliteConnection: SQLiteConnection;
  sqliteResults: QueryResult[];
  isSqliteConnected: boolean;

  // Redis
  redisConnection: RedisConnection;
  redisResults: RedisResult[];
  isRedisConnected: boolean;

  // Actions
  connectSqlite: (path: string) => Promise<void>;
  disconnectSqlite: () => void;
  executeSqliteQuery: (query: string) => Promise<QueryResult[]>;

  connectRedis: (config: RedisConfig) => Promise<void>;
  disconnectRedis: () => void;
  executeRedisCommand: (command: string, args: any[]) => Promise<RedisResult>;
}

interface QueryResult {
  columns: string[];
  rows: any[][];
  executionTime: number;
  affectedRows?: number;
}

useProcessShellArsenal

Process management and shell operations.

interface ProcessHook {
  // Process State
  processes: ProcessInfo[];
  activeProcess: ProcessInfo | null;
  isRunning: boolean;

  // Socket State
  socketConnections: SocketInfo[];
  socketStats: SocketStats;

  // Actions
  spawnProcess: (command: string, args: string[]) => Promise<ProcessInfo>;
  killProcess: (pid: number) => void;
  sendProcessSignal: (pid: number, signal: string) => void;

  createSocket: (type: 'tcp' | 'udp', config: SocketConfig) => Promise<SocketInfo>;
  closeSocket: (id: string) => void;
  sendSocketData: (id: string, data: Buffer) => void;
}

interface ProcessInfo {
  pid: number;
  command: string;
  args: string[];
  status: 'running' | 'stopped' | 'exited';
  cpu: number;
  memory: number;
  startTime: Date;
}

useTestingArsenal

Testing framework management and execution.

interface TestingHook {
  // Test State
  tests: TestSuite[];
  runningTests: TestSuite[];
  testResults: TestResult[];
  coverage: CoverageReport;

  // Configuration
  testConfig: TestConfig;

  // Actions
  runAllTests: () => Promise<void>;
  runTestSuite: (suiteId: string) => Promise<void>;
  runSingleTest: (testId: string) => Promise<void>;
  stopTests: () => void;

  updateTestConfig: (config: Partial<TestConfig>) => void;
  loadTestFile: (path: string) => Promise<void>;
  generateTestReport: (format: 'json' | 'html' | 'xml') => Promise<string>;
}

interface TestResult {
  id: string;
  name: string;
  status: 'passed' | 'failed' | 'skipped';
  duration: number;
  error?: string;
  stack?: string;
}

🎨 UI Components

Layout Components

Footer

Professional footer with performance metrics and navigation.

import { Footer } from '@bun/performance-arsenal';

function App() {
  return (
    <div>
      <main>{/* Main content */}</main>
      <Footer />
    </div>
  );
}

Banner

Rotating feature announcements and project statistics.

import { Banner } from '@bun/performance-arsenal';

function App() {
  return (
    <div>
      <Banner />
      <main>{/* Main content */}</main>
    </div>
  );
}

EnhancedBanner

Advanced banner with social links and metrics.

import { EnhancedBanner } from '@bun/performance-arsenal';

function App() {
  return (
    <div>
      <EnhancedBanner
        showStats={true}
        showSocialLinks={true}
      />
    </div>
  );
}

Arsenal-Specific UI

TabNavigation

Consistent tab navigation across all arsenals.

import { TabNavigation } from '@bun/performance-arsenal/ui';

const tabs = [
  { id: 'performance', label: 'Performance', icon: '⚡' },
  { id: 'database', label: 'Database', icon: '🗄️' }
];

function MyComponent() {
  const [activeTab, setActiveTab] = useState('performance');

  return (
    <TabNavigation
      tabs={tabs}
      activeTab={activeTab}
      onTabChange={setActiveTab}
    />
  );
}

CodeBlock

Syntax-highlighted code display with copy functionality.

import { CodeBlock } from '@bun/performance-arsenal/ui';

function MyComponent() {
  const code = `console.log('Hello, Bun!');`;

  return (
    <CodeBlock
      code={code}
      language="javascript"
      showCopyButton={true}
      onCopy={() => console.log('Copied!')}
    />
  );
}

PerformanceMetric

Real-time performance metric display.

import { PerformanceMetric } from '@bun/performance-arsenal/ui';

function MyComponent() {
  return (
    <div>
      <PerformanceMetric
        label="FPS"
        value={60}
        unit="fps"
        status="good"
      />
      <PerformanceMetric
        label="Memory"
        value={128}
        unit="MB"
        status="warning"
      />
    </div>
  );
}

🔧 Utility Functions

Analytics

Performance tracking and analytics utilities.

import {
  trackBenchmark,
  trackInteraction,
  exportAnalytics,
  clearAnalytics
} from '@bun/performance-arsenal/utils/analytics';

// Track benchmark results
trackBenchmark('crypto-sha256', {
  inputSize: '1MB',
  duration: 45,
  throughput: '22.2 MB/s'
});

// Export analytics data
const data = await exportAnalytics();
console.log(JSON.stringify(data, null, 2));

Copy to Clipboard

Cross-platform clipboard utilities.

import { copyToClipboard } from '@bun/performance-arsenal/utils/copyToClipboard';

// Copy text to clipboard
await copyToClipboard('Hello, World!');

// Copy with callback
copyToClipboard('Code snippet', () => {
  console.log('Copied successfully!');
});

Hardware Detection

System hardware profiling.

import { detectHardware } from '@bun/performance-arsenal/utils/hardware';

const hardware = await detectHardware();
console.log({
  cores: hardware.cores,
  memory: hardware.totalMemory,
  platform: hardware.platform,
  arch: hardware.arch
});

Storage

Persistent storage utilities.

import { getStorageItem, setStorageItem } from '@bun/performance-arsenal/utils/storage';

// Store user preferences
setStorageItem('theme', 'dark');
setStorageItem('analytics', true);

// Retrieve stored data
const theme = getStorageItem('theme', 'light');
const analytics = getStorageItem('analytics', false);

📊 Type Definitions

Enums

enum Target {
  Browser = 'browser',
  Bun = 'bun',
  Node = 'node'
}

enum Format {
  ESM = 'esm',
  CJS = 'cjs',
  IIFE = 'iife'
}

enum SourcemapType {
  None = 'none',
  Linked = 'linked',
  Inline = 'inline',
  External = 'external'
}

Error Types

class ArsenalError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: any
  ) {
    super(message);
    this.name = 'ArsenalError';
  }
}

class BenchmarkError extends ArsenalError {
  constructor(message: string, public benchmark: string) {
    super(message, 'BENCHMARK_ERROR', { benchmark });
  }
}

class BuildError extends ArsenalError {
  constructor(message: string, public config: BuildConfiguration) {
    super(message, 'BUILD_ERROR', { config });
  }
}

🚀 Advanced Usage

Custom Benchmark Creation

Create custom performance benchmarks:

import { createBenchmark } from '@bun/performance-arsenal';

const customBenchmark = createBenchmark({
  name: 'custom-algorithm',
  setup: () => {
    // Setup test data
    return { data: generateTestData() };
  },
  run: (context) => {
    // Run the algorithm
    return processAlgorithm(context.data);
  },
  iterations: 1000
});

// Run the benchmark
const result = await customBenchmark.run();
console.log(`Result: ${result.duration}ms`);

Plugin System

Extend Arsenal Lab with custom plugins:

import { registerPlugin } from '@bun/performance-arsenal';

registerPlugin({
  name: 'custom-plugin',
  version: '1.0.0',
  hooks: {
    onBenchmarkStart: (benchmark) => {
      console.log(`Starting ${benchmark.name}`);
    },
    onBenchmarkEnd: (result) => {
      console.log(`Completed in ${result.duration}ms`);
    }
  }
});

Configuration Management

Advanced configuration management:

import { configureArsenal } from '@bun/performance-arsenal';

// Global configuration
configureArsenal({
  analytics: {
    enabled: true,
    retention: '30-days',
    endpoint: 'https://analytics.example.com'
  },
  performance: {
    warnings: {
      lowFps: 30,
      highMemory: 500
    }
  },
  ui: {
    theme: 'dark',
    animations: true
  }
});

📚 Migration Guide

From v1.2 to v1.3

• New CLI options in BuildConfigurationArsenal
• Enhanced analytics with privacy controls
• Improved error handling and TypeScript support

Breaking Changes

• useAnalytics hook renamed to usePerformanceMonitor
• Footer component now requires React 18+
• Build configuration validation is stricter

📚 Related Documentation

Document	Description
🏠 Wiki Home	Overview and getting started
📊 Analytics Guide	Performance monitoring and metrics
🗄️ Database Guide	Database integration patterns
📝 SQL Examples	Query patterns and examples

📞 Support & Community

• 💬 Discussions - Community conversations
• 🐛 Issues - Bug reports and feature requests
• 📖 Full Documentation - Complete documentation hub

---

Built with ❤️ for the Bun ecosystem • Last updated: October 21, 2025