Builder Functions

Source: packages/core/src/core/generators/builder.ts, packages/core/src/core/generators/fields.ts, packages/core/src/core/generators/persona.ts, packages/core/src/core/generators/dataset.ts, packages/core/src/core/monitoring/event-validation.ts

All builder functions are identity functions that exist for TypeScript type narrowing and editor IntelliSense. They return their input unchanged (except defineAction, which compiles fields into a handler when no custom handler is provided).

defineJourney

function defineJourney(config: Journey): Journey;

Defines a journey. See types.md for the Journey interface.

const journey = defineJourney({
  id: 'onboarding',
  name: 'Onboarding',
  adventures: [welcomeAdventure],
});

defineAdventure

function defineAdventure(config: Adventure): Adventure;

Defines an adventure (session/interaction period within a journey).

const adventure = defineAdventure({
  id: 'browse',
  name: 'Browse Pages',
  timeSpan: { min: 500, max: 3000 },
  actions: [viewHome, viewProduct],
});

defineAction

function defineAction(config: ActionDefinition): Action;

Defines an action. Accepts either a fields map (compiled to a single-event handler) or a custom handler function that returns Event[].

// Declarative (fields)
const viewHome = defineAction({
  id: 'view-home',
  name: 'page_view',
  fields: { page: '/home', referrer: (ctx) => ctx.faker.internet.url() },
});

// Imperative (handler)
const addToCart = defineAction({
  id: 'add-to-cart',
  name: 'add_to_cart',
  handler: (ctx) => {
    const product = ctx.typedDataset<Product>('products').randomRow();
    return [
      {
        id: ctx.generateId('event'),
        userId: ctx.userId,
        sessionId: ctx.sessionId,
        name: 'add_to_cart',
        timestamp: ctx.now(),
        payload: { productId: product.id, price: product.price },
      },
    ];
  },
});

definePersona

function definePersona(config: PersonaDefinition): PersonaDefinition;

Defines a persona with weighted attribute distributions.

const shoppers = definePersona({
  id: 'shoppers',
  name: 'Online Shoppers',
  attributes: {
    locale: weighted({ en: 0.6, de: 0.2, fr: 0.2 }),
    tier: weighted({ free: 0.7, pro: 0.2, enterprise: 0.1 }),
    age: fake((f) => f.number.int({ min: 18, max: 65 })),
    device: oneOf(['mobile', 'desktop', 'tablet']),
  },
});

The PersonaDefinition interface:

interface PersonaDefinition {
  id: string;
  name: string;
  attributes: Record<string, FieldGenerator>;
}

defineDataset

function defineDataset<TFields>(config: DatasetDefinition<TFields>): DatasetDefinition<TFields>;

Defines a dataset. Use InferDatasetRow<typeof def> to extract the row type.

const productsDef = defineDataset({
  id: 'products',
  name: 'Products',
  count: 200,
  fields: {
    id: (_ctx, row) => `prod-${row.index}`,
    name: (ctx) => ctx.faker.commerce.productName(),
    price: (ctx) => ctx.faker.number.float({ min: 10, max: 500 }),
  },
});

type Product = InferDatasetRow<typeof productsDef>;

defineEventSchema

function defineEventSchema<T extends z.ZodRawShape>(shape: T): z.ZodObject<T>;

Convenience wrapper around z.object() for defining event payload schemas. Used with RunOptions.eventSchema for runtime validation.

import { z } from 'zod';
import { defineEventSchema } from '@synode/core';

const pageViewSchema = defineEventSchema({
  url: z.string().url(),
  referrer: z.string().optional(),
});

Field Helpers

oneOf

function oneOf<T>(options: T[]): FieldGenerator<T>;

Returns one of the provided options at random with equal probability.

weighted

function weighted<T extends string>(options: Record<T, number>): FieldGenerator<T>;

Returns a value based on weighted probabilities. Weights are normalized if they do not sum to 1.

chance

function chance(probability: number): FieldGenerator<boolean>;

Returns true with the given probability (0-1).

fake

function fake<T>(generator: (faker: Faker) => T): FieldGenerator<T>;

Returns a value generated by the context's locale-aware Faker instance.