Embeddable code snippetsDelivered 2025-01-23
The editor snippets on the EYG homepage and in the documentation page can be edited and executed. This is very helpful when explaining concepts as they can immediately be played with.
The snippets are Lustre components and can only be used in Lustre apps. I want all features of EYG, the language and runtime, to be widely available. Therefore it should be possible to use the same style of code snippet in other webpages.
Done when an interactive snippet can be embedded in any HTML using a script tag.
Example code in the shellDelivered 2025-01-14
To help users get started have a selection of examples that can be loaded into the shell.
This previously existed in an earlier iteration of the shell.
Done when when a selection of code examples are presented in the empty shell.
Stable AST formatPending
The Abstract Syntax Tree (AST) has been effectively stable for a long time, only small changes to the set of builtin functions have happened.
A goal of EYG is that any program will continue to work indefinitely. This promise requires that all changes to the AST are conducted in a backwards compatible way.
The shallow effect handler will be removed to have only a single kind of effect handler in the AST. Currently deep and shallow handlers are supported only because of previous exploratory work. A stable encoding of the AST is required to give stable hash references
Done when all programs are saved with a version identifier for the format.
Open source license decisionPending
The whole EYG project is currently unlicensed, this needs to change to enable contributions which have already been submitted.
The reason to not use a fully open license is to protect the process of name resolution. This is because I want EYG to be embedded in lots of places and behave the same way, including named reference lookup. i.e. @bank should always point to the same code otherwise it's a security risk for users. Other than that I intend for everything to be available.
I should consider if different parts of the project need different licensing, but I would like to avoid that.
Done when all repos have a license file.
Stable content address for expressionsPending
Code can be referenced by name (@) or hash (#). EYG source is saved as JSON which means that the hash is not stable. This is not currently an issue because published code is stored immutably in the database with the hash acting as an opaque identifier.
To use the hash as a checksum and enable signing of package publishing the hash format needs to be stable.
Use DAG-JSON as the storage and hashing format for the AST.
This format enables storing EYG code on IPFS and building towards a decentralised package management solution.
Done when hashing is deterministic for a given expression.
Editor for large programsPending
The current editor is also a shell. It is optimised for quickly writing and running small programs.
There should be an editing environment optimised for creating and subsequently modifying larger programs. several of the early iterations were optimised for this kind of editing but not built on the latest structural edit library code
This environment would use more screen for the code and make collapsing/expanding code easy to focus within a large program. Saving and loading code from a host computer would be supported, instead of relying on the current approach of copy/paste. It would not have the ability to run any effectful code and would not keep a history of code runs. Running pure code might still be useful for integration with tests or similar.
Done when loading, editing and saving larger programs is easy.
Sign package releasePending
There should be a way for consumers to receive updates to their dependencies without relying on the authority of EYG. This is foundational for building resiliance to supply-chain attack.
Users register keys to their account which they use for signing package releases. EYG will centrally validate that all new releases are signed with a valid user key. A consumer application will be able to verify all releases have a valid signature.
Done when all new relases have signatures validated against account public keys.
Generalised effects in single functionPending
External effects currently unify to the same type, when used in the same function. This behaviour is too constrained for some effects. For example the Abort effect does not resume and so it's reply type should remain generalised across use in a single function.
This unification behaviour would allow all builtins to be replaced with effects. Moving builtins to effects would allow checking to see if a program uses them and remove them from the compiled artifact if not. Removing the builtins should be a separate task.
Done when effects that do not resume can remain general in the same function.
Structural code diffsPending
There is currently no way to see diffs between two EYG expressions. Providing a diff is a quality of life improvement that will become more important as programs grow.
Tree diffing is a solved problem, however there are choices to be made around presentation of the diffs. The Difftastic project is a good inspiration for how this can look.
Done when when two expressions can visually be compared.
Collapsible value components.Pending
All values are printed in the same way. Large values are truncated which makes working with them difficult
The browser is a rich environment that can be utilised for creating interactive views on values. For inspiration here consider how large objects are printed in the JavaScript console.
Done when large runtime values can be rendered and a user can interact with them.
Native runtimePending
The current interpreter is implemented in JavaScript and can used in the shell using the npm package.
writing a native interpreter that could be used to build an installable binary would make use in the shell easier.
A native version should also improve performance. A language with good WASM support should be picked so that the performance improvement can also be leveraged in the web environment. I know Rust is sufficient for the job from working on the Gleam compiler that is fast and can run in the browser via a WASM build. The interpreter is a small program and Zig is an interesting option.
Done when a single binary can be installed to run EYG programs.
Property test editor navigationPending
Write tests to ensure that in all cases navigation is consistent.
The behaviour of the editor is already understood: Left then right navigation should always return to the same node if on a leaf node. Left or right navigation should go to a child if starting on a non-leaf node.
Implementing property tests for these expectations would help handle the large number of edge cases.
Done when the listed navigation properties are tested.