Core Utilities — API Reference

Framework-agnostic functions and classes exported from react-minimal-survey-builder/core. Use these in any JavaScript or TypeScript project — no React required.

Import

import {
  parseSchema,
  getAllQuestions,
  findQuestion,
  generateId,
  SurveySchemaError,
  validateQuestion,
  validatePage,
  validateSurvey,
  evaluateCondition,
  getVisibleQuestionIds,
  getVisiblePages,
  getVisibleQuestionsForPage,
  SurveyStateManager,
  createSurveyManager,
} from 'react-minimal-survey-builder/core';

Schema Parser

parseSchema

parseSchematypescript

function parseSchema(schema: SurveySchema): SurveySchema;

// Validates and normalises a schema. Throws SurveySchemaError on invalid input.
const parsed = parseSchema(rawSchema);

getAllQuestions

getAllQuestionstypescript

function getAllQuestions(schema: SurveySchema): Question[];

// Flattens all questions from all pages into a single array.
const questions = getAllQuestions(schema);

findQuestion

findQuestiontypescript

function findQuestion(schema: SurveySchema, questionId: string): Question | undefined;

const q = findQuestion(schema, 'email');

generateId

generateIdtypescript

function generateId(): string;

// Generates a unique ID string for new questions or pages.
const id = generateId(); // e.g. "q_abc123"

SurveySchemaError

SurveySchemaErrortypescript

class SurveySchemaError extends Error {
  constructor(message: string);
}

// Thrown by parseSchema when the schema is invalid.
try {
  parseSchema(badSchema);
} catch (e) {
  if (e instanceof SurveySchemaError) {
    console.error('Invalid schema:', e.message);
  }
}

Validation Engine

validateQuestion

validateQuestiontypescript

function validateQuestion(
  question: Question,
  value: AnswerValue,
  answers?: SurveyAnswers
): ValidationError[];

const errors = validateQuestion(
  { id: 'name', type: 'text', label: 'Name', required: true },
  ''
);
// [{ questionId: 'name', message: 'This field is required', rule: 'required' }]

validatePage

validatePagetypescript

function validatePage(
  page: Page,
  answers: SurveyAnswers
): ValidationError[];

const errors = validatePage(schema.pages[0], { name: '' });

validateSurvey

validateSurveytypescript

function validateSurvey(
  schema: SurveySchema,
  answers: SurveyAnswers
): ValidationError[];

const allErrors = validateSurvey(schema, answers);

Condition Evaluator

evaluateCondition

evaluateConditiontypescript

function evaluateCondition(
  condition: string | undefined,
  answers: SurveyAnswers
): boolean;

evaluateCondition("{role} === 'admin'", { role: 'admin' });  // true
evaluateCondition("{age} >= 18", { age: 16 });                // false
evaluateCondition(undefined, {});                             // true (no condition)

getVisibleQuestionIds

getVisibleQuestionIdstypescript

function getVisibleQuestionIds(
  schema: SurveySchema,
  answers: SurveyAnswers
): Set<string>;

const visibleIds = getVisibleQuestionIds(schema, answers);
// Set { 'name', 'email', 'satisfaction' }

getVisiblePages

getVisiblePagestypescript

function getVisiblePages(
  schema: SurveySchema,
  answers: SurveyAnswers
): Page[];

const pages = getVisiblePages(schema, answers);

getVisibleQuestionsForPage

getVisibleQuestionsForPagetypescript

function getVisibleQuestionsForPage(
  page: Page,
  answers: SurveyAnswers
): Question[];

const questions = getVisibleQuestionsForPage(schema.pages[0], answers);

SurveyStateManager

A framework-agnostic class that manages the full survey lifecycle — answers, validation, navigation, visibility, and events:

SurveyStateManagertypescript

class SurveyStateManager {
  constructor(schema: SurveySchema, options?: SurveyOptions);

  // Getters
  getState(): SurveyState;
  getSchema(): SurveySchema;
  getAnswers(): SurveyAnswers;
  getCurrentPage(): Page | null;
  getCurrentPageIndex(): number;
  getTotalPages(): number;
  getErrors(): ValidationError[];
  isValid(): boolean;

  // Mutations
  setAnswer(id: string, value: AnswerValue): void;
  setAnswers(answers: SurveyAnswers): void;
  nextPage(): boolean;
  prevPage(): void;
  goToPage(index: number): boolean;
  validate(): boolean;
  validateCurrentPage(): boolean;
  submit(): Promise<void>;
  reset(): void;

  // Events
  on(event: SurveyEventType, handler: SurveyEventHandler): () => void;
  onStateChange(callback: (state: SurveyState) => void): () => void;
}

createSurveyManager

createSurveyManagertypescript

function createSurveyManager(
  schema: SurveySchema,
  options?: SurveyOptions
): SurveyStateManager;

// Factory function — equivalent to new SurveyStateManager(schema, options)
const manager = createSurveyManager(schema, {
  onSubmit: (answers) => console.log(answers),
});

// Set answers
manager.setAnswer('name', 'Alice');

// Navigate
manager.nextPage();

// Listen for events
const unsubscribe = manager.on('answerChanged', (event) => {
  console.log('Answer changed:', event.payload);
});

// Listen for state changes
manager.onStateChange((state) => {
  console.log('Current page:', state.currentPageIndex);
  console.log('Errors:', state.errors);
});

// Clean up
unsubscribe();

When to Use Core?

Use the core module when you need the survey engine outside of React — for example, in a Vue app, a Node.js server, or a vanilla JavaScript project. The React useSurvey hook is built on top of these same utilities.