Skip to content
EvidentSource EvidentSource

TypeScript SDK

TypeScript SDK for building client applications that connect to EvidentSource servers.

Status: Stable

SDK Components

Section titled “SDK Components”
ComponentDescription
@evidentsource/coreCore library: identifiers, events, selectors, constraints
@evidentsource/clientClient library: gRPC connectivity to EvidentSource servers

Requirements

Section titled “Requirements”
  • Node.js 20.0 or later
  • pnpm 9.0 or later
  • Protocol Buffers compiler (protoc) for proto generation

Installation

Section titled “Installation”
Terminal window
# Install from source (development)
git clone https://github.com/evidentsystems/evidentsource-sdks.git
cd evidentsource-sdks/typescript
pnpm install
pnpm build

Quick Start

Section titled “Quick Start”
import {
  EvidentSource,
  databaseName,
  stateViewName,
  stateChangeName,
  jsonCommandRequest,
  stateViewContentAsJson,
  DatabaseError,
} from "@evidentsource/client";


// Connect to server
const es = EvidentSource.connect("http://localhost:50051");


// Create database if needed
const dbName = databaseName("my-database");
try {
  await es.createDatabase(dbName);
} catch (e) {
  if (e instanceof DatabaseError && e.code === "ALREADY_EXISTS") {
    // Already exists, that's fine
  } else {
    throw e;
  }
}


// Get connection
const conn = await es.connectDatabase(dbName);


// Execute a state change
const db = await conn.executeStateChange(
  stateChangeName("create-todo"),
  1,
  jsonCommandRequest({
    todoId: "123",
    title: "Buy milk",
    effectiveTimestamp: new Date().toISOString(),
  })
);


// Query a state view
const view = await db.viewState(stateViewName("todo-list"), 1);
const todos = stateViewContentAsJson<{ todos: Todo[] }>(view);


// Clean up
await conn.close();
es.close();

Features

Section titled “Features”

Branded Types

Section titled “Branded Types”

Type-safe identifiers with runtime validation:

import { databaseName, streamName, stateViewName } from "@evidentsource/core";


const dbName = databaseName("my-database");   // Validated at runtime
const viewName = stateViewName("account-summary");

Composable Selectors

Section titled “Composable Selectors”

Build event selectors with a fluent API:

import { EventSelector, streamName, eventType } from "@evidentsource/core";


const selector = EventSelector.and(
  EventSelector.streamEquals(streamName("accounts")),
  EventSelector.typeStartsWith(eventType("com.example."))
);

Connection Management

Section titled “Connection Management”

Automatic subscription and reconnection:

const conn = await es.connectDatabase(dbName);


// Connection maintains a live subscription to the database
// Automatically reconnects on connection loss


// Get the latest database state
const db = await conn.latestDatabase();
console.log(`Current revision: ${db.revision}`);

Examples

Section titled “Examples”
ExampleDescription
TodoMVCServer-side rendered todo app with HTMX
Savings AccountREST API for banking operations

Project Structure

Section titled “Project Structure”
typescript/
├── packages/
│   ├── evidentsource-core/    # Foundation types (no dependencies)
│   └── evidentsource-client/  # gRPC client
└── examples/
    ├── todomvc/               # Server-rendered todo app
    └── savings-account/       # Banking REST API

Development

Section titled “Development”
Terminal window
# Install dependencies
pnpm install


# Build all packages
pnpm build


# Run tests
pnpm test


# Type check
pnpm lint

API Reference

Section titled “API Reference”

API documentation will be available on npm when packages are published.

Next Steps

Section titled “Next Steps”