This repository contains a TypeScript implementation for (parts of) the LionWeb specification – specifically: release version 2023.1 of the LionWeb specification.
Note that this repo doesn't implement the specification completely. In particular:
utilities
and validation
packages is provided “as-is”.The implementation of the JSON serialization format, serialization from in-memory representations to that format, and vice versa, are all pretty solid.
The implementation is divided up in a number of NPM packages in the directory packages
(in order of importance):
core
The "core stuff" such as: base types, the LionCore M3 (including the builtins
language), and (de-)serialization.utilities
Utilities on top of the core
packages that might be broadly useful, but should not go into the core
package.validation
Validators that validate a JSON serialization.test
A package containing (unit) tests for the packages above.cli
A package with an executable to trigger some of the functionality in utilities
through a commandline interface (CLI), i.e. from the commandline.artifacts
A package that generates artifacts (serialization chunks, diagrams, JSON Schemas) from some of the models constructed in the core
and test
packages.Each of these packages have their own README.md
.
The core
, utilities
, cli
, and validation
packages are published in the scope of the lionweb
organization, meaning that they're all prefixed with @lionweb/
.
The other packages are for internal use only.
All these packages declare their own NPM semver identification, which isn't directly related to the release version of the LionWeb specification.
This repo relies on the following tools being installed:
Note that development tends to be done against the latest LTS (or even more recent) versions of Node.js and NPM.
Run the following command to setup the project:
npm run clean
npm install
npm run setup
Run the following command to build each of the packages:
# Build the project
npm run build
This includes cleaning up and installing any NPM (dev) dependencies.
The preceding commands can also be run as follows:
npm run initialize
The following command statically style-checks the source code in all the packages:
# Run lint
npm run lint
Note that this does not catch TypeScript compilation errors! (That's because linting only does parsing, not full compilation.)
Run the following command to run the tests:
# Run the tests
npm run test
The output should look similar to this (but much longer):
To keep the version numbers of the various packages under packages/
aligned throughout this repository, you can use the Node.js script update-package-versions.js
.
You execute this script as follows from the repo's root:
node update-package-versions.js
This reads the file packages/versions.json
and updates the package.json
files of all packages under packages/
according to it.
This script runs npm install
afterward to update the package-lock.json
.
Inspect the resulting diffs to ensure correctness, and don't forget to run npm install
to update the package-lock.json
in case you made corrections.
Packages are released to the npm registry (website): see the badges at the top of this document.
We'll use the terms “release/releasing” from now on, instead of “publication/publishing” as npm itself does.
We only release the following packages: core
, validation
, utilities
, cli
.
Releasing a package involves the following steps:
package.json
.
package.json
in the other packages.npm run initialize
to update package-lock.json
and catch any (potential) problems.main
branch — if necessary, through a PR.release
script of the package:
npm run release
This requires access as a member of the lionweb
organization on the npm registry — check whether you can access the packages overview page.
This step also requires a means of authenticating with npm, e.g. using the Google Authenticator app.
<package>-<version>
, and push the tag.0.7.0-beta.0
.
npm run initialize
to update package-lock.json
again.main
branch — if necessary, through a PR.Note that beta releases are different in a couple of ways:
<semver>-beta.<beta sequence number>
, e.g.: 0.7.0-beta.0
.release-beta
scripts.Releasing all (releasable) packages at the same time can be done through the top-level release
script.
If you do that, you can perform the manual steps above all at the same time, which might save time and commits.
Currently, we're not using a tool like changesets
– including its CLI tool – to manage the versioning and release/publication.
That might change in the (near-)future, based on experience with using changesets
for the LionWeb repository implementation.
All the code in this repository is written in TypeScript, with the following code style conventions:
Indentation is: 4 spaces.
No semicolons (;
s).
This is slightly controversial, but I (=Meinte Boersma) simply hate semicolons as a statement separator that's virtually always unnecessary.
The TypeScript compiler simply adds them back in the appropriate places when transpiling to JavaScript.
Use "FP-lite", meaning using Array.map
and such functions over more imperative ways to compute results.
We use prettier with parameters defined in .prettierrc
.
Note that currently we don't automatically run prettier
over the source code.
If you prefer not to install the development dependencies on your machine, you can use our containerized development environment for the LionCore TypeScript project. This environment provides a consistent and isolated development environment that is easy to set up and use. To get started, follow the instructions in our containerized development environment guide. However, you can streamline the process by running the following command:
docker run -it --rm --net host --name working-container -v ${PWD}:/work indamutsa/lionweb-devenv:v1.0.0 /bin/zsh
docker run
: Initiates a new container.-it
: Enables interactive mode with a pseudo-TTY.--rm
: Removes container after exit.--net host
: Shares the host's network.--name working-container
: Names the container.-v ${PWD}:/work
: Maps host's current directory to /work
in the container.indamutsa/lionweb-devenv:v1.0.0
: Specifies the Docker image./bin/zsh
: Starts a Zsh shell inside the container.We're happy to receive feedback in the form of