WASM Processing

WebAssembly file processing capabilities that handle Perspective's WASM modules with configurable loading strategies and webpack compatibility features.

Capabilities

WASM Plugin Factory

Creates an esbuild plugin for processing WebAssembly files with configurable loading modes.

/**
 * Creates a WASM processing plugin for esbuild
 * @param inline - Whether to inline WASM files as binary data
 * @param webpack_hack - Enable webpack URL compatibility mode
 * @returns Plugin object with WASM handling logic
 */
function WasmPlugin(inline: boolean, webpack_hack: boolean): EsbuildPlugin;

interface EsbuildPlugin {
  name: string;
  setup: (build: PluginBuild) => void;
}

Note: WasmPlugin is an internal component used by PerspectiveEsbuildPlugin and is not directly accessible to users. Configuration is done through the main plugin options.

Loading Strategies

The plugin supports two primary WASM loading strategies:

Inline Loading

When inline: true, WASM files are embedded directly into the JavaScript bundle as binary data.

• Pros: Single file distribution, no additional HTTP requests
• Cons: Larger bundle size, memory usage for large WASM files
• Use Case: Small WASM modules or when minimizing HTTP requests is critical

// Generated code for inline mode
import wasm from "./perspective.wasm";
export default function() { 
    return Promise.resolve(wasm.buffer); 
};

External Loading

When inline: false, WASM files are loaded as separate resources via fetch.

• Pros: Smaller initial bundle, lazy loading capability
• Cons: Additional HTTP request, requires proper MIME type configuration
• Use Case: Large WASM modules or when optimizing initial load time

// Generated code for external mode
import wasm from "./perspective.wasm";
export default function() { 
    return fetch(new URL("wasm", import.meta.url));
};

Webpack Compatibility Mode

When webpack_hack: true, the plugin provides compatibility with webpack-style WASM URL handling.

/**
 * Enables webpack-compatible WASM URL generation
 * Processes generated JavaScript files to convert placeholder URLs to actual file paths
 */
webpack_hack: boolean;

This mode:

• Generates placeholder URLs during build
• Post-processes JavaScript files to replace placeholders with actual file paths
• Maintains compatibility with webpack-based build systems

Generated URL Pattern:

// Placeholder during build
__PSP_INLINE_WASM__123456__(wasm)

// Replaced with actual filename
"perspective-abc123.wasm"

File Resolution

The plugin handles .wasm file imports through multiple resolution namespaces:

• wasm-inline: Resolves WASM files for inline embedding
• wasm-stub: Resolves WASM files for external loading
• wasm: Final resolution namespace for actual file content

Build Integration

The WASM plugin integrates with esbuild's build lifecycle:

1. onResolve: Intercepts .wasm file imports and determines loading strategy
2. onLoad: Generates appropriate wrapper code based on the loading mode
3. onEnd: Post-processes files for webpack compatibility if enabled

Configuration through PerspectiveEsbuildPlugin:

const esbuild = require("esbuild");
const { PerspectiveEsbuildPlugin } = require("@finos/perspective-esbuild-plugin");

esbuild.build({
  entryPoints: ["src/index.js"],
  plugins: [
    PerspectiveEsbuildPlugin({
      wasm: {
        inline: false,      // External loading
        webpack_hack: true  // Disable webpack compatibility
      }
    })
  ],
  format: "esm",
  bundle: true,
  metafile: true,
});