|
2 | 2 |
|
3 | 3 | ### Table of Contents |
4 | 4 |
|
5 | | -- [Functions](#functions) |
| 5 | +- [Core Functions](#core-functions) |
6 | 6 | - [parseFormData](#parseformdata) |
7 | 7 | - [decode](#decode) |
8 | 8 | - [serialize](#serialize) |
9 | 9 | - [getPath](#getpath) |
10 | 10 | - [setPath](#setpath) |
| 11 | +- [Coerce Functions](#coerce-functions) |
| 12 | + - [coerceString](#coercestring) |
| 13 | + - [coerceNumber](#coercenumber) |
| 14 | + - [coerceBigint](#coercebigint) |
| 15 | + - [coerceBoolean](#coerceboolean) |
| 16 | + - [coerceDate](#coercedate) |
| 17 | + - [coerceFile](#coercefile) |
| 18 | + - [coerceArray](#coercearray) |
11 | 19 | - [Types](#types) |
12 | 20 | - [Submission](#submission) |
13 | 21 | - [PathsFromObject](#pathsfromobject) |
14 | 22 |
|
15 | | -## Functions |
| 23 | +## Core Functions |
16 | 24 |
|
17 | 25 | ### parseFormData |
18 | 26 |
|
@@ -107,6 +115,107 @@ const newObj = setPath({ a: { b: { c: [] } } }, "a.b.c[1]", "hey"); |
107 | 115 | // Returns { a: { b: { c: [<empty>, 'hey'] } } } |
108 | 116 | ``` |
109 | 117 |
|
| 118 | +## Coerce Functions |
| 119 | + |
| 120 | +The coerce functions provide utilities for converting form input values to their expected types. These functions are essential for building custom schema implementations (like zod or valibot schemas) where you need to transform string-based form data into proper JavaScript types before validation. All coerce functions handle empty strings by returning `undefined` and pass through non-matching types unchanged, making them safe to use in schema transformation pipelines. |
| 121 | + |
| 122 | +### coerceString |
| 123 | + |
| 124 | +Converts string input to a string value, returning `undefined` for empty strings. |
| 125 | + |
| 126 | +```typescript |
| 127 | +import { coerceString } from "conformal"; |
| 128 | + |
| 129 | +console.log(coerceString("hello")); // "hello" |
| 130 | +console.log(coerceString("")); // undefined |
| 131 | +console.log(coerceString(123)); // 123 (unchanged) |
| 132 | +``` |
| 133 | + |
| 134 | +### coerceNumber |
| 135 | + |
| 136 | +Converts string input to a number, returning `undefined` for empty or whitespace-only strings. |
| 137 | + |
| 138 | +```typescript |
| 139 | +import { coerceNumber } from "conformal"; |
| 140 | + |
| 141 | +console.log(coerceNumber("42")); // 42 |
| 142 | +console.log(coerceNumber("3.14")); // 3.14 |
| 143 | +console.log(coerceNumber("")); // undefined |
| 144 | +console.log(coerceNumber(" ")); // undefined |
| 145 | +console.log(coerceNumber("abc")); // NaN |
| 146 | +``` |
| 147 | + |
| 148 | +### coerceBigint |
| 149 | + |
| 150 | +Converts string input to a BigInt, returning `undefined` for empty or whitespace-only strings. Returns the original string if conversion fails. |
| 151 | + |
| 152 | +```typescript |
| 153 | +import { coerceBigint } from "conformal"; |
| 154 | + |
| 155 | +console.log(coerceBigint("42")); // 42n |
| 156 | +console.log(coerceBigint("9007199254740991")); // 9007199254740991n |
| 157 | +console.log(coerceBigint("")); // undefined |
| 158 | +console.log(coerceBigint("abc")); // "abc" (unchanged) |
| 159 | +``` |
| 160 | + |
| 161 | +### coerceBoolean |
| 162 | + |
| 163 | +Converts string input to a boolean based on common truthy/falsy string values. |
| 164 | + |
| 165 | +```typescript |
| 166 | +import { coerceBoolean } from "conformal"; |
| 167 | + |
| 168 | +console.log(coerceBoolean("true")); // true |
| 169 | +console.log(coerceBoolean("on")); // true |
| 170 | +console.log(coerceBoolean("1")); // true |
| 171 | +console.log(coerceBoolean("yes")); // true |
| 172 | +console.log(coerceBoolean("false")); // false |
| 173 | +console.log(coerceBoolean("off")); // false |
| 174 | +console.log(coerceBoolean("0")); // false |
| 175 | +console.log(coerceBoolean("no")); // false |
| 176 | +console.log(coerceBoolean("")); // undefined |
| 177 | +console.log(coerceBoolean("maybe")); // "maybe" (unchanged) |
| 178 | +``` |
| 179 | + |
| 180 | +### coerceDate |
| 181 | + |
| 182 | +Converts string input to a Date object, returning `undefined` for empty strings. Returns the original string if the date is invalid. |
| 183 | + |
| 184 | +```typescript |
| 185 | +import { coerceDate } from "conformal"; |
| 186 | + |
| 187 | +console.log(coerceDate("2023-01-01")); // Date object |
| 188 | +console.log(coerceDate("")); // undefined |
| 189 | +console.log(coerceDate("invalid-date")); // "invalid-date" (unchanged) |
| 190 | +``` |
| 191 | + |
| 192 | +### coerceFile |
| 193 | + |
| 194 | +Handles File objects, returning `undefined` for empty files (size 0). |
| 195 | + |
| 196 | +```typescript |
| 197 | +import { coerceFile } from "conformal"; |
| 198 | + |
| 199 | +const emptyFile = new File([], "test.txt"); |
| 200 | +const file = new File(["content"], "test.txt"); |
| 201 | + |
| 202 | +console.log(coerceFile(emptyFile)); // undefined |
| 203 | +console.log(coerceFile(file)); // File object |
| 204 | +console.log(coerceFile("not-a-file")); // "not-a-file" (unchanged) |
| 205 | +``` |
| 206 | + |
| 207 | +### coerceArray |
| 208 | + |
| 209 | +Converts any input to an array. Empty strings become empty arrays, arrays pass through unchanged, and other values are wrapped in an array. |
| 210 | + |
| 211 | +```typescript |
| 212 | +import { coerceArray } from "conformal"; |
| 213 | + |
| 214 | +console.log(coerceArray("")); // [] |
| 215 | +console.log(coerceArray([1, 2, 3])); // [1, 2, 3] |
| 216 | +console.log(coerceArray("hello")); // ["hello"] |
| 217 | +``` |
| 218 | + |
110 | 219 | ## Types |
111 | 220 |
|
112 | 221 | ### Submission |
|
0 commit comments