While the milestone technically requires Javascript support, we implemented Typescript support which is a typed superset of Javascript. This was done to better interpolate with existing Javascript/Typescript libraries on Cardano such as lucid, cardano-js-sdk, cardano-serialization-lib, etc. With Typescript support, we get Javascript support for free as the compilation from Typescript to Javascript is a well established practise.
+A LambdaBuffers code generation module that outputs type constructors and derived implementations in the Javascript programming language given a LambdaBuffers schema.
+A Javascript library that implements the LambdaBuffers Prelude runtime. +This module would include standardised JSON encoding and equality +implementations for all declared type class instances in the schema. +- A standalone Prelude library for Typescript was implemented together with +its runtime for LambdaBuffers. These can be found here: +- prelude-typescript +- runtimes/typescript/lbr-prelude
+A Javascript test suite that assures the manually implemented and automatically generated implementations are consistent with the predefined LambdaBuffers Prelude golden data set of JSON files and perform correct implementation derivation. +- A test suite ensuring that the manually implemented and automatically generated implementations can be found here: testsuites/lbt-prelude/lbt-prelude-typescript.
+A Javascript library that implements the LambdaBuffers Plutus runtime. This module would include standardised PlutusData encoding implementations for all declared type class instances in the Plutus schema. +- A standalone Plutus library for Typescript was implemented together with +its runtime for LambdaBuffers. These can be found here:
- [plutus-ledger-api-typescript](https://github.com/mlabs-haskell/plutus-ledger-api-typescript) + + - [runtimes/typescript/lbr-plutus](https://github.com/mlabs-haskell/lambda-buffers/tree/dc5ee6797d1230661d6bb3dfa658eddeadd7cb60/runtimes/typescript/lbr-plutus) +
+A Javascript test suite that assures the manually implemented and automatically generated implementations are consistent with the predefined LambdaBuffers Plutus golden data set of PlutusData encoded files and perform correct implementation derivation. +- A test suite ensuring that the manually implemented and automatically generated implementations can be found here: testsuites/lbf-plutus/lbf-plutus-typescript
+Nix devops modules (Nix API) for streamlining the LambdaBuffers code generation pipeline to Javascript. +- New flake modules were implemented to easily generate NPM packages from LambdaBuffers +- lbf-typescript +- lbf-prelude-typescript +- lbf-plutus-typescript
+Documentation on LambdaBuffers usage patterns for Javascript. +- A new page was created for the TypeScript use case
Like with product types, they become Rust struct with named fields.
struct
All types and their fields are public, allowing to manipulate them without accessors.
This chapter will walk through a translation from a LambdaBuffers' module into a Typescript module.
To demonstrate this, we will use the lbf-prelude-to-typescript CLI tool which is just a convenient wrapper over the raw lbf CLI. +To this end, we may enter a development shell which provides this tool along with many other Lambda Buffers CLI tools with the following command.
lbf-prelude-to-typescript
lbf
$ nix develop github:mlabs-haskell/lambda-buffers#lb +$ lbf<tab> +lbf lbf-plutus-to-haskell lbf-plutus-to-rust lbf-prelude-to-haskell lbf-prelude-to-rust +lbf-list-modules-typescript lbf-plutus-to-purescript lbf-plutus-to-typescript lbf-prelude-to-purescript lbf-prelude-to-typescript + +
Or, we may directly refer to the lbf-prelude-to-typescript CLI with the following command.
nix run github:mlabs-haskell/lambda-buffers#lbf-prelude-to-typescript +
In this chapter, we will use the former option.
Consider the Document.lbf schema which we may recall is as follows.
module Document + +-- Importing types +import Prelude (Text, List, Set, Bytes) + +-- Author +sum Author = Ivan | Jovan | Savo + +-- Reviewer +sum Reviewer = Bob | Alice + +-- Document +record Document a = { + author : Author, + reviewers : Set Reviewer, + content : Chapter a + } + +-- Chapter +record Chapter a = { + content : a, + subChapters : List (Chapter a) + } + +-- Some actual content +sum RichContent = Image Bytes | Gif Bytes | Text Text + +-- Rich document +prod RichDocument = (Document RichContent) +
We generate the corresponding Typescript code with the following commands.
$ nix develop github:mlabs-haskell/lambda-buffers#lb +$ lbf-list-modules-typescript lbf-document=. > lb-pkgs.json +$ lbf-prelude-to-typescript --gen-opt="--packages lb-pkgs.json" Document.lbf +$ find autogen/ +autogen/ +autogen/LambdaBuffers +autogen/LambdaBuffers/Document.mts +autogen/build.json +
The generated autogen directory created contains the generated Typescript modules.
autogen
Note that lbf-list-modules-typescript is needed to create a JSON object which maps package names (for NPM) to Lambda Buffers' modules. +Thus, in this example, one should have a package.json file which associates the key "name" with the string value "lbf-document".
lbf-list-modules-typescript
package.json
"name"
"lbf-document"
The autogen/build.json file can be ignored.
autogen/build.json
The file autogen/LambdaBuffers/Document.mts contains the outputted Typescript module:
autogen/LambdaBuffers/Document.mts
// @ts-nocheck +import * as LambdaBuffers$Document from './Document.mjs' +import * as LambdaBuffers$Prelude from './Prelude.mjs' + +export type Author = | { name : 'Ivan' } + | { name : 'Jovan' } + | { name : 'Savo' } +export const Author : unique symbol = Symbol('Author') +export type Chapter<$a> = { content : $a + , subChapters : LambdaBuffers$Prelude.List<Chapter<$a>> + } +export const Chapter : unique symbol = Symbol('Chapter') +export type Document<$a> = { author : Author + , reviewers : LambdaBuffers$Prelude.Set<Reviewer> + , content : Chapter<$a> + } +export const Document : unique symbol = Symbol('Document') +export type Reviewer = | { name : 'Bob' } | { name : 'Alice' } +export const Reviewer : unique symbol = Symbol('Reviewer') +export type RichContent = | { name : 'Image' + , fields : LambdaBuffers$Prelude.Bytes + } + | { name : 'Gif' + , fields : LambdaBuffers$Prelude.Bytes + } + | { name : 'Text' + , fields : LambdaBuffers$Prelude.Text + } +export const RichContent : unique symbol = Symbol('RichContent') +export type RichDocument = Document<RichContent> +export const RichDocument : unique symbol = Symbol('RichDocument') +
The type RichDocument have been declared as a product type in the LambdaBuffers schema using the prod keyword.
RichDocument
prod
In general, product types are mapped to tuple types in Typescript most of the time. The exception is if there is only one element in the tuple in which case the type is translated to a type alias.
More precisely, given a LambdaBuffers' product type as follows
prod MyProduct = SomeType1 ... SomeTypeN +
where the ... denotes iterated SomeTypei for some i, then
...
SomeTypei
i
If N = 0 so prod MyProduct =, then we map this to the Typescript type
N = 0
prod MyProduct =
export type MyProduct = [] +
If N = 1 so prod MyProduct = SomeType1, then we map this to the Typescript type
N = 1
prod MyProduct = SomeType1
export type MyProduct = SomeType1 +
i.e., MyProduct simply aliases SomeType1
MyProduct
SomeType1
If N >= 2 so prod MyProduct = SomeType1 ... SomeTypeN, then we map this to the Typescript type
N >= 2
prod MyProduct = SomeType1 ... SomeTypeN
export type MyProduct = [SomeType1, ..., SomeTypeN] +
i.e., MyProduct is a tuple with a fixed number of elements with known types.
The types Author, Reviewer, and RichContent have been declared as sum types in the LambdaBuffers schema using the sum keyword.
Author
Reviewer
RichContent
sum
In general, sum types are mapped to a union type in Typescript and with the additional following rules. +Given a LambdaBuffers' sum type as follows
sum MySum + = Branch1 Branch1Type1 ... Branch1TypeM1 + | ... + | BranchN BranchNType1 ... BranchNTypeMN +
where the ... denotes either an iterated Branchi for some i, or an iterated BranchiTypej for some i and j, then each branch, say Branchi is translated as follows.
Branchi
BranchiTypej
j
If Branchi has no fields i.e., | Branchi, then the corresponding Typescript type's union member is
| Branchi
| { name: 'Branchi' } +
If Branchi has one or more fields i.e., | Branchi BranchiType1 ... BranchiTypeMi, then the corresponding Typescript type's union member is
| Branchi BranchiType1 ... BranchiTypeMi
| { name: 'Branchi' + , fields: <Product translation of BranchiType1 ... BranchiTypeMi> + } +
where <Product translation of BranchiType1 ... BranchiTypeMi> denotes the right hand side of the product translation of prod FieldsProduct = BranchiType1 ... BranchiTypeMi.
<Product translation of BranchiType1 ... BranchiTypeMi>
prod FieldsProduct = BranchiType1 ... BranchiTypeMi
So, for example, given | Branchi BranchiType1, the corresponding Typescript type is as follows
| Branchi BranchiType1
| { name: 'Branchi' + , fields: BranchiType1 + } +
And given | Branchi BranchiType1 BranchiType2, the corresponding Typescript type is as follows.
| Branchi BranchiType1 BranchiType2
| { name: 'Branchi' + , fields: [BranchiType1, BranchiType2] + } +
The types Document and Chapter have been declared as record types in the LambdaBuffers schema using the record keyword.
Document
Chapter
record
Record types are mapped to object types in Typescript. +Given a LambdaBuffers' record type as follows
record MyRecord = { field1: SomeType1, ..., fieldN: SomeTypeN } +
where ... denotes iterated fieldi: SomeTypei for some i, the corresponding Typescript type is
fieldi: SomeTypei
type MyRecord = { field1: SomeType1, ..., fieldN, SomeTypeN } +
Typescript has no builtin implementation of type classes. As such, LambdaBuffers rolled its own type classes. +A complete usage example can be found in the Typescript Prelude sample project, but assuming the packaging is setup correctly, the interface to use a typeclass is as follows
import * as LbrPrelude from "lbr-prelude"; + +// In Haskell, this is `10 == 11` +LbrPrelude.Eq[LbrPrelude.Integer].eq(10n, 11n) // false + +// In Haskell, this is `Just 3 == Nothing` +LbrPrelude.Eq[LbrPrelude.Maybe](LbrPrelude.Eq[LbrPrelude.Integer]) + .eq( { name: 'Just', fields: 3 } + , { name: 'Nothing' }) // false +
In particular, we access a global variable LbrPrelude.Eq which contains the type class instances, and pick out a particular instance with the type's name like LbrPrelude.Integer. Note that the LbrPrelude.Maybe instance requires knowledge of the Eq instance of the LbrPrelude.Integer, so we must pass that in as a function argument.
LbrPrelude.Eq
LbrPrelude.Integer
LbrPrelude.Maybe
Eq
A type class in Typescript is an object type which defines a set of methods. +For example, the Eq type class in Haskell defines the set of methods == (equality) and /= (inequality) as follows.
==
/=
class Eq a where + (==) :: a -> a -> Bool + (/=) :: a -> a -> Bool +
The corresponding Eq class in Typescript is:
export interface Eq<A> { + readonly eq: (l: Readonly<A>, r: Readonly<A>) => boolean; + readonly neq: (l: Readonly<A>, r: Readonly<A>) => boolean; +} +
Each type class in Typescript must have an associated global variable which maps unique representations of its instance types to the corresponding object of the type class implementation. +For example, the Eq type class has the global variable defined in the lbr-prelude library defined as follows
export const Eq: EqInstances = { } as EqInstances +
where EqInstances is an interface type that is initially empty but will be extended with instances of types later.
EqInstances
export interface EqInstances { } +
Finally, the following invariant is maintained in the code generator:
T
So, the type Integer has
Integer
export type Integer = bigint +export const Integer: unique symbol = Symbol('Integer') +
and implementing its Eq instance amounts to the following code.
export interface EqInstances { + [Integer]: Eq<Integer> +} +Eq[Integer] = { eq: (l,r) => l === r + , neq: (l,r) => l !== r + } +
For types defined in the LambdaBuffers schema, this chunk of code will be automatically generated provided there is an appropriate derive construct.
derive
Recall in Haskell that the Eq instance for a tuple may be defined as follows
instance (Eq a, Eq b) => Eq (MyPair a b) where + MyPair a1 a2 == MyPair b1 b2 = a1 == b1 && a2 == b2 + MyPair a1 a2 != MyPair b1 b2 = a1 != b1 || a2 != b2 +
The corresponding Typescript type definition and instance would be defined as follows
export type MyPair<a, b> = [a, b] +export const MyPair: unique symbol = Symbol('MyPair') + +export interface EqInstances { + [MyPair]: <A,B>(a : Eq<A>, b : Eq<B>) => Eq<MyPair<A,B>> +} +Eq[MyPair] = (dictA, dictB) => { return { eq: (a,b) => dictA.eq(a[0], b[0]) && dictB.eq(a[1], b[1]) + , neq: (a,b) => dictA.neq(a[0], b[0]) || dictB.neq(a[1], b[1]) + } + } +
Note that the constraints (Eq a, Eq b) => become arguments dictA and dictB that are used to construct the Eq instance for MyPair.
(Eq a, Eq b) =>
dictA
dictB
MyPair
This loosely follows the original translation given in the paper How to make ad-hoc polymorphism less ad hoc with some minor modifications.
Only Haskell 2010 typeclasses are supported for the Typescript code generator. So, the following schemas will probably generate incorrect code.
derive Eq (MyPair a a) +derive Eq (MyMaybe (MyMaybe Integer)) +derive Eq (MyMaybe Integer) +
This repository relies heavily on the Nix Package @@ -2504,14 +2747,14 @@ Compariso
Types of the form Time = Present | Past | Future, which allow a type do be constructed by one of many variants. Think Rust's enums.
Time = Present | Past | Future
enums
Types of the form Person = MkPerson Age Name, where MkPerson is of Kind Type->Type->Type. Product types combine multiple elements into one data type without tagging the elements.
Person = MkPerson Age Name
MkPerson
Type->Type->Type
Types of the form Person = MkPerson { age :: Age, name :: Name }. Record types are similar to structs in most programming languages.
Person = MkPerson { age :: Age, name :: Name }
structs