> ## 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.

# JavaScript Codegen

> Generate JavaScript/TypeScript bindings from Daml interfaces and templates.

# 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:

```none theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**:

| Daml           | TypeScript       | TypeScript definition                                     |
| -------------- | ---------------- | --------------------------------------------------------- |
| `()`           | `Unit`           | `{}`                                                      |
| `Bool`         | `Bool`           | `boolean`                                                 |
| `Int`          | `Int`            | `string`                                                  |
| `Decimal`      | `Decimal`        | `string`                                                  |
| `Numeric ν`    | `Numeric`        | `string`                                                  |
| `Text`         | `Text`           | `string`                                                  |
| `Time`         | `Time`           | `string`                                                  |
| `Party`        | `Party`          | `string`                                                  |
| `[τ]`          | `List<τ>`        | `τ[]`                                                     |
| `Date`         | `Date`           | `string`                                                  |
| `ContractId τ` | `ContractId<τ>`  | `string`                                                  |
| `Optional τ`   | `Optional<τ>`    | `null \| (null extends τ ? [] \| [Exclude<τ, null>] : τ)` |
| `TextMap τ`    | `TextMap<τ>`     | `{ [key: string]: τ }`                                    |
| `(τ₁, τ₂)`     | `Tuple₂<τ₁, τ₂>` | `{_1: τ₁; _2: τ₂}`                                        |

<Note>
  The types given in the **TypeScript** column are defined in @daml/types.
</Note>

<Note>
  For *n*-tuples where *n ≥ 3*, representation is analogous with the pair case (the last line of the table).
</Note>

<Note>
  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.
</Note>

<Note>
  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**).
</Note>

#### 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.

```haskell theme={"theme":{"light":"github-light","dark":"github-dark"}}
data Person =
  Person with
    name: Text
    party: Party
    age: Int
```

Given the above definition, the generated TypeScript code will be as follows.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```haskell theme={"theme":{"light":"github-light","dark":"github-dark"}}
data Expr a =
    Lit a
  | Var Text
  | Add (Expr a, Expr a)
```

In TypeScript, it is represented as a discriminated union.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```haskell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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,

```haskell theme={"theme":{"light":"github-light","dark":"github-dark"}}
data Color = Red | Blue | Yellow
```

the generated TypeScript will consist of a type declaration and the definition of an associated companion object.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```haskell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` template[^1],[^2].

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

[^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.