un-inception/clients/javascript/async/README.md

Unsandbox Async JavaScript SDK

Asynchronous JavaScript SDK for unsandbox.com code execution service.

Execute code in 50+ programming languages with full async/await support in Node.js.

Features

• ES Modules: Native ESM with async/await and native fetch
• 50+ Languages: Python, JavaScript, Go, Rust, Java, C/C++, and 44+ more
• Flexible Execution: Sync execution (blocks until completion) or async (fire-and-forget)
• Job Management: Poll, wait, cancel running jobs
• Credential Management: 4-tier credential resolution system
• Request Signing: HMAC-SHA256 authentication
• Language Detection: Automatic language detection from filenames
• Caching: Built-in language list caching
• Concurrent Execution: Execute multiple jobs concurrently with Promise.all()

Installation

# Clone the repository
git clone https://github.com/unsandbox/un-inception
cd clients/javascript/async

# Install dependencies (for testing)
npm install

Quick Start

Basic Async Execution

import { executeCode } from './src/un_async.js';

// Execute code and wait for completion
const result = await executeCode('python', 'print("Hello World")');
console.log(result.stdout);

Fire-and-Forget with Polling

import { executeAsync, waitForJob } from './src/un_async.js';

// Start execution (returns immediately)
const jobId = await executeAsync('javascript', 'console.log("Job started")');
console.log(`Job ID: ${jobId}`);

// Poll for completion
const result = await waitForJob(jobId);
console.log(`Status: ${result.status}`);
console.log(`Output: ${result.stdout}`);

Concurrent Execution

import { executeCode } from './src/un_async.js';

// Run multiple executions concurrently
const results = await Promise.all([
  executeCode('python', "print('Python')"),
  executeCode('javascript', "console.log('JavaScript')"),
  executeCode('go', 'fmt.Println("Go")'),
]);

for (const result of results) {
  console.log(`Language: ${result.language}, Output: ${result.stdout}`);
}

Credential Management (4-Tier Priority)

Credentials are resolved in the following order:

1. Function Arguments (highest priority)

   const result = await executeCode(
     'python',
     "print('hello')",
     'your_public_key',
     'your_secret_key'
   );
   

2. Environment Variables

   export UNSANDBOX_PUBLIC_KEY="your_public_key"
   export UNSANDBOX_SECRET_KEY="your_secret_key"
   node script.js
   

3. Config File (~/.unsandbox/accounts.csv)

   public_key_1,secret_key_1
   public_key_2,secret_key_2
   # Select account with: export UNSANDBOX_ACCOUNT=1
   

4. Local Directory (./accounts.csv) Same format as config file

Using Multiple Accounts

# List accounts in ~/.unsandbox/accounts.csv
# Use the second account (0-indexed)
export UNSANDBOX_ACCOUNT=1
node script.js

API Reference

Execution Functions

executeCode(language, code, publicKey?, secretKey?)

Execute code synchronously and wait for completion.

Args:

• language (string): Programming language (e.g., "python", "javascript")
• code (string): Source code to execute
• publicKey (string, optional): API public key
• secretKey (string, optional): API secret key

Returns: Promise