Pollway NPM Package

A TypeScript library for handling survey flow logic and navigation.

Installation

npm install pollway

Core Functions

getNextQuestion(surveyData, currentQuestionId, response)

Determines the next question in a survey based on the current question and user response.

• Parameters:
  • surveyData: Object containing survey questions and branches
  • currentQuestionId: String ID of the current question
  • response: User's response (string or string[])
• Returns: String ID of the next question or null if no next question exists

getPreviousQuestion(surveyData, currentQuestionId, previousResponse)

Navigates to the previous question in the survey flow based on the current question and the previous response.

• Parameters:
  • surveyData: Object containing survey questions and branches
  • currentQuestionId: String ID of the current question
  • previousResponse: Previous user's response (string or string[])
• Returns: String ID of the previous question or null if:
  • No incoming branches exist
  • No matching conditional branch is found
  • No default branch exists

The function works by:

1. Finding all branches that point to the current question
2. For speech-type questions, returns the first incoming question
3. For other questions, evaluates branch conditions against the previous response
4. Falls back to an unconditional branch if no conditional branches match

encodeSurvey(surveyData)

Encodes survey data for transmission or storage.

decodeSurvey(encodedData)

Decodes previously encoded survey data.

Types

Question Types

type QuestionType = 'multipleChoice' | 'multipleSelect' | 'textInput' | 'speech'

Question Categories

type QuestionCategory = 'generic' | 'speech' | 'call to action' | 'voting' | 'volunteering' | 'personal info'

Core Interfaces

Question

Represents a survey question:

interface Question {
  id: string
  category: QuestionCategory
  type: QuestionType
  label: QuestionLabel
  text: string
  icon: string
  options: string[]
  position: Position
  color: string
  isStartingPoint?: boolean
  isEditingInput?: boolean
  isEndingQuestion?: boolean
  validation?: {
    pattern?: string
    format?: string
    errorMessage?: string
  }
  customProperties?: {
    wasCustomized?: boolean
    [key: string]: any
  }
}

Branch

Defines the connection between questions:

interface Branch {
  id: string
  fromId: string
  toId: string
  conditions: BranchCondition[]
  selectedOption?: string
}

Session

Represents a survey session:

interface Session {
  id: string
  timestamp: number
  name?: string
  questions: Question[]
  branches: Branch[]
}

Branch Conditions

RegexCondition

interface RegexCondition {
  type: 'regex'
  pattern: string
}

OptionCondition

interface OptionCondition {
  type: 'option'
  value: string
}

SurveyData

interface SurveyData {
  questions: Question[]
  branches: Branch[]
}

Usage Example

import {
  getNextQuestion,
  getPreviousQuestion,
  encodeSurvey,
  decodeSurvey
  type SurveyData,
} from 'pollway';

type Direction = 'forward' | 'backward'

// Create survey data
const surveyData: SurveyData = {
  questions: [...],
  branches: [...]
};

// Navigate forward based on response
const nextQuestionId = getNextQuestion(surveyData, 'question1', 'Yes');

// Navigate backward based on previous response
const previousQuestionId = getPreviousQuestion(surveyData, 'question2', 'Yes');

// Encode survey for storage
const encoded = encodeSurvey(surveyData);

// Decode survey data
const decoded = decodeSurvey(encoded);

// Example of handling navigation in both directions
function navigateSurvey(
  surveyData,
  currentQuestionId,
  response,
  direction: 'forward' | 'backward'
): string | null {
  if (direction === 'forward') {
    return getNextQuestion(surveyData, currentQuestionId, response);
  } else {
    return getPreviousQuestion(surveyData, currentQuestionId, response);
  }
}