Skip to content

feat: add minimal Chronicle TypeScript client sample - #583

Merged
woksin merged 2 commits into
mainfrom
feat/typescript-sample
Aug 28, 2026
Merged

feat: add minimal Chronicle TypeScript client sample#583
woksin merged 2 commits into
mainfrom
feat/typescript-sample

Conversation

@woksin

@woksin woksin commented Aug 28, 2026

Copy link
Copy Markdown
Collaborator

What

Adds Chronicle/TypeScript — a minimal runnable Node.js/TypeScript sample for the @cratis/chronicle client covering the three-step journey append → react → read:

  • events.ts — two past-tense @eventType() classes (VisitorArrived, VisitorWelcomed)
  • reactor.ts — a @reactor() returning a side-effect event, making the reaction visible in the history
  • index.ts — connect, append, waitForCompletion(), read the combined history
  • docker-compose.yml — single cratis/chronicle:latest-development container (bundles MongoDB)
  • README.md — pinned versions, docker compose instructions, expected output, cleanup
  • samples.json catalog entry (track getting-started) and a row in the root README table — the catalog/docs-sync path clearly supports new entries (README contributing steps 5–6, scripts/validate-samples.mjs, CI yarn samples:validate)

npm dependencies are pinned exactly: @cratis/chronicle 3.1.0, @cratis/fundamentals 7.18.2, reflect-metadata 0.2.2.

Verification

  • node scripts/validate-samples.mjs — passes (10 samples across 7 tracks)
  • npm install + npm run compile — clean
  • End-to-end run against cratis/chronicle:16.33.0-developmentworks: append at seq 0, reactor side effect at seq 1, both read back
  • End-to-end run against cratis/chronicle:latest-development (digest sha256:a42361…, built 2026-08-28) — fails: /Cratis.Chronicle.Contracts.EventStores/Ensure UNIMPLEMENTED

Why this PR is left open (do not merge yet)

The sample was required to run against cratis/chronicle:latest-development, and it currently cannot — through no fault of the sample code:

  • Chronicle server commit a34f5b2b1 (2026-08-14, first released in v16.33.1) renamed the EventStores/Ensure RPC to EnsureEventStore.
  • @cratis/chronicle.contracts 17.0.0 carries the renamed contract, but the latest published client @cratis/chronicle 3.1.0 still pins contracts 16.13.4 and calls Ensure.
  • Result: the published npm client cannot complete getEventStore() against any server ≥ 16.33.1, including today's latest-development and the current release image.

The sample README carries a clearly marked known-incompatibility warning with the verified fallback tag (16.33.0-development). Suggested unblock: publish a @cratis/chronicle client release on contracts 17.x, then re-run this sample against latest-development and merge.

Also found (upstream, fixed in-sample)

The client's default artifact discoveryPatterns (!**/node_modules) do not exclude files inside node_modules in a standalone npm layout (the upstream Console sample never hits this because its dependencies are hoisted). The sample passes explicit discoveryPatterns: ['*.ts', …]. Worth an upstream issue in Chronicle.TypeScript.

woksin added 2 commits August 28, 2026 20:07
Adds Chronicle/TypeScript — a small runnable Node.js/TypeScript sample using
the @cratis/chronicle client: append a VisitorArrived event, let a reactor
respond with a VisitorWelcomed side-effect event, and read the combined
history back. Includes a single-container docker-compose.yml, pinned npm
dependencies, a catalog entry in samples.json, and a row in the samples
table.
…e servers

- 3.1.1 adopts chronicle.contracts 17 with the renamed EnsureEventStore RPC, so the sample runs against cratis/chronicle:latest-development
- remove the known-incompatibility warning that no longer applies
@woksin

woksin commented Aug 28, 2026

Copy link
Copy Markdown
Collaborator Author

Unblocked: @cratis/chronicle 3.1.1 (published from Cratis/Chronicle.TypeScript#56) adopts chronicle.contracts 17 with the renamed EnsureEventStore RPC. Sample pin updated to 3.1.1 and re-verified end to end against cratis/chronicle:latest-development: append at seq 0, reactor side effect at seq 1, both read back. Known-incompatibility warning removed from the README.

@woksin
woksin merged commit 9a55f67 into main Aug 28, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant