# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Tedious is a pure-JavaScript/TypeScript implementation of the TDS (Tabular Data Stream) protocol for connecting to Microsoft SQL Server databases. It supports TDS versions 7.1-7.4 (SQL Server 2000-2022).

## Common Commands

```bash
# Build (compiles TypeScript via Babel to lib/)
npm run build

# Lint and type check
npm run lint

# Run unit tests
npm run test

# Run a single test file
npx mocha test/unit/<test-file>.ts

# Run a single test by name
npx mocha test/unit/ --grep "test name pattern"

# Run integration tests (requires SQL Server)
npm run test-integration

# Run all tests
npm run test-all

# Generate documentation
npm run docs
```

## Integration Tests Setup

Integration tests require a SQL Server instance. Use the dev container or start SQL Server manually:

```bash
# Using docker-compose (from .devcontainer/)
docker-compose -f .devcontainer/docker-compose.yml up -d mssql

# Default connection: server=mssql (or localhost), user=sa, password=yourStrong(!)Password
```

Test configuration is in `test/config.ts`. CI uses `test/config.ci.ts`.

## Architecture

### Core Classes

- **`src/connection.ts`** - Main `Connection` class managing TDS protocol handshake, authentication, state machine, and request queuing. This is the primary entry point (~3,600 lines).
- **`src/request.ts`** - `Request` class representing SQL queries/commands with parameters and callbacks.
- **`src/bulk-load.ts`** - `BulkLoad` class for bulk data loading operations.

### TDS Protocol Implementation

- **`src/message-io.ts`** - Message encoding/decoding for TDS protocol
- **`src/packet.ts`** - TDS packet structure and constants
- **`src/prelogin-payload.ts`** - Pre-login negotiation
- **`src/login7-payload.ts`** - SQL Server login mechanism
- **`src/sqlbatch-payload.ts`** - SQL batch execution
- **`src/rpcrequest-payload.ts`** - RPC/stored procedure calls

### Token Parsers (`src/token/`)

~20 parsers for TDS protocol response tokens (COLMETADATA, ROW, DONE, ERROR, INFO, LOGINACK, etc.). Each parser handles a specific token type from the server response stream.

### Data Types (`src/data-types/`)

41 SQL Server data type implementations (int, varchar, datetime, money, xml, etc.). Each file exports a `DataType` object with `name`, `id`, `declaration`, `generateTypeInfo`, `generateParameterLength`, `generateParameterData`, and `validate` methods.

### Always Encrypted (`src/always-encrypted/`)

Column-level encryption support with Azure Key Vault integration for encrypted column data.

## Key Patterns

- **Event-driven async**: Connection emits events (`connect`, `end`, `error`, `infoMessage`, `errorMessage`, `debug`)
- **State machine**: Connection maintains internal state for TDS protocol handshake
- **Streaming**: Token parsers process response streams incrementally
- **Buffer management**: `src/tracking-buffer/` handles binary data serialization

## TypeScript Configuration

- Strict mode enabled with ES2022 target
- Babel transpiles to `lib/` directory
- Type declarations generated separately via `tsconfig.build-types.json`
- Node.js >=18.17 required