Skip to content

Latest commit

 

History

History
94 lines (76 loc) · 4.78 KB

typescript.md

File metadata and controls

94 lines (76 loc) · 4.78 KB

TypeScript type definitions for .NET APIs

Building type definitions

At the moment, a .d.ts file is generated by the C# source generator at the same time it generates [JSExport] marshaling code. That is not appropriate for a C# source generator, and anyway it doesn't support generating type definitions for pre-built assemblies. So this functionality will move to a separate tool soon, along with MSBuild integration support.

Type projections reference

Primitive types

C# Type TypeScript Projection
bool boolean
sbyte number
byte number
short number
ushort number
int number
uint number
long number
ulong number
nint number
nuint number
float number
double number
string string

Object types

C# Type TypeScript Projection
class Example class Example
struct Example class Example
interface IExample interface IExample
delegate A Example(B value) type Example = (value: B) => A

.NET property names and method names are automatically camel-cased when projected to JavaScript / TypeScript by a C# node module. Names are projected as-is (without any camel-casing) when dynamically invoking .NET APIs from JavaScript.

Enums

C# Type TypeScript Projection
enum Example { None = 0, One } enum Example { None = 0, One = 1 }

.NET enums are projected to JS in the style of TypeScript non-const enums: JS objects with read-only numeric properties and a reverse mapping from enum values to name strings. (Enum member names are NOT camel-cased.)

Array types

C# Type TypeScript Projection
T[] T[] aka Array<T>
Memory<sbyte> Int8Array
Memory<sbyte> UInt8Array
Memory<short> Int16Array
Memory<ushort> UInt16Array
Memory<int> Int32Array
Memory<uint> UInt32Array
Memory<long> BigInt64Array
Memory<ulong> BigUInt64Array
Memory<float> Float32Array
Memory<double> Float64Array

Regular .NET arrays are copied (passed by value) to or from JS, because there's no way to create a .NET array over external memory.

Instead of larger arrays, use Memory<T> if the element type is one of the typed-array element types. Memory<T> and typed arrays can share memory so that no marshalling or proxying is needed for element access. Otherwise prefer collection interfaces (below) which are passed by proxy.

Collection types

C# Type TypeScript Projection
IEnumerable<T> Iterable<T>
IReadOnlyCollection<T> ReadonlySet<T>
ICollection<T> Set<T>
IReadOnlySet<T> ReadonlySet<T>
ISet<T> Set<T>
IReadOnlyList<T> readonly T[] (ReadonlyArray<T>)
IList<T> T[] aka Array<T>
IReadOnlyDictionary<T> ReadonlyMap<T>
IDictionary<T> Map<T>

Collections exported from .NET use JavaScript proxies with .NET handlers to avoid copying items across the .NET/JS boundary. But this implementation detail does not affect the types visible to JavaScript code, e.g. a dictionary from .NET still satisfies instanceof Map in JS.

Special types

C# Type TypeScript Projection
Task Promise<void>
Task<T> Promise<T>
DateTime Date
DateTimeOffset [Date, number]
TimeSpan number
BigInteger BigInt
Tuple<A, B, ...> [A, B, ...]
Stream Duplex

Dates marshalled from JavaScript will always be Utc kind. A TimeSpan is projected to JavaScript as a decimal number of milliseconds. A DateTimeOffset is projected as a tuple of the UTC date-time and the offset in (positive or negative) milliseconds.