# ceifa/wasmoon architecture

> Architecture diagram of the GitHub repository ceifa/wasmoon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ceifa/wasmoon
- Repository: https://github.com/ceifa/wasmoon

## Overview

##### Project Type & Purpose
- This is a language interoperation library where JavaScript interacts with Lua through a WebAssembly layer.
- Its main goal is to allow JS applications (both backend and web) to run Lua scripts with performance improvements achieved via wasm.

##### Analyzing the File Structure
- Top-level directories include:
- “src”: Contains the TypeScript source code, with components like the Lua engine (engine.ts), factory (factory.ts), and various modules providing type extensions and utility functions.
- “lua”: Likely holds the Lua source or build assets tied to the WebAssembly component.
- “bin”: Contains the CLI executable script (wasmoon) to run Lua code from the command line.
- “test”: Houses tests that ensure the different functionalities (e.g., engine initialization, global variables, promise management) work as expected.
- “bench”: Contains benchmarking scripts (including Lua heapsort and JavaScript comparisons) to measure performance differences and validate the wasm advantages.
- “utils”: Contains scripts to assist with creating bindings and other build-related helper functions.
- Configuration files like package.json, tsconfig.json, and various GitHub CI workflow files indicate the project’s adherence to modern build, test, and deployment practices.

##### Examining the README for Architectural Insights
- The README highlights both API and CLI usage, indicating that Wasmoon works as a library for embedding Lua and also as a command-line tool.
- It discusses the performance benefits driven by wasm and compares with similar tools like fengari.
- There are build and deployment instructions that mention using Docker, emscripten, and various Node.js scripts.
- The README contains usage examples that reference core objects such as LuaFactory and Engine, thereby highlighting the importance of the factory design pattern and the Lua engine abstraction.

a. Main components:
- JS Environment: Represents where Wasmoon is embedded (Node.js, Deno, or Browser).
- LuaFactory: The component used to initialize and manage Lua engine instances.
- Lua Engine: The core module (src/engine.ts and related files) that provides an interface to the underlying Lua state (via WebAssembly).
- WebAssembly Layer: Represents the compiled Lua code (in wasm) coming from the lua submodule.
- Global and Type Extensions: Modules that extend Lua functionality (e.g., type-extensions packages: error, function, promise, etc.).
- CLI Interface: The binary available under the “bin” directory that allows command-line interactions.
- Build and Test Infrastructure: Components such as Docker, emscripten build scripts, and continuous integration (CI) setups indicated under “.github/workflows” and “build.sh”.

b. Relationships & Interactions:
- LuaFactory creates and configures Lua Engines.
- Each Lua Engine communicates with the WebAssembly Layer where Lua code is executed.
- Modules for type extensions, multireturn, pointer, and others serve as utility wrappers around Lua’s raw data, improving interoperability.
- The CLI component wraps around these core API modules to allow script execution from the terminal.
- Testing and benchmarking components validate performance and accuracy during runtime.

c. Architectural Patterns:
- Use of the Factory Pattern (LuaFactory) for engine instantiation.
- Separation of Concerns: Distinct modules for engine execution, low-level type handling, and utility functions.
- Integration through a WebAssembly boundary: Core Lua functionality is executed via wasm, ensuring high performance.
- A modular design: Each file or module in “src” handles a specific aspect (global states, pointers, threads, raw result handling, etc.).

d. Relevant Technologies:
- TypeScript (for the implementation in “src”).
- WebAssembly (wasm) compiled Lua runtime.
- Node.js, Deno, and potential browser environments.
- Build and CI tools: Docker, emscripten, GitHub Actions, ESLint, Prettier.
- Testing libraries and scripts shown in the “test” folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core API"
        A["JS Environment (Embedding API)"]:::core
        B["LuaFactory"]:::core
        C["Lua Engine"]:::core
        D["WebAssembly Lua VM"]:::wasm
        A -->|"initializes"| B
        B -->|"creates"| C
        C -->|"calls"| D
    end

    subgraph "Extensions"
        E["Global Configurations"]:::ext
        F["Type Extension Core"]:::ext
        G["Type Extensions Modules"]:::ext
        C -->|"uses"| E
        C -->|"uses"| F
        C -->|"uses"| G
    end

    H["CLI Interface"]:::cli
    H -->|"wraps"| B
    H -->|"accesses"| C

    subgraph "Build & Test Infrastructure"
        I["Build Scripts"]:::build
        J["CI & Configs"]:::build
        K["Testing Modules"]:::build
        I -->|"builds"| A
        J -->|"deploys"| A
        K -->|"tests"| A
    end

    click A "https://github.com/ceifa/wasmoon/blob/main/src/index.ts"
    click B "https://github.com/ceifa/wasmoon/blob/main/src/factory.ts"
    click C "https://github.com/ceifa/wasmoon/blob/main/src/engine.ts"
    click D "https://github.com/ceifa/wasmoon/blob/main/src/luawasm.ts"
    click E "https://github.com/ceifa/wasmoon/blob/main/src/global.ts"
    click F "https://github.com/ceifa/wasmoon/blob/main/src/type-extension.ts"
    click G "https://github.com/ceifa/wasmoon/tree/main/src/type-extensions"
    click H "https://github.com/ceifa/wasmoon/tree/main/bin/wasmoon"
    click I "https://github.com/ceifa/wasmoon/blob/main/build.sh"
    click J "https://github.com/ceifa/wasmoon/tree/main/.github/workflows"
    click K "https://github.com/ceifa/wasmoon/tree/main/test"

    classDef core fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef wasm fill:#e3f2fd,stroke:#0d47a1,stroke-width:2px;
    classDef ext fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef cli fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
    classDef build fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
```
