best-practices

Documentation

• When changing code, review nearby JSDoc comments to ensure they are up to date
• Include @throws tags in JSDoc for all errors that methods can throw
• Provide usage examples in JSDoc using code blocks with ```typescript for public APIs
• Document parameter constraints and validation rules in JSDoc
• Mark internal APIs with /** @internal */ to exclude them from public documentation

Error Handling

• Use appropriate custom error classes from src/errors (e.g., PineconeArgumentError, PineconeBadRequestError, PineconeConnectionError)
• All custom errors extend BasePineconeError
• Include descriptive error messages that help users understand what went wrong
• When wrapping errors, preserve the original cause using the constructor that accepts Error as the second parameter: new ErrorClass(message, cause)
• Map HTTP status codes to appropriate error types using mapHttpStatusError patterns

Validation

• Validate input parameters early in public methods, throwing PineconeArgumentError for invalid inputs
• Provide clear, actionable error messages that reference documentation when appropriate
• Use helper validation functions for complex validation logic that may be reused
• Validate null, undefined, and empty strings/arrays explicitly before use
• Leverage TypeScript's type system to catch many validation issues at compile time

Code Generation

• Never manually edit files in src/pinecone-generated-ts-fetch/** - these are auto-generated
• If changes are needed to generated code, update the source OpenAPI/Proto files in codegen/ and regenerate using npm run generate:openapi

Testing

• Ensure all major requirements are captured as test cases
• Write unit tests for validation logic and error handling paths
• Include integration tests for end-to-end workflows (sparingly)
• Test both success and failure scenarios, including edge cases
• Use descriptive test names that clearly indicate what is being tested
• Test both Node.js and Edge runtime environments when applicable