07. Extension System

TitanPL supports three distinct types of extensions to suit different performance and security needs. All extensions are registered on the global t object for seamless use in your JavaScript actions.

🚀 Extension Types

1. JavaScript (JS-Only)

• Best for: Standard utilities, helper functions, and non-blocking logic.
• Complexity: Zero build step.
• Security: Always safe, runs inside the V8 sandbox.
• How to Create:

  titan create ext <name>
  # Select 'js'

• Structure:
  • index.js: Main logic.
  • titan.json: Metadata.
• Registration: Uses utils/registerExtension.js to safely attach to the global t.

2. WebAssembly (WASM)

• Best for: Performance-critical algorithms, parsers, or portable Rust logic.
• Complexity: Requires titan build ext (compiles Rust to .wasm).
• Security: Sandboxed, requires allowWasm: true in tanfig.json.
• How to Create:

  titan create ext <name>
  # Select 'wasm'

• Build: titan build ext (requires Rust toolchain).

3. Native (Rust/C++)

• Best for: Direct OS access, high-performance database drivers, or hardware acceleration.
• Complexity: Out-of-process execution for stability. Requires titan build ext.
• Security: Hard-Blocked by default. Requires explicit listing in tanfig.json.
• How to Create:

  titan create ext <name>
  # Select 'native'

• Build: titan build ext (compiles to .dll or .so).

🛡️ Security Configuration (tanfig.json)

To prevent unvetted code from running, TitanPL requires explicit permissions for non-JS extensions.

{
  "name": "my-secure-app",
  "extensions": {
    "allowWasm": true,
    "allowNative": [
      "@titanpl/core",
      "my-custom-native-ext"
    ]
  }
}

🛠️ Usage in Actions

Once an extension is loaded, it is available globally on the t object. You can also import specific components for better IDE support.

// app/actions/my-action.js
import { log, crypto } from "@titanpl/native"; // Typed access

export function myAction(req) {
    // Both syntaxes work:
    t.log("Extension is ready!");
    log("Direct access also works!");
    
    return { status: "success" };
}

Summary

• Choose the right extension type (JS, WASM, or Native) based on your needs.
• Use titan create ext to scaffold new extensions.
• Explicitly authorize WASM and Native extensions in tanfig.json.
• Access extensions via the global t object or specific imports.