TypeScript client

@cratis/chronicle lets a Node.js application written in TypeScript append events to Chronicle, build read models from them, and react to them, using decorated classes instead of hand-written gRPC calls. It builds on the @cratis/chronicle.contracts gRPC contracts package.

This section covers what is specific to TypeScript: installation, TypeScript configuration, decorators, connection setup, and TypeScript-only APIs. Chronicle concepts and workflows are explained once in the shared Chronicle docs, which show TypeScript examples in their TypeScript tabs.

Start here

Get started with the TypeScript client takes you from an empty folder to a program that appends events and reads the projected read model back. It also covers Node.js and TypeScript requirements, decorator modes, and the most common setup errors.

Then read Connect to Chronicle before you point the client at anything other than a local development kernel. The client skips TLS certificate validation by default, and it retries a failing connection silently.

Shared Chronicle topics

• Get started
• Events and event logs
• Appending events
• Read models
• Projections
• Reactors
• Reducers
• Constraints
• Event seeding
• Compliance
• Transactions and unit of work
• Event evolution

The TypeScript examples on those pages are compiled with legacy decorators (experimentalDecorators). Examples that declare event properties as constructor parameters, such as constructor(readonly name: string), need legacy decorators. With standard decorators, declare the properties with @field(Type) instead, as described in Decorator mode and schema types.

TypeScript-specific pages

• Connect to Chronicle — connection strings, credentials, TLS, reconnection, compatibility, and shutdown
• Preserve existing append routes — keep writing to existing streams after the append-routing change
• Observers — listing observers and removing one whose declaring code is gone
• Sinks — choose where read models are stored
• Jobs — inspect and control Chronicle jobs
• Constraints — unique event properties and event types
• Webhooks — register webhooks in code or with decorators
• External Services — register HTTP and database services in code
• Seeding — seed events with @seeder classes
• Identity, Causation, and Correlation — the metadata the client attaches to every append
• Failed Partitions — find observers that stopped processing an event source

Known limitations

• AppendResult.waitForCompletion() can time out when an observer on the event sequence does not handle the appended event. The kernel waits for every observer on the sequence (Cratis/Chronicle#4132).
• Earlier client versions registered standard-decorated property-only read models only after construction. This client discovers exported models before construction; compiled JavaScript without discovery patterns needs a class-level @fromEvent(...) or explicit registration. Store creation emits a diagnostic warning once per process for unresolved mappings. See Artifact discovery.