feat: Typescript Native interface and Wrapper

[giorgiopiatti-dfinity]

Goal

The goal is to generate a typescript interface of a canister, which is more readable by AI models and follows Typescript standard types.

This introduces new functionality, is not changing existing functionality. It wraps the existing js/ts solution.

The new type mapping changes how optionals are mapped, instead of using arrays ([] for None and [Value] for Some(Value)) we use:

• T | null for bottom-most optional
• Optional<T> for nested optionals
• optionalProperty? as part of record definition e.g.
  interface { optionalProperty?: string; other: string; }

How to run

We expose 2 new target options to bind: ts-native-wrapperand ts-native-interface, which can be used:

• didc bind --target ts-native-interface example.did > example.d.ts
• didc bind --target ts-native-wrapper example.did > example.ts

How to run tests

The test are based on Typescript type checker, we check that the generated wrapper correctly translates data between the old interface and the new typescript interface. Currently the generation of the new interface is not part of the tests, as is similar to the old interface.

cd tests/typescript-native && ./test.sh <test-case>

where <test-case> is a .did file, currently we have recursive.did, example_1.did, small.did.

Future Extensions

• Add arguments names of candid functions. Motoko can now generate candid with named args see feat: preserve named types in semantic types and when translating between Motoko and Candid motoko#4943
• Add comments present in original file

[github-actions]

Name	Max Mem (Kb)	Encode	Decode
blob	4_224	20_459_040 ($\textcolor{green}{-0.00\%}$)	12_083_944
btreemap	75_456	4_686_454_551 ($\textcolor{green}{-0.00\%}$)	15_670_310_244 ($\textcolor{green}{-0.00\%}$)
nns	128	2_133_627 ($\textcolor{green}{-0.09\%}$)	5_790_336 ($\textcolor{green}{-0.31\%}$)
nns_list_proposal	1_088	7_754_219 ($\textcolor{green}{-0.37\%}$)	81_882_901 ($\textcolor{green}{-0.03\%}$)
option_list	128	7_944_439 ($\textcolor{red}{0.07\%}$)	26_139_091 ($\textcolor{red}{0.28\%}$)
text	6_336	20_455_272 ($\textcolor{green}{-0.00\%}$)	17_839_908
variant_list	128	7_938_028 ($\textcolor{red}{0.07\%}$)	24_705_708
vec_int16	16_704	168_582_026 ($\textcolor{green}{-0.00\%}$)	1_101_029_062

• Parser cost: 18_352_846 ($\textcolor{green}{-0.01\%}$)
• Extra args: 3_234_958 ($\textcolor{green}{-0.00\%}$)

Click to see raw report

---------------------------------------------------

Benchmark: blob
  total:
    instructions: 32.55 M (-0.00%) (change within noise threshold)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 20.46 M (-0.00%) (change within noise threshold)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 12.08 M (no change)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: text
  total:
    instructions: 38.30 M (-0.00%) (change within noise threshold)
    heap_increase: 99 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 20.46 M (-0.00%) (change within noise threshold)
    heap_increase: 66 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 17.84 M (no change)
    heap_increase: 33 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: vec_int16
  total:
    instructions: 1.27 B (-0.00%) (change within noise threshold)
    heap_increase: 261 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 168.58 M (-0.00%) (change within noise threshold)
    heap_increase: 261 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 1.10 B (no change)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: btreemap
  total:
    instructions: 20.36 B (-0.00%) (change within noise threshold)
    heap_increase: 1179 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 4.69 B (-0.00%) (change within noise threshold)
    heap_increase: 159 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 15.67 B (-0.00%) (change within noise threshold)
    heap_increase: 1020 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: option_list
  total:
    instructions: 34.09 M (0.23%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 7.94 M (0.07%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 26.14 M (0.28%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: variant_list
  total:
    instructions: 32.65 M (0.02%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 7.94 M (0.07%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 24.71 M (no change)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: nns
  total:
    instructions: 27.11 M (-0.08%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  0. Parsing (scope):
    instructions: 18.35 M (-0.01%) (change within noise threshold)
    heap_increase: 2 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 2.13 M (-0.09%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 5.79 M (-0.31%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: nns_list_proposal
  total:
    instructions: 89.64 M (-0.06%) (change within noise threshold)
    heap_increase: 17 pages (no change)
    stable_memory_increase: 0 pages (no change)

  1. Encoding (scope):
    instructions: 7.75 M (-0.37%) (change within noise threshold)
    heap_increase: 3 pages (no change)
    stable_memory_increase: 0 pages (no change)

  2. Decoding (scope):
    instructions: 81.88 M (-0.03%) (change within noise threshold)
    heap_increase: 14 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------

Benchmark: extra_args
  total:
    instructions: 3.23 M (-0.00%) (change within noise threshold)
    heap_increase: 0 pages (no change)
    stable_memory_increase: 0 pages (no change)

---------------------------------------------------
Successfully persisted results to canbench_results.yml

[luc-blaeser]

I like the clean idiomatic TS interface.
Maybe add the test that Nathan suggested

[giorgiopiatti-dfinity]

Depends on fix from #604