Files

Juergen Kunz d4a100ff32 feat(smartdeno): Run small scripts in-memory via stdin, fall back to temp files for large scripts; remove internal HTTP script server and simplify plugin dependencies; update API and docs.

2025-12-02 11:39:46 +00:00

7.0 KiB

Raw Permalink Blame History

@push.rocks/smartdeno

Run Deno scripts from Node.js with automatic Deno management, permission control, and ephemeral script execution. 🦕➡️📦

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

npm install @push.rocks/smartdeno
# or
pnpm add @push.rocks/smartdeno

Usage

🚀 Basic Example

import { SmartDeno } from '@push.rocks/smartdeno';

const smartDeno = new SmartDeno();

// Start SmartDeno (downloads Deno if needed)
await smartDeno.start();

// Execute a Deno script
const result = await smartDeno.executeScript(`console.log("Hello from Deno!")`);
console.log(result.stdout); // "Hello from Deno!"
console.log(result.exitCode); // 0

// Clean up when done
await smartDeno.stop();

⚙️ Configuration Options

Start Options

await smartDeno.start({
  // Force download a local copy of Deno even if it's in PATH
  forceLocalDeno: true,
});

🔐 Deno Permissions

Control what your Deno scripts can access using the permissions option:

// Allow network access
const result = await smartDeno.executeScript(
  `const response = await fetch("https://api.example.com/data");
   console.log(await response.text());`,
  { permissions: ['net'] }
);

// Allow environment variable access
const envResult = await smartDeno.executeScript(
  `console.log(Deno.env.get("HOME"))`,
  { permissions: ['env'] }
);

// Allow all permissions (use with caution! ⚠️)
const fullResult = await smartDeno.executeScript(
  `// Script with full access`,
  { permissions: ['all'] }
);

Available Permissions

Permission	Description
`all`	Grant all permissions (`-A` flag)
`env`	Environment variable access
`ffi`	Foreign function interface
`hrtime`	High-resolution time measurement
`net`	Network access
`read`	File system read access
`run`	Subprocess execution
`sys`	System information access
`write`	File system write access

📤 Execution Results

The executeScript method returns detailed execution information:

const result = await smartDeno.executeScript(`console.log("test")`);

console.log(result.exitCode); // 0 for success, non-zero for errors
console.log(result.stdout);   // Standard output
console.log(result.stderr);   // Standard error output

🛡️ Error Handling

// Scripts that throw errors return non-zero exit codes
const result = await smartDeno.executeScript(`throw new Error("Something went wrong")`);

if (result.exitCode !== 0) {
  console.error('Script failed:', result.stderr);
}

// Attempting to execute before starting throws an error
try {
  const unstarted = new SmartDeno();
  await unstarted.executeScript(`console.log("test")`);
} catch (error) {
  console.error(error.message); // "SmartDeno is not started. Call start() first."
}

🔄 Lifecycle Management

const smartDeno = new SmartDeno();

// Check if running
console.log(smartDeno.isRunning()); // false

await smartDeno.start();
console.log(smartDeno.isRunning()); // true

// Execute scripts...

await smartDeno.stop();
console.log(smartDeno.isRunning()); // false

// Safe to call stop() multiple times
await smartDeno.stop(); // No error

🌐 Integration Example

Using SmartDeno in an Express server:

import express from 'express';
import { SmartDeno } from '@push.rocks/smartdeno';

const app = express();
const smartDeno = new SmartDeno();

app.use(express.json());

// Initialize on startup
await smartDeno.start();

app.post('/execute', async (req, res) => {
  const { script, permissions } = req.body;

  try {
    const result = await smartDeno.executeScript(script, { permissions });
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Cleanup on shutdown
process.on('SIGTERM', async () => {
  await smartDeno.stop();
  process.exit(0);
});

app.listen(3000);

🔧 How It Works

SmartDeno works by:

🦕 Deno Management — Automatically downloads the latest Deno binary for your platform if not available or if forceLocalDeno is set
💾 In-Memory Execution — Scripts < 2MB are executed via stdin (deno run -), staying fully in-memory with no disk I/O
📁 Large Script Support — Scripts >= 2MB automatically use a temp file (cleaned up after execution)
🔒 Permission Control — Translates permission options to Deno's security flags

📚 API Reference

`SmartDeno`

Constructor

const smartDeno = new SmartDeno();

Methods

Method	Description
`start(options?)`	Initialize SmartDeno (downloads Deno if needed)
`stop()`	Stop SmartDeno instance
`isRunning()`	Check if SmartDeno is currently running
`executeScript(script, options?)`	Execute a Deno script

Types

interface ISmartDenoOptions {
  forceLocalDeno?: boolean;
}

interface IExecuteScriptOptions {
  permissions?: TDenoPermission[];
}

type TDenoPermission =
  | 'all'
  | 'env'
  | 'ffi'
  | 'hrtime'
  | 'net'
  | 'read'
  | 'run'
  | 'sys'
  | 'write';

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

7.0 KiB Raw Permalink Blame History