|
| 1 | +# TypeScript SDK Style Guide |
| 2 | + |
| 3 | +## JSDoc Documentation Standards |
| 4 | + |
| 5 | +**🚨 ALWAYS use JSDoc format (`/** ... */`) for:** |
| 6 | + |
| 7 | +- **ALL exported functions** - Every function with `export` keyword must have JSDoc docstring describing its purpose, parameters, and return value |
| 8 | +- **ALL exported variables/constants** - Any constant or variable with `export` keyword used outside the current file |
| 9 | +- **ALL exported types and interfaces** - Including their properties and purpose |
| 10 | +- **ALL interface/type properties** - Individual property descriptions |
| 11 | + |
| 12 | +**⚠️ When you see `export function`, `export const`, `export type`, or `export interface`, automatically add JSDoc format.** |
| 13 | + |
| 14 | +### When NOT to Use JSDoc Format |
| 15 | + |
| 16 | +- **Implementation comments** - Comments inside function bodies explaining logic flow |
| 17 | +- **Inline comments** - Comments on the same line as code |
| 18 | +- **Temporary/debugging comments** - Comments meant for development purposes only |
| 19 | +- **Non-exported private utilities** - Internal helper functions not used elsewhere |
| 20 | + |
| 21 | +### JSDoc Formatting Requirements |
| 22 | + |
| 23 | +#### Basic Structure |
| 24 | + |
| 25 | +```typescript |
| 26 | +/** |
| 27 | + * Brief description of the function/variable/type |
| 28 | + * @param {type} paramName - Description of parameter |
| 29 | + * @returns {type} Description of return value |
| 30 | + * @type {type} - For variable type annotations |
| 31 | + */ |
| 32 | +``` |
| 33 | + |
| 34 | +#### Quality Guidelines |
| 35 | + |
| 36 | +- **Be Concise** - Keep descriptions clear and to the point |
| 37 | +- **Be Specific** - Explain what the function/variable does, not how it works |
| 38 | +- **Use Proper Grammar** - Start with capital letters, end with periods |
| 39 | +- **Avoid Redundancy** - Don't repeat information already clear from the code |
| 40 | +- **Include Edge Cases** - Document important limitations or special behaviors |
| 41 | + |
| 42 | +### Code Enforcement Rules |
| 43 | + |
| 44 | +**When generating or reviewing code, LLM should:** |
| 45 | + |
| 46 | +1. **Detect export keywords** - Scan for `export function`, `export const`, `export type`, `export interface` |
| 47 | +2. **Check for JSDoc** - Verify each export has proper `/** ... */` documentation |
| 48 | +3. **Suggest JSDoc format** - Auto-complete JSDoc blocks for any missing documentation |
| 49 | +4. **Flag regular comments** - Convert `//` comments above exports to JSDoc format |
| 50 | +5. **Apply to all files** - Enforce in `apps/`, `packages/`, and all TypeScript files |
| 51 | + |
| 52 | +### Detection Patterns for Regular Comments Above Exports |
| 53 | + |
| 54 | +**🚨 CRITICAL: Always detect and flag these patterns for JSDoc conversion:** |
| 55 | + |
| 56 | +- `// comment\nexport function` → Convert to JSDoc |
| 57 | +- `/* comment */\nexport function` → Convert to JSDoc |
| 58 | +- `// comment\nexport const` → Convert to JSDoc |
| 59 | +- `// comment\nexport interface` → Convert to JSDoc |
| 60 | +- `// comment\nexport type` → Convert to JSDoc |
| 61 | +- `// comment\nexport class` → Convert to JSDoc |
| 62 | + |
| 63 | +**Example:** |
| 64 | + |
| 65 | +❌ **Avoid - Regular comment above export:** |
| 66 | + |
| 67 | +```typescript |
| 68 | +// calculates position notional value |
| 69 | +export function calculateNotional(size: BigDecimal, price: BigDecimal) { |
| 70 | + // Should be converted to JSDoc format |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +✅ **Good - Proper JSDoc:** |
| 75 | + |
| 76 | +```typescript |
| 77 | +/** |
| 78 | + * Calculates the notional value of a position |
| 79 | + * @param size - Position size in base units (BigDecimal) |
| 80 | + * @param price - Current price per unit (BigDecimal, precision 18) |
| 81 | + * @returns Notional value in quote currency (USDC), rounded to 6 decimal places |
| 82 | + * @throws {InvalidPositionError} When size is zero or negative |
| 83 | + */ |
| 84 | +export function calculateNotional( |
| 85 | + size: BigDecimal, |
| 86 | + price: BigDecimal, |
| 87 | +): BigDecimal { |
| 88 | + // Implementation |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +## TypeScript Conventions |
| 93 | + |
| 94 | +- Use `interface` for object shapes that might be extended or implemented |
| 95 | +- Use `type` for unions, primitives, computed types, and utility types |
| 96 | +- **Never use `any` type** - Prefer `unknown` for truly unknown types, or create proper type definitions |
| 97 | +- Use descriptive generic constraints: `<T extends Record<string, unknown>>` |
| 98 | + |
| 99 | +## Error Handling Patterns |
| 100 | + |
| 101 | +- Create custom error classes extending base `Error` |
| 102 | +- Use `@throws` JSDoc tags to document all possible errors |
| 103 | +- Provide detailed error context and recovery suggestions |
| 104 | + |
| 105 | +✅ **Good error class patterns:** |
| 106 | + |
| 107 | +```typescript |
| 108 | +/** |
| 109 | + * Error thrown when wallet client is not provided for operations requiring it |
| 110 | + */ |
| 111 | +export class WalletNotProvidedError extends Error { |
| 112 | + constructor() { |
| 113 | + // Set descriptive message and proper error name |
| 114 | + super('Wallet client not provided'); |
| 115 | + this.name = 'WalletNotProvidedError'; |
| 116 | + } |
| 117 | +} |
| 118 | + |
| 119 | +/** |
| 120 | + * Error thrown when engine server returns a failure response |
| 121 | + */ |
| 122 | +export class EngineServerFailureError extends Error { |
| 123 | + // Store server response data as readonly property for debugging |
| 124 | + constructor(readonly responseData: ServerFailureResponse) { |
| 125 | + // Call super() with optional message |
| 126 | + super(); |
| 127 | + } |
| 128 | +} |
| 129 | +``` |
| 130 | + |
| 131 | +## Naming Conventions |
| 132 | + |
| 133 | +- **Use camelCase** for variables, functions, and methods |
| 134 | +- **Use PascalCase** for classes, interfaces, types, and enums |
| 135 | +- **Use CAPITAL_SNAKE_CASE** for constants and environment variables |
| 136 | +- **Client classes** should end with `Client` (e.g., `MarketClient`, `VertexClient`) |
| 137 | +- **Error classes** should end with `Error` (e.g., `ValidationError`, `NetworkError`) |
| 138 | +- **Type guards** should start with `is` (e.g., `isMarketOrder`, `isValidAddress`) |
| 139 | + |
| 140 | +## Constants and Configuration |
| 141 | + |
| 142 | +✅ **Good constants patterns:** |
| 143 | + |
| 144 | +```typescript |
| 145 | +/** |
| 146 | + * Common BigDecimal constants used throughout the SDK |
| 147 | + */ |
| 148 | +export const BigDecimals = Object.freeze({ |
| 149 | + // Freeze object to prevent mutation |
| 150 | + // Use semantic names for commonly used values |
| 151 | + ZERO: toBigDecimal(0), |
| 152 | + ONE: toBigDecimal(1), |
| 153 | + INF: toBigDecimal(Infinity), |
| 154 | + MAX_I128: toBigDecimal('170141183460469231731687303715884105727'), |
| 155 | +}); |
| 156 | + |
| 157 | +/** |
| 158 | + * Quote product ID for USDC |
| 159 | + */ |
| 160 | +export const QUOTE_PRODUCT_ID = 0; |
| 161 | +``` |
| 162 | + |
| 163 | +## Utility Function Patterns |
| 164 | + |
| 165 | +- Write pure functions where possible |
| 166 | +- Include comprehensive JSDoc with examples |
| 167 | +- Use proper type guards and validators |
| 168 | +- Handle edge cases gracefully |
| 169 | + |
| 170 | +✅ **Good utility function patterns:** |
| 171 | + |
| 172 | +```typescript |
| 173 | +/** |
| 174 | + * BigDecimal is a renamed `BigNumber` type from `bignumber.js`. |
| 175 | + * Includes valid values & instances for BigDecimal. |
| 176 | + * @see https://mikemcl.github.io/bignumber.js/ |
| 177 | + */ |
| 178 | +export type BigDecimalish = BigDecimal | BigDecimal.Value | bigint; |
| 179 | + |
| 180 | +/** |
| 181 | + * Converts a value to an instance of BigDecimal |
| 182 | + * @param val - The value to convert to BigDecimal |
| 183 | + * @returns A new BigDecimal instance |
| 184 | + */ |
| 185 | +export function toBigDecimal(val: BigDecimalish): BigDecimal { |
| 186 | + // Handle different input types with type guards |
| 187 | + const bnConstructorVal = (() => { |
| 188 | + if (val instanceof BigDecimal) { |
| 189 | + return val; // Already BigDecimal, return as-is |
| 190 | + } else if (typeof val === 'string' || typeof val === 'number') { |
| 191 | + return val; // Native types supported by BigNumber constructor |
| 192 | + } else if (typeof val === 'bigint') { |
| 193 | + return val.toString(); // Convert bigint to string |
| 194 | + } |
| 195 | + // Fallback for unexpected types (edge case handling) |
| 196 | + return JSON.stringify(val); |
| 197 | + })(); |
| 198 | + return new BigDecimal(bnConstructorVal); |
| 199 | +} |
| 200 | +``` |
| 201 | + |
| 202 | +## Code Quality Checklist |
| 203 | + |
| 204 | +When reviewing SDK code, ensure: |
| 205 | + |
| 206 | +- [ ] JSDoc format is used for all exported functions, classes, and types |
| 207 | +- [ ] Proper error handling with custom error classes |
| 208 | +- [ ] Type safety with no `any` types |
| 209 | +- [ ] Async operations use proper Promise handling |
| 210 | +- [ ] Constants are properly frozen and exported |
| 211 | +- [ ] Tests cover both success and error scenarios |
| 212 | +- [ ] Naming conventions are followed consistently |
0 commit comments