@thefarce/loom-vm-polyfill

What is this?

@thefarce/loom-vm-polyfill is a lightweight polyfill that enables the @thefarce/loom package to run in browser environments. The @thefarce/loom package relies on Node.js’s vm module for safe evaluation of JavaScript template literals during AST interpolation. This polyfill provides a browser-compatible implementation of the vm module using vm-browserify, allowing you to use @thefarce/loom seamlessly in client-side JavaScript applications.

When should I use this?

Use this polyfill when you want to use @thefarce/loom in a browser-based project (e.g., with a bundler like Webpack or Rollup). By importing this polyfill, you ensure that @thefarce/loom’s interpolation functionality works without requiring the Node.js vm module, which is unavailable in browsers.

Installation

npm install @thefarce/loom @thefarce/loom-vm-polyfill

You must also have a bundler (e.g., Webpack, Rollup, or Vite) configured to handle ES modules and browserify dependencies, as this polyfill relies on vm-browserify.

Usage

To use @thefarce/loom in a browser environment, import @thefarce/loom-vm-polyfill before any code that uses @thefarce/loom. This shims the Node.js vm module, enabling @thefarce/loom’s interpolation features to work correctly.

Example

import { createContext, runInContext } from './index.mjs'
import { htmlToAst, astToHtml } from '@thefarce/loom-html5'
import { interpolateTree } from '@thefarce/loom'

// Example: Interpolate a name into an HTML fragment
async function render() {
  const ast = htmlToAst('<p>Hello, ${name}!</p>', { fragment: true });
  const interpolated = await interpolateTree(ast, { name: 'Othello' }, { createContext, runInContext });
  console.log(astToHtml(interpolated)); // Outputs: <p>Hello, Othello!</p>
}
render();

Notes

• Bundler Requirement: Ensure your project uses a bundler that supports ES modules and can resolve vm-browserify. Most modern bundlers (e.g., Webpack, Rollup) handle this automatically.
• Security: The vm-browserify library uses an iframe for sandboxing, which is less secure than Node.js’s vm module. Avoid evaluating untrusted code without additional security measures (e.g., Content Security Policy).
• Compatibility: This polyfill is designed for use with @thefarce/loom version 1.x.x and 2.x.x. Ensure compatibility by checking the version of @thefarce/loom in your project.

API

This package exports the following functions to shim the Node.js vm module:

• createContext(context): Creates a sandboxed context for evaluating JavaScript code, using the provided context object.
• runInContext(code, context): Evaluates the code string in the specified context, returning the result.

These functions are automatically used by @thefarce/loom’s interpolateString function and do not typically need to be called directly.

Contributing

Contributions are welcome! Please submit pull requests with tests and documentation. Ensure code passes linting and tests by running:

npm run lint
npm run test

VIM

This project includes a .vimrc file to assist with development. See the file for configuration details.

License

MIT