Skip to content

feat(typescript): @diaryx/twig, TypeScript bindings over twig compiled to WebAssembly - #17

Merged
adammharris merged 5 commits into
mainfrom
ts-bindings
Oct 21, 2026
Merged

adammharris merged 5 commits into
mainfrom
ts-bindings

Conversation

@adammharris

Copy link
Copy Markdown
Member

Adds @diaryx/twig, TypeScript bindings for twig, built the way fig builds @diaryx/fig.

What changes

  • bindings/typescript (new npm package). twig-capi is compiled for wasm32-unknown-unknown with every language twig ships and inlined as base64 (1.3 MiB module, 1.8 MiB as base64). It loads lazily, or with await init() on a browser main thread, and imports nothing. The API:
    • Document: parse (format by code or name, Markdown flags), renderHtml, serialize (convert), diagnostics, ast, query, nodes (flat tree), children, nodeAt/nodesAt.
    • Editor: locator edits (replace, insertBefore/After/Child, delete, unwrap, moveBefore/After, filter), editRange, undo/redo, revision, and a live document() view.
    • Metadata: metadata(at) (lang, spans, body), metadataValue(at) (the body as data), Editor#setMetadata(body, { at, lang }). Front and end blocks and HTML <script type="application/…"> islands (feat(meta): read and edit a document's HTML <script> data island #16). To keep comments, edit the body with @diaryx/fig. A test does this round trip with the published fig 7 packages.
    • One-call helpers: renderHtml, convert, parseAst, readMetadata, metadataValue, setMetadata.
  • C ABI (additive, TWIG_ABI_VERSION stays 6): twig_document_metadata, twig_document_metadata_json, twig_editor_set_metadata, twig_alloc, twig_free. twig-capi now also asserts the wasm32 struct layouts the package reads. A wasm cargo profile is added.
  • Core: Embed::set_body and Embed::open_or_init_with. open_or_init could not write a new JSON block, because an empty body is not valid JSON.
  • Versioning and release: the package takes the workspace version. ship's post_bump runs scripts/version-sync.mjs, and new version and typescript ship jobs check it. CI gets a typescript job. release-npm.yml publishes on a v* tag.
  • Docs: docs/typescript.md (made with prov new; it is also the npm README), plus README and RELEASING.

Verified

  • ship ci: all 5 jobs pass (test, cli-wasi, capi with the new C header checks, version, typescript 19/19).
  • cargo test -p twig-doc --no-default-features passes.
  • I checked the built dist/ loads without the source condition, and that npm pack --dry-run has the expected contents.

Not done here

  • Nothing is published. The NPM_TOKEN secret is not set on this repo, and nobody has claimed @diaryx/twig on npm yet.
  • I tested on Node 26 only. The tests need Node 24 or later; I did not run the package on Node 22, Bun, Deno or a browser.

Embed::set_body takes a body edited outside fig's Rust editor (fig's TypeScript one, say) and render splices it in. Embed::open_or_init_with opens a new block on a given body rather than empty, which a JSON block needs: an empty body is not a JSON document, so open_or_init could never write a new JSON block.
twig_document_metadata locates a document's front or end metadata block (or an HTML page's <script> data island), twig_document_metadata_json reads its body as JSON through fig, and twig_editor_set_metadata replaces the body, or writes a new front block, as one splice and one undo step. twig_alloc and twig_free let a caller outside the library's memory, the WebAssembly build driven from JavaScript, place its input. All additive, so TWIG_ABI_VERSION stays 6.

The workspace gains a size-first `wasm` profile for the module @diaryx/twig inlines, and twig-capi asserts the wasm32 struct layouts that package reads.
…Script and JavaScript

bindings/typescript is a new npm package, built as fig's @diaryx/fig is: twig-capi compiled for wasm32-unknown-unknown with every language twig ships, inlined as base64, and loaded lazily (or with init() on a browser main thread). It wraps parsing, rendering, conversion and its diagnostics, queries, the flat tree and hit tests, the lossless editor with undo, and a document's metadata: located, read as data, and replaced, with @diaryx/fig for edits that keep comments.

The package takes the workspace's version: ship's post_bump writes it in with scripts/version-sync.mjs, and the new `version` job checks it. A `typescript` job builds and tests the package, in ship ci and in CI, and release-npm.yml publishes it on a v* tag. The guide is docs/typescript.md.
…() was pending

init() replaced the module's exports when its compile resolved, even if a synchronous call had already made an instance. Handles made before then live in the first instance's memory, so the next call on one ran against the second and trapped. The first instance now stays, and a test in a process of its own covers the mix.
…at does not parse

twig::meta::replace_body replaces a block's whole body without parsing the old one, so it repairs a block whose body does not parse, and reparses the host to check the block reads the new body back. A body that parses as its language but holds the block's closing fence (TOML's +++ inside a multi-line string) would have ended the block early and left the rest as document text; it is Error::BodyEscapesBlock now, and nothing changes. Embed::open_with opens a block on a new body. twig_editor_set_metadata goes through replace_body and reports the new refusal as TWIG_STATUS_UNSAFE_METADATA.
@adammharris
adammharris merged commit 8ae7605 into main Oct 21, 2026
5 checks passed
@adammharris
adammharris deleted the ts-bindings branch October 30, 2026 01:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant