@adriansteffan/reactive 0.0.42 → 0.0.44

package/src/utils/simulation.ts

@@ -0,0 +1,268 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  compileTimeline,
+  advanceToNextContent,
+  applyMetadata,
+  RefinedTrialData,
+  ComponentResultData,
+  TimelineItem,
+  Store,
+} from './bytecode';
+
+
+export type ParticipantState = Record<string, any>;
+
+export type SimulatorResult = {
+  responseData: any;
+  participantState: ParticipantState;
+  storeUpdates?: Record<string, any>;
+  duration?: number;
+};
+
+export type SimulateFunction = (
+  trialProps: Record<string, any>,
+  experimentState: {
+    data: RefinedTrialData[];
+    store: Store;
+  },
+  simulators: Record<string, any>,
+  participant: ParticipantState,
+) => SimulatorResult | Promise<SimulatorResult>;
+
+
+interface ComponentSimulation {
+  simulate: SimulateFunction;
+  defaultSimulators: Record<string, any>;
+}
+
+const simulationRegistry: Record<string, ComponentSimulation> = {};
+
+export function registerSimulation(
+  type: string,
+  simulate: SimulateFunction,
+  defaultSimulators: Record<string, any>,
+) {
+  simulationRegistry[type] = { simulate, defaultSimulators };
+}
+
+export function getSimulation(type: string): ComponentSimulation | undefined {
+  return simulationRegistry[type];
+}
+
+export const noopSimulate: SimulateFunction = (_trialProps, _experimentState, _simulators, participant) => ({
+  responseData: {},
+  participantState: participant,
+});
+
+export function resolveSimulation(content: any, data: RefinedTrialData[], store: Store) {
+  const trialProps =
+    typeof content.props === 'function' ? content.props(data, store) : content.props || {};
+  const registration = simulationRegistry[content.type];
+  const simulateFn = typeof content.simulate === 'function' ? content.simulate : registration?.simulate;
+
+  if (!simulateFn) {
+    throw new Error(`No simulation registered for trial type '${content.type}' (name: '${content.name ?? 'unnamed'}'). Register one with registerSimulation() or add a simulate function to the timeline item.`);
+  }
+
+  const simulators = { ...registration?.defaultSimulators, ...content.simulators };
+  return { trialProps, simulateFn, simulators };
+}
+
+let _backendUrl = 'http://localhost:8001/backend';
+export function setBackendUrl(url: string) { _backendUrl = url; }
+export function getBackendUrl() { return _backendUrl; }
+
+let _initialParticipant: ParticipantState | undefined;
+export function getInitialParticipant() { return _initialParticipant; }
+
+
+export async function simulateParticipant(
+  timeline: TimelineItem[],
+  participant: ParticipantState,
+): Promise<RefinedTrialData[]> {
+  _initialParticipant = { ...participant };
+  let currentParticipantState = { ...participant };
+  const bytecode = compileTimeline(timeline);
+  let store: Store = {};
+  const data: RefinedTrialData[] = [
+    {
+      index: -1,
+      trialNumber: -1,
+      start: 0,
+      end: 0,
+      duration: 0,
+      type: '',
+      name: '',
+      responseData: { userAgent: 'simulated', params: {} },
+    },
+  ];
+  
+  const getStore = () => store;
+  const getData = () => data;
+  const onUpdateStore = (s: Store) => { store = s; };
+
+  let trialNumber = 0;
+  let currentTime = 0;
+
+  let pointer = advanceToNextContent(bytecode, 0, getStore, getData, onUpdateStore);
+
+  while (pointer < bytecode.instructions.length) {
+    const content = (bytecode.instructions[pointer] as any).content;
+    if (typeof content !== 'object' || content === null || typeof content.type !== 'string') {
+      pointer = advanceToNextContent(bytecode, pointer + 1, getStore, getData, onUpdateStore);
+      continue;
+    }
+
+    const { trialProps, simulateFn, simulators } = resolveSimulation(content, data, store);
+
+    const result = await simulateFn(
+      trialProps,
+      { data, store },
+      simulators,
+      currentParticipantState,
+    );
+    currentParticipantState = result.participantState;
+    if (result.storeUpdates) store = { ...store, ...result.storeUpdates };
+
+    trialNumber++;
+    const duration = result.duration ?? 0;
+    const startTime = currentTime;
+    currentTime += duration;
+
+    let trialData: ComponentResultData = {
+      index: pointer,
+      trialNumber,
+      start: startTime,
+      end: currentTime,
+      duration,
+      type: content.type,
+      name: content.name ?? '',
+      responseData: result.responseData,
+    };
+
+    data.push(applyMetadata(trialData, content, data, store));
+    pointer = advanceToNextContent(bytecode, pointer + 1, getStore, getData, onUpdateStore);
+  }
+
+  return data;
+}
+
+
+export interface RunSimulationConfig {
+  participants: ParticipantState[] | { generator: (index: number) => ParticipantState; count: number };
+  backendPort?: number;
+  concurrency?: number;
+}
+
+export async function orchestrateSimulation(config: RunSimulationConfig, scriptPath: string): Promise<void> {
+  const { spawn } = await import('child_process');
+
+  const port = config.backendPort ?? 8001;
+  const backendUrl = `http://localhost:${port}/backend`;
+
+  const participantCount = Array.isArray(config.participants)
+    ? config.participants.length
+    : config.participants.count;
+
+  const backend = spawn('npx', ['tsx', 'src/backend.ts'], {
+    cwd: './backend',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  // Wait for backend to signal readiness before spawning workers
+  await new Promise<void>((resolve, reject) => {
+    backend.on('error', reject);
+
+    backend.stdout?.on('data', (data: any) => {
+      const msg = data.toString();
+      if (msg.includes('REACTIVE_BACKEND_READY')) {
+        resolve();
+      }
+    });
+
+    backend.stderr?.on('data', (data: any) => {
+      console.error(`[backend] ${data.toString().trim()}`);
+    });
+
+    setTimeout(() => reject(new Error('Backend did not start within 10 seconds')), 10000);
+  });
+
+  console.log(`Backend running on port ${port}`);
+
+  try {
+    const concurrency = config.concurrency ?? (await import('os')).cpus().length;
+    console.log(`Simulating ${participantCount} participants (concurrency: ${concurrency})...`);
+
+    let completed = 0;
+    const errors: { index: number; error: string }[] = [];
+
+    const writeProgress = () => {
+      const pct = Math.min(100, Math.round((completed / participantCount) * 100));
+      const filled = Math.floor(pct / 2);
+      const bar = '█'.repeat(filled) + '░'.repeat(50 - filled);
+      process.stdout.write(`\r  ${bar} ${completed}/${participantCount} (${pct}%)`);
+    };
+
+    const spawnWorker = (i: number) => new Promise<void>((resolve) => {
+      let stderr = '';
+      const worker = spawn('npx', ['tsx', scriptPath], {
+        env: {
+          ...process.env,
+          _REACTIVE_WORKER_INDEX: String(i),
+          _REACTIVE_BACKEND_URL: backendUrl,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      worker.stderr?.on('data', (data: any) => { stderr += data.toString(); });
+
+      worker.on('close', (code: number) => {
+        if (code !== 0) {
+          errors.push({ index: i, error: stderr.trim() || `exited with code ${code}` });
+        }
+        completed++;
+        writeProgress();
+        resolve();
+      });
+      worker.on('error', (err: Error) => {
+        errors.push({ index: i, error: err.message });
+        completed++;
+        writeProgress();
+        resolve();
+      });
+    });
+
+    writeProgress();
+
+    // Worker pool: always keep `concurrency` workers running
+    let nextIndex = 0;
+    await new Promise<void>((resolveAll) => {
+      const startNext = () => {
+        if (nextIndex >= participantCount) {
+          if (completed >= participantCount) resolveAll();
+          return;
+        }
+        const i = nextIndex++;
+        spawnWorker(i).then(startNext);
+      };
+      for (let j = 0; j < Math.min(concurrency, participantCount); j++) {
+        startNext();
+      }
+    });
+
+    process.stdout.write('\n');
+
+    if (errors.length > 0) {
+      console.error(`\n${errors.length} participant(s) failed:`);
+      for (const { index, error } of errors) {
+        console.error(`  Participant ${index}: ${error}`);
+      }
+    }
+
+    console.log(`Simulation complete. ${completed - errors.length}/${participantCount} participants simulated successfully.`);
+  } finally {
+    backend.kill();
+    console.log('Backend stopped.');
+  }
+}

package/src/utils/upload.ts

@@ -0,0 +1,299 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { FileUpload, Store, TrialData } from './common';
+
+type DataObject = {
+  [key: string]: string | number | boolean | null | undefined;
+};
+
+export function escapeCsvValue(value: any): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  const stringValue = String(value);
+
+  if (stringValue.includes(',') || stringValue.includes('"') || stringValue.includes('\n')) {
+    const escapedValue = stringValue.replace(/"/g, '""');
+    return `"${escapedValue}"`;
+  }
+
+  return stringValue;
+}
+
+export function convertArrayOfObjectsToCSV(data: DataObject[]): string {
+  if (!data || data.length === 0) {
+    return '';
+  }
+
+  const headerSet = new Set<string>();
+  data.forEach((obj) => {
+    Object.keys(obj).forEach((key) => {
+      headerSet.add(key);
+    });
+  });
+  const headers = Array.from(headerSet);
+
+  const headerRow = headers.map((header) => escapeCsvValue(header)).join(',');
+
+  const dataRows = data.map((obj) => {
+    return headers
+      .map((header) => {
+        const value = obj[header];
+        return escapeCsvValue(value);
+      })
+      .join(',');
+  });
+
+  return [headerRow, ...dataRows].join('\n');
+}
+
+export const defaultFlatteningFunctions: Record<
+  string,
+  (item: TrialData) => any[] | Record<string, any[]>
+> = {
+  CanvasBlock: (item: TrialData) => {
+    const responseData = item.responseData;
+    if (Array.isArray(responseData)) {
+      return responseData.map((i) => ({
+        block: item.name,
+        ...i,
+      }));
+    }
+    return [];
+  },
+};
+
+export const transform = ({ responseData, ...obj }: any) => ({
+  ...obj,
+  ...Object.entries(responseData || {}).reduce(
+    (acc, [k, v]) => ({ ...acc, [`data_${k}`]: v }),
+    {},
+  ),
+});
+
+export type CSVBuilder = {
+  filename?: string;
+  trials?: string[];
+  fun?: (row: Record<string, any>) => Record<string, any>;
+};
+
+export function combineTrialsToCsv(
+  data: any[],
+  filename: string,
+  names: string[],
+  flatteningFunctions: Record<string, (item: any) => any[] | Record<string, any[]>>,
+  fun?: (obj: any) => any,
+): FileUpload | FileUpload[] {
+  // Collect all flattener results first, filtering out completely empty results
+  const allResults: (any[] | Record<string, any[]>)[] = names
+    .flatMap((name) => {
+      const matchingItems = data.filter((d) => d.name === name);
+
+      return matchingItems.map((item) => {
+        const flattener = item.type && flatteningFunctions[item.type];
+        const result = flattener ? flattener(item) : [transform(item)];
+
+        if (Array.isArray(result) && result.length === 0) {
+          return null;
+        }
+
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+          const hasAnyData = Object.values(result).some(
+            (val) => Array.isArray(val) && val.length > 0,
+          );
+          if (!hasAnyData) {
+            return null;
+          }
+        }
+
+        return result;
+      });
+    })
+    .filter((result) => result !== null);
+
+  const hasMultiTable = allResults.some(
+    (result) =>
+      result &&
+      typeof result === 'object' &&
+      !Array.isArray(result) &&
+      Object.keys(result).some((key) => Array.isArray(result[key])),
+  );
+
+  if (!hasMultiTable) {
+    const processedData = allResults
+      .flatMap((result) => (Array.isArray(result) ? result : []))
+      .map((x) => (fun ? fun(x) : x));
+
+    if (processedData.length === 0) {
+      return [];
+    }
+
+    return {
+      filename,
+      encoding: 'utf8' as const,
+      content: convertArrayOfObjectsToCSV(processedData),
+    };
+  }
+
+  const allTableKeys = new Set<string>();
+  allResults.forEach((result) => {
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+      Object.keys(result).forEach((key) => {
+        if (Array.isArray(result[key])) {
+          allTableKeys.add(key);
+        }
+      });
+    }
+  });
+
+  const files: FileUpload[] = [];
+
+  for (const tableKey of allTableKeys) {
+    const tableData = allResults
+      .flatMap((result) => {
+        if (Array.isArray(result)) {
+          return result;
+        } else if (result && typeof result === 'object' && result[tableKey]) {
+          return result[tableKey];
+        }
+        return [];
+      })
+      .map((x) => (fun ? fun(x) : x));
+
+    if (tableData.length === 0) {
+      continue;
+    }
+
+    const baseFilename = filename.replace(/\.csv$/, '');
+
+    files.push({
+      filename: `${baseFilename}_${tableKey}.csv`,
+      encoding: 'utf8' as const,
+      content: convertArrayOfObjectsToCSV(tableData),
+    });
+  }
+
+  if (files.length === 0) {
+    return [];
+  }
+
+  return files.length === 1 ? files[0] : files;
+}
+
+export function buildUploadFiles(config: {
+  sessionID: string;
+  data: any[];
+  store?: Store;
+  generateFiles?: (sessionID: string, data: any[], store?: Store) => FileUpload[];
+  sessionCSVBuilder?: CSVBuilder;
+  trialCSVBuilder?: {
+    flatteners: Record<string, (item: any) => any[] | Record<string, any[]>>;
+    builders: CSVBuilder[];
+  };
+  uploadRaw?: boolean;
+}): FileUpload[] {
+  const {
+    sessionID,
+    data,
+    store,
+    generateFiles,
+    sessionCSVBuilder,
+    trialCSVBuilder,
+    uploadRaw = true,
+  } = config;
+
+  const files: FileUpload[] = generateFiles ? generateFiles(sessionID, data, store) : [];
+
+  if (uploadRaw) {
+    files.push({
+      filename: `${sessionID}.raw.json`,
+      content: JSON.stringify(data),
+      encoding: 'utf8',
+    });
+  }
+
+  if (sessionCSVBuilder) {
+    type ParamDetails = {
+      value?: any;
+      defaultValue: any;
+    };
+    let paramsDict: Record<string, any> = {};
+    const paramsSource: Record<string, ParamDetails | any> | undefined =
+      data?.[0]?.responseData?.params;
+    if (paramsSource && typeof paramsSource === 'object' && paramsSource !== null) {
+      paramsDict = Object.entries(paramsSource).reduce(
+        (
+          accumulator: Record<string, any>,
+          [paramName, paramDetails]: [string, ParamDetails | any],
+        ) => {
+          if (
+            paramDetails &&
+            typeof paramDetails === 'object' &&
+            'defaultValue' in paramDetails
+          ) {
+            const chosenValue = paramDetails.value ?? paramDetails.defaultValue;
+            accumulator[paramName] = chosenValue;
+          }
+          return accumulator;
+        },
+        {} as Record<string, any>,
+      );
+    }
+
+    let content: Record<string, any> = {
+      sessionID,
+      userAgent: data?.[0]?.responseData?.userAgent,
+      ...paramsDict,
+    };
+
+    if (
+      sessionCSVBuilder.trials &&
+      Array.isArray(sessionCSVBuilder.trials) &&
+      sessionCSVBuilder.trials.length > 0
+    ) {
+      for (const trialName of sessionCSVBuilder.trials) {
+        const matchingDataElement = data.find((element) => element.name === trialName);
+
+        if (matchingDataElement?.responseData) {
+          if (
+            typeof matchingDataElement.responseData === 'object' &&
+            matchingDataElement.responseData !== null
+          ) {
+            content = { ...content, ...matchingDataElement.responseData };
+          }
+        }
+      }
+    }
+
+    files.push({
+      content: convertArrayOfObjectsToCSV([
+        sessionCSVBuilder.fun ? sessionCSVBuilder.fun(content) : content,
+      ]),
+      filename: `${sessionID}${sessionCSVBuilder.filename}.csv`,
+      encoding: 'utf8' as const,
+    });
+  }
+
+  if (trialCSVBuilder) {
+    for (const builder of trialCSVBuilder.builders) {
+      const result = combineTrialsToCsv(
+        data,
+        `${sessionID}${builder.filename}.csv`,
+        builder.trials ?? [],
+        { ...defaultFlatteningFunctions, ...trialCSVBuilder.flatteners },
+        builder.fun,
+      );
+
+      if (Array.isArray(result)) {
+        if (result.length > 0) {
+          files.push(...result);
+        }
+      } else {
+        files.push(result);
+      }
+    }
+  }
+
+  return files;
+}

package/template/README.md

@@ -85,6 +85,65 @@ To update the app, simply stop the running containers, run a `git pull` and buil
 The server will create a "data" directory in the root directory of the cloned repo,
 
 
+## Simulation
+
+You can simulate your experiment headlessly to generate synthetic data, test your data pipeline, or plan sample sizes.
+
+### Setup
+
+Define your participant generator and simulation config in `Experiment.tsx`:
+
+```tsx
+export const simulationConfig = {
+  participants: {
+    generator: (i) => ({ id: i, nickname: `participant_${i}` }),
+    count: 10,
+  },
+};
+```
+
+### Running
+
+```
+npm run simulate
+```
+
+This starts the backend, simulates all participants through the experiment, and shuts down. The simulated data ends up in `backend/data/`.
+
+### Customizing participant behavior
+
+Each trial component has default decision functions that model participant behavior. Override them per-trial using the `simulators` property on a timeline item:
+
+```tsx
+{
+  type: 'PlainInput',
+  props: { content: <p>What is your name?</p> },
+  simulators: {
+    respond: (_trialProps, participant) => ({
+      value: participant.nickname,
+      participantState: participant,
+    }),
+  },
+}
+```
+
+### Custom components
+
+Register simulations for your custom trial components using `registerSimulation`. See the `CustomTrial` example in `Experiment.tsx` and the [reactive README](https://github.com/adriansteffan/reactive) for details.
+
+### Hybrid mode
+
+During development, auto-advance simulated trials while manually interacting with others:
+
+Add `?hybridSimulation=true` to the URL:
+
+```
+http://localhost:5173?hybridSimulation=true
+```
+
+Trials with `simulators` or `simulate: true` defined will auto-advance. Others render normally for human interaction. Hybrid mode is enabled by default during development. For production, set `VITE_DISABLE_HYBRID_SIMULATION=true` to disable it.
+
+
 ## Target: Windows or MacOS
 
 ### Development

package/template/backend/src/backend.ts

@@ -95,5 +95,6 @@ if (process.env.NODE_ENV === 'production') {
 }
 
 app.listen(PORT, () => {
+  console.log(`REACTIVE_BACKEND_READY`);
   console.log(`Server is Fire at http://localhost:${PORT}`);
 });

package/template/package.json

@@ -47,6 +47,7 @@
     "dev": "vite",
     "backend": "npm run dev --prefix backend",
     "dev:all": "concurrently -n \"FRONT,BACK\" -c \"blue,green\" \"npm run dev\" \"npm run backend\"",
+    "simulate": "npx tsx simulate.ts",
     "build": "tsc && vite build",
     "test": "vitest --silent=false",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
@@ -85,6 +86,7 @@
     "@typescript-eslint/parser": "^8.16.0",
     "@vitejs/plugin-react": "^4.2.1",
     "concurrently": "^9.1.0",
+    "tsx": "^4.19.2",
     "electron": "^35.0.0",
     "electron-builder": "^25.1.8",
     "electron-vite": "^3.0.0",

package/template/simulate.ts

@@ -0,0 +1,15 @@
+import { orchestrateSimulation, simulateParticipant, setBackendUrl } from '@adriansteffan/reactive';
+import { experiment, simulationConfig } from './src/Experiment';
+
+// Each simulated participant runs as a separate subprocess to get fresh module-level
+// randomization (e.g., group assignment). The orchestrator spawns workers that re-run
+// this script with _REACTIVE_WORKER_INDEX set.
+if (process.env._REACTIVE_WORKER_INDEX) {
+  const index = parseInt(process.env._REACTIVE_WORKER_INDEX);
+  const participants = simulationConfig.participants;
+  const participant = Array.isArray(participants) ? participants[index] : participants.generator(index);
+  setBackendUrl(process.env._REACTIVE_BACKEND_URL!);
+  await simulateParticipant(experiment, participant);
+} else {
+  await orchestrateSimulation(simulationConfig, import.meta.filename);
+}