git:20261008.6afc208 to git:20261012.8a4854a

---

name: cratis-chronicle-client-typescript

description: Talk to a Chronicle server from a Node.js or TypeScript application with @cratis/chronicle - reflect-metadata and decorator compiler settings, ChronicleClient and connection strings, @eventType classes, eventLog.append, reactors and reducers dispatched by camelCase method name, model-bound and declarative projections, variants (@variantOf/@entersOn/@globalFor or .variantOf()/.entersOn()) for an entity with mutually exclusive lifecycle shapes, glob-based artifact discovery, and the lazy connect and keepalive lifecycle. Use when a Node application appends to or observes a Chronicle event store. Do not use for the .NET, Kotlin, or Elixir clients, and do not use for Arc React frontends or generated Arc proxies.

license: MIT

---

# The Chronicle client for TypeScript

`@cratis/chronicle` is a **standalone Node.js client SDK** that speaks gRPC to a

Chronicle server. It is not a browser library and it is not the Arc TypeScript

proxy layer — an Arc frontend calls generated command and query proxies over

HTTP and never sees this package.

## Common pitfalls

| Pitfall | Why it bites |

| --- | --- |

| `instanceof` on the event inside a handler | It is a `JSON.parse`d plain object, not your class |

| Two `@eventType()` classes sharing a class name | The id defaults to the class name and they collide |

| Omitting a side-effect import of an artifact module | Its decorator never runs, so it is never registered |

| Forgetting `import 'reflect-metadata'` at the entry point | Decorators do not work at runtime |

| Forgetting to install `@cratis/fundamentals` | It is a peer dependency and is not installed for you |

| Importing `ChronicleConnectionString` | There is no `./connection` export; pass a string |

| A connection string with no credentials | Silently falls back to the development client credentials |

| Shipping the default TLS behavior | `skipTlsValidation` defaults to `true` |

| Reading `result.sequenceNumber` as a number | It is a `bigint` behind `.value` |

| A `@globalFor` mapping targeting a property one variant lacks | `GlobalHandlerPropertyNotOnVariant` when the group is built, not a silently skipped mapping |

| Expecting a `@globalFor`-only class to appear as a projection | It is never registered on its own; it is merged into its variants |

## Verified product sources

| Package | Version | Where |

| --- | --- | --- |

> **Do not read the version out of the repository.** `Source/package.json` says

> `1.0.0`; `publish-version.js` overwrites it at publish time. Take the version

> from npm.

## Project setup

```shell

yarn add @cratis/chronicle @cratis/fundamentals reflect-metadata

```

`@cratis/fundamentals` is a peer dependency, so it does not arrive on its own.

```typescript

import 'reflect-metadata';

```

```jsonc

{

"compilerOptions": {

}

}

```

## Connecting

```typescript

import 'reflect-metadata';

import { ChronicleClient, ChronicleOptions } from '@cratis/chronicle';

const client = new ChronicleClient(ChronicleOptions.development());

try {

const store = await client.getEventStore('<EventStoreName>');

// ... use store ...

} finally {

client.dispose();

}

```

`ChronicleClient`'s constructor takes exactly one argument —

**Connecting is implicit and lazy.** There is no `connect()`. The constructor

starts a health-check watchdog and kicks off artifact discovery; the actual

connect happens on the first `getEventStore`/`getEventStores` through an internal

`ensureConnected()`. `getEventStore` also *creates* the store if it does not

`Symbol.dispose` or `Symbol.asyncDispose`. After disposal every call throws.

### Options

> `programIdentifier`, `softwareVersion`, and `softwareCommit` exist on the type

> Do not write guidance that configures them.

### The connection string

Schemes `chronicle://` and `chronicle+srv://`, default port `35000`

(`Source/connection/ChronicleConnectionString.ts`). Query parameters: `apiKey`,

`disableTls`, `skipTlsValidation`, `certificatePath`, `certificatePassword`,

`loadBalancer`, `srvNameServer`.

Two facts to carry into production guidance:

- **`skipTlsValidation` defaults to `true`.** TLS is on but the certificate chain

is not validated, because a development kernel serves a self-signed

certificate. Set `?skipTlsValidation=false` against a real server.

- **A connection string with no credentials silently falls back to the

An anonymous-looking connection string is not anonymous; it is

`chronicle-dev-client`.

> **There is no `./connection` subpath export.** `ChronicleConnectionString`,

> `ChronicleConnectionStringBuilder`, `AuthenticationMode`, and `LoadBalancerMode`

> are unreachable from the public entry points — `Source/index.ts` never

> re-exports them and `Source/package.json`'s `exports` map has no

> `"./connection"` key. **Application code passes a connection *string*.** Do not

> write an example that imports a connection-string type.

The subpath exports that do exist: `.`, `./events`, `./eventSequences`,

`./eventStoreSubscriptions`, `./compliance`, `./reactors`, `./reducers`,

`./seeding`, `./readModels`, `./projections`, `./jobs`, `./webhooks`,

`./externalServices`, `./identities`, `./observation`, `./sinks`, `./schemas`,

`./types`, `./artifacts`, `./identity`, `./auditing`, `./correlation`,

## Event types

```typescript

import { eventType } from '@cratis/chronicle';

@eventType()

export class <EventName> {

}

```

**The event type id defaults to the class name** — `new EventTypeId(id || constructor.name)`

## Appending

`IEventLog` is an empty extension of `IEventSequence`

```typescript

```

```typescript

const result = await store.eventLog.append('<event-source-id>', new <EventName>('<value>'));

if (!result.isSuccess) {

// result.constraintViolations, result.concurrencyViolation, result.errors

}

```

- **The event source id is a plain `string`.** There is no `EventSourceId` value

type at this boundary.

- **`sequenceNumber` wraps a `bigint`.** Read it as `result.sequenceNumber.value`.

`EventContext.sequenceNumber` is a `bigint` too.

Correlation id, identity, and the causation chain are picked up from the ambient

module-level managers (`identityProvider`, `causationManager`,

`correlationIdManager`) — you do not pass them.

Several appends as one unit:

```typescript

const unitOfWork = store.unitOfWorkManager.begin();

await store.eventLog.transactional.append('<id>', new <EventName>('<value>'));

await unitOfWork.commit();

```

`ITransactionalEventSequence` returns `Promise<void>`, not an `AppendResult`;

## Observing

```typescript

import { EventContext, EventForEventSourceId } from '@cratis/chronicle';

@reactor()

export class <ReactorName> {

async <eventName>(event: <EventName>, context: EventContext): Promise<EventForEventSourceId> {

return {

eventSourceId: '<other-event-source-id>',

event: new <SideEffectEvent>(context.eventSourceId)

};

}

}

```

A returned event, array, or `EventForEventSourceId` is appended as a side effect;

a failed side-effect append fails the partition.

### Read models and projections

Read [references/read-models-and-projections.md](references/read-models-and-projections.md) when reading a read model instance, choosing a projection style, or declaring a constraint.

### Variants — mutually exclusive read models for one entity's lifecycle

One entity with mutually exclusive lifecycle shapes is modeled as variants, with `@variantOf`/`@entersOn`/`@globalFor` or the fluent `.variantOf()`/`.entersOn()`; every variant needs an entering event.

Read [references/variants.md](references/variants.md) when a read model for one entity changes shape over its lifecycle, or when you meet `VariantMustDeclareEntersOnEvent` or `GlobalHandlerPropertyNotOnVariant`.

`EventStore.registerArtifacts()` registers event types first, then everything else

in parallel, and re-runs for every cached event store on reconnect.

## Lifecycle

- A health-check watchdog runs `getVersionInfo` every 5 seconds and reconnects on

failure; the interval handle is `unref()`'d so it does not hold the process open.

- Reconnect uses exponential backoff with jitter, capped at 30 seconds, rebuilding

the gRPC channel on every attempt.

- **Keepalive registration is what keeps observers alive.** Losing it triggers a

full reconnect, because the kernel tears down the client's observers otherwise.

- Failed operations are retried once after reconnecting, keyed on gRPC status

codes 4/13/14 plus a substring match over the error text.

## Verify

- The installed version is the one you intended, taken from npm, and

`@cratis/fundamentals` is installed alongside it.

- `reflect-metadata` is imported exactly once, at the entry point.

- A production connection string carries credentials and `skipTlsValidation=false`.

- `client.dispose()` runs on shutdown.

- Every variant group has at least one `@entersOn`/`entersOn(...)` per variant,

and every `@globalFor` member exists on every variant it targets.

- Lint, `tsc`, and the test suite are clean against the verified package version.