tamedevil

library0.1.0jsnpmunverified

Tamedevil is a JavaScript/TypeScript library designed to mitigate the inherent dangers and complexities associated with `eval` and `new Function` for dynamic code generation. It achieves this by leveraging tagged template literals, ensuring that all string segments interpolated into the generated code are either trusted author-written code or properly escaped data. This approach significantly reduces the risk of code injection vulnerabilities. The library also addresses garbage collection concerns by ensuring generated functions operate without capturing ephemeral closure data, requiring all parameters to be passed explicitly. Currently at version `0.1.0` and actively developed as part of the Graphile Crystal ecosystem, it aims to provide a safer, more performant method for building dynamic functions where traditional `eval` is typically avoided.

auth-security serialization

npm install tamedevil

github ↗package ↗

INSTALL

IMPORT

SIG · TAMEDEVIL

tamedevil

auth-securityjavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { te } from 'tamedevil';

✗ const te = require('tamedevil').te;

`te` is the primary export for ESM. Helpers like `te.ref` and `te.lit` are properties on this function.

✓ const { te } = require('tamedevil');

✗ import te from 'tamedevil';

`te` is a named export, even in CommonJS via destructuring assignment. There is no default export.

te.ref

✓ import { te } from 'tamedevil'; const myRef = te.ref(someVariable);

Helpers like `te.ref` and `te.lit` are accessed as properties of the main `te` tagged template literal function.

Demonstrates how to safely build a dynamic JavaScript function using `tamedevil`'s tagged template literal and helpers like `te.ref` (for injecting variables) and `te.lit` (for embedding string literals safely), then executes it.

import { te } from "tamedevil"; import assert from "node:assert"; // Simulate a data source class class Source { constructor(data) { this.data = data; } find(spec) { return this.data.filter(item => JSON.stringify(item).includes(spec)); } } // Simulate a connection function function connection(records) { return records.map(r => `Found: ${JSON.stringify(r)}`).join('\n'); } // Here's a string we want to embed into the function: const spec = "foo"; // And here's a complex variable we want to use within the function's scope: const source = new Source([{id: 1, name: 'foobar'}, {id: 2, name: 'baz'}]); const toEval = te`\ const source = ${te.ref(source)}; const connectionFn = ${te.ref(connection)}; return function plan($record) { const $records = source.find(${te.lit(spec)}); // `spec` is treated as a literal search string return connectionFn($records); } `; const plan = te.run(toEval); const result = plan({}); // $record not used in this simplified example assert.strictEqual( result, `Found: {"id":1,"name":"foobar"}` ); console.log(result);

Debug

Known issues

gotchaUsing raw JavaScript `eval()` or `new Function()` directly without `tamedevil`'s constructs (e.g., `te.lit`, `te.ref`) still carries significant security risks, particularly code injection. `tamedevil` only mitigates these risks by ensuring only trusted code or properly escaped strings are evaluated. It does not provide a magic bullet for arbitrary code execution security.

fix

Always use `te.lit(myString)` for any literal string content that should be treated as data within the generated code, and `te.ref(variableName)` for injecting runtime variables or functions into the evaluated context to prevent accidental code injection.

affects: >=0.1.0

gotcha`tamedevil` functions are designed not to capture the closure in which they are defined. This means any external variables or functions you intend to use within the dynamically generated code must be explicitly passed using `te.ref`. Attempting to access an undeclared variable will result in a `ReferenceError` at runtime.

fix

Ensure all necessary external data, functions, or objects are passed into the `te` template literal using `te.ref(myVariable)` to make them accessible within the generated function's scope.

affects: >=0.1.0

gotchaWhile `tamedevil` significantly improves the security and garbage collection aspects of dynamic JavaScript code evaluation, it does not directly address potential difficulties in debugging. Errors or issues within dynamically generated code may still be challenging to inspect, profile, or map back to original source lines.

fix

Implement robust and comprehensive testing for any dynamically generated code paths. Avoid overly complex or deeply nested dynamic logic if debugging clarity is a primary concern for that specific code segment.

affects: >=0.1.0

breakingThis package explicitly requires Node.js version 22 or higher, as indicated by its `engines` declaration in `package.json`. Attempting to install or run `tamedevil` in environments with older Node.js versions will lead to installation failures or runtime errors.

fix

Upgrade your Node.js environment to version 22 or newer to ensure compatibility and proper functioning of `tamedevil`.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: someVariable is not defined

An external variable (`someVariable`) was used inside a `tamedevil` template literal without being explicitly passed in via `te.ref`, causing it to be undefined within the generated function's scope.

fix

To make `someVariable` available inside the generated function, pass it using `te.ref`: `const someVariable = 'value'; const code = te`return ${te.ref(someVariable)};``

SyntaxError: Unexpected identifier

A string containing unescaped content that is not valid JavaScript syntax was directly interpolated into the `te` template literal, resulting in malformed JavaScript code for the generated function. This can happen when intending to inject data as a string literal.

fix

If the content is meant to be a literal string within the generated code (e.g., a search query, a message), use `te.lit()` to ensure it's properly escaped: `const userQuery = 'some user input; delete *'; const code = te`const q = ${te.lit(userQuery)}; // Now safe`

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/graphile/crystal ↗

packagehttps://www.npmjs.com/package/tamedevil ↗