1  // SPDX-License-Identifier: AGPL-3.0-or-later
 2  // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
 3  = beamdeno
 4  :toc: macro
 5  :icons: font
 6  
 7  **Connect Deno to the BEAM ecosystem (Erlang, Elixir, Gleam).**
 8  
 9  image:https://img.shields.io/badge/license-AGPL--3.0-blue[License]
10  image:https://img.shields.io/badge/deno-runtime-green[Deno]
11  image:https://img.shields.io/badge/BEAM-ecosystem-purple[BEAM]
12  
13  toc::[]
14  
15  == Overview
16  
17  beamdeno enables Deno applications to communicate with BEAM-based systems (Erlang, Elixir, Gleam, LFE). Call Erlang functions, send messages to Elixir GenServers, and integrate with the actor model from JavaScript.
18  
19  == Architecture
20  
21  [source]
22  ----
23  ┌─────────────────┐         ┌─────────────────┐
24  │      Deno       │  ETF    │      BEAM       │
25  │   Application   │◄───────►│  Erlang/Elixir  │
26  └─────────────────┘  Port   └─────────────────┘
27          │                           │
28          └───── beamdeno ────────────┘
29  ----
30  
31  == Connection Methods
32  
33  [cols="1,1,1,1"]
34  |===
35  | Method | Complexity | Performance | Use Case
36  
37  | **Erlang Ports** | Medium | Good | Most common, spawn erl process
38  | **Distribution Protocol** | Hard | Best | Direct node communication
39  | **HTTP/JSON** | Easy | Slower | Simple integration
40  | **NIFs via Zig** | Hard | Best | Shared native code
41  |===
42  
43  == Quick Start
44  
45  [source,typescript]
46  ----
47  import { BeamConnection } from "beamdeno";
48  
49  // Connect to running BEAM node
50  const beam = await BeamConnection.connect({
51    node: "myapp@localhost",
52    cookie: "secret_cookie"
53  });
54  
55  // Call Erlang function
56  const result = await beam.call("lists", "seq", [1, 10]);
57  console.log(result); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
58  
59  // Send message to GenServer
60  await beam.cast("MyApp.Worker", { type: "process", data: "hello" });
61  
62  // Pattern match on messages
63  beam.receive((msg) => {
64    console.log("Received from BEAM:", msg);
65  });
66  ----
67  
68  == Features
69  
70  * **ETF Encoding/Decoding** — Native Erlang Term Format support
71  * **Port Communication** — Spawn and manage Erlang processes
72  * **Message Passing** — Send/receive with BEAM processes
73  * **GenServer Integration** — Call, cast, and subscribe to GenServers
74  * **Supervision Trees** — Monitor BEAM process health from Deno
75  
76  == Roadmap
77  
78  * **v0.1** — ETF encoder/decoder, basic port communication
79  * **v0.2** — GenServer call/cast support
80  * **v0.3** — Distribution protocol (direct node connection)
81  * **v1.0** — Full bidirectional messaging
82  
83  == Related Projects
84  
85  * https://github.com/hyperpolymath/bundeno[bundeno] — Deno/Bun portability
86  * https://github.com/hyperpolymath/deno-bunbridge[deno-bunbridge] — Bun ecosystem access
87  * https://github.com/hyperpolymath/v-deno[v-deno] — V language FFI
88  
89  == License
90  
91  AGPL-3.0-or-later