Synode

Appearance

Types Module ​

Source: packages/core/src/core/types.ts

Core type definitions for the Synode domain model. All types are re-exported from the package root (import { Event, Journey, ... } from '@synode/core').

Event ​

The atomic output unit -- a single tracking event generated by an action handler.

typescript
interface Event {
  id: string;
  userId: string;
  sessionId: string;
  name: string;
  timestamp: Date;
  payload: Record<string, unknown>;
}

Context ​

Per-user execution context passed to every action handler. Provides access to faker, state, timing, datasets, and identity.

typescript
interface Context {
  readonly userId: string;
  readonly sessionId: string;
  readonly locale: string;
  readonly faker: Faker;

  get<T>(key: string): T | undefined;
  set<T>(key: string, value: T, options?: ContextSetOptions): void;
  now(): Date;
  generateId(prefix?: string): string;
  hasCompletedJourney(journeyId: string): boolean;
  markJourneyComplete(journeyId: string): void;
  dataset(id: string): DatasetHandle;
  typedDataset<TRow extends DatasetRow>(id: string): DatasetHandle<TRow>;
}

ContextScope ​

Lifecycle scope for automatic field cleanup: 'action' | 'adventure' | 'journey'.

ContextSetOptions ​

Options passed to ctx.set() for scoped fields.

typescript
interface ContextSetOptions {
  scope?: ContextScope;
}

Journey ​

Top-level behavioral flow containing adventures.

typescript
interface Journey {
  id: string;
  name: string;
  requires?: string[];
  adventures: Adventure[];
  bounceChance?: number; // 0-1
  suppressionPeriod?: SuppressionPeriod;
}

Adventure ​

Session or interaction period containing actions. Runs sequentially within a journey.

typescript
interface Adventure {
  id: string;
  name: string;
  actions: Action[];
  timeSpan?: TimeSpan;
  bounceChance?: number; // 0-1
  onBounce?: 'stop' | 'skip';
}

Action ​

A resolved action with a handler function. Created by defineAction().

typescript
interface Action {
  id: string;
  name: string;
  handler: (context: Context) => Event[] | Promise<Event[]>;
  timeSpan?: TimeSpan;
  bounceChance?: number;
}

ActionDefinition ​

Configuration object accepted by defineAction(). Supports either fields (declarative) or handler (imperative). When handler is provided, fields is ignored.

typescript
interface ActionDefinition {
  id: string;
  name: string;
  fields?: Record<string, FieldGenerator>;
  handler?: (context: Context) => Event[] | Promise<Event[]>;
  timeSpan?: TimeSpan;
  bounceChance?: number;
}

TimeSpan ​

Delay configuration between actions or events (milliseconds).

typescript
interface TimeSpan {
  min: number;
  max: number;
  distribution?: 'uniform' | 'gaussian' | 'exponential';
}

SuppressionPeriod ​

Cooldown after journey completion or bounce (milliseconds).

typescript
interface SuppressionPeriod {
  min: number;
  max: number;
}

DatasetDefinition<TFields> ​

Configuration for defineDataset(). Fields can be static values or generator functions.

typescript
interface DatasetDefinition<TFields extends Record<string, unknown>> {
  id: string;
  name: string;
  count: number; // 0 to 10,000,000
  fields: {
    [K in keyof TFields]:
      | TFields[K]
      | ((ctx: Context, row: { index: number; data: DatasetRow }) => TFields[K]);
  };
}

Dataset<TRow> ​

A hydrated dataset with an id, name, and array of rows.

DatasetRow ​

Alias for Record<string, unknown>.

DatasetHandle<TRow> ​

Handle returned by ctx.dataset() and ctx.typedDataset().

typescript
interface DatasetHandle<TRow = DatasetRow> {
  randomRow(): TRow;
  getRowById(id: string | number): TRow | undefined;
  getRowByIndex(index: number): TRow | undefined;
  getAllRows(): TRow[];
  size(): number;
}

InferDatasetRow<T> ​

Utility type that extracts the row type from a DatasetDefinition, unwrapping generator functions and promises.

typescript
const def = defineDataset({
  id: 'x',
  name: 'X',
  count: 10,
  fields: { price: (ctx) => ctx.faker.number.float({ min: 1, max: 99 }) },
});
type Row = InferDatasetRow<typeof def>; // { price: number }

FieldGenerator<T> ​

A static value or (context: Context, payload: Record<string, unknown>) => T | Promise<T>.

DatasetFieldGenerator<T> ​

Like FieldGenerator but receives { index, data } instead of payload.

EventSchemaConfig ​

Configures Zod-based event validation in RunOptions.eventSchema.

typescript
interface EventSchemaConfig {
  schema: z.ZodType | Record<string, z.ZodType>;
  mode?: EventValidationMode; // default 'strict'
}

EventValidationMode ​

'strict' | 'warn' | 'skip' -- controls behavior on schema validation failure.