@push.rocks/smartdeno

A module to run Deno scripts from Node.js, including functionalities for downloading Deno and executing Deno scripts.

readme.md for @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:

  1. 🦕 Deno Management — Automatically downloads the latest Deno binary for your platform if not available or if forceLocalDeno is set
  2. 💾 In-Memory Execution — Scripts < 2MB are executed via stdin (deno run -), staying fully in-memory with no disk I/O
  3. 📁 Large Script Support — Scripts >= 2MB automatically use a temp file (cleaned up after execution)
  4. 🔒 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';

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.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @push.rocks/smartdeno

2025-12-02 - 1.2.0 - 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 - 1.1.0 - feat(core)

Add permission-controlled Deno execution, configurable script server port, improved downloader, dependency bumps and test updates

2024-05-29 - 1.0.3 - maintenance

Consolidated metadata and build configuration updates for 1.0.3.

2024-03-17 - 1.0.2 - fix(core)

Core fix included in the 1.0.2 release.

2024-03-16 - 1.0.1 - fix(core)

Core fix included in the 1.0.1 release.

2024-03-16 - 2024-03-17 - 1.0.2..1.0.3 - housekeeping

Version-only commits (no substantive code changes) recorded for completeness.