54 lines
4.2 KiB
Markdown
54 lines
4.2 KiB
Markdown
---
|
|
tags: adr
|
|
status: accepted
|
|
date: "2024-10-03"
|
|
deciders: "[[Zef Hemel]]"
|
|
owner: "[[Zef Hemel]]"
|
|
lastReviewed: "2026-06-19"
|
|
related:
|
|
- "[[ADR/003 Indexed Object Graph]]"
|
|
references:
|
|
- client/space_lua.ts
|
|
- client/space_lua/runtime.ts
|
|
- client/space_lua/parse.ts
|
|
---
|
|
# Context
|
|
SilverBullet lets users put dynamic content: live queries, computed views, templated rendering, and custom logic directly in their pages. In v1 this was spread across **three separate mechanisms**, each with its own syntax:
|
|
|
|
* a custom **query language** for live queries (originally HTML-comment "directives");
|
|
* **Handlebars-style templates** (Live Templates, Live Template Widgets, Page Templates) for rendering;
|
|
* **Space Script**, a **JavaScript** layer, for custom functions and logic.
|
|
|
|
Three languages to learn and maintain, with awkward seams between them (a query feeding a Handlebars template feeding a JS function).
|
|
|
|
# Decision
|
|
Adopt **Lua** as a single embedded language ([[Space Lua]]) that unifies scripting, templating, and querying:
|
|
|
|
* `space-lua` code blocks define space-wide functions and config;
|
|
* `${...}` expressions render inline via [[Live Preview]], replacing Handlebars templates;
|
|
* **Space Lua Integrated Query (SLIQ)** — `${query[[ from ... select ... ]]}` replaces the old query language; because the body after `from` is a Lua expression, it can query the [[Object Index|object index]] *or* any Lua table.
|
|
|
|
[[Space Lua]] is a **custom, from-scratch implementation** — not the official [Lua](https://www.lua.org) or [LuaJIT](https://luajit.org), nor a WebAssembly build of them — largely Lua-5.4-compatible with a few non-standard additions. It replaced Space Script (JS) and the v1 template/query mechanisms.
|
|
|
|
Writing our own interpreter (for partly historical reasons) bought a very smooth interoperability story: friction-free access to a lot of SilverBullet and browser functionality, and deep enough integration with the Lua runtime to support editor features like code completion and jump-to-definition. It also opened the path to develop SilverBullet-specific language extensions, specifically [[Space Lua/Integrated Query]] that otherwise would have been impossible.
|
|
|
|
# Consequences
|
|
## Positive
|
|
* **One language instead of three.** Queries, templates, and scripting share one syntax and runtime — far less to learn and maintain.
|
|
* **Composable.** A query can call a template function in its `select`, and expressions can call space-wide functions — no seams between separate engines.
|
|
* **Embeddable and safe.** Lua is small and designed to be embedded and sandboxed — a better fit than JavaScript for user code running inside the app.
|
|
* **Deep, friction-free integration.** Because the interpreter is our own rather than a black-box VM, Lua interoperates smoothly with SilverBullet and browser APIs, and the runtime can power editor features like (some) code completion and jump-to-definition.
|
|
|
|
## Negative / trade-offs
|
|
* **A custom Lua dialect to maintain.** Space Lua is its own implementation, with ongoing work to track Lua 5.4 semantics.
|
|
* **Less familiar than JavaScript.** Most web developers know JS, not Lua — a higher initial learning curve (offset by Lua's small surface).
|
|
* **Migration cost.** This shift was a hard breaking change transitioning from v1 to v2, and spaces using directives / Handlebars / Space Script had to be ported. We likely lost users over this, see [[Migrate from v1]].
|
|
|
|
# Alternatives considered
|
|
* **Keep JavaScript (Space Script) + Handlebars + the old query language.** Rejected: three languages and the seams between them, and JS is awkward to sandbox safely for in-space user code.
|
|
* **Embed an existing Lua (a WebAssembly build, Fengari, or LuaJIT).** Rejected: a from-scratch implementation gives a far smoother interoperability story with SilverBullet and browser functionality, and allows the deep runtime integration (code completion, jump-to-definition) a black-box VM would not, it also allowed to repurpose Lua for [[Space Lua/Integrated Query]].
|
|
|
|
# References
|
|
* First Lua integration: [commit 3cf7b72e](https://github.com/silverbulletmd/silverbullet/commit/3cf7b72e) (2024-10).
|
|
* [[Space Lua]] · [[Space Lua/Integrated Query]] · [[Migrate from v1]] — what changed from directives / Handlebars / Space Script.
|