https://github.com/marcomuser/conformal
Type-safe form submissions for the modern web.
https://github.com/marcomuser/conformal
formdata schema submission typescript
Last synced: 2 months ago
JSON representation
Type-safe form submissions for the modern web.
- Host: GitHub
- URL: https://github.com/marcomuser/conformal
- Owner: marcomuser
- License: mit
- Created: 2025-08-22T12:02:09.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-19T10:08:46.000Z (8 months ago)
- Last Synced: 2026-01-16T05:18:55.325Z (5 months ago)
- Topics: formdata, schema, submission, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/conformal
- Size: 250 KB
- Stars: 35
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Conformal
> Type-safe form submissions for the modern web.
Conformal helps you work with native [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData). It solves two major pain points:
- ✅ **Strongly typed FormData parsing** – Turn native `FormData` into real objects with full TypeScript inference (nested objects and arrays with dot/bracket notation).
- ✅ **Canonical submission flow** – A single `Submission` object that preserves raw input, separates field vs. form errors, and standardizes the success/error states.
Works everywhere: In browsers, Node.js, and edge runtimes with React, Vue, Svelte, or vanilla JavaScript.
### Table of Contents
- [Getting Started](#getting-started)
- [Live Examples](#live-examples)
- [API Reference](#api-reference)
- [License](#license)
## Getting Started
Install Conformal via npm or the package manager of your choice:
```bash
npm install conformal
```
Here's a quick example showing how Conformal handles form validation with a user registration form:
```typescript
import { parseFormData } from "conformal";
import * as z from "zod";
// Tip: Use conformal's coerce functions for form input preprocessing
const schema = z.object({
name: z.string().min(2, "Name must be at least 2 characters"),
email: z.email("Invalid email address"),
age: z.coerce.number().min(18, "Must be at least 18 years old"),
acceptTerms: z.coerce.boolean(),
});
// In your form action or handler
const result = parseFormData(schema, formData);
const submission = result.submission();
if (submission.status === "success") {
// submission.value is fully typed: { name: string, email: string, age: number, acceptTerms: boolean }
console.log("User registered:", submission.value);
} else {
// submission.fieldErrors contains validation errors: { email: ["Invalid email address"] }
console.log("Validation errors:", submission.fieldErrors);
// submission.input preserves the raw user input for re-display
console.log("User input:", submission.input);
}
```
That's it! Conformal automatically handles FormData parsing, type coercion, and provides a clean submission interface.
## Live Examples
- **React** - Form actions with useActionState: [StackBlitz](https://stackblitz.com/github/marcomuser/conformal/tree/main/examples/react?embed=1&theme=dark&preset=node&file=src/Form.tsx) | [Source](https://github.com/marcomuser/conformal/tree/main/examples/react)
- **SvelteKit** - Server-side form actions: [StackBlitz](https://stackblitz.com/github/marcomuser/conformal/tree/main/examples/svelte?embed=1&theme=dark&preset=node&file=src/routes/%2Bpage.server.ts) | [Source](https://github.com/marcomuser/conformal/tree/main/examples/svelte)
## API Reference
### Functions
- **[`parseFormData`](src/README.md#parseformdata)** - Parse FormData with schema validation and get Submission object
- **[`decode`](src/README.md#decode)** - Convert FormData to structured objects (no validation)
- **[`serialize`](src/README.md#serialize)** - Transform typed values back to form-compatible strings
- **[`getPath`](src/README.md#getpath)** - Safely access nested values using dot/bracket notation
- **[`setPath`](src/README.md#setpath)** - Immutably set nested values using dot/bracket notation
- **[`coerceX`](src/README.md#coerce-functions)** - A set of coercion functions for use with schema libraries
### Types
- **[`Submission`](src/README.md#submission)** - Standardized submission result with success/error states
- **[`PathsFromObject`](src/README.md#pathsfromobject)** - Type utility to extract all possible object paths
### Valibot Utilities
> ⚠️ **Experimental**: These utilities are still in development and may change.
- **[Coercion Pipes](src/valibot/README.md#coercion-pipes)** - Pipes for automatic form input preprocessing
## License
Conformal is licensed under the MIT License.