Type mapping

The proxy generator translates the .NET types on your commands, queries and read models into TypeScript types on the generated proxies. This page records that translation, so you can tell from the C# what the browser will actually receive.

Primitive and common types

.NET type	TypeScript type	Metadata constructor	Imported from
bool	boolean	Boolean	—
string, char, Uri	string	String	—
byte, sbyte, short, int, long, ushort, uint, ulong, float, double, decimal	number	Number	—
DateTime, DateTimeOffset	Date	Date	—
DateOnly	DateOnly	DateOnly	@cratis/fundamentals
TimeOnly	TimeOnly	TimeOnly	@cratis/fundamentals
Guid	Guid	Guid	@cratis/fundamentals
TimeSpan	TimeSpan	TimeSpan	@cratis/fundamentals
Cratis.Geospatial.Point, LineString, Polygon	same name	same name	@cratis/fundamentals
object, JsonNode, JsonObject, JsonArray, JsonDocument	Record<string, unknown>	Object	—

The metadata constructor is passed to the generated @field(...) decorator, which records the runtime type used during deserialization.

An enum becomes a TypeScript enum and travels as its underlying number. A ConceptAs<T> is unwrapped to T and mapped by this same table. A Nullable<T> is unwrapped to T and the generated property is declared optional. This mapping holds equally for a query or command parameter, not only for a read model or command property — a query method taking a plain or nullable enum argument generates the same enum-typed parameter as an equivalent property would.

Collections become arrays. A dictionary becomes Record<string, TValue> when its key maps to string, and ValueMap<TKey, TValue> otherwise.

Enum generation

Referenced enums are generated with camelCase member names and numeric values. These paired declarations illustrate the type output; the C# enum must be reachable from a discovered endpoint/model or included through library mode:

public enum ReadModelStatus
{
    Unknown = 0,
    Active = 1,
    Inactive = 2,
    Archived = 3
}

export enum ReadModelStatus {
    unknown = 0,
    active = 1,
    inactive = 2,
    archived = 3,
}

Flags enums

[Flags] uses a dedicated template that also exports all<EnumName>, combining every nonzero member with bitwise OR:

[System.Flags]
public enum AnchorEdges
{
    None = 0,
    Top = 1 << 0,
    Right = 1 << 1,
    Bottom = 1 << 2,
    Left = 1 << 3,
}

export enum AnchorEdges {
    none = 0,
    top = 1,
    right = 2,
    bottom = 4,
    left = 8,
}

export const allAnchorEdges =
    AnchorEdges.top | AnchorEdges.right | AnchorEdges.bottom | AnchorEdges.left;

The zero-valued none contributes nothing and is excluded. Composite nonzero members are included too. This is JavaScript numeric/bitwise output, not a bigint mapping: avoid assuming .NET 64-bit flag values retain their semantics under JavaScript’s 32-bit bitwise operators. Large integral values also face JavaScript number precision limits.

Dates, times and instants

DateTime and DateTimeOffset denote instants, so they map to the JavaScript Date that also denotes one.

DateOnly and TimeOnly do not. A calendar date has no time and no zone; a time of day has no date. Both cross the wire as their ISO-8601 string — "2026-05-12" and "14:30:45" — and each has a type of its own in @cratis/fundamentals that holds exactly that, with no instant invented for it.

This matters because a Date cannot hold either value without inventing one that was never sent:

new Date('2026-05-12'); // 2026-05-12T00:00:00.000Z — UTC midnight, an instant nobody sent
new Date('14:30:45'); // Invalid Date — a time of day is not a date at all

The first is the more dangerous of the two, because it looks like it worked. UTC midnight read back through any browser-local getter reports the previous day everywhere west of UTC, while remaining correct at or east of it — so the bug is invisible to a developer in Europe and constant for a user in the Americas:

const asAnInstant = new Date('2026-05-12');
asAnInstant.toLocaleDateString('en-CA', { timeZone: 'Europe/Oslo' }); // '2026-05-12'
asAnInstant.toLocaleDateString('en-CA', { timeZone: 'America/New_York' }); // '2026-05-11'  ← wrong

DateOnly holds the three parts the server sent, so there is no instant to convert and nothing to shift. The following are illustrative expressions assuming a deserialized readModel with a DateOnly-typed dueDate:

readModel.dueDate.toString(); // '2026-05-12', in every time zone
readModel.dueDate.year; // 2026
readModel.dueDate.day; // 12

Where you genuinely need a Date — to feed a date picker, or to do calendar arithmetic — toDate() constructs one at midnight in the local zone. It is a method rather than what the value is, precisely because calling it invents a time, and that choice belongs at the call site making it:

const localMidnight = readModel.dueDate.toDate();

TimeOnly works the same way, with hour, minute, second and millisecond.

Declaring how your own types cross the wire

The table above is the default. A TypeToTsType item overrides it, and is also how you declare a type the generator has never seen:

<ItemGroup>
    <TypeToTsType Include="calendar-date"
                  TypeName="System.DateOnly"
                  TsType="LocalDate"
                  Package="@acme/time" />
</ItemGroup>

Every DateOnly then generates as LocalDate, imported from @acme/time. Omit Package to generate a bare TypeScript type with no import.

Mappings are consulted ahead of the built-in table, so this corrects an existing type as readily as it declares a new one. A build that configures none generates exactly what it generated before.

Mappings change both the type and deserialization

The defaults are chosen to be right without configuration — reach for a mapping when your application wants a different type, not to work around a default that is wrong.

Whatever you map to has to be able to deserialize from what the server actually sends. DateOnly arrives as "2026-05-12" and TimeOnly as "14:30:45", so register a converter for the type you map to with JsonSerializer.registerConverter, or the value arrives as the raw string wearing the declared type’s name.

Unmapped types

A collected complex type not in the table above, and not declared through TypeToTsType, normally generates as a TypeScript class with runtime field metadata. Its folder follows namespace configuration; its filename follows the artifact name or source-file grouping. Types from package-mapped assemblies are imported instead of generated.

Plain model interfaces are a separate CLI output mode, not the default and not a replacement for constructors needed by query/identity deserialization.