1  // SPDX-License-Identifier: AGPL-3.0-or-later
  2  // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
  3  = bundeno
  4  :toc: macro
  5  :toc-title: Contents
  6  :icons: font
  7  :source-highlighter: rouge
  8  
  9  **Write once, run on Deno and Bun.**
 10  
 11  image:https://img.shields.io/badge/license-AGPL--3.0-blue[License]
 12  image:https://img.shields.io/badge/deno-compatible-green[Deno]
 13  image:https://img.shields.io/badge/bun-compatible-orange[Bun]
 14  
 15  toc::[]
 16  
 17  == Overview
 18  
 19  bundeno is a runtime compatibility layer that enables JavaScript/TypeScript code to run seamlessly on both https://deno.land[Deno] and https://bun.sh[Bun] runtimes.
 20  
 21  Instead of polyfilling missing APIs, bundeno detects your runtime and delegates to native implementations—giving you the best of both worlds.
 22  
 23  == Features
 24  
 25  * **Runtime Detection** — Detect Deno, Bun, Node.js, or browser at runtime
 26  * **Unified File System** — `readTextFile`, `writeFile`, `readDir`, `stat`, etc.
 27  * **Process Abstraction** — Environment variables, subprocess execution, cwd
 28  * **Type-Safe** — Full TypeScript support with proper types
 29  * **Zero Dependencies** — No external packages required
 30  * **Future: Zig Native** — Performance-critical FFI via shared Zig libraries
 31  
 32  == Quick Start
 33  
 34  [source,typescript]
 35  ----
 36  import { RUNTIME, isDeno, isBun } from "bundeno/runtime";
 37  import { readTextFile, writeTextFile } from "bundeno/fs";
 38  import { exec, getEnv } from "bundeno/process";
 39  
 40  // Works on both Deno and Bun!
 41  console.log(`Running on: ${RUNTIME}`);
 42  
 43  const content = await readTextFile("./config.json");
 44  const home = getEnv("HOME");
 45  const result = await exec(["git", "status"]);
 46  ----
 47  
 48  == Installation
 49  
 50  === Deno
 51  
 52  [source,typescript]
 53  ----
 54  import { ... } from "jsr:@hyperpolymath/bundeno";
 55  ----
 56  
 57  === Bun
 58  
 59  [source,bash]
 60  ----
 61  bun add @hyperpolymath/bundeno
 62  ----
 63  
 64  == API Reference
 65  
 66  === Runtime Detection
 67  
 68  [cols="1,2"]
 69  |===
 70  | Function | Description
 71  
 72  | `detectRuntime()` | Returns `"deno"`, `"bun"`, `"node"`, `"browser"`, or `"unknown"`
 73  | `isDeno()` | Returns `true` if running on Deno
 74  | `isBun()` | Returns `true` if running on Bun
 75  | `RUNTIME` | Cached runtime value (evaluated once at import)
 76  |===
 77  
 78  === File System (`bundeno/fs`)
 79  
 80  [cols="1,2"]
 81  |===
 82  | Function | Description
 83  
 84  | `readTextFile(path)` | Read file as UTF-8 string
 85  | `readFile(path)` | Read file as `Uint8Array`
 86  | `writeTextFile(path, content)` | Write string to file
 87  | `writeFile(path, content)` | Write bytes to file
 88  | `exists(path)` | Check if file/directory exists
 89  | `stat(path)` | Get file stats (size, mtime, isFile, etc.)
 90  | `mkdir(path, options?)` | Create directory (recursive by default)
 91  | `remove(path, options?)` | Remove file or directory
 92  | `readDir(path)` | List directory contents
 93  | `copyFile(src, dest)` | Copy a file
 94  | `rename(src, dest)` | Rename/move a file
 95  |===
 96  
 97  === Process (`bundeno/process`)
 98  
 99  [cols="1,2"]
100  |===
101  | Function | Description
102  
103  | `getEnv(key)` | Get environment variable
104  | `setEnv(key, value)` | Set environment variable
105  | `getAllEnv()` | Get all environment variables
106  | `cwd()` | Get current working directory
107  | `chdir(path)` | Change current working directory
108  | `exit(code?)` | Exit the process
109  | `args()` | Get command line arguments
110  | `run(cmd, options?)` | Run command and get result
111  | `exec(cmd, options?)` | Run command and return stdout as string
112  |===
113  
114  == Why bundeno?
115  
116  The JavaScript runtime landscape is fragmented. Deno and Bun have different APIs for common operations:
117  
118  [cols="1,1,1"]
119  |===
120  | Operation | Deno | Bun
121  
122  | Read file | `Deno.readTextFile()` | `Bun.file().text()`
123  | Write file | `Deno.writeTextFile()` | `Bun.write()`
124  | Subprocess | `Deno.Command` | `Bun.spawn`
125  | FFI | `Deno.dlopen` | Native Zig imports
126  |===
127  
128  bundeno abstracts these differences so your code works everywhere.
129  
130  == Architecture
131  
132  [source]
133  ----
134  ┌─────────────────────────────────────────────┐
135  │                Your Code                     │
136  └─────────────────────────────────────────────┘
137                        │
138                        ▼
139  ┌─────────────────────────────────────────────┐
140  │              bundeno API                     │
141  │  (fs, process, sqlite, ffi, ...)            │
142  └─────────────────────────────────────────────┘
143                        │
144           ┌────────────┴────────────┐
145           ▼                         ▼
146  ┌─────────────────┐       ┌─────────────────┐
147  │   Deno Native   │       │   Bun Native    │
148  │   Deno.*        │       │   Bun.*         │
149  └─────────────────┘       └─────────────────┘
150  ----
151  
152  == Roadmap
153  
154  See link:ROADMAP.adoc[ROADMAP.adoc] for planned features.
155  
156  * **v0.1** — Foundation (fs, process, runtime detection)
157  * **v0.2** — Extended APIs (SQLite, WebSocket, Crypto)
158  * **v0.3** — Zig Native (shared FFI libraries)
159  * **v1.0** — Stable API, full test coverage
160  
161  == Contributing
162  
163  See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for guidelines.
164  
165  == License
166  
167  AGPL-3.0-or-later. See link:LICENSE.txt[LICENSE.txt].
168  
169  == Related Projects
170  
171  * https://deno.land[Deno] — Secure runtime for JavaScript and TypeScript
172  * https://bun.sh[Bun] — Fast all-in-one JavaScript runtime
173  * https://wintercg.org[WinterCG] — Web-interoperable Runtimes Community Group
174  * https://github.com/hyperpolymath/bunsenite[bunsenite] — Nickel configuration parser (sibling project)