@ydbjs/query/ai-instructions/.instructions.example.md

High-level, type-safe YQL query and transaction client for YDB. Supports tagged template syntax, parameter binding, transactions, and statistics.

# YDB JavaScript SDK Instructions for AI Assistants

This file provides guidance for AI assistants (GitHub Copilot, Cursor, Claude, etc.) when working with YDB JavaScript SDK.

## YQL Query Security Requirements

### MANDATORY: Template Literal Usage
- Use `yql\`SELECT...\`` template literal syntax for all queries
- Template literals automatically parameterize interpolated values
- This prevents SQL injection by design

### FORBIDDEN: String Concatenation
- Never use `yql(queryString)` with manually built strings
- Never concatenate user input into query strings
- This creates SQL injection vulnerabilities

### Dynamic Elements
- Table/column names: Use `identifier()` function
- Static SQL fragments: Use `unsafe()` only in trusted contexts
- User data: Always validate and use template literal parameters

### Type Safety
- Import YDB types: `Int32`, `Text`, `Optional`, etc.
- Use `Optional<T>` for nullable database values
- Enable TypeScript strict mode

### Input Validation
- Validate all user inputs before queries
- Apply size limits to prevent DoS
- Handle null/undefined values explicitly

This ensures generated code follows YDB security best practices.