Package Exports
- @tsports/go-osc52
- @tsports/go-osc52/README.md
- @tsports/go-osc52/go-style
- @tsports/go-osc52/package.json
- @tsports/go-osc52/types
Readme
@tsports/go-osc52
A TypeScript port of go-osc52 - Generate OSC52 escape sequences for terminal clipboard operations.
OSC52 is a terminal escape sequence that allows copying text to the clipboard from anywhere, including:
- SSH sessions
- Docker containers
- Terminal multiplexers (tmux, screen)
- Local terminals
This library provides a complete TypeScript implementation with 100% API compatibility with the original Go package.
๐ Installation
# Using npm
npm install @tsports/go-osc52
# Using bun (recommended)
bun add @tsports/go-osc52
# Using yarn
yarn add @tsports/go-osc52๐ Quick Start
TypeScript-native API (Recommended)
import { Sequence } from '@tsports/go-osc52';
// Copy text to system clipboard
const seq = new Sequence('Hello, clipboard!');
process.stderr.write(seq.toString());
// Copy to primary clipboard (X11)
const primary = new Sequence('Primary clipboard text').primary();
process.stderr.write(primary.toString());
// Use with tmux
const tmux = new Sequence('From tmux session').tmux();
process.stderr.write(tmux.toString());
// Query clipboard contents
const query = new Sequence().query();
process.stderr.write(query.toString());
// Clear clipboard
const clear = new Sequence().clear();
process.stderr.write(clear.toString());Go-compatible API
import { New, Query, Clear } from '@tsports/go-osc52/go-style';
// Exact Go API compatibility
const seq = New('Hello from Go-style API');
process.stderr.write(seq.String());
// Chain operations like in Go
const result = New('text')
.Primary()
.Tmux()
.Limit(1000);
process.stderr.write(result.String());
// Query and clear operations
process.stderr.write(Query().String());
process.stderr.write(Clear().String());๐ง API Reference
Core Types
enum Clipboard {
SystemClipboard = 'c', // System clipboard
PrimaryClipboard = 'p' // X11 primary clipboard
}
enum Mode {
DefaultMode = 0, // Standard OSC52
ScreenMode = 1, // Escape for GNU screen
TmuxMode = 2 // Escape for tmux
}
enum Operation {
SetOperation = 0, // Copy to clipboard
QueryOperation = 1, // Query clipboard
ClearOperation = 2 // Clear clipboard
}Sequence Class
class Sequence {
// Fluent API methods
tmux(): Sequence // Set tmux mode
screen(): Sequence // Set screen mode
primary(): Sequence // Use primary clipboard
withLimit(limit: number): Sequence // Set size limit
query(): Sequence // Query operation
clear(): Sequence // Clear operation
// Output methods
toString(): string // Get escape sequence
writeTo(writer: Writer): Promise<number> // Write to stream
}Module Functions
// Create new sequences
New(...strings: string[]): Sequence
Query(): Sequence
Clear(): Sequence
// TypeScript-native alternatives
newSequence(...strings: string[]): Sequence
querySequence(): Sequence
clearSequence(): Sequence๐จ Usage Examples
SSH Session Clipboard
import { Sequence } from '@tsports/go-osc52';
// Detect if we're in tmux and adjust accordingly
const isInTmux = process.env.TMUX !== undefined;
let seq = new Sequence('Copied from SSH!');
if (isInTmux) {
seq = seq.tmux();
}
process.stderr.write(seq.toString());Large Text with Limits
import { Sequence } from '@tsports/go-osc52';
const largeText = 'A'.repeat(10000);
// Set a limit to prevent terminal issues
const seq = new Sequence(largeText).withLimit(5000);
const result = seq.toString();
if (result === '') {
console.log('Text too large for clipboard');
} else {
process.stderr.write(result);
}Environment-aware Copying
import { Sequence } from '@tsports/go-osc52';
function smartCopy(text: string): string {
let seq = new Sequence(text);
// Detect terminal environment
const term = process.env.TERM || '';
if (term.includes('screen')) {
seq = seq.screen();
} else if (process.env.TMUX) {
seq = seq.tmux();
}
return seq.toString();
}
// Use it
process.stderr.write(smartCopy('Smart clipboard copy!'));Multiple Clipboard Targets
import { Sequence, Clipboard } from '@tsports/go-osc52';
const text = 'Copy to multiple clipboards';
// System clipboard
const system = new Sequence(text);
process.stderr.write(system.toString());
// Primary clipboard (X11)
const primary = new Sequence(text).primary();
process.stderr.write(primary.toString());Stream Integration
import { Sequence } from '@tsports/go-osc52';
import { Writable } from 'stream';
const seq = new Sequence('Stream integration example');
// Write to process.stderr
await seq.writeTo(process.stderr);
// Write to custom stream
const customStream = new Writable({
write(chunk, encoding, callback) {
console.log('Received:', chunk.toString());
callback();
}
});
await seq.writeTo(customStream);๐งช Terminal Compatibility
| Terminal | OSC52 Support | Notes |
|---|---|---|
| Alacritty | โ Yes | Full support |
| iTerm2 | โ Yes | May need configuration |
| Kitty | โ Yes | Full support |
| WezTerm | โ Yes | Full support |
| tmux | โ ๏ธ Partial | Use .tmux() mode or configure set-clipboard on |
| GNU Screen | โ ๏ธ Partial | Use .screen() mode |
| Windows Terminal | โ Yes | Recent versions |
| VS Code Terminal | โ No | Use extension workarounds |
๐ง Configuration
Tmux Configuration
Add to your ~/.tmux.conf:
# Enable clipboard integration
set -g set-clipboard on
# Or for manual mode (use .tmux() in code)
set -g allow-passthrough onSSH Configuration
For clipboard forwarding over SSH, some terminals support it automatically. For others, OSC52 sequences work without additional configuration.
๐๏ธ Development
# Clone the repository
git clone https://github.com/tsports/go-osc52.git
cd go-osc52
# Install dependencies
bun install
# Run tests
bun test
# Build the project
bun run build
# Run examples
bun run examples/usage-comparison.ts๐งช Testing
The library includes comprehensive tests that verify 100% compatibility with the original Go implementation:
# Run all tests
bun test
# Run specific test suites
bun test test/basic.test.tsTest coverage includes:
- All OSC52 sequence variations
- Tmux and Screen mode escaping
- Base64 encoding correctness
- Size limits and edge cases
- WriteTo functionality
- Go API compatibility
๐ฆ Package Structure
@tsports/go-osc52/
โโโ index.js # TypeScript-native API
โโโ go-style.js # Go-compatible API
โโโ types.d.ts # Type definitions
โโโ package.jsonImport paths:
// TypeScript-native (recommended)
import { Sequence, New, Query, Clear } from '@tsports/go-osc52';
// Go-compatible API
import { New, Query, Clear, Sequence } from '@tsports/go-osc52/go-style';๐ค Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Add tests for new functionality
- Ensure all tests pass (
bun test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
๐ License
MIT License - see the LICENSE file for details.
๐ Acknowledgments
- Ayman Bagabas - Author of the original go-osc52 library
- Charm - For the excellent terminal tooling ecosystem
- OSC52 Specification - For the technical documentation
๐ Related Projects
- go-osc52 - Original Go implementation
- @tsports/uniseg - Unicode text segmentation
- Charm - Terminal applications and tools
Made with โค๏ธ for the terminal community