@genesislcap/event-type-codegen
Build-time TypeScript interfaces for Genesis event DETAILS payloads, discovered from Kotlin PAL event handlers without a running server.
Configuration
Enable via genx.config.* or the genx / genesis key in package.json:
{
"genx": {
"eventTypes": {
"enabled": true,
"serverModule": "../server/my-app",
"kotlinSources": [
"src/main/kotlin/**/dto/**/*.kt",
"src/main/genesis/scripts/**/*.kts"
],
"generatedDaoSources": [
"build/internal-modules/**/*-generated-dao/build/generated/sources/dao/global/genesis/gen/dao/**/*.kt"
],
"handlerScan": [
"src/main/kotlin/**/*.kt",
"src/main/genesis/scripts/**/*.kts"
],
"output": "src/generated/genesis-event-types.ts",
"runOnBuild": true
}
}
}
When enabled is false or the block is omitted, codegen is skipped.
generatedDaoSources globs are resolved against both the app module (serverModule) and its parent Gradle server/ directory (where dictionary-cache DAOs usually live). Defaults cover common monorepo layouts after ./gradlew … has generated DAO sources. Custom data class DTOs always override a generated DAO with the same class name.
CLI
From a client app directory:
genx generate event-types
genx build runs codegen first when eventTypes.enabled and runOnBuild (default true when enabled).
In the showcase server Gradle build, generateDao is finalizedBy generateEventTypes, which runs genx generate event-types in react-client when genx is available (after monorepo bootstrap). Disable with -PenableEventTypeCodegen=false.
Limitations (v1)
- Discovery uses Kotlin source parsing, not the compiler or live JSON Schema.
- Only handlers with a resolvable DETAILS shape (custom DTO or generated table/index from
generatedDaoSources) get*Detailstypes andEventDetailsMapentries. Anything else is listed in a comment at the top of the generated file. - Full table DAO handlers (e.g.
eventHandler<Trade>("TRADE_INSERT")) and index handlers (e.g.eventHandler<Trade.ById>("TRADE_DELETE")) are mapped when generated DAO.ktsources are present undergeneratedDaoSources. - Class-based handler sources named
*EventHandler.ktunder adto/path are skipped. Thedto/**glob is for inputdata classes only; those files are usuallySyncValidatingEventHandlerimplementations and are not PALeventHandler { }scripts. PAL handlers in*-eventhandler.kts(and otherhandlerScanpaths) are still discovered. - Generate DAO sources (Gradle) before client codegen in CI if the trees are not committed.
- Dictionary ENUM fields: string literal unions when
enum classand/or companionField.Type.ENUMvalues = "…"appear undergeneratedDaoSources(gen/dao/**/*.kt). - Enum exports are named after the Kotlin enum, and are qualified with the owning table only
when declarations disagree. Genesis emits an enum either unscoped, in the flat
global.genesis.gen.dao.enums, or table-scoped, in…enums.<dictionary>.<table>— so several declarations can share a simple name. Identical value sets share one export; differing ones are qualified (AxeStatus/RfqStatus/OrderStatus) so no table's fields point at another's values. Where an unscoped declaration is among them it keeps the bare name, because that is the one a PAL script's default import resolves to. - A field's enum is resolved the way Kotlin resolves the name, against the file that wrote it:
a type the file declares itself, then an explicit
import, then the file's own package, then star imports. Each rung shadows those below it — an explicitimportthat names something outside the generated tree yieldsunknown, never a same-named generated enum. - PAL scripts (
.ktsundergenesis/scripts/) additionally carry the default imports the Genesis compiler supplies (…gen.dao.enums.*,…gen.dao.*and the generated config/view packages), which is whyval feeType: FeeTyperesolves there with noimportline. Star imports do not recurse, so a table-scoped enum named with no import in a script still resolves tounknown: Genesis does supply those as explicit default imports viatables-info.json, but that tier is not modelled yet. A plain.ktsource, and anything undergenesis/cfg/, gets no defaults.
Typed commits
*Detailsinterfaces — DETAILS payload from Kotlin DTOs.GenesisEvent(from@genesislcap/foundation-comms) — abstract base; subclass setsMESSAGE_TYPE.- Per-handler classes — e.g.
EventAqsCounterpartyInsert.
import { commitGenesisEvent } from '@genesislcap/foundation-comms';
import { EventAqsCounterpartyInsert } from './generated/genesis-event-types';
await commitGenesisEvent(
connect,
new EventAqsCounterpartyInsert({ COUNTERPARTY_ID: 'x' }),
);
Metadata dump path (FUI-2608)
Generate from a live-server snapshot instead of (or in addition to) Kotlin source scan:
- In a connected app with
foundation-header, press Ctrl/Cmd+Shift+E (dev builds only) to downloadevent-metadata.json. - Run:
genx generate event-types --from-metadata event-metadata.json
This uses inbound JSON Schema DETAILS (field names, JSON_TYPE, requiredness) as the contract — useful for comparing against the Kotlin-scan output and for handlers the source scanner misses.
Wire field naming for the Kotlin path matches genesis-server toUpperUnderscoreWithAcronyms (e.g. addressLine1 → ADDRESS_LINE_1). Date/DateTime Kotlin types map to TypeScript number (epoch millis / JSON_TYPE: integer).
Migration
| App | Action |
|---|---|
| New genx template | Enable eventTypes, commit or gitignore generated output |
| Legacy | Add config, run genx generate event-types, adopt typed commits incrementally |
| No Kotlin DTOs | Leave disabled |