npm package: @samklep/ts-ref
Description: Interactive CLI for JavaScript (MDN) and TypeScript documentation reference
Author: Sam Klepper
Latest version: 0.1.0
Deprecated: This package has been renamed to ts-quick-ref

# ts-ref

Interactive CLI for JavaScript (MDN) and TypeScript documentation reference.

Quickly look up JavaScript APIs and TypeScript concepts directly from your terminal with offline caching and a beautiful interactive interface.

## Installation

```bash
npm install -g ts-ref
```

Or run directly with npx:

```bash
npx ts-ref Array.map
```

## Usage

### Quick Lookup

```bash
# JavaScript (MDN) documentation
ts-ref Array.map
ts-ref Promise.all
ts-ref Object.keys
ts-ref fetch

# TypeScript documentation
ts-ref generics
ts-ref interfaces
ts-ref utility
ts-ref narrowing
```

### Specify Source

```bash
# Force JavaScript/MDN source
ts-ref --source js Array

# Force TypeScript source
ts-ref --source ts generics
ts-ref -s typescript mapped
```

### Search

```bash
# Search across all documentation
ts-ref search "array methods"
ts-ref s "promise"

# Search specific source
ts-ref search --source mdn "fetch api"
ts-ref search --source ts "type guards"

# Limit results
ts-ref search --limit 5 "string"

# Offline search (cached docs only)
ts-ref search --offline "array"
```

### Interactive Mode

Launch the interactive TUI for browsing documentation:

```bash
ts-ref
ts-ref -i
ts-ref --interactive
```

**Keyboard shortcuts:**
- `Enter` - Search / Select
- `↑↓` - Navigate results
- `Esc` - Go back
- `q` - Quit

### Cache Management

```bash
# View cache statistics
ts-ref cache stats

# Pre-fetch common documentation for offline use
ts-ref cache update

# Clear the cache
ts-ref cache clear
```

## Commands

| Command | Description |
|---------|-------------|
| `ts-ref <query>` | Look up documentation for a topic |
| `ts-ref search <query>` | Search documentation |
| `ts-ref cache <action>` | Manage documentation cache |

## Options

| Option | Description |
|--------|-------------|
| `-s, --source <source>` | Source to search: `mdn`, `js`, `ts`, `typescript` |
| `-r, --raw` | Output raw markdown without terminal formatting |
| `-i, --interactive` | Start interactive TUI mode |
| `-V, --version` | Show version number |
| `-h, --help` | Show help |

## Supported Topics

### JavaScript (MDN)

- Global objects: `Array`, `Object`, `String`, `Number`, `Promise`, `Map`, `Set`, `Date`, `RegExp`, `JSON`, `Math`, `Error`
- Array methods: `Array.map`, `Array.filter`, `Array.reduce`, `Array.find`, `Array.forEach`
- Object methods: `Object.keys`, `Object.values`, `Object.entries`, `Object.assign`
- Promise methods: `Promise.all`, `Promise.race`, `Promise.allSettled`
- Statements: `for`, `if`, `const`, `let`, `async`, `await`, `class`, `import`, `export`
- Operators: `...` (spread), `?.` (optional chaining), `??` (nullish coalescing)

### TypeScript

- Basics: `types`, `basics`, `everyday-types`
- Type System: `generics`, `interfaces`, `type`, `union`, `intersection`
- Narrowing: `narrowing`, `type-guards`, `never`
- Advanced Types: `keyof`, `typeof`, `conditional`, `mapped`, `template`
- Other: `classes`, `modules`, `functions`, `objects`, `tuples`

## How It Works

1. **Hybrid Caching**: Documentation is fetched from MDN and TypeScript sources, then cached locally in SQLite for fast offline access
2. **Smart Lookup**: Searches use fuzzy matching to find the best results
3. **Terminal Rendering**: Markdown is rendered with syntax highlighting for readability

## Cache Location

Documentation is cached at:
- **Linux/macOS**: `~/.ts-ref/cache.db`
- **Windows**: `%USERPROFILE%\.ts-ref\cache.db`

Cache expires after 7 days and is automatically refreshed on next lookup.

## Requirements

- Node.js >= 18.0.0

## Attribution

This tool fetches and caches documentation from the following sources:

- **JavaScript documentation**: [MDN Web Docs](https://developer.mozilla.org), licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)
- **TypeScript documentation**: [TypeScript Handbook](https://www.typescriptlang.org/docs/), © Microsoft, licensed under [Apache 2.0](https://github.com/microsoft/TypeScript-Website/blob/v2/LICENSE)

This project is not affiliated with Mozilla or Microsoft.

## License

MIT