@posit-dev/positron-types NPM

@posit-dev/positron-types

⚠️ EXPERIMENTAL - USE WITH EXTREME CAUTION
This package is currently experimental and should be used with extreme caution. The API definitions may change without notice, break compatibility, or be removed entirely. This package is not yet recommended for production use. Use at your own risk.

TypeScript definitions for the Positron API.

Positron is a next-generation data science IDE powered by VS Code, designed specifically for data science workflows in Python and R.

Installation

npm install --save-dev @posit-dev/positron-types @types/vscode

Usage

Basic Usage

import { getPositronApi } from '@posit-dev/positron-types';
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const positronApi = getPositronApi();
  
  if (positronApi) {
    // Running in Positron - enhanced features available
    vscode.window.showInformationMessage('Enhanced by Positron!');
    positronApi.runtime.executeCode('python', 'print("Hello Positron!")', true);
  } else {
    // Running in VS Code - standard functionality only
    vscode.window.showInformationMessage('Running in VS Code mode');
  }
}

Advanced Usage

Runtime Detection

import { getPositronApi } from '@posit-dev/positron-types';

function isPositronAvailable(): boolean {
  return getPositronApi() !== undefined;
}

function executeInPositron(code: string) {
  const api = getPositronApi();
  if (api) {
    return api.runtime.executeCode('python', code, false);
  }
  throw new Error('Positron not available');
}

Type-only Imports

import type { 
  LanguageRuntimeMetadata, 
  RuntimeState,
  LanguageRuntimeSession 
} from '@posit-dev/positron-types';

function processRuntime(runtime: LanguageRuntimeMetadata) {
  // Use types for development, getPositronApi() for runtime access
}

Feature Flagging

import { getPositronApi } from '@posit-dev/positron-types';

export class MyExtension {
  private positronApi = getPositronApi();

  async showData(data: any[]) {
    if (this.positronApi) {
      // Use Positron's data viewer
      await this.positronApi.window.previewUrl(/* data url */);
    } else {
      // Fallback to VS Code's generic viewer
      await vscode.commands.executeCommand('vscode.open', /* data file */);
    }
  }
}

API Coverage

This package includes TypeScript definitions for:

Core APIs

Runtime Management: LanguageRuntimeManager, LanguageRuntimeSession
Language Runtime Messages: All message types and interfaces
Runtime States: State enums and metadata interfaces
Client Management: Runtime client types and handlers

UI APIs

Window Extensions: Preview panels, output channels, modal dialogs
Language Features: Statement range providers, help topic providers
Console Integration: Console API for language-specific interactions

Specialized APIs

Connections: Database connection driver interfaces
Environment: Environment variable management
AI Features: Language model and chat agent interfaces
Plotting: Plot rendering settings and formats

Version Compatibility

@posit-dev/positron-types	Positron Version	VS Code API
1.x.x	2024.12.0+	1.74.0+

Development

This package is automatically generated from the Positron source code. The types are extracted and processed to be standalone, with all internal dependencies inlined.

Building from Source

# Clone the Positron repository
git clone https://github.com/posit-dev/positron.git
cd positron/packages/positron-types

# Build the types
npm run build

Examples

Working with Language Runtimes

import { getPositronApi } from '@posit-dev/positron-types';
import type { RuntimeCodeExecutionMode } from '@posit-dev/positron-types';

// Execute code in a runtime (Positron only)
const positronApi = getPositronApi();
if (positronApi) {
  await positronApi.runtime.executeCode(
    'python',
    'print("Hello from Positron!")',
    true, // focus console
    false, // require complete code
    RuntimeCodeExecutionMode.Interactive
  );

  // Get active sessions
  const sessions = await positronApi.runtime.getActiveSessions();
  for (const session of sessions) {
    console.log(`Session: ${session.runtimeMetadata.runtimeName}`);
  }
}

Creating Preview Panels

import { getPositronApi } from '@posit-dev/positron-types';
import * as vscode from 'vscode';

// Create a preview panel for web content (Positron only)
const positronApi = getPositronApi();
if (positronApi) {
  const panel = positronApi.window.createPreviewPanel(
    'myExtension.preview',
    'My Preview',
    true, // preserve focus
    {
      enableScripts: true,
      localResourceRoots: [vscode.Uri.file('/path/to/resources')]
    }
  );

  panel.webview.html = '<html><body><h1>Hello Positron!</h1></body></html>';
}