Cline

# Component Design Standards for Bun This document outlines coding standards specifically for component design in Bun. It aims to provide guidance for creating reusable, maintainable, and performant components within the Bun runtime environment. These standards are designed to be used both by developers and AI coding assistants. ## 1. Component Architecture & Philosophy ### 1.1. Embrace Functional Components and Reactivity **Standard:** Favor functional components over class-based components. Leverage Bun's native support for reactivity and its compatibility with JavaScript frameworks utilizing reactivity, such as React and Preact. **Do This:** Use functional components with hooks for managing state and side effects. **Don't Do This:** Rely primarily on class-based components unless specifically justified by framework requirements or legacy codebases. **Why:** Functional components are generally easier to read, test, and maintain. They promote a more declarative style of programming. By leveraging reactivity, components can efficiently update only the necessary parts of the UI when data changes. **Example:** """javascript // Functional component using React with Bun import React, { useState } from 'react'; function Counter() { const [count, setCount] = useState(0); const increment = () => { setCount(count + 1); }; return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> </div> ); } export default Counter; """ ### 1.2. Single Responsibility Principle (SRP) **Standard:** Each component should have a single, well-defined responsibility. **Do This:** Decompose complex components into smaller, more focused components. **Don't Do This:** Create "god components" that handle multiple unrelated tasks. **Why:** SRP improves code readability, maintainability, and testability. It also promotes reusability, as smaller components can be composed in different ways to create new functionality. **Example:** Instead of a single "UserProfile" component that fetches user data, displays profile information, and handles profile editing, break it down into: * "UserFetch": Fetches user data. * "UserProfileDisplay": Displays user profile information. * "UserProfileEditor": Handles profile editing. ### 1.3. Composition over Inheritance **Standard:** Prefer composition over inheritance for code reuse. **Do This:** Create components that can be composed together to create more complex functionality. **Don't Do This:** Rely heavily on inheritance hierarchies to share code between components. **Why:** Composition is more flexible and less prone to the fragile base class problem. It allows you to combine components in various ways without creating tight coupling. Inheritance creates tight coupling making refactoring more difficult. **Example:** """javascript // Composition using React function Button(props) { return ( <button className={"button ${props.className}"} onClick={props.onClick}> {props.children} </button> ); } function PrimaryButton(props) { return ( <Button className="primary-button" {...props}> {props.children} </Button> ); } // Usage <PrimaryButton onClick={() => console.log('Clicked!')}>Click Me</PrimaryButton> """ Here "PrimaryButton" *composes* "Button" instead of inheriting from it. The CSS class styles the "Button" element. ### 1.4. API Design: Props and Events **Standard:** Design clear and concise component APIs using props for configuration and events for communication. **Do This:** * Use descriptive prop names. * Define prop types with "propTypes" or TypeScript. * Pass data down via props. * Communicate events up via callbacks. * Use default prop values where appropriate. **Don't Do This:** * Rely on global state directly within components (except for specific framework-managed contexts). * Mutate props directly. * Create overly complex prop structures. **Why:** Well-defined component APIs make components easier to understand, use, and test. They also reduce the risk of unexpected behavior. Clear interfaces are critical for maintaining a modular architecture. **Example (React with Prop Types):** """javascript import React from 'react'; import PropTypes from 'prop-types'; function Greeting(props) { return <p>Hello, {props.name}!</p>; } Greeting.propTypes = { name: PropTypes.string.isRequired, }; Greeting.defaultProps = { name: 'Guest', }; export default Greeting; """ ## 2. Component Implementation Details ### 2.1. State Management **Standard:** Use appropriate state management techniques based on component complexity and scope. **Do This:** * Use local component state for simple, isolated state. * Use context/providers for sharing state between related components. * Leverage state management libraries (e.g., Redux, Zustand, Jotai) for complex, application-wide state. **Don't Do This:** * Overuse global state for local component concerns. * Mutate state directly without using "setState" or appropriate state management hooks. **Why:** Proper state management ensures predictable component behavior and prevents performance issues. **Example (React with useState hook):** """javascript import React, { useState } from 'react'; function Toggle() { const [isOn, setIsOn] = useState(false); const toggle = () => { setIsOn(!isOn); }; return ( <button onClick={toggle}> {isOn ? 'On' : 'Off'} </button> ); } export default Toggle; """ ### 2.2. Rendering Optimization **Standard:** Optimize component rendering for performance. **Do This:** * Use "React.memo" or similar techniques to prevent unnecessary re-renders. * Implement "shouldComponentUpdate" (if using class components) or "useMemo" to control render updates. * Use virtualization techniques for large lists. * Debounce or throttle event handlers for performance-sensitive updates. **Don't Do This:** * Force re-renders unnecessarily. * Perform heavy calculations or expensive operations during rendering. **Why:** Optimizing rendering prevents performance bottlenecks, especially in complex UIs. **Example (React with React.memo):** """javascript import React from 'react'; function DisplayName({ name }) { console.log("DisplayName re-rendered!"); // For debugging return <p>Name: {name}</p>; } export default React.memo(DisplayName, (prevProps, nextProps) => { // Return true if props are equal, preventing re-render. return prevProps.name === nextProps.name; }); //Usage function App() { const [name, setName] = React.useState("Initial Name"); return ( <div> <DisplayName name={name} /> <button onClick={() => setName("New Name")}>Change Name</button> </div> ); } """ In this example, the "DisplayName" component will only re-render if the "name" prop changes. ### 2.3. Asynchronous Operations **Standard:** Handle asynchronous operations within components correctly. **Do This:** * Use "async/await" syntax for cleaner asynchronous code. * Handle errors appropriately with "try/catch" blocks or ".catch()" methods. * Use "useEffect" hook in React for performing side effects (including asynchronous operations) after rendering. **Don't Do This:** * Ignore errors from asynchronous operations. * Update component state after the component has been unmounted (leading to potential memory leaks). Use "AbortController" to manage asynchronous operations and cancel them when the component unmounts. **Why:** Proper asynchronous handling ensures that components behave predictably and avoids common errors like race conditions and memory leaks. **Example (React with useEffect and async/await):** """javascript import React, { useState, useEffect } from 'react'; function DataFetcher({ url }) { const [data, setData] = useState(null); const [isLoading, setIsLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const fetchData = async () => { setIsLoading(true); try { const response = await fetch(url); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const json = await response.json(); setData(json); } catch (e) { setError(e); } finally { setIsLoading(false); } }; fetchData(); }, [url]); // useEffect depends on the 'url' prop if (isLoading) { return <p>Loading...</p>; } if (error) { return <p>Error: {error.message}</p>; } return ( <div> <pre>{JSON.stringify(data, null, 2)}</pre> </div> ); } export default DataFetcher; """ ### 2.4. Accessibility (a11y) **Standard:** Build accessible components that are usable by people with disabilities. **Do This:** * Use semantic HTML elements. * Provide alternative text for images. * Ensure proper keyboard navigation. * Use ARIA attributes to enhance accessibility. * Test components with accessibility tools (e.g., Axe). **Don't Do This:** * Rely solely on visual cues. * Use generic elements (e.g., "<div>", "<span>") without appropriate semantic roles. **Why:** Accessibility makes your application usable by a wider audience and is often a legal requirement. **Example (Accessible Button):** """javascript import React from 'react'; function AccessibleButton({ onClick, children, ariaLabel }) { return ( <button onClick={onClick} aria-label={ariaLabel}> {children} </button> ); } export default AccessibleButton; """ ### 2.5. Testing **Standard:** Write unit tests, integration tests, and end-to-end tests for your components. **Do This:** * Use testing frameworks like Jest or Vitest. * Test component behavior in various scenarios. * Use mocking to isolate components during testing. * Strive for high test coverage. * Write tests for edge cases. **Don't Do This:** * Skip testing complex components. * Write tests that are too tightly coupled to implementation details. * Rely solely on manual testing. **Why:** Testing ensures that your components function correctly and reduces the risk of regressions. Automated tests are crucial for maintainability and continuous integration. Bun is compatible with all Javascript testing frameworks and runners. **Example (Jest test for Counter Component):** """javascript import React from 'react'; import { render, screen, fireEvent } from '@testing-library/react'; import Counter from './Counter'; test('increments count when button is clicked', () => { render(<Counter />); const incrementButton = screen.getByText('Increment'); fireEvent.click(incrementButton); const countElement = screen.getByText('Count: 1'); expect(countElement).toBeInTheDocument(); }); """ ## 3. Bun-Specific Considerations ### 3.1. Performance Benefits **Standard:** Leverage Bun's performance advantages when designing components. **Do This:** * Use Bun's fast file system APIs for component data loading scenarios (where applicable and appropriate for design context). * Benchmark different component implementations to identify performance bottlenecks. * Use Bun's faster startup time to your advantage when rendering server-side components. **Don't Do This:** * Assume that Bun automatically optimizes all component code; profiling and optimization are still necessary. * Neglect standard web performance optimizations (e.g., code splitting, lazy loading). **Why:** Bun's performance improvements can significantly improve the responsiveness and user experience of your components. However, you still need to write efficient code and apply standard best practices. ### 3.2. Ecosystem Compatibility **Standard:** Ensure compatibility with the broader JavaScript ecosystem. **Do This:** * Use standard ES modules. * Follow established npm/yarn package management practices. * Leverage existing React, Preact, or other framework component libraries (if applicable). **Don't Do This:** * Rely on non-standard Bun-specific features unless absolutely necessary. * Create custom component ecosystems that are incompatible with existing tools and libraries. **Why:** Maintaining ecosystem compatibility ensures that your components can be easily reused and integrated with other projects. ### 3.3. Server Components in Bun **Standard:** Utilize server components wisely, especially when using React Server Components. **Do This:** * Fetch data directly on the server for improved security and performance. * Keep server components close to the data source and separate from client-side interactivity. * Take advantages of the server's file system and database access capabilities. **Don't Do This:** * Introduce client-side dependencies in server components (they don't execute on the client). * Handle UI interactivity and state management on the server. They should be in client components. **Example:** """javascript // Server Component (fetching data) import { Database } from 'bun:sqlite' async function getProducts() { const db = new Database('mydb.sqlite'); const products = db.query("SELECT * FROM products").all(); db.close(); return products } export default async function ProductList() { const products = await getProducts(); return ( <ul> {products.map((product) => ( <li key={product.id}>{product.name}</li> ))} </ul> ); } """ ### 3.4. Bun Plugins for Components **Standard:** Create and use Bun plugins to extend component functionality. **Do This:** * Use Bun plugins to transform component code during the build process. * Create plugins for tasks such as CSS-in-JS compilation, image optimization, and code minification. * Publish your component plugins to the Bun package registry. **Don't Do This:** * Overuse plugins for simple component transformations. * Create plugins that modify component behavior at runtime. **Example:** """javascript // bun-plugin-example.js export default { name: "example-plugin", setup(build) { build.onLoad({ filter: /\.css$/ }, async (args) => { // Transform CSS files const contents = await Bun.file(args.path).text(); const transformedContents = transformCSS(contents); // Implement your CSS transformation logic return { contents: transformedContents, loader: "css" }; }); }, }; // bunfig.toml [plugins] "example-plugin" = "./bun-plugin-example.js" """ ## 4. Common Anti-Patterns * **God Components:** Components responsible for too many unrelated tasks. * **Prop Drilling:** Passing props through multiple layers of components that don't need them. Use context or state management libraries to avoid this. * **Tight Coupling:** Components that are highly dependent on each other, making it difficult to reuse or modify them independently. * **Ignoring Error Handling:** Failing to handle errors in asynchronous operations or other potentially failing code. * **Over-optimization:** Spending too much time optimizing components that are not performance bottlenecks. Measure before optimizing. * **Lack of Testing:** Failing to write tests for components, leading to regressions and difficult maintenance. * **Direct DOM Manipulation:** Directly manipulating the DOM without using the framework's facilities unless there is a very specific and compelling reason to do so. Increases complexity and risk. * **Global State Abuse:** Using global state for localized component concerns. This creates unnecessary dependencies. ## 5. Conclusion These component design standards for Bun provide a foundation for building high-quality, maintainable, and performant applications. By following these guidelines, developers can create components that are easy to understand, reuse, test, and extend. Remember that the best standards are those which are adopted and followed by the team. So, ensure the standards are clear, concise and readily available when needed. Regularly review this document and iterate on it to adapt to the ever-evolving landscape of web development.

# Performance Optimization Standards for Bun This document outlines performance optimization standards for Bun projects. It provides guidelines for writing efficient and performant code, covering various aspects from architectural considerations to low-level implementation details. These standards aim to improve application speed, responsiveness, and resource usage, leveraging Bun's features and capabilities. ## 1. Architectural Considerations ### 1.1. Modular Design **Standard:** Break down large applications into smaller, independent modules with well-defined interfaces. * **Do This:** Use ES modules or CommonJS modules to organize code. * **Don't Do This:** Create monolithic files with tightly coupled code. **Why:** Modules improve code organization, testability, and reusability. They also allow for selective loading of code, reducing initial load times. **Example:** """javascript // math.js export function add(a, b) { return a + b; } // app.js import { add } from './math.js'; console.log(add(5, 3)); """ ### 1.2. Microservices Architecture **Standard:** Consider microservices for large-scale applications where independent services can be scaled and deployed separately. * **Do This:** Design microservices with clear API boundaries and efficient communication protocols (e.g., HTTP/2, gRPC). * **Don't Do This:** Build a single, large application that's difficult to scale and maintain. **Why:** Microservices enhance scalability, fault isolation, and deployment flexibility. ### 1.3. Caching Strategies **Standard:** Implement caching at various levels (e.g., browser, CDN, server) to reduce latency and server load. * **Do This:** Use HTTP caching headers, CDN caching, and in-memory caching. Leverage Bun's built-in caching capabilities where applicable. * **Don't Do This:** Overlook caching opportunities or use overly aggressive caching strategies. **Why:** Caching reduces network requests and server processing, improving response times. **Example:** """javascript // Setting HTTP caching headers (using Elysia.js) import { Elysia } from 'elysia' const app = new Elysia() .get('/', () => 'Hello Elysia', { response: { headers: { 'Cache-Control': 'public, max-age=3600' // 1 hour cache } } }) .listen(3000) """ ### 1.4. Connection Pooling **Standard:** Employ connection pooling for database or other resource connections to minimize connection overhead. * **Do This:** Use a connection pool library (e.g., "pg" for PostgreSQL, "mysql2" for MySQL) to manage connections. Bun's built-in SQLite support automatically handles connection pooling. * **Don't Do This:** Create a new connection for each request. **Why:** Connection pooling reduces the overhead of establishing and closing connections, improving performance. **Example (PostgreSQL with "pg"):** """javascript import { Pool } from 'pg'; const pool = new Pool({ user: 'dbuser', host: 'localhost', database: 'mydb', password: 'secretpassword', port: 5432, max: 20, // Maximum number of clients in the pool idleTimeoutMillis: 30000, // Close idle clients after 30 seconds connectionTimeoutMillis: 2000, // Return an error after 2 seconds if connection could not be established }); async function queryDatabase(sql, params) { const client = await pool.connect(); try { const result = await client.query(sql, params); return result; } finally { client.release(); // Release the client back to the pool } } // Example usage queryDatabase('SELECT * FROM users WHERE id = $1', [1]) .then(result => console.log(result.rows)) .catch(err => console.error(err)); """ ## 2. Code-Level Optimization ### 2.1. Efficient Data Structures **Standard:** Choose appropriate data structures for specific tasks to minimize time and space complexity. * **Do This:** Use Maps for key-value lookups, Sets for unique value collections, and Arrays when order matters. * **Don't Do This:** Use Arrays when key-value lookups are frequent or perform unnecessary iterations. **Why:** Selecting the right data structure can significantly improve algorithm performance. **Example:** """javascript // Using a Map for efficient key-value lookup const userMap = new Map(); userMap.set('123', { name: 'Alice', age: 30 }); const user = userMap.get('123'); // O(1) lookup // Using a Set for unique value collection const uniqueIds = new Set(); uniqueIds.add(1); uniqueIds.add(2); uniqueIds.add(1); // Duplicate is ignored """ ### 2.2. Minimize Object Creation **Standard:** Reduce unnecessary object creation to minimize garbage collection overhead. * **Do This:** Reuse objects when possible, use object pools, and avoid creating objects in tight loops. * **Don't Do This:** Create new objects for every iteration in a loop or store large amounts of unneeded data in objects. **Why:** Excessive object creation leads to frequent garbage collection cycles, which can pause execution. **Example:** """javascript // Reusing an object const point = { x: 0, y: 0 }; for (let i = 0; i < 1000; i++) { point.x = i; point.y = i * 2; // Use the point object } // Object Pooling (Manual Implementation - Consider using a library for production) class ObjectPool { constructor(objectFactory, size) { this.pool = []; this.objectFactory = objectFactory; this.size = size; this.initialize(); } initialize() { for (let i = 0; i < this.size; i++) { this.pool.push(this.objectFactory()); } } acquire() { if (this.pool.length > 0) { return this.pool.pop(); } else { // Pool is empty, create a new object if necessary return this.objectFactory(); } } release(object) { this.pool.push(object); } } //usage const myObjectPool = new ObjectPool(() => ({x: 0, y: 0}), 10); const obj = myObjectPool.acquire(); obj.x = 5; obj.y = 10; myObjectPool.release(obj); """ ### 2.3. Optimize Loops **Standard:** Write efficient loops to minimize the number of iterations and operations within the loop. * **Do This:** Cache loop invariants, unroll loops, and use optimized loop constructs (e.g., "for...of" vs. "for...in"). * **Don't Do This:** Perform expensive operations within loops, access array lengths in each iteration, or use inefficient loop types. **Why:** Loop optimization can significantly reduce execution time for repetitive tasks. **Example:** """javascript // Caching loop invariant const arr = [1, 2, 3, 4, 5]; const len = arr.length; // Cache the length for (let i = 0; i < len; i++) { console.log(arr[i]); } // Optimized for...of loop: for (const item of arr) { console.log(item); } """ ### 2.4. String Concatenation **Standard:** Use efficient string concatenation methods to minimize memory allocation and copying. * **Do This:** Use template literals or array joins for large strings. Avoid repeated string concatenation using the "+" operator. * **Don't Do This:** Use the "+" operator for concatenating many strings, creating unnecessary intermediate strings. **Why:** String concatenation can be expensive, especially for large strings. Template literals and array joins are more efficient. Bun also optimizes string handling more efficiently than traditional Node.js. **Example:** """javascript // Efficient string concatenation with template literals const name = 'Alice'; const age = 30; const message = "Hello, my name is ${name} and I am ${age} years old."; // Efficient string concatenation with array joins const parts = ['Hello', 'my name is', name, 'and I am', age, 'years old.']; const message2 = parts.join(' '); """ ### 2.5. Regular Expression Optimization **Standard:** Optimize regular expressions for performance by minimizing backtracking and using appropriate flags (e.g., "i" for case-insensitive matching). * **Do This:** Use specific patterns, avoid using ".*" at the beginning of expressions, and precompile regular expressions for reuse. * **Don't Do This:** Use overly complex regular expressions or create new regular expressions in loops. **Why:** Inefficient regular expressions can cause performance bottlenecks. **Example:** """javascript // Precompiling a regular expression const regex = /pattern/g; // 'g' for global, precompiled function testString(str) { return regex.test(str); } console.log(testString('pattern')); """ ### 2.6 Asynchronous operations **Standard:** Utilize Bun's fast "async/await" and native Promise implementations effectively. Avoid blocking the event loop. * **Do This:** Use "async/await" for concise asynchronous code. Take advantage of Bun's optimized Promise implementation. Employ "Bun.sleep()" for non-blocking delays when needed. Consider using "Bun.spawn" for executing external commands concurrently without blocking. * **Don't Do This:** Use callback-hell or block the event loop with synchronous operations, especially when dealing with network requests or file I/O. **Why:** Asynchronous programming allows for non-blocking operations, which are crucial for maintaining responsiveness in I/O-bound applications. Bun's fast event loop and optimized Promise implementation make async operations more performant. "Bun.sleep()" pauses execution without blocking the main thread, and "Bun.spawn" enables efficient execution of external commands, crucial for performance in task orchestration. **Example:** """javascript // Async operation with async/await async function fetchData() { try { const response = await fetch('https://example.com/data'); const data = await response.json(); return data; } catch (error) { console.error('Error fetching data:', error); return null; } } // Usage fetchData().then(data => { if (data) { console.log('Data:', data); } }); //Example of non-blocking delay async function delayedAction() { console.log("Starting action..."); await Bun.sleep(2000); // Wait for 2 seconds without blocking console.log("Action completed!"); } delayedAction(); //Example using Bun.spawn for concurrent task execution async function executeCommand(command) { const proc = Bun.spawn(command, { stdout: "pipe", stderr: "pipe", }); const output = await new Response(proc.stdout).text(); const errorOutput = await new Response(proc.stderr).text(); const exitCode = await proc.exited; return { output, errorOutput, exitCode }; } async function main() { console.log("Starting concurrent command execution..."); const { output, errorOutput, exitCode } = await executeCommand(["ls", "-l"]); if (exitCode === 0) { console.log("Command output:", output); } else { console.error("Command failed with error:", errorOutput); } } main(); """ ## 3. Bun-Specific Optimizations ### 3.1. Native Modules (FFI) **Standard:** Use Bun's native module capabilities (Foreign Function Interface - FFI) for performance-critical tasks by writing code directly in Zig (Bun's underlying language) or other languages like C/C++. * **Do This:** Utilize FFI to implement computationally intensive operations or when leveraging existing native libraries. * **Don't Do This:** Overuse FFI for tasks that can be efficiently handled in JavaScript or Typescript, as the overhead of context switching can negate the benefits. **Why:** FFI allows you to bypass JavaScript's performance limitations by executing code directly in native languages, which can be significantly faster for CPU-bound tasks. This is particularly beneficial in Bun due to its efficient interop capabilities with Zig. **Example:** """zig // example.zig const std = @import("std"); export fn add(a: i32, b: i32) i32 { return a + b; } """ """typescript // index.ts const lib = new Bun.FFI({ dlopen: { // Use dlopen for maximum compatibility, even if less performant linux: "./example.so", darwin: "./example.dylib", windows: "./example.dll", }, symbols: { add: { args: [Bun.FFI.i32, Bun.FFI.i32], returns: Bun.FFI.i32, }, }, }); const result = lib.symbols.add(5, 3); console.log(result); // Output: 8 """ ### 3.2. Bun.Transpiler **Standard:** Leverage "Bun.Transpiler" for ahead-of-time (AOT) compilation of TypeScript and JSX to JavaScript. * **Do This:** Utilize "Bun.Transpiler" in your build process to pre-compile code, especially for server-side rendering or computationally intensive tasks, improving startup time and runtime performance. * **Don't Do This:** Rely solely on just-in-time (JIT) compilation for production deployments, as it can introduce performance overhead during runtime. **Why:** AOT compilation with "Bun.Transpiler" reduces the need for runtime compilation or transpilation, leading to faster execution and reduced CPU usage, especially during the initial stages of application execution. **Example:** """typescript // Compile TypeScript to JavaScript const transpiler = new Bun.Transpiler({ loader: 'ts', }); const tsCode = " function add(a: number, b: number): number { return a + b; } console.log(add(5, 3)); "; const jsCode = await transpiler.transform(tsCode); console.log(jsCode); // Compile JSX to JavaScript. const jsxCode = " function MyComponent() { return ( <div> <h1>Hello, world!</h1> </div> ); } "; const transpilerJSX = new Bun.Transpiler({ loader: "jsx", }); const jsCodeJSX = await transpilerJSX.transform(jsxCode); console.log(jsCodeJSX); """ ### 3.3. Bun.serve **Standard:** Usethe "Bun.serve" API for high-performance web servers. * **Do This:** Utilize "Bun.serve" for creating web servers with its optimized HTTP implementation, WebSocket support, and TLS integration. * **Don't Do This:** Rely on traditional Node.js frameworks like Express.js for new Bun projects unless backward compatibility is a firm requirement. **Why:** "Bun.serve" is designed for speed and efficiency within the Bun runtime, delivering significant performance improvements compared to traditional Node.js web frameworks due to its optimized architecture and low-level access. **Example:** """typescript // Serving static files and dynamic content const server = Bun.serve({ port: 3000, async fetch(req) { const url = new URL(req.url); if (url.pathname === '/') { return new Response('Hello, Bun!'); } if (url.pathname.startsWith('/static')) { const filePath = '.' + url.pathname; const file = Bun.file(filePath); return new Response(file); } return new Response('404 Not Found', { status: 404 }); }, error(error) { console.error(error); return new Response("Internal Server Error", { status: 500 }); }, }); console.log("Server listening on port ${server.port}"); """ ### 3.4. SQLite Integration **Standard:** Harness Bun's native SQLite integration for performant database operations. * **Do This:** Leverage the built-in SQLite client when dealing with lightweight data storage needs, especially for read-heavy workloads. * **Don't Do This:** Neglect optimizing SQLite queries or schema design, as these considerably impact performance. For very large or complex data scenarios, consider other database solutions and connection pooling as above. **Why:** Bun's native SQLite integration offers excellent performance for simple data storage use cases. Operations are generally very fast when reading. **Example:** """typescript import { Database } from 'bun:sqlite'; // Use ":memory:" for an in-memory database const db = new Database(':memory:'); db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);'); // Insert data const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?);'); insert.run('Alice', 'alice@example.com'); insert.run('Bob', 'bob@example.com'); // Query data const query = db.prepare('SELECT * FROM users;'); const users = query.all(); console.log(users); db.close(); """ ## 4. Memory Management ### 4.1. Explicitly Release Resources **Standard:** Ensure that resources like file handles, database connections, and allocated memory are explicitly released when they are no longer needed. * **Do This:** Use "try...finally" blocks to ensure resources are released even if errors occur. Close database connections after use if not using connection pooling. * **Don't Do This:** Rely solely on garbage collection to release resources, as it can be unpredictable and lead to resource leaks. **Why:** Explicit resource management prevents memory leaks and ensures that system resources are available for other processes. **Example:** """typescript import { open, close } from 'node:fs/promises'; async function readFile(filePath) { let fileHandle = null; try { fileHandle = await open(filePath, 'r'); const contents = await fileHandle.readFile({ encoding: 'utf8' }); return contents; } catch (error) { console.error('Error reading file:', error); return null; } finally { if (fileHandle) { await fileHandle.close(); console.log('File handle closed.'); } } } readFile('example.txt').then(contents => { if (contents) { console.log('File contents:', contents); } }); """ ### 4.2. Avoid Global Variables **Standard:** Minimize the use of global variables to avoid unintentional memory retention and naming conflicts. * **Do This:** Use closures, modules, or classes to encapsulate variables and limit their scope. * **Don't Do This:** Declare large objects or arrays as global variables. **Why:** Global variables can lead to increased memory usage and make it harder to reason about the state of the application. ### 4.3. Weak References **Standard:** Use WeakRef and WeakMap objects when holding references to objects that should not prevent garbage collection. * **Do This:** Employ WeakRef for caching or memoization of expensive computations when the underlying data can be reclaimed by the garbage collector. Use WeakMap to associate data which are needed only when the original key objects are alive. * **Don't Do This:** Overuse weak references, as they can make debugging more difficult and introduce unpredictable behavior if not managed carefully. **Why:** Weak references allow you to hold references to objects without preventing them from being garbage collected, which is useful for caching and other memory-sensitive operations. **Example:** """typescript // Using WeakRef for caching const cache = new Map(); function getCachedData(key, expensiveComputation) { if (cache.has(key)) { const weakRef = cache.get(key); const cachedData = weakRef.deref(); //Dereference, return either undefined or the original value if (cachedData) { console.log('Using cached data'); return cachedData; } } const data = expensiveComputation(key); cache.set(key, new WeakRef(data)); console.log('Computed and cached data'); return data; } // Example Usage function computeData(key) { console.log('Computing data for key:', key); // Simulate an expensive computation return "Expensive data for ${key}"; } let data1 = getCachedData('key1', computeData); // Computes and caches the data let data2 = getCachedData('key1', computeData); // Retrieves data from cache //Simulate a garbage collection global.gc(); let data3 = getCachedData('key1', computeData); //Recomputes after GC """ ## 5. Monitoring and Profiling ### 5.1. Performance Monitoring Tools. **Standard:** Integrate performance monitoring tools to track application performance metrics and identify bottlenecks. * **Do This:** Use tools like Bun's built-in profiler, "console.time" and "console.timeEnd", or third-party APM solutions (like DataDog). * **Don't Do This:** Ignore performance metrics or rely solely on anecdotal evidence to identify performance issues. **Why:** Performance monitoring provides insights into application behavior and helps identify areas for optimization. **Example:** """javascript // Using console.time and console.timeEnd console.time('myFunction'); // Code to be measured for (let i = 0; i < 100000; i++) { //Some task } console.timeEnd('myFunction'); // Outputs the time taken //Simple Bun-specific profiler example Bun.profile(() => { //Code to profile for (let i = 0; i < 1000000; i++) { //Some task } }, { output: "profile.json" }) """ ### 5.2. Profiling Techniques **Standard:** Use profiling techniques (e.g., CPU profiling, memory profiling) to identify performance bottlenecks and memory leaks. * **Do This:** Use the built-in Node.js Inspector, Chrome DevTools, or third-party profiling tools to capture performance data. * **Don't Do This:** Profile code without a specific goal or fail to analyze profiling data. **Why:** Profiling helps pinpoint the exact lines of code that are causing performance issues. ## 6. Testing and Continuous Integration ### 6.1. Performance Testing **Standard:** Implement performance tests to measure and track application performance over time. * **Do This:** Use tools like Jest or k6 to write performance tests that simulate real-world scenarios. * **Don't Do This:** Neglect performance testing or rely solely on functional tests. **Why:** Performance tests help ensure that performance does not degrade with code changes. ### 6.2. Continuous Integration **Standard:** Integrate performance testing into the continuous integration (CI) pipeline. * **Do This:** Run performance tests automatically on each commit or pull request and set performance budgets to prevent regressions. * **Don't Do This:** Run performance tests manually or skip them during CI. **Why:** Continuous integration ensures that performance is continuously monitored and that regressions are detected early. By adhering to these performance optimization standards, Bun developers can build efficient, scalable, and performant applications that deliver exceptional user experiences while maximizing resource utilization. Remember to stay up-to-date with the latest version of Bun and its features to leverage the latest performance improvements.

# State Management Standards for Bun This document outlines standards for managing application state in Bun projects. It focuses on maintainability, performance, reactivity, and security, providing actionable guidelines and illustrative examples. ## 1. Principles of State Management in Bun State management in Bun applications involves orchestrating data flow, reactivity, and application state changes. Effective state management leads to predictable application behavior, easier debugging, and scalable architectures. Bun’s speed and Javascript/Typescript compatibility provide a robust foundation for various state management approaches. ### 1.1. Immutability **Standard:** Treat application state as immutable whenever possible. Modify state through explicit updates that create new state objects rather than mutating existing ones. **Why:** Immutability simplifies debugging, change detection, and concurrency management. Mutation makes it difficult to track state changes and can lead to unexpected side effects. **Do This:** """typescript // Preferred: Creating a new object const oldState = { count: 0 }; const newState = { ...oldState, count: oldState.count + 1 }; // Using a library like Immer import { produce } from "immer"; const baseState = { deeply: { nested: { obj: { count: 0 } } } }; const nextState = produce(baseState, (draft) => { draft.deeply.nested.obj.count += 1; }); """ **Don't Do This:** """typescript // Avoid: Mutating the original object const state = { count: 0 }; state.count = 1; // Direct mutation """ ### 1.2. Unidirectional Data Flow **Standard:** Enforce a clear, unidirectional data flow. State changes should originate from a single source and propagate downwards through the component tree or application modules. **Why:** Unidirectional data flow simplifies reasoning about application behavior and makes debugging easier. Avoid bidirectional data flow, which can result in entangled dependencies and unpredictable state updates. **Do This:** Define clear actions or events that trigger state updates, and ensure these updates are handled in a predictable manner. **Don't Do This:** Allow components to directly modify the state of other components or external data stores. Create central data stores that multiple components can mutate unexpectedly. ### 1.3. Centralized vs. Decentralized State **Standard:** Choose the appropriate state management strategy based on the complexity and scale of your application. Centralized state management is suitable for complex applications, while decentralized state management may be adequate for smaller applications. **Why:** Centralized state offers a single source of truth, simplifies debugging, and streamlines data flow, but can introduce complexity. Decentralized state is flexible for smaller applications, but harder manage in large, collaborative codebases. **Do This:** * For small to medium-sized applications, consider React's built-in "useState" and "useContext" hooks or lightweight libraries like Zustand. * For large and complex applications, use state management libraries like Redux, Zustand, or Jotai. **Don't Do This:** * Over-engineer state management for small applications by using complex centralized state management solutions. * Underestimate the complexity of state management for larger applications by relying solely on component-level state. ### 1.4. Predictable Side Effects **Standard:** Isolate and manage side effects (e.g., API calls, timers, DOM manipulations) explicitly. **Why:** Side effects can make application state unpredictable and difficult to test. Managing them predictably improves code maintainability and reliability. **Do This:** * Use middleware in libraries like Redux (e.g., Redux Thunk, Redux Saga) to handle asynchronous actions. * Use React's "useEffect" hook to manage side effects within components. **Don't Do This:** * Perform side effects directly within component render functions or state reducers. * Ignore error handling when dealing with side effects. ## 2. State Management Approaches in Bun Bun's compatibility with JavaScript and TypeScript allows it to fully support a variety of state management paradigms. Choosing the right one depends on your project size, complexity, and architectural preferences. ### 2.1. Global State Management Libraries #### 2.1.1. Redux **Standard:** Use Redux for complex, large-scale applications requiring predictable state management and centralized control. **Why:** Redux provides a well-defined architecture (store, actions, reducers) and encourages immutability, making it easier to reason about application state. Middleware support facilitates handling asynchronous actions and side effects. **Do This:** """typescript // actions.ts export const increment = () => ({ type: 'INCREMENT' }); export const decrement = () => ({ type: 'DECREMENT' }); // reducers.ts const initialState = { count: 0 }; const reducer = (state = initialState, action: any) => { switch (action.type) { case 'INCREMENT': return { ...state, count: state.count + 1 }; case 'DECREMENT': return { ...state, count: state.count - 1 }; default: return state; } }; export default reducer; // store.ts import { createStore } from 'redux'; import reducer from './reducers'; const store = createStore(reducer); export default store; // Component Example import { useSelector, useDispatch } from 'react-redux'; import { increment, decrement } from './actions'; function Counter() { const count = useSelector((state: any) => state.count); const dispatch = useDispatch(); return ( <div> <p>Count: {count}</p> <button onClick={() => dispatch(increment())}>Increment</button> <button onClick={() => dispatch(decrement())}>Decrement</button> </div> ); } export default Counter; """ **Don't Do This:** * Avoid using Redux for trivial applications, as it introduces unnecessary boilerplate. * Mutate state directly within reducers; always return a new state object. * Place complex business logic within components, keep that logic inside actions and/or middleware. #### 2.1.2. Zustand **Standard:** Use Zustand for simpler state management with minimal boilerplate, particularly in React applications. **Why:** Zustand offers a straightforward API, reduces boilerplate, and simplifies state mutations using Immer integration. It is a good choice for projects where Redux is too complex, but component-level state is insufficient. **Do This:** """typescript import { create } from 'zustand'; interface CounterState { count: number; increment: () => void; decrement: () => void; } const useCounterStore = create<CounterState>((set) => ({ count: 0, increment: () => set((state) => ({ count: state.count + 1 })), decrement: () => set((state) => ({ count: state.count - 1 })), })); // Component Example function Counter() { const { count, increment, decrement } = useCounterStore(); return ( <div> <p>Count: {count}</p> <button onClick={increment}>Increment</button> <button onClick={decrement}>Decrement</button> </div> ); } export default Counter; """ **Don't Do This:** * Don't overuse global state in Zustand for component-specific state. * Avoid complex state logic directly in components. Define state updates within the store's set function. #### 2.1.3. Jotai **Standard:** Use Jotai for fine-grained state management with a focus on simplicity and performance. **Why:** Jotai uses an atomic approach, where each piece of state is represented as a "atom." It offers excellent performance due to its minimal re-renders and integrates well with React. **Do This:** """typescript import { atom, useAtom } from 'jotai'; const countAtom = atom(0); // Component Example function Counter() { const [count, setCount] = useAtom(countAtom); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> <button onClick={() => setCount(count - 1)}>Decrement</button> </div> ); } export default Counter; """ **Don't Do This:** * Avoid overusing atomic state if related pieces of state are frequently updated together. Consider grouping them within a single atom for efficiency. * Don't directly mutate the value of an atom; always use the "setCount" function. ### 2.2. Component-Local State **Standard:** Use React's "useState" and "useReducer" hooks for managing state within individual components, particularly for simple, localized state. **Why:** Component-local state simplifies state management for smaller components and avoids the overhead of global state management libraries. **Do This:** """typescript import { useState, useReducer } from 'react'; function Counter() { const [count, setCount] = useState(0); const reducer = (state: number, action: { type: 'increment' | 'decrement' }) => { switch (action.type) { case 'increment': return state + 1; case 'decrement': return state - 1; default: return state; } }; const [state, dispatch] = useReducer(reducer, 0); return ( <div> <p>Count (useState): {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> <p>Count (useReducer): {state}</p> <button onClick={() => dispatch({ type: 'increment' })}>Increment (useReducer)</button> </div> ); } export default Counter; """ **Don't Do This:** * Avoid prop drilling by passing state down through multiple layers of components. Consider using "useContext" or a global state management library. * Overuse component-local state for state that needs to be shared across multiple components or application modules. ### 2.3. Context API **Standard:** Use React's Context API for sharing state across a component tree without prop drilling. **Why:** The Context API provides a simple way to share state between components without manually passing props through each level of the tree. **Do This:** """typescript import React, { createContext, useContext, useState } from 'react'; interface ThemeContextType { theme: string; toggleTheme: () => void; } const ThemeContext = createContext<ThemeContextType | undefined>(undefined); interface ThemeProviderProps { children: React.ReactNode; } function ThemeProvider({ children }: ThemeProviderProps) { const [theme, setTheme] = useState('light'); const toggleTheme = () => { setTheme((prevTheme) => (prevTheme === 'light' ? 'dark' : 'light')); }; const value: ThemeContextType = { theme, toggleTheme, }; return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>; } function useTheme() { const context = useContext(ThemeContext); if (!context) { throw new Error('useTheme must be used within a ThemeProvider'); } return context; } // Component Example function ThemedComponent() { const { theme, toggleTheme } = useTheme(); return ( <div style={{ backgroundColor: theme === 'light' ? 'white' : 'black', color: theme === 'light' ? 'black' : 'white' }}> <p>Current Theme: {theme}</p> <button onClick={toggleTheme}>Toggle Theme</button> </div> ); } function App() { return ( <ThemeProvider> <ThemedComponent /> </ThemeProvider> ); } export default App; """ **Don't Do This:** * Avoid managing complex, frequently changing state with the Context API, as it can trigger unnecessary re-renders. Consider using a global state management library for more granular control over updates. * Don't update the context value unnecessarily. Make sure the components using the Context API are optimized to avoid re-rendering when the context value changes. This is particularly important if the context value contains large or complex objects ## 3. Performance Considerations Efficient state management is crucial for building high-performance Bun applications. Overly complex or inefficient state management can lead to performance bottlenecks and a poor user experience. ### 3.1. Minimizing Re-renders **Standard:** Minimize unnecessary component re-renders by optimizing state updates and using memoization techniques. **Why:** Frequent re-renders can degrade performance, particularly in complex UIs. Ensuring that components only re-render when their relevant state changes improves responsiveness. **Do This:** * Use "React.memo" to memoize functional components based on their props. * Use "useMemo" and "useCallback" hooks to memoize computed values and event handlers. * Use selectors in Redux to compute derived data and prevent unnecessary re-renders. * Use "shouldComponentUpdate" (for class components) to prevent re-renders based on prop and state changes. **Don't Do This:** * Avoid passing new objects or functions as props to memoized components, as this will cause them to re-render regardless of the actual prop values. * Don't skip memoization entirely; analyze the render performance of your components and memoize those that are causing bottlenecks. ### 3.2. Lazy Initialization **Standard:** Initialize state lazily when it is not immediately needed, especially for expensive or asynchronous operations. **Why:** Lazy initialization improves application startup time and reduces unnecessary computations. **Do This:** * Use the lazy initialization form of "useState": """typescript const [data, setData] = useState(() => { // Perform expensive operation here return computeInitialData(); }); """ * Implement lazy loading of modules or components that are not immediately visible on the screen. **Don't Do This:** * Perform expensive operations during component initialization that block the UI thread and degrade performance. ### 3.3. Batch State Updates **Standard:** Batch multiple state updates into a single update to reduce the number of re-renders. **Why:** Batching updates minimizes the overhead associated with each state update and improves rendering performance. **Do This:** * Use "ReactDOM.unstable_batchedUpdates" or "setTimeout" to batch multiple state updates within a single event handler. """typescript import ReactDOM from 'react-dom'; function handleClick() { ReactDOM.unstable_batchedUpdates(() => { setCount(count + 1); setOtherValue(otherValue + 1); }); } """ * Use "useReducer" to combine multiple state updates into a single dispatch. **Don't Do This:** * Avoid triggering multiple state updates within a tight loop or event handler without batching them, as this can lead to performance issues. ## 4. Security Best Practices for State Management Secure state management is essential to protect sensitive data and prevent vulnerabilities in Bun applications. Following security best practices helps mitigate risks and ensure the integrity of your application. ### 4.1. Storing Sensitive Data **Standard:** Avoid storing sensitive data (e.g., passwords, API keys, personal information) directly in application state, especially in client-side state. **Why:** Client-side state is often exposed to the client and can be easily accessed by malicious actors. Storing sensitive data in client-side state increases the risk of data breaches. **Do This:** * Store sensitive data on the server and only expose it to the client as needed using secure APIs. * Use encrypted storage mechanisms (e.g., browser cookies with the "HttpOnly" and "Secure" flags) for sensitive data that must be stored on the client. * Use environment variables to store API keys and configuration settings, and avoid hardcoding them directly in the source code. **Don't Do This:** * Store passwords, API keys, or other sensitive data directly in component state or global state. * Expose sensitive data in client-side logs or error messages. * Commit sensitive data to version control systems. ### 4.2. Input Validation and Sanitization **Standard:** Validate and sanitize all user inputs before storing them in application state or sending them to the server. **Why:** Input validation and sanitization prevent cross-site scripting (XSS) attacks and other security vulnerabilities by ensuring that user inputs are safe and do not contain malicious code. **Do This:** * Use input validation libraries (e.g., Joi, Yup) to validate user inputs against predefined schemas. * Use sanitization libraries (e.g., DOMPurify) to sanitize user inputs and remove any potentially malicious code. * Encode user inputs properly when displaying them in the UI to prevent XSS attacks. **Don't Do This:** * Trust user inputs implicitly without validation or sanitization. * Insert user inputs directly into the DOM without encoding them. * Disable XSS protection in your application. ### 4.3. Secure API Communication **Standard:** Use HTTPS for all API communication to encrypt data in transit and prevent eavesdropping. **Why:** HTTPS ensures that data exchanged between the client and server is encrypted, protecting it from interception and tampering. **Do This:** * Obtain and configure SSL/TLS certificates for your server. * Enforce HTTPS by redirecting all HTTP requests to HTTPS. * Use secure API authentication mechanisms (e.g., JWT, OAuth) to verify the identity of clients and protect API endpoints. **Don't Do This:** * Use HTTP for API communication, especially when transmitting sensitive data. * Store API keys or authentication tokens in client-side code. * Disable SSL/TLS encryption on your server. ### 4.4. State Injection **Standard:** Avoid directly injecting state from external sources (query parameters, local storage) into your state management without proper validation **Why:** Directly injecting state from external sources without validation can lead to unexpected or malicious behavior, especially if the external source is controlled by an attacker. **Do This:** * Create a validation schema for data that can be injected. * Properly handle any exceptions raised by the validation process. * Do not trust any inputs that have not been validated. **Don't Do This:** * Trust that data from external sources is in a secure manner without validation * Inject code into application state that is not validated first. ## 5. Error Handling and Logging Proper error handling and logging are crucial for maintaining the stability and reliability of Bun applications. ### 5.1. Centralized Error Handling **Standard:** Implement a centralized error handling mechanism to catch and handle errors consistently across your application. **Why:** Catching errors in one place makes it easier to log and manage the errors. Implement graceful fallbacks when errors occur. **Do This:** * Create a global error boundary component to catch and handle errors from all child components. * Use "try...catch" blocks to catch errors in asynchronous operations and state updates. * Log errors to a centralized logging service for analysis and monitoring. **Don't Do This:** * Let unhandled exceptions crash the application. * Ignore errors silently without logging them. ### 5.2. Logging **Standard**: Implement robust logging practices to track state changes, API requests, and other important events in your application. **Why**: Comprehensive logs make it easy to analyze runtime issues. Logging best practice involves setting the proper logging level i.e. debug, info, warn or error as appropriate. **Do This:** * Use structured logging to capture state changes. * Correlate logs from React components from Bun server components. **Don't Do This:** * Store sensitive information in logs. * Depend on console logging for production applications. ### 5.3. State Recovery **Standard**: Implement state recovery mechanisms to restore the application to a stable state after an error occurs. **Why**: Crash the application leads to data loss and bad user experience. State recovery could involve reloading the application, redirecting to the default state, or using a previous state in session storage. **Do This:** * Implement rollback logic. * Persist state from session storage. Handle errors that occur. **Don't Do This:** * Leave the application in bad state after an error. * Store sensitive information in local or session storage. ## 6. Testing State Management Thoroughly testing your state management logic is essential for ensuring the correctness and reliability of your Bun applications. ### 6.1. Unit Testing **Standard**: Write unit tests for all state reducers, actions, and selectors to verify their behavior in isolation. **Why**: Ensure the application is accurate and prevent regression bugs. Writing the unit tests in isolation also validates if components are loosely coupled. **Do This:** * Use testing libraries to test state management. * Mock dependencies to ensure stability. **Don't Do This:** * Neglect writing unit tests to state management components. * Implement the application without unit tests. ### 6.2. Integration Testing **Standard**: Write integration tests to verify the interaction between state management and the React components. **Why**: Check and ensure the interaction between state management and components is working as expected. Verify functional flows and logic integration across various components. **Do This:** * Use testing libraries like Playwright to write integration tests. * Mock API requests and other dependencies to ensure stability. **Don't Do This:** * Fail to test the integration components. ### 6.3 End-to-End (E2E) Testing **Standard**: Write complete E2E tests to simulate user interactions and verify the application as a whole. **Why**: Catch bugs early and allow developers to ship new features quickly and efficiently. Write the functional flows as the user would experience. **Do This:** * Use end-to-end testing fameworks such as Selenium to test components. * Make sure E2E tests cover the most important user flows. **Don't Do This:** * Neglect complete E2E testing. * Skimp on E2E testing to save on expenses. * Rely only on manual testing. These standards provide a comprehensive guide for managing state in your Bun applications. Adhering to these guidelines will result in cleaner, more maintainable, secure, and performant code. By following these guidelines and best practices, you can build scalable and enjoyable Bun applications.

# Testing Methodologies Standards for Bun This document outlines the testing standards for Bun projects, covering unit, integration, and end-to-end testing strategies. It aims to ensure code quality, reliability, and maintainability while leveraging Bun's unique features. ## 1. General Testing Principles ### 1.1. Test Pyramid * **Do This:** Follow the test pyramid concept, prioritizing unit tests, followed by integration tests, and lastly, end-to-end tests. * **Don't Do This:** Rely heavily on end-to-end tests at the expense of unit and integration tests. This leads to slow feedback loops and difficult debugging. * **Why:** The test pyramid ensures a balanced testing strategy. Unit tests are fast and isolate problems, while integration and end-to-end tests verify interactions between components and the system as a whole. ### 1.2. Test-Driven Development (TDD) * **Do This:** Write tests *before* implementing the code. * **Don't Do This:** Write tests after the code is already written, or skip tests altogether. * **Why:** TDD forces you to think about the desired behavior and interface of your code before implementation, leading to better design and testability. ### 1.3. Test Coverage * **Do This:** Aim for high test coverage (e.g., 80% or higher), but prioritize testing critical business logic and complex code paths. Use Bun's built-in test coverage tools to measure coverage. * **Don't Do This:** Strive for 100% coverage at all costs. This can lead to writing superficial tests that don't add value and become difficult to maintain. * **Why:** Test coverage provides a metric for assessing the extent to which your code is tested. Focus should be on meaningful tests, not just achieving a specific number. ### 1.4. Test Naming and Organization * **Do This:** Use descriptive test names that clearly indicate what is being tested. Organize tests logically within your project structure. Match component/module folder structure. * **Don't Do This:** Use vague or ambiguous test names. Dump all tests into a single folder. * **Why:** Clear naming and organization make it easier to understand the purpose of tests and navigate the test suite. ## 2. Unit Testing ### 2.1. Scope and Purpose * **Do This:** Unit test individual functions, classes, or modules in isolation, mocking dependencies. * **Don't Do This:** Test interactions between different parts of the system in unit tests. That's the job of integration tests. * **Why:** Unit tests are fast, reliable, and isolate problems to specific units of code. ### 2.2. Assertion Libraries * **Do This:** Use a robust assertion library like "expect" (built-in to Bun) or "chai". * **Don't Do This:** Write custom assertion logic. * **Why:** Assertion libraries provide a clear and consistent way to express expectations in your tests. ### 2.3. Mocking and Stubbing * **Do This:** Use mocking libraries like "sinon" or "jest" (compatible with Bun) to isolate the unit under test. Focus on stubbing external dependencies and data to control inputs. * **Don't Do This:** Over-mock, replace parts that are not relevant to the target test or mock the target of the test itself. * **Why:** Mocking allows you to test units of code in isolation without relying on external systems. ### 2.4. Example: Unit Testing a Simple Function """typescript // src/utils.ts export function add(a: number, b: number): number { return a + b; } // test/utils.test.ts import { add } from '../src/utils'; import { expect, it, describe } from 'bun:test'; describe('add', () => { it('should return the sum of two numbers', () => { expect(add(2, 3)).toBe(5); }); it('should handle negative numbers', () => { expect(add(-1, 5)).toBe(4); }); it('should handle zero', () => { expect(add(0, 0)).toBe(0); }); }); """ ### 2.5. Example: Unit Testing Asynchronous Code """typescript // src/api.ts export async function fetchData(url: string): Promise<any> { const response = await fetch(url); return response.json(); } // test/api.test.ts import { fetchData } from '../src/api'; import { expect, it, describe, mock } from 'bun:test'; describe('fetchData', () => { it('should fetch data from the API', async () => { const mockResponse = { data: 'test data' }; global.fetch = mock(() => Promise.resolve({ json: () => Promise.resolve(mockResponse), }) as any ); const data = await fetchData('https://example.com/api'); expect(data).toEqual(mockResponse); }); it('should handle errors', async () => { global.fetch = mock(() => Promise.reject(new Error('Network error')) as any); await expect(fetchData('https://example.com/api')).rejects.toThrow('Network error'); }); }); """ ### 2.6. Anti-Patterns in Unit Testing * **Testing implementation details:** Unit tests should focus on the *behavior* of the code, not its implementation. Avoid tests that depend on specific internal logic. * **Skipping error handling:** Make sure to test how your code handles errors and edge cases. * **Using real dependencies:** Avoid hitting real databases, APIs, or other external systems in unit tests. Use mocks, stubs, or test doubles. ## 3. Integration Testing ### 3.1. Scope and Purpose * **Do This:** Integration tests verify the interactions between different modules or components within your system. Often focuses on the 'seams' between components/services, or between a service and its database. * **Don't Do This:** Test individual units of code in isolation. Test the entire system end-to-end. * **Why:** Integration tests ensure that different parts of your application work together correctly. ### 3.2. Database Integration * **Do This:** Use test databases for integration tests. Seed the database with known data before running tests. Clean up the database after tests. Tools like "testcontainers" may also be useful. * **Don't Do This:** Run integration tests against production databases. * **Why:** Isolation and data control are crucial for reliable and repeatable integration tests. ### 3.3. API Integration * **Do This:** Test interactions with external APIs. Mock external API responses when possible, or use a sandbox environment. * **Don't Do This:** Rely on the availability and stability of live external APIs for every test run. * **Why:** External APIs can be unreliable. Mocking or using a sandbox minimizes the impact on your test suite. ### 3.4. Example: Integration Testing with a Database """typescript // src/user-service.ts import { Database } from 'bun:sqlite'; export class UserService { private readonly db: Database; constructor(db: Database) { this.db = db; this.db.exec(" CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE ) "); } async createUser(name: string, email: string): Promise<number> { const query = this.db.query("INSERT INTO users (name, email) VALUES (?, ?) RETURNING id"); const result = query.get(name, email) as { id: number } | undefined; if (!result) { throw new Error("Failed to create user"); } return result.id; } async getUser(id: number): Promise<{ id: number; name: string; email: string } | undefined> { const query = this.db.query("SELECT id, name, email FROM users WHERE id = ?"); return query.get(id) as { id: number; name: string; email: string } | undefined; } } // test/user-service.test.ts import { UserService } from '../src/user-service'; import { Database } from 'bun:sqlite'; import { expect, it, describe, beforeAll, afterAll } from 'bun:test'; describe('UserService', () => { let db: Database; let userService: UserService; beforeAll(() => { db = new Database(':memory:'); // In-memory database for testing userService = new UserService(db); }); afterAll(() => { db.close(); }); it('should create a user', async () => { const userId = await userService.createUser('John Doe', 'john.doe@example.com'); expect(userId).toBeGreaterThan(0); const user = await userService.getUser(userId); expect(user).toEqual({ id: userId, name: 'John Doe', email: 'john.doe@example.com' }); }); }); """ ### 3.5. Example: Integration Testing with an HTTP API """typescript // src/product-service.ts import { fetch } from 'undici'; // 'undici' is the recommended "fetch" implementation for Bun export class ProductService { private readonly apiUrl: string; constructor(apiUrl: string) { this.apiUrl = apiUrl; } async getProduct(id: number): Promise<any> { const response = await fetch("${this.apiUrl}/products/${id}"); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } return await response.json(); } } // test/product-service.test.ts import { ProductService } from '../src/product-service'; import { expect, it, describe, mock } from 'bun:test'; describe('ProductService', () => { it('should fetch a product', async () => { const mockProduct = { id: 1, name: 'Test Product', price: 10 }; global.fetch = mock(() => Promise.resolve({ ok: true, json: () => Promise.resolve(mockProduct), } as any) ); const productService = new ProductService('https://api.example.com'); const product = await productService.getProduct(1); expect(product).toEqual(mockProduct); }); it('should handle errors when fetching a product', async () => { global.fetch = mock(() => Promise.resolve({ ok: false, status: 500, } as any) ); const productService = new ProductService('https://api.example.com'); await expect(productService.getProduct(1)).rejects.toThrowError("HTTP error! status: 500"); }); }); """ ### 3.6. Anti-Patterns in Integration Testing * **Testing too much:** Integration tests should focus on verifying the interaction between components but shouldn't be end-to-end tests. * **Using inconsistent test data:** Ensure that your test data is consistent and well-defined. Use factories or fixtures to create test data. * **Ignoring dependencies:** Understand and manage the dependencies of your integration tests. ## 4. End-to-End (E2E) Testing ### 4.1. Scope and Purpose * **Do This:** E2E tests verify that the entire system works as expected from the user's perspective, simulating real user workflows. * **Don't Do This:** Use E2E tests to test individual units of code or interactions between components. * **Why:** E2E tests provide the highest level of confidence that your application is working correctly. ### 4.2. Testing Tools * **Do This:** Use modern E2E testing tools like Playwright or Cypress. These tools provide features like browser automation, test recording, and detailed reporting, and have been tested with Bun. * **Don't Do This:** Use outdated or unreliable testing tools that make it difficult to write and maintain E2E tests. * **Why:** Modern E2E testing tools offer a better developer experience and more robust testing capabilities. ### 4.3. Test Environment * **Do This:** Run E2E tests in a dedicated test environment that closely mirrors production. Use environment variables or configuration files to manage test-specific settings. * **Don't Do This:** Run E2E tests against production environments. * **Why:** A dedicated test environment ensures isolation and prevents unintended side effects. ### 4.4. Example: E2E Testing with Playwright First, install Playwright: """bash bun add -d playwright bun playwright install """ """typescript // playwright.config.ts import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: 'html', use: { baseURL: 'http://localhost:3000', // Replace with your app's URL trace: 'on-first-retry', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, ], webServer: { command: 'bun run dev', // Replace with your start command url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, }, }); """ """typescript // tests/example.spec.ts import { test, expect } from '@playwright/test'; test('has title', async ({ page }) => { await page.goto('/'); await expect(page).toHaveTitle(/Bun App/); // Replace with your title }); test('get started link', async ({ page }) => { await page.goto('/'); await page.getByRole('link', { name: 'Get started' }).click(); await expect(page).toHaveURL(/.*intro/); }); """ To run these tests: """bash bun test """ ### 4.5. Anti-Patterns in E2E Testing * **Flaky tests:** E2E tests can be flaky due to timing issues or external dependencies. Implement retries and timeouts to mitigate flakiness. * **Over-reliance on UI elements:** Avoid relying too heavily on specific UI element locators. Use more robust techniques like testing based on content or semantic roles. * **Ignoring accessibility:** Make sure your E2E tests verify the accessibility of your application. ## 5. Specific Bun Considerations ### 5.1. Bun's Built-in Test Runner * **Do This:** Leverage Bun's built-in test runner for unit and integration tests where possible. It is optimized for speed and integrates well with the Bun ecosystem. * **Don't Do This:** Avoid using Bun's test runner if you require advanced features like code coverage reporting or mocking that may be better supported by other tools. Bun has built-in code coverage now so this is less relevant. * **Why:** Bun's test runner is fast and easy to use. ### 5.2. Compatibility with Existing Testing Frameworks * **Do This:** Use existing testing frameworks like Jest or Mocha if you have existing test suites or require features not yet available in Bun's built-in test runner. The frameworks are generally compatible. * **Don't Do This:** Avoid using older versions of these frameworks that may not be fully compatible with Bun. * **Why:** Leverage existing investments in testing frameworks and libraries where possible. ### 5.3. Bun's Performance * **Do This:** Keep in mind that Bun is fast and can cause tests to run too quickly if your system isn't warmed up and ready. You *may* need to add some small delays in tests that rely on async operations. Profile tests to identify performance bottlenecks. * **Don't Do This:** Blindly add delays to your tests just for the sake of it. Debug performance issues systematically. * **Why:** Bun's speed can expose performance issues in your tests that might not be apparent in other environments. ### 5.4. Utilizing Bun's Features in Tests * **Do This:** Utilize features like Bun's built-in SQLite support for testing database interactions or Bun's "fetch" implementation in integration tests, which reduces dependencies. * **Don't Do This:** Overcomplicate tests by re-implementing functionalities that Bun already provides efficiently and optimized. * **Why:** Leverage Bun's features to simplify testing code and improve performance. ### 5.5. Example: Performance Testing While Bun doesn't have a dedicated performance testing framework *built-in*, you can leverage its speed and "console.time" for simple benchmarks and performance analysis. """typescript import { expect, it, describe } from 'bun:test'; describe('Performance Test', () => { it('Should perform operation within acceptable time', async () => { const operation = async () => { console.time('operation'); // Simulate some work let sum = 0; for (let i = 0; i < 1000000; i++) { sum += i; } console.timeEnd('operation'); return sum; }; const startTime = Date.now(); const result = await operation(); const endTime = Date.now(); const duration = endTime - startTime; console.log("Operation result: ${result}"); console.log("Duration: ${duration}ms"); expect(duration).toBeLessThan(500); // Example threshold - Adjust as needed }); }); """ **Note:** This is a basic example. For more comprehensive performance testing, consider using dedicated tools like "autocannon" or artillery within Bun. ## 6. Continuous Integration/Continuous Deployment (CI/CD) ### 6.1. Automated Testing * **Do This:** Integrate all tests (unit, integration, E2E) into your CI/CD pipeline. Run tests automatically on every commit or pull request. * **Don't Do This:** Rely on manual testing only. * **Why:** Automated testing provides early feedback and prevents regressions. ### 6.2. Reporting and Monitoring * **Do This:** Use a test reporting tool to track test results and identify failing tests. Monitor test execution time and identify slow tests. This can often be integrated as part of your CI/CD Pipeline automatically. * **Don't Do This:** Ignore failing tests or let test suites become slow and unreliable. * **Why:** Test reporting and monitoring helps you maintain a healthy test suite and identify potential problems early on. ### 6.3. Git Hooks * **Do This:** Use git hooks to run linters, formatters, and unit tests before commits, ensuring code consistency and preventing broken code from being committed. * **Don't Do This:** Skip pre-commit checks for speed. These checks can prevent a lot of problems early! * **Why:** Catch code quality issues before they are pushed to the repository. By following these testing standards, you can ensure the quality, reliability, and maintainability of your Bun projects.

# API Integration Standards for Bun This document outlines coding standards for API integration within Bun projects. It aims to ensure maintainability, performance, security, and consistency across all aspects of interacting with external services and backend systems. These standards are tailored for use with the latest Bun features and best practices. ## 1. Architectural Considerations ### 1.1 Abstraction and Separation of Concerns * **Do This:** Abstract API interaction logic into dedicated modules or services. Shield core application logic from the specifics of API endpoints, request structures, and response formats. * **Don't Do This:** Embed API calls directly within UI components or business logic without abstraction. This creates tight coupling and makes your code harder to test and refactor. * **Why:** Abstraction improves testability, maintainability, and allows for easier swapping of API implementations (e.g., switching from one payment gateway to another or mocking APIs for testing). It reduces the impact of API changes on the rest of the application. * **Example:** """typescript // api-client.ts (Abstraction Layer) import { request } from 'undici'; // Undici, Bun's built-in HTTP client interface User { id: number; name: string; email: string; } const API_URL = process.env.API_URL || 'https://example.com/api'; async function fetchUser(id: number): Promise<User> { try { const response = await request("${API_URL}/users/${id}"); if (response.statusCode !== 200) { throw new Error("HTTP error! status: ${response.statusCode}"); } const { body } = await response.body.json(); return body as User; } catch (error) { console.error("Error fetching user:", error); throw error; // Re-throw for handling higher up } } export { fetchUser }; // user-service.ts (Usage) import { fetchUser } from './api-client'; async function getUserProfile(userId: number): Promise<User> { try { const user = await fetchUser(userId); // Additional business logic specific to user retrieval. return user; } catch (error) { console.error("Failed to get user profile:", error); throw new Error("Unable to retrieve user profile."); } } export { getUserProfile }; """ ### 1.2 Environment Configuration * **Do This:** Externalize API endpoints, authentication tokens, and other configuration parameters using environment variables. Use ".env" files during development and environment-specific configuration in production. In Bun, leverage the built-in ".env" file support. * **Don't Do This:** Hardcode API URLs or sensitive information directly into your codebase. * **Why:** This simplifies deployments and reduces the risk of accidentally exposing sensitive information in version control. It allows for different API configurations across different environments (development, staging, production). * **Example:** Create a ".env" file: """ API_URL=https://api.example.com API_KEY=your_secret_api_key """ Access the config through "process.env": """typescript const apiUrl = process.env.API_URL; const apiKey = process.env.API_KEY; if (!apiUrl || !apiKey) { console.error("API_URL or API_KEY not configured!"); } """ ### 1.3 Error Handling and Resilience * **Do This:** Implement robust error handling, including retry mechanisms (with exponential backoff), circuit breaking, and proper logging. Utilize "try...catch" blocks and handle specific error types to provide meaningful error messages. * **Don't Do This:** Ignore errors, only log generic error messages, or assume API calls will always succeed. * **Why:** Handling API errors gracefully makes your application more resilient to transient network issues or API outages. Provides a better user experience by avoiding crashes or unclear error states. * **Example:** """typescript import { request } from 'undici'; async function fetchDataWithRetry(url: string, maxRetries = 3, retryDelay = 1000) { let retries = 0; while (retries < maxRetries) { try { const response = await request(url); if (response.statusCode >= 200 && response.statusCode < 300) { const data = await response.body.json(); return data; } else { // Retry on server errors (5xx) or rate limits (429) if (response.statusCode >= 500 || response.statusCode === 429) { retries++; console.warn("Attempt ${retries} failed with status ${response.statusCode}. Retrying in ${retryDelay}ms"); await new Promise(resolve => setTimeout(resolve, retryDelay)); retryDelay *= 2; // Exponential backoff } else { // Don't retry on client errors (4xx, except 429) throw new Error("Request failed with status ${response.statusCode}"); } } } catch (error) { console.error("Error fetching data: ${error}"); retries++; if (retries >= maxRetries) { throw new Error("Max retries reached. Failed to fetch data from ${url}. Last error: ${error}"); } console.warn("Retrying in ${retryDelay}ms..."); await new Promise(resolve => setTimeout(resolve, retryDelay)); retryDelay *= 2; // Exponential backoff } } throw new Error("Max retries reached. Failed to fetch data from ${url}."); } // Usage async function callAPI() { try { const data = await fetchDataWithRetry('https://api.example.com/data'); console.log('Data:', data); } catch (error) { console.error('Failed to fetch data after multiple retries:', error); // Handle the error appropriately, e.g., display an error message to the user. } } """ ### 1.4 API Versioning * **Do This:** Implement API versioning (e.g., using URL path "/api/v1/", headers, or content negotiation). Clearly document the implemented versioning strategy. * **Don't Do This:** Make breaking changes to APIs without introducing a new version. * **Why:** Allows for evolving APIs without breaking existing clients. Provides a smooth migration path for consumers of the API. ### 1.5 Rate Limiting * **Do This:** Implement rate limiting on API requests to protect backend resources. Utilize middleware or dedicated libraries to manage rate limits. Consider both client-side and server-side rate limiting as appropriate (though generally this is server-side). * **Don't Do This:** Overwhelm external APIs with excessive requests. Fail to handle "429 Too Many Requests" errors appropriately. * **Why:** Prevents abuse, protects against denial-of-service attacks, and ensures fair usage of API resources. Improves the reliability of your application by avoiding being blocked due to exceeding rate limits. ## 2. Implementation Details ### 2.1 Choosing an HTTP Client * **Do This:** Utilize "undici", Bun’s built-in HTTP client, for most API interactions. For more complex use cases (e.g., interceptors, automatic retries), consider libraries like "node-fetch" (with caution, see below), "axios" (with polyfills if server-side only). * **Don't Do This:** Rely on outdated or less performant HTTP clients without a strong justification. * **Why:** "undici" is highly performant and natively supported by Bun, offering significant performance advantages. However, it can be lower-level, needing more manual configuration for many common scenarios. "node-fetch" introduces a "fetch" compatible API, but may require polyfills when targeting only the server side. * **Considerations for node-fetch/axios:** If you decide to use "node-fetch" or "axios" in Bun, pay close attention to polyfills. Since Bun aims to be a drop-in replacement for Node.js, some libraries may not work out-of-the-box, requiring you to install and configure polyfills for missing browser APIs. Only add them if absolutely necessary. * **Example (Using "undici"):** """typescript import { request } from 'undici'; interface Post { userId: number; id: number; title: string; body: string; } async function getPosts(): Promise<Post[]> { try { const response = await request('https://jsonplaceholder.typicode.com/posts'); if (response.statusCode !== 200) { throw new Error("HTTP error! Status: ${response.statusCode}"); } const posts = await response.body.json() as Post[]; return posts; } catch (error) { console.error("Error fetching posts:", error); throw error; } } getPosts() .then(posts => console.log(posts)) .catch(error => console.error("Failed to get posts:", error)); """ ### 2.2 Data Serialization and Deserialization * **Do This:** Use "JSON.stringify" and "JSON.parse" for JSON data. For more complex data formats (e.g., XML, Protobuf), use appropriate libraries. Implement validation to ensure data integrity. Consider using TypeScript interfaces or libraries like "zod" or "yup" to define and validate data structures. * **Don't Do This:** Manually construct or parse JSON strings. Trust API data implicitly without validation. * **Why:** Proper data serialization and deserialization ensure data integrity and type safety. Validation prevents unexpected errors and security vulnerabilities. * **Example (Using "zod" for validation):** """typescript import { request } from 'undici'; import { z } from "zod"; const PostSchema = z.object({ userId: z.number(), id: z.number(), title: z.string(), body: z.string(), }); type Post = z.infer<typeof PostSchema>; // Infer the TypeScript type async function getPosts(): Promise<Post[]> { try { const response = await request('https://jsonplaceholder.typicode.com/posts'); if (response.statusCode !== 200) { throw new Error("HTTP error! Status: ${response.statusCode}"); } const rawData = await response.body.json(); // Validation using Zod const validatedData = z.array(PostSchema).safeParse(rawData); if (!validatedData.success){ console.error("Validation Error:", validatedData.error); throw new Error("Invalid API response format."); } return validatedData.data; } catch (error) { console.error("Error fetching posts:", error); throw error; } } getPosts() .then(posts => console.log(posts)) .catch(error => console.error("Failed to get posts:", error)); """ ### 2.3 Authentication and Authorization * **Do This:** Implement secure authentication and authorization mechanisms using industry-standard protocols like OAuth 2.0, JWT, or API keys. Store sensitive credentials securely (e.g., using environment variables or a secrets management system). Use HTTPS for all API communication. * **Don't Do This:** Hardcode credentials in code, commit secrets to version control, or use insecure protocols (HTTP). * **Why:** Protects your APIs and your application's data from unauthorized access. * **Example (Using API Keys):** """typescript import { request } from 'undici'; const API_KEY = process.env.API_KEY; async function fetchData(url: string) { if (!API_KEY) { throw new Error("API_KEY is not defined in the environment."); } try { const response = await request(url, { headers: { 'X-API-Key': API_KEY, }, }); if (response.statusCode !== 200) { throw new Error("HTTP error! Status: ${response.statusCode}"); } return await response.body.json(); } catch (error) { console.error("Error fetching data:", error); throw error; } } // Usage: fetchData('https://api.example.com/protected/data') .then(data => console.log(data)) .catch(error => console.error(error)); """ ### 2.4 Logging and Monitoring * **Do This:** Log all API requests, responses, and errors with sufficient detail for debugging and monitoring. Include timestamps, request URLs, HTTP status codes, and relevant data. Use structured logging for easier analysis. Integrate with monitoring tools to track API performance and availability. * **Don't Do This:** Log sensitive data (e.g., passwords, API keys) in plain text. Fail to monitor API performance or errors. * **Why:** Provides insights into API usage patterns, helps to identify and resolve issues quickly, and enables proactive monitoring of API health. * **Example:** """typescript import { request } from 'undici'; async function fetchData(url: string) { const startTime = Date.now(); try { const response = await request(url); const endTime = Date.now(); const duration = endTime - startTime; console.log("API Request: ${url} - Status: ${response.statusCode} - Duration: ${duration}ms"); if (response.statusCode !== 200) { throw new Error("HTTP error! Status: ${response.statusCode}"); } return await response.body.json(); } catch (error) { const endTime = Date.now(); const duration = endTime - startTime; console.error("API Request Failed: ${url} - Duration: ${duration}ms - Error: ${error}"); throw error; } } """ ## 3. Advanced Patterns ### 3.1 Caching * **Do This:** Implement caching strategies to reduce API calls and improve performance. Use appropriate cache headers (e.g., "Cache-Control", "ETag") on the server-side and client-side. Consider using in-memory caching, Redis, or other caching solutions. * **Don't Do This:** Cache sensitive data without proper security measures. Cache data indefinitely without invalidation strategies. Use the same Cache TTL for all requests. * **Why:** Reduces latency, improves application responsiveness, and reduces load on backend systems. ### 3.2 GraphQL * **Do This:** Consider using GraphQL when dealing with complex data requirements or when needing to optimize data fetching. Use libraries like "graphql-js" with "bun" or frameworks like "mercurius" (fastest GraphQL framework) or "fastify-gql". * **Don't Do This:** Neglect the use of proper data loading techniques to prevent N+1 query problems in GraphQL resolvers. * **Why:** GraphQL allows clients to request only the specific data they need, improving performance and reducing over-fetching. It also provides a strong type system and introspection capabilities. Bun is optimized for GraphQL. ### 3.3 Server-Sent Events (SSE) and WebSockets * **Do This:** Use SSE or WebSockets for real-time data updates. Use appropriate libraries and protocols (e.g., "ws" for WebSockets). * **Don't Do This:** Use polling for real-time updates when SSE or WebSockets are more appropriate. * **Why:** Provides efficient, low-latency communication for real-time applications. Bun performance is well suited to handling numerous concurrent connections thanks to Javascript and Zig interoperability. ## 4. Bun-Specific Optimizations ### 4.1 Transpilation and Bundling * **Do This:** Utilize Bun's built-in transpiler and bundler for optimal performance. Configure "bunfig.toml" appropriately for your project. * **Don't Do This:** Rely on external transpilers or bundlers unless absolutely necessary. * **Why:** Bun's native tooling is optimized for speed and efficiency within the Bun ecosystem. ### 4.2 Zig Interoperability (advanced) * **Do This:** Consider leveraging Zig interoperability for performance-critical API integration tasks, such as parsing binary data or implementing custom protocols. * **Don't Do This:** Use Zig without a clear understanding of its benefits and drawbacks. Keep Zig code isolated and well-tested. * **Why:** Zig offers significant performance advantages over JavaScript for certain tasks. Bun's Zig integration provides a powerful way to optimize critical sections of your code. ### 4.3 Bun.serve * **Do This:** Use the "Bun.serve" API for creating web servers and handling API endpoints. * **Don't Do This:** Use other server implementations that lack Bun's performance benefits unless there is a specific reason. * **Why:** Bun's built-in server is faster and more memory-efficient than many Node.js alternatives. These coding standards provide a foundation for building robust, performant, and secure API integrations within Bun projects. By adhering to these guidelines, development teams can ensure code consistency, improve maintainability, and deliver high-quality applications. Remember to adapt and refine these standards based on the specific needs and circumstances of your project.