@form-engine-ts/core 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -6,10 +6,16 @@ interface DisplayCondition {
     readonly operator: ConditionOperator;
     readonly value?: ConditionValue;
 }
+interface LocalizedText {
+    readonly title?: string;
+    readonly description?: string;
+}
+type SchemaTranslations = Readonly<Record<string, LocalizedText>>;
 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;
+    readonly translations?: Readonly<Record<string, string>>;
 }
 interface BaseField {
     readonly id: string;
@@ -20,6 +26,7 @@ interface BaseField {
     readonly required: boolean;
     readonly messages?: Partial<Record<ValidationCode, string>>;
     readonly displayCondition?: DisplayCondition;
+    readonly translations?: SchemaTranslations;
 }
 interface TextField extends BaseField {
     readonly type: "text" | "textarea";
@@ -54,13 +61,25 @@ interface CheckboxField extends BaseField {
     readonly type: "checkbox";
 }
 type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
+interface FormPage {
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly questionIds: readonly string[];
+    readonly displayCondition?: DisplayCondition;
+    readonly translations?: SchemaTranslations;
+}
 interface FormSchema {
     readonly id: string;
     readonly version: number;
     readonly title: string;
     readonly description?: string;
     readonly submitLabelKey?: string;
+    readonly defaultLocale?: string;
+    readonly supportedLocales?: readonly string[];
+    readonly translations?: SchemaTranslations;
     readonly fields: readonly FormField[];
+    readonly pages?: readonly FormPage[];
 }
 type FormValue = string | number | boolean | readonly string[] | undefined;
 type FormValues = Readonly<Record<string, FormValue>>;
@@ -105,9 +124,13 @@ interface AsyncTranslationAdapter {
     translateText(text: string, targetLocale: string, sourceLocale?: string): Promise<string>;
     translateBatch(texts: readonly string[], targetLocale: string, sourceLocale?: string): Promise<readonly string[]>;
 }
+interface SubmissionQueryOptions {
+    readonly since?: string;
+    readonly until?: string;
+}
 interface StorageAdapter {
     saveSubmission(submission: FormSubmission): Promise<void>;
-    listSubmissions(formId: string, formVersion?: number): Promise<readonly FormSubmission[]>;
+    listSubmissions(formId: string, formVersion?: number, options?: SubmissionQueryOptions): Promise<readonly FormSubmission[]>;
     clearResponses?(formId: string): Promise<void>;
     clear(): Promise<void>;
 }
@@ -160,6 +183,14 @@ type Question = FormField;
 type QuestionType = FieldType;
 type ChoiceOption = FieldOption;
 type FormResponse = FormSubmission;
+interface CrossTabulationResult {
+    readonly rowQuestionId: string;
+    readonly colQuestionId: string;
+    readonly matrix: Readonly<Record<string, Readonly<Record<string, number>>>>;
+    readonly rowTotals: Readonly<Record<string, number>>;
+    readonly colTotals: Readonly<Record<string, number>>;
+    readonly grandTotal: number;
+}
 
 interface ChoiceDistributionEntry {
     readonly count: number;
@@ -173,6 +204,7 @@ interface NumericSummary {
 }
 declare function calculateChoiceDistribution(responses: readonly FormSubmission[], questionId: string): Record<string, ChoiceDistributionEntry>;
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
+declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
 declare function escapeCsvCell(value: string | number | null | undefined): string;
 interface CsvExportOptions {
@@ -180,6 +212,27 @@ interface CsvExportOptions {
 }
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
+type FormEventType = "response.submitted" | "schema.updated";
+interface FormEvent<T = unknown> {
+    readonly id: string;
+    readonly type: FormEventType;
+    readonly formId: string;
+    readonly timestamp: string;
+    readonly payload: T;
+}
+interface WebhookConfig {
+    readonly url: string;
+    readonly secret?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+}
+interface WebhookDispatchResult {
+    readonly success: boolean;
+    readonly status?: number;
+    readonly error?: string;
+}
+declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig, fetchImpl?: typeof fetch): Promise<WebhookDispatchResult>;
+
 type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
 interface SchemaStructureIssue {
     readonly type: SchemaStructureIssueType;
@@ -200,12 +253,17 @@ interface CreateSubmissionOptions {
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+declare function resolveLocalizedSchema(schema: FormSchema, targetLocale: string): FormSchema;
+declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter): Promise<FormSchema>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
+declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
 
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
+declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
+declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, 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 };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type LocalizedText, 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 SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -6,10 +6,16 @@ interface DisplayCondition {
     readonly operator: ConditionOperator;
     readonly value?: ConditionValue;
 }
+interface LocalizedText {
+    readonly title?: string;
+    readonly description?: string;
+}
+type SchemaTranslations = Readonly<Record<string, LocalizedText>>;
 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;
+    readonly translations?: Readonly<Record<string, string>>;
 }
 interface BaseField {
     readonly id: string;
@@ -20,6 +26,7 @@ interface BaseField {
     readonly required: boolean;
     readonly messages?: Partial<Record<ValidationCode, string>>;
     readonly displayCondition?: DisplayCondition;
+    readonly translations?: SchemaTranslations;
 }
 interface TextField extends BaseField {
     readonly type: "text" | "textarea";
@@ -54,13 +61,25 @@ interface CheckboxField extends BaseField {
     readonly type: "checkbox";
 }
 type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
+interface FormPage {
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly questionIds: readonly string[];
+    readonly displayCondition?: DisplayCondition;
+    readonly translations?: SchemaTranslations;
+}
 interface FormSchema {
     readonly id: string;
     readonly version: number;
     readonly title: string;
     readonly description?: string;
     readonly submitLabelKey?: string;
+    readonly defaultLocale?: string;
+    readonly supportedLocales?: readonly string[];
+    readonly translations?: SchemaTranslations;
     readonly fields: readonly FormField[];
+    readonly pages?: readonly FormPage[];
 }
 type FormValue = string | number | boolean | readonly string[] | undefined;
 type FormValues = Readonly<Record<string, FormValue>>;
@@ -105,9 +124,13 @@ interface AsyncTranslationAdapter {
     translateText(text: string, targetLocale: string, sourceLocale?: string): Promise<string>;
     translateBatch(texts: readonly string[], targetLocale: string, sourceLocale?: string): Promise<readonly string[]>;
 }
+interface SubmissionQueryOptions {
+    readonly since?: string;
+    readonly until?: string;
+}
 interface StorageAdapter {
     saveSubmission(submission: FormSubmission): Promise<void>;
-    listSubmissions(formId: string, formVersion?: number): Promise<readonly FormSubmission[]>;
+    listSubmissions(formId: string, formVersion?: number, options?: SubmissionQueryOptions): Promise<readonly FormSubmission[]>;
     clearResponses?(formId: string): Promise<void>;
     clear(): Promise<void>;
 }
@@ -160,6 +183,14 @@ type Question = FormField;
 type QuestionType = FieldType;
 type ChoiceOption = FieldOption;
 type FormResponse = FormSubmission;
+interface CrossTabulationResult {
+    readonly rowQuestionId: string;
+    readonly colQuestionId: string;
+    readonly matrix: Readonly<Record<string, Readonly<Record<string, number>>>>;
+    readonly rowTotals: Readonly<Record<string, number>>;
+    readonly colTotals: Readonly<Record<string, number>>;
+    readonly grandTotal: number;
+}
 
 interface ChoiceDistributionEntry {
     readonly count: number;
@@ -173,6 +204,7 @@ interface NumericSummary {
 }
 declare function calculateChoiceDistribution(responses: readonly FormSubmission[], questionId: string): Record<string, ChoiceDistributionEntry>;
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
+declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
 declare function escapeCsvCell(value: string | number | null | undefined): string;
 interface CsvExportOptions {
@@ -180,6 +212,27 @@ interface CsvExportOptions {
 }
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
+type FormEventType = "response.submitted" | "schema.updated";
+interface FormEvent<T = unknown> {
+    readonly id: string;
+    readonly type: FormEventType;
+    readonly formId: string;
+    readonly timestamp: string;
+    readonly payload: T;
+}
+interface WebhookConfig {
+    readonly url: string;
+    readonly secret?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+}
+interface WebhookDispatchResult {
+    readonly success: boolean;
+    readonly status?: number;
+    readonly error?: string;
+}
+declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig, fetchImpl?: typeof fetch): Promise<WebhookDispatchResult>;
+
 type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
 interface SchemaStructureIssue {
     readonly type: SchemaStructureIssueType;
@@ -200,12 +253,17 @@ interface CreateSubmissionOptions {
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+declare function resolveLocalizedSchema(schema: FormSchema, targetLocale: string): FormSchema;
+declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter): Promise<FormSchema>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
+declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
 
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
+declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
+declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, 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 };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type LocalizedText, 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 SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };