Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt

Use this file to discover all available pages before exploring further.

This section was copied from existing reviewed documentation. Source: docs/replicated/daml/3.4/sdk/component-howtos/application-development/daml-codegen-javascript.rst Reviewers: Skip this section. Remove markers after final approval.

​
Daml Codegen for JavaScript

Use the Daml Codegen for JavaScript (dpm codegen-js) to generate JavaScript/TypeScript code representing all Daml data types defined in a Daml Archive (.dar) file. The generated code makes it easier to construct types and work with JSON when using the JSON Ledger API. See Get started with Canton and the JSON Ledger API for details on how to use the generated code to interact with JSON Ledger API. See the sections below for guidance on setting up and invoking the codegen.

​
Install

Install the Daml Codegen for JavaScript by installing DPM.

​
Configure

To configure the Daml Codegen, choose one of the two following methods:
  • Command line configuration: Specify all settings directly in the command line.
  • Project file configuration: Define all settings in the daml.yaml file.

​
Command line configuration

To view all available command line configuration options for Daml Codegen for JavaScript, run dpm codegen-js --help in your terminal: 
DAR-FILES                DAR files to generate TypeScript bindings for
-o DIR                   Output directory for the generated packages
-s SCOPE                 The NPM scope name for the generated packages;
                         defaults to daml.js
-h,--help                Show this help text

​
Project file configuration

Specify the above settings in the codegen element of the Daml project file daml.yaml. Here is an example: sdk-version: 3.4.9 name: quickstart source: daml init-script: Main:initialize parties:
  • Alice
  • Bob
  • USD_Bank
  • EUR_Bank version: 0.0.1 exposed-modules:
  • Main dependencies:
  • daml-prim
  • daml-stdlib codegen: js: output-directory: ui/daml.js npm-scope: daml.js

​
Operate

Run the Daml Codegen using project file configuration with: $ dpm codegen-js or using command line configuration with: $ dpm codegen-js ./.daml/dist/quickstart-0.0.1.dar -o ui/daml.js -s daml.js

​
References

​
Generated JavaScript/TypeScript code

​
Daml primitives to TypeScript

Daml built-in types are translated to the following equivalent types in TypeScript. The TypeScript equivalents of the primitive Daml types are provided by the @daml/types. Interfaces:
  • interface Template<T extends object, K = unknown, I extends string = string>
  • interface Choice<T extends object, C, R, K = unknown>
Types:
DamlTypeScriptTypeScript definition
()Unit{}
BoolBoolboolean
IntIntstring
DecimalDecimalstring
Numeric νNumericstring
TextTextstring
TimeTimestring
PartyPartystring
[τ]List<τ>τ[]
DateDatestring
ContractId τContractId<τ>string
Optional τOptional<τ>null | (null extends τ ? [] | [Exclude<τ, null>] : τ)
TextMap τTextMap<τ>{ [key: string]: τ }
(τ₁, τ₂)Tuple₂<τ₁, τ₂>{_1: τ₁; _2: τ₂}
The types given in the TypeScript column are defined in @daml/types.
For n-tuples where n ≥ 3, representation is analogous with the pair case (the last line of the table).
The TypeScript types Time, Decimal, Numeric and Int all alias to string. These choices relate to the avoidance of precision loss under serialization over the JSON Ledger API.
The TypeScript definition of type Optional<τ> in the above table might look complicated. It accounts for differences in the encoding of optional values when nested versus when they are not (i.e. “top-level”). For example, null and "foo" are two possible values of Optional<Text> whereas, [] and ["foo"] are two possible values of type Optional<Optional<Text>> (null is another possible value, [null] is not).

​
Generated TypeScript mappings

The mappings from user-defined data types in Daml to TypeScript are best explained by example.
Records (a.k.a. product types)
In Daml, we might model a person like this. 
data Person =
  Person with
    name: Text
    party: Party
    age: Int
Given the above definition, the generated TypeScript code will be as follows. 
type Person = {
  name: string;
  party: damlTypes.Party;
  age: damlTypes.Int;
}
Variants (a.k.a. sum types)
This is a Daml type for a language of additive expressions. 
data Expr a =
    Lit a
  | Var Text
  | Add (Expr a, Expr a)
In TypeScript, it is represented as a discriminated union. 
type Expr<a> =
  |  { tag: 'Lit'; value: a }
  |  { tag: 'Var'; value: string }
  |  { tag: 'Add'; value: Tuple2<Expr<a>, Expr<a>> }
Sum of products
Let’s slightly modify the Expr a type of the last section into the following. 
data Expr a =
    Lit a
  | Var Text
  | Add {lhs: Expr a, rhs: Expr a}
Compared to the earlier definition, the Add case is now in terms of a record with fields lhs and rhs. This renders in TypeScript like so. 
type Expr<a> =
  |  { tag: 'Lit'; value: a }
  |  { tag: 'Var'; value: string }
  |  { tag: 'Add'; value: Expr.Add<a> }

namespace Expr {
  type Add<a> = {
    lhs: Expr<a>;
    rhs: Expr<a>;
  }
}
Note how the definition of the Add case has given rise to a record type definition Expr.Add.
Enums
Given a Daml enumeration like this, 
data Color = Red | Blue | Yellow
the generated TypeScript will consist of a type declaration and the definition of an associated companion object. 
type Color = 'Red' | 'Blue' | 'Yellow'

const Color:
  damlTypes.Serializable<Color> & {
  }
& { readonly keys: Color[] } & { readonly [e in Color]: e };
Templates and Choices
Here is a Daml template of a basic ‘IOU’ contract. 
template Iou
  with
    issuer: Party
    owner: Party
    currency: Text
    amount: Decimal
  where
    signatory issuer
    choice Transfer: ContractId Iou
      with
        newOwner: Party
      controller owner
      do
        create this with owner = newOwner
The dpm codegen-js command generates types for each of the choices defined on the template as well as the template itself. 
type Transfer = {
  newOwner: damlTypes.Party;
}

type Iou = {
  issuer: damlTypes.Party;
  owner: damlTypes.Party;
  currency: string;
  amount: damlTypes.Numeric;
}
Each template results in the generation of an interface and a companion object. Here, is a schematic of the one generated from the Iou template1,2. 
interface IouInterface {
  Archive: damlTypes.Choice<Iou, DA.Internal.Template.Archive, {}, undefined> & damlTypes.ChoiceFrom<damlTypes.Template<Iou, undefined>>;
  Transfer: damlTypes.Choice<Iou, Transfer, damlTypes.ContractId<Iou>, undefined> & damlTypes.ChoiceFrom<damlTypes.Template<Iou, undefined>>;
}

const Iou:
  damlTypes.Template<Iou, undefined, '&lt;template_id&gt;'> &
  damlTypes.ToInterface<Iou, never> &
  IouInterface;
See the Use contracts and transactions in JavaScript for details on how to use generated code to interact with the JSON Ledger API.

Footnotes

  1. The undefined type parameter captures the fact that Iou has no contract key. ↩
  2. The never type parameter captures the fact that Iou does not implement directly any interface. ↩