Chronicle TypeScript Client

Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle.

Chronicle is an event-sourcing database and processing runtime with a first-class .NET SDK and additional TypeScript, Kotlin/Java (JVM), and Elixir clients — with a Python client coming soon — plus pluggable storage-provider implementations including MongoDB (default), PostgreSQL, SQL Server, and SQLite. This package is the TypeScript client.

Overview

@cratis/chronicle provides a clean, type-safe TypeScript API for interacting with the Chronicle Kernel. It builds on top of @cratis/chronicle.contracts (the gRPC contracts package) and exposes idiomatic TypeScript constructs including:

• Decorators — @eventType, @eventTypeMigration, @reactor, @reducer, @seeder, @constraint, @projection, graph decorators such as @node and @edge, and model-bound decorators such as @fromEvent
• Value objects — EventSequenceNumber, EventTypeId, EventStoreName, etc.
• Fluent client — ChronicleClient → EventStore → EventLog → append()

Beyond appending and observing events, the client covers the full Chronicle surface:

• Transactions — group appends into a unit of work with a single commit
• Jobs — inspect and control long-running kernel jobs
• Webhooks — push events to HTTP endpoints
• Compliance / PII — classify event data and handle personally identifiable information
• OpenTelemetry — built-in metrics and tracing instrumentation

Installation

npm install @cratis/chronicle @cratis/fundamentals reflect-metadata

Requirements:

• Node.js 22.19 or later. The undici dependency requires it, and the package fails to import on Node.js 20.
• The package ships ES modules only. Use it from an ES module project, or require() it on a Node.js version with require(esm) support.
• A running Chronicle kernel. The easiest local setup is the development Docker image, published on this machine only:

docker run -d --name chronicle -p 127.0.0.1:35000:35000 cratis/chronicle:latest-development

Quick Example

import 'reflect-metadata';
import { field } from '@cratis/fundamentals';
import { ChronicleClient, ChronicleOptions, eventType } from '@cratis/chronicle';

@eventType()
class EmployeeHired {
    @field(String) firstName!: string;
    @field(String) lastName!: string;

    constructor(firstName: string, lastName: string) {
        this.firstName = firstName;
        this.lastName = lastName;
    }
}

const client = new ChronicleClient(ChronicleOptions.development());
const store = await client.getEventStore('MyStore');
const result = await store.eventLog.append('employee-123', new EmployeeHired('Jane', 'Doe'));
console.log(`Appended at sequence number ${result.sequenceNumber.value}`);
client.dispose();

Decorators and TypeScript configuration

Chronicle decorators work with both TC39 standard decorators (TypeScript 5.2+; do not enable experimentalDecorators) and legacy decorators (experimentalDecorators: true). Keep reflect-metadata imported at your entry point for Chronicle's runtime metadata storage. In standard mode, TypeScript does not emit design:type or design:paramtypes; declare event and read-model fields with @field(Type) from @cratis/fundamentals so Chronicle can generate their schemas. For arrays, provide an element type with @field(Array, { genericArguments: [ItemType] }). For a ConceptAs<string> or ConceptAs<number>, declare static readonly valueType = String, Number, Boolean, Guid, or Date on the concept class. Member-less event types and read models are valid. Unresolved standard-mode types fail on first schema read or during connection before Kernel registration; property decorators support public instance fields, not standard accessors or getters.

Read models are inferred from @projection('id', Model), @reducer('id', sequenceId, Model), or an exported model with @fromEvent(Event) or other model-bound property mappings. Their schema comes from the model type; the default identifier is its class name. See read models for preserving existing custom identifiers.

Decorated artifacts register when their modules are imported. When the entry file is TypeScript (run through a loader such as tsx), the client also scans **/*.ts files by default; compiled JavaScript scans nothing unless you set discoveryPatterns. See artifact discovery.

The client skips TLS certificate validation unless the connection string sets skipTlsValidation=false (the default stays true in this release; an explicit false requires validation). Set it for every server other than a local development kernel; the client logs a warning when it skips validation for a non-loopback host; see Connect to Chronicle.

Documentation

Read the TypeScript client documentation, starting with Get started with the TypeScript client. The Chronicle documentation explains the concepts, with TypeScript examples.

The Cratis ecosystem

This package is part of Cratis — free, MIT-licensed tools for building event-sourced and CQRS applications.

• Chronicle — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. Docs
• Chronicle clients — first-class .NET SDK, plus TypeScript, Kotlin/Java, and Elixir; Python coming soon (pre-alpha). AI agents connect through the Chronicle MCP server.
• Arc — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. Docs
• Components — React components aligned with Arc patterns. Docs
• CLI + Workbench — inspect and diagnose Chronicle from the terminal or the browser. Docs
• Samples — runnable event sourcing and CQRS samples for the whole stack

Everything Cratis publishes today is MIT licensed and free to use.