@form-engine-ts/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,211 @@
+type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
+type ConditionOperator = "equals" | "not_equals" | "contains" | "not_empty";
+type ConditionValue = string | number | boolean;
+interface DisplayCondition {
+    readonly questionId: string;
+    readonly operator: ConditionOperator;
+    readonly value?: ConditionValue;
+}
+type ValidationCode = "required" | "invalid_type" | "min_length" | "max_length" | "pattern" | "min" | "max" | "step" | "invalid_option" | "min_selections" | "max_selections" | "unknown_field";
+interface FieldOption {
+    readonly id: string;
+    readonly label: string;
+}
+interface BaseField {
+    readonly id: string;
+    readonly type: FieldType;
+    readonly title: string;
+    readonly description?: string;
+    readonly translationKey?: string;
+    readonly required: boolean;
+    readonly messages?: Partial<Record<ValidationCode, string>>;
+    readonly displayCondition?: DisplayCondition;
+}
+interface TextField extends BaseField {
+    readonly type: "text" | "textarea";
+    readonly placeholderKey?: string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+}
+interface NumberField extends BaseField {
+    readonly type: "number";
+    readonly placeholderKey?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+interface RatingField extends BaseField {
+    readonly type: "rating";
+    readonly min?: number;
+    readonly max?: number;
+}
+interface SelectField extends BaseField {
+    readonly type: "select" | "radio";
+    readonly options: readonly FieldOption[];
+}
+interface MultiSelectField extends BaseField {
+    readonly type: "multi-select";
+    readonly options: readonly FieldOption[];
+    readonly minSelections?: number;
+    readonly maxSelections?: number;
+}
+interface CheckboxField extends BaseField {
+    readonly type: "checkbox";
+}
+type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
+interface FormSchema {
+    readonly id: string;
+    readonly version: number;
+    readonly title: string;
+    readonly description?: string;
+    readonly submitLabelKey?: string;
+    readonly fields: readonly FormField[];
+}
+type FormValue = string | number | boolean | readonly string[] | undefined;
+type FormValues = Readonly<Record<string, FormValue>>;
+interface SchemaIssue {
+    readonly path: string;
+    readonly code: string;
+    readonly message: string;
+}
+type SchemaValidationResult = {
+    readonly valid: true;
+    readonly value: FormSchema;
+    readonly issues: readonly [];
+} | {
+    readonly valid: false;
+    readonly issues: readonly SchemaIssue[];
+};
+interface ValidationIssue {
+    readonly fieldId: string;
+    readonly code: ValidationCode;
+    readonly messageKey: string;
+    readonly params: Readonly<Record<string, string | number>>;
+}
+type AnswerValidationResult = {
+    readonly valid: true;
+    readonly issues: readonly [];
+} | {
+    readonly valid: false;
+    readonly issues: readonly ValidationIssue[];
+};
+interface FormSubmission {
+    readonly id: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly locale: string;
+    readonly values: FormValues;
+    readonly submittedAt: string;
+}
+interface TranslationAdapter {
+    translate(key: string, locale: string, params?: Readonly<Record<string, string | number>>): string;
+}
+interface AsyncTranslationAdapter {
+    translateText(text: string, targetLocale: string, sourceLocale?: string): Promise<string>;
+    translateBatch(texts: readonly string[], targetLocale: string, sourceLocale?: string): Promise<readonly string[]>;
+}
+interface StorageAdapter {
+    saveSubmission(submission: FormSubmission): Promise<void>;
+    listSubmissions(formId: string, formVersion?: number): Promise<readonly FormSubmission[]>;
+    clearResponses?(formId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface FormStorageAdapter extends StorageAdapter {
+    saveSchema(schema: FormSchema): Promise<void>;
+    getSchema(formId: string, formVersion: number): Promise<FormSchema | null>;
+    listSchemas(): Promise<readonly FormSchema[]>;
+    deleteSchema(formId: string, formVersion: number): Promise<void>;
+    deleteSubmission(submissionId: string): Promise<void>;
+}
+interface BaseQuestionAggregate {
+    readonly fieldId: string;
+    readonly answeredCount: number;
+    readonly unansweredCount: number;
+}
+interface TextQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "text" | "textarea";
+}
+interface NumberQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "number" | "rating";
+    readonly minimum: number | null;
+    readonly maximum: number | null;
+    readonly average: number | null;
+    readonly total: number;
+}
+interface OptionAggregate {
+    readonly id: string;
+    readonly count: number;
+    readonly percentageOfSubmissions: number;
+}
+interface ChoiceQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "select" | "radio" | "multi-select";
+    readonly options: readonly OptionAggregate[];
+}
+interface CheckboxQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "checkbox";
+    readonly trueCount: number;
+    readonly falseCount: number;
+    readonly truePercentageOfSubmissions: number;
+    readonly falsePercentageOfSubmissions: number;
+}
+type QuestionAggregate = TextQuestionAggregate | NumberQuestionAggregate | ChoiceQuestionAggregate | CheckboxQuestionAggregate;
+interface FormAnalytics {
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly submissionCount: number;
+    readonly questions: readonly QuestionAggregate[];
+}
+type Question = FormField;
+type QuestionType = FieldType;
+type ChoiceOption = FieldOption;
+type FormResponse = FormSubmission;
+
+interface ChoiceDistributionEntry {
+    readonly count: number;
+    readonly percentage: number;
+}
+interface NumericSummary {
+    readonly average: number | null;
+    readonly min: number | null;
+    readonly max: number | null;
+    readonly total: number;
+}
+declare function calculateChoiceDistribution(responses: readonly FormSubmission[], questionId: string): Record<string, ChoiceDistributionEntry>;
+declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
+declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
+declare function escapeCsvCell(value: string | number | null | undefined): string;
+interface CsvExportOptions {
+    readonly withBom?: boolean;
+}
+declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
+
+type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
+interface SchemaStructureIssue {
+    readonly type: SchemaStructureIssueType;
+    readonly questionId: string;
+    readonly choiceId?: string;
+    readonly message: string;
+}
+declare function validateSchemaStructure(schema: FormSchema): SchemaStructureIssue[];
+declare function sanitizeSchema(schema: FormSchema): FormSchema;
+
+declare function validateFormSchema(input: unknown): SchemaValidationResult;
+declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
+
+interface CreateSubmissionOptions {
+    readonly id: string;
+    readonly locale: string;
+    readonly submittedAt: string;
+}
+declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
+
+declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
+
+declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
+
+declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
+declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
+declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
+
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormField, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaValidationResult, type SelectField, type StorageAdapter, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateFieldVisibility, calculateNumericSummary, createSubmission, escapeCsvCell, exportResponsesToCsv, isQuestionVisible, resolveFormTranslation, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validateSchemaStructure };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
+type ConditionOperator = "equals" | "not_equals" | "contains" | "not_empty";
+type ConditionValue = string | number | boolean;
+interface DisplayCondition {
+    readonly questionId: string;
+    readonly operator: ConditionOperator;
+    readonly value?: ConditionValue;
+}
+type ValidationCode = "required" | "invalid_type" | "min_length" | "max_length" | "pattern" | "min" | "max" | "step" | "invalid_option" | "min_selections" | "max_selections" | "unknown_field";
+interface FieldOption {
+    readonly id: string;
+    readonly label: string;
+}
+interface BaseField {
+    readonly id: string;
+    readonly type: FieldType;
+    readonly title: string;
+    readonly description?: string;
+    readonly translationKey?: string;
+    readonly required: boolean;
+    readonly messages?: Partial<Record<ValidationCode, string>>;
+    readonly displayCondition?: DisplayCondition;
+}
+interface TextField extends BaseField {
+    readonly type: "text" | "textarea";
+    readonly placeholderKey?: string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+}
+interface NumberField extends BaseField {
+    readonly type: "number";
+    readonly placeholderKey?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+}
+interface RatingField extends BaseField {
+    readonly type: "rating";
+    readonly min?: number;
+    readonly max?: number;
+}
+interface SelectField extends BaseField {
+    readonly type: "select" | "radio";
+    readonly options: readonly FieldOption[];
+}
+interface MultiSelectField extends BaseField {
+    readonly type: "multi-select";
+    readonly options: readonly FieldOption[];
+    readonly minSelections?: number;
+    readonly maxSelections?: number;
+}
+interface CheckboxField extends BaseField {
+    readonly type: "checkbox";
+}
+type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
+interface FormSchema {
+    readonly id: string;
+    readonly version: number;
+    readonly title: string;
+    readonly description?: string;
+    readonly submitLabelKey?: string;
+    readonly fields: readonly FormField[];
+}
+type FormValue = string | number | boolean | readonly string[] | undefined;
+type FormValues = Readonly<Record<string, FormValue>>;
+interface SchemaIssue {
+    readonly path: string;
+    readonly code: string;
+    readonly message: string;
+}
+type SchemaValidationResult = {
+    readonly valid: true;
+    readonly value: FormSchema;
+    readonly issues: readonly [];
+} | {
+    readonly valid: false;
+    readonly issues: readonly SchemaIssue[];
+};
+interface ValidationIssue {
+    readonly fieldId: string;
+    readonly code: ValidationCode;
+    readonly messageKey: string;
+    readonly params: Readonly<Record<string, string | number>>;
+}
+type AnswerValidationResult = {
+    readonly valid: true;
+    readonly issues: readonly [];
+} | {
+    readonly valid: false;
+    readonly issues: readonly ValidationIssue[];
+};
+interface FormSubmission {
+    readonly id: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly locale: string;
+    readonly values: FormValues;
+    readonly submittedAt: string;
+}
+interface TranslationAdapter {
+    translate(key: string, locale: string, params?: Readonly<Record<string, string | number>>): string;
+}
+interface AsyncTranslationAdapter {
+    translateText(text: string, targetLocale: string, sourceLocale?: string): Promise<string>;
+    translateBatch(texts: readonly string[], targetLocale: string, sourceLocale?: string): Promise<readonly string[]>;
+}
+interface StorageAdapter {
+    saveSubmission(submission: FormSubmission): Promise<void>;
+    listSubmissions(formId: string, formVersion?: number): Promise<readonly FormSubmission[]>;
+    clearResponses?(formId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface FormStorageAdapter extends StorageAdapter {
+    saveSchema(schema: FormSchema): Promise<void>;
+    getSchema(formId: string, formVersion: number): Promise<FormSchema | null>;
+    listSchemas(): Promise<readonly FormSchema[]>;
+    deleteSchema(formId: string, formVersion: number): Promise<void>;
+    deleteSubmission(submissionId: string): Promise<void>;
+}
+interface BaseQuestionAggregate {
+    readonly fieldId: string;
+    readonly answeredCount: number;
+    readonly unansweredCount: number;
+}
+interface TextQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "text" | "textarea";
+}
+interface NumberQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "number" | "rating";
+    readonly minimum: number | null;
+    readonly maximum: number | null;
+    readonly average: number | null;
+    readonly total: number;
+}
+interface OptionAggregate {
+    readonly id: string;
+    readonly count: number;
+    readonly percentageOfSubmissions: number;
+}
+interface ChoiceQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "select" | "radio" | "multi-select";
+    readonly options: readonly OptionAggregate[];
+}
+interface CheckboxQuestionAggregate extends BaseQuestionAggregate {
+    readonly kind: "checkbox";
+    readonly trueCount: number;
+    readonly falseCount: number;
+    readonly truePercentageOfSubmissions: number;
+    readonly falsePercentageOfSubmissions: number;
+}
+type QuestionAggregate = TextQuestionAggregate | NumberQuestionAggregate | ChoiceQuestionAggregate | CheckboxQuestionAggregate;
+interface FormAnalytics {
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly submissionCount: number;
+    readonly questions: readonly QuestionAggregate[];
+}
+type Question = FormField;
+type QuestionType = FieldType;
+type ChoiceOption = FieldOption;
+type FormResponse = FormSubmission;
+
+interface ChoiceDistributionEntry {
+    readonly count: number;
+    readonly percentage: number;
+}
+interface NumericSummary {
+    readonly average: number | null;
+    readonly min: number | null;
+    readonly max: number | null;
+    readonly total: number;
+}
+declare function calculateChoiceDistribution(responses: readonly FormSubmission[], questionId: string): Record<string, ChoiceDistributionEntry>;
+declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
+declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
+declare function escapeCsvCell(value: string | number | null | undefined): string;
+interface CsvExportOptions {
+    readonly withBom?: boolean;
+}
+declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
+
+type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
+interface SchemaStructureIssue {
+    readonly type: SchemaStructureIssueType;
+    readonly questionId: string;
+    readonly choiceId?: string;
+    readonly message: string;
+}
+declare function validateSchemaStructure(schema: FormSchema): SchemaStructureIssue[];
+declare function sanitizeSchema(schema: FormSchema): FormSchema;
+
+declare function validateFormSchema(input: unknown): SchemaValidationResult;
+declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
+
+interface CreateSubmissionOptions {
+    readonly id: string;
+    readonly locale: string;
+    readonly submittedAt: string;
+}
+declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
+
+declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
+
+declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
+
+declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
+declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
+declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
+
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormField, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaValidationResult, type SelectField, type StorageAdapter, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateFieldVisibility, calculateNumericSummary, createSubmission, escapeCsvCell, exportResponsesToCsv, isQuestionVisible, resolveFormTranslation, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validateSchemaStructure };