@formdata/parser NPM

@formdata/parser

A specialized parser for Form-Data text-based form definitions. This package converts the .fd format into structured JSON that can be used to render forms.

Installation

npm install @formdata/parser

Features

📋 Simple Syntax: Parse the human-readable .fd format
🧩 Form Structure: Convert form definitions into structured objects
⚠️ Error Handling: Detailed error reporting for validation
🔍 Diagnostics: Editor-compatible diagnostics for IDEs
📐 Extensible: Supports numerous input types and validations

Usage

import { parseFormDefinition } from '@formdata/parser';

// Form definition in .fd format
const formContent = `
type form
name Contact form
action https://example.com/submit
message Thank you for your message!
design
    theme light
    background #f5f5f5

type h1
text Contact Us

type text
name full_name
label Full Name
placeholder Enter your name
validations required|length:3,50

type email
name email_address
label Email Address
placeholder you@example.com
validations required|email

type submit
label Send Message
`;

// Parse the definition
const result = parseFormDefinition(formContent);

console.log(result.name); // "Contact form"
console.log(result.endpoint); // "https://example.com/submit"
console.log(result.blocks); // Array of form elements
console.log(result.errors); // Array of any parsing errors

Form Definition Format

The .fd format uses a simple syntax with indentation for nesting:

Basic Structure

type <block_type>
property1 value1
property2 value2
nested_property
    key1 value1
    key2 value2

Example Form

type form
name my_contact_form
action https://example.com/submit
message Thank you for contacting us!
design
    theme light
    background #f5f5f5

type h1
text Contact Us

type text
name full_name
label Full Name
placeholder Enter your full name
validations required|length:3,50

type email
name email
label Email Address
placeholder example@domain.com
validations required|email

type submit
label Send Message

Supported Block Types

Block Type	Description
`form`	The root form element
`h1` to `h6`	Heading elements
`text`	Text input field
`email`	Email input field
`tel`	Telephone input field
`date`	Date input field
`textarea`	Multiline text area
`select`	Dropdown select field
`radio`	Radio button group
`checkbox`	Single checkbox
`checkboxGroup`	Group of checkboxes
`file`	File upload field
`slider`	Range slider input
`rating`	Star rating input
`button`	Generic button
`submit`	Submit button

Common Properties

Most form elements support these properties:

Property	Description
`name`	Field name (used in form submission)
`label`	Display label for the field
`placeholder`	Placeholder text
`validations`	Validation rules separated by pipe (`\\|`)
`default`	Default value
`help`	Help text displayed below the field
`attributes`	Custom HTML attributes

Indented Properties

Some properties use indentation for nested values:

Design Settings

type form
name my_form
design
    theme dark
    background #333333

Options for Select, Radio, and CheckboxGroup

type select
name fruit
label Choose a fruit
options
    Apple
        value apple
    Banana
        value banana
    Orange
        value orange

Validation Rules

Validation rules are specified using a pipe-separated format:

validations required|length:3,50|email

Common validation rules:

required: Field must not be empty
email: Must be a valid email
length:min,max: Text length constraints
min:value: Minimum value (for numeric inputs)
max:value: Maximum value (for numeric inputs)
matches:/regex/: Custom regex pattern

Error Handling

The parser returns detailed error information:

const result = parseFormDefinition(formContent);

if (result.errors.length > 0) {
  result.errors.forEach(error => {
    console.log(`Line ${error.line}: ${error.message} (${error.code})`);
  });
}

Error codes:

PROPERTY_NOT_SUPPORTED: Property not supported for the block type
MISSING_REQUIRED_PROPERTY: Missing a required property
INVALID_INDENTATION: Incorrect indentation structure
INVALID_BLOCK_TYPE: Unknown block type
INVALID_PROPERTY_VALUE: Invalid property value
DUPLICATE_PROPERTY: Property defined multiple times

Editor Integration

The parser includes utilities for IDE/editor integration:

import { createDiagnostics } from '@formdata/parser';

// Create CodeMirror-compatible diagnostics
const diagnostics = createDiagnostics(formContent, result.errors);