chore: add zod stringbool support (squashed)

Author: ciscoheat

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added support for Zod 4 [stringbools](https://zod.dev/api?id=stringbool). [#610](https://github.com/ciscoheat/sveltekit-superforms/issues/610)
+
 ### Changed
 
 - TypeBox adapter has been bumped to 1.0! Check the [migration guide](https://github.com/sinclairzx81/typebox/blob/main/changelog/1.0.0-migration.md) to upgrade. Note that if you need to stay on 0.x for a while, you cannot upgrade to this version of Superforms.

STRINGBOOL_SUPPORT.md

@@ -0,0 +1,156 @@
+# Zod v4 `stringbool()` Support
+
+Superforms now supports Zod v4's `z.stringbool()` type, which allows strict validation of boolean string values.
+
+## What is `z.stringbool()`?
+
+`z.stringbool()` is a Zod v4 feature that validates string inputs and converts them to booleans, but only accepts specific truthy/falsy string values. Unlike `z.boolean()` or `z.coerce.boolean()`, which accept any non-"false" value as truthy, `stringbool()` enforces strict validation.
+
+## Implementation Details
+
+Internally, `z.stringbool()` is implemented as a pipe: `string -> transform -> boolean`
+
+Superforms detects this pattern in the JSON Schema generation phase and:
+
+1. Marks the field with `format: "stringbool"` in the JSON Schema
+2. Keeps the value as a string during FormData parsing
+3. Lets Zod perform the validation and transformation
+
+## Usage Examples
+
+### Basic Example
+
+```typescript
+import { z } from 'zod/v4';
+import { superValidate } from 'sveltekit-superforms';
+import { zod } from 'sveltekit-superforms/adapters';
+
+const schema = z.object({
+	acceptTerms: z.stringbool({
+		truthy: ['true'],
+		falsy: ['false'],
+		case: 'sensitive'
+	})
+});
+
+// Server-side (+page.server.ts)
+export const actions = {
+	default: async ({ request }) => {
+		const form = await superValidate(request, zod(schema));
+
+		if (!form.valid) {
+			return fail(400, { form });
+		}
+
+		// form.data.acceptTerms is now a boolean (true or false)
+		console.log(form.data.acceptTerms); // boolean
+
+		return { form };
+	}
+};
+```
+
+### Client-side Form
+
+```svelte
+<script lang="ts">
+	import { superForm } from 'sveltekit-superforms';
+
+	export let data;
+
+	const { form, errors, enhance } = superForm(data.form);
+</script>
+
+<form method="POST" use:enhance>
+	<input type="hidden" name="acceptTerms" value="true" />
+	<button type="submit">Accept Terms</button>
+</form>
+```
+
+### Custom Truthy/Falsy Values
+
+You can customize which string values are considered truthy or falsy:
+
+```typescript
+const schema = z.object({
+	status: z.stringbool({
+		truthy: ['yes', 'on', '1'],
+		falsy: ['no', 'off', '0'],
+		case: 'insensitive' // Case-insensitive matching
+	})
+});
+```
+
+With this schema:
+
+- `"yes"`, `"YES"`, `"on"`, `"ON"`, `"1"` → `true`
+- `"no"`, `"NO"`, `"off"`, `"OFF"`, `"0"` → `false`
+- Any other value → Validation error
+
+## Benefits Over Regular Boolean
+
+| Feature         | `z.boolean()` / `z.coerce.boolean()`       | `z.stringbool()`                                 |
+| --------------- | ------------------------------------------ | ------------------------------------------------ |
+| Validation      | Accepts any value as truthy except "false" | Only accepts specified truthy/falsy values       |
+| Type Safety     | Less strict                                | More strict                                      |
+| Error Detection | May miss invalid inputs                    | Catches invalid inputs                           |
+| Use Case        | General boolean fields                     | Security-critical or strict validation scenarios |
+
+## Common Use Cases
+
+### Toggle Role Buttons
+
+```typescript
+const schema = z.object({
+	role: z.string(),
+	hadRole: z.stringbool({
+		truthy: ['true'],
+		falsy: ['false'],
+		case: 'sensitive'
+	})
+});
+```
+
+Hidden form fields that track whether a user had a role when the page loaded, preventing unexpected toggles.
+
+### Checkbox-like Hidden Inputs
+
+```typescript
+const schema = z.object({
+	consent: z.stringbool({
+		truthy: ['true'],
+		falsy: ['false']
+	})
+});
+```
+
+For forms that look like buttons to the user but need to track boolean state.
+
+### Feature Flags
+
+```typescript
+const schema = z.object({
+	enabled: z.stringbool({
+		truthy: ['enabled', 'on'],
+		falsy: ['disabled', 'off'],
+		case: 'insensitive'
+	})
+});
+```
+
+## Testing
+
+Run the stringbool tests:
+
+```bash
+npm test -- stringbool
+```
+
+## Related Issues
+
+- [Issue #610](https://github.com/ciscoheat/sveltekit-superforms/issues/610) - Original feature request
+- [Zod Issue #4821](https://github.com/colinhacks/zod/issues/4821) - Discussion about detecting stringbool in JSON Schema
+
+## Credits
+
+Thanks to [@fr33bits](https://github.com/fr33bits) for reporting the issue and [@colinhacks](https://github.com/colinhacks) for clarifying the stringbool implementation.

src/lib/adapters/zod4.ts

@@ -49,6 +49,50 @@ const defaultJSONSchemaOptions = {
 		} else if (def.type === 'bigint') {
 			ctx.jsonSchema.type = 'string';
 			ctx.jsonSchema.format = 'bigint';
+		} else if (def.type === 'pipe') {
+			// Handle z.stringbool() - it's a pipe from string->transform->boolean
+			// Colin Hacks explained: stringbool is just string -> transform -> boolean
+			// When io:'input', we see the string schema; when io:'output', we see boolean
+			const pipeDef = def as typeof def & { in: any; out: any };
+			const inSchema = pipeDef.in;
+			const outSchema = pipeDef.out;
+
+			// Check if it's: string -> (transform or pipe) -> boolean
+			if (inSchema?._zod?.def.type === 'string') {
+				// Traverse through the output side (right) to find if it ends in boolean
+				let currentSchema = outSchema;
+				let isStringBool = false;
+
+				// Traverse through transforms and pipes to find boolean
+				while (currentSchema?._zod?.def) {
+					const currentDef = currentSchema._zod.def;
+					if (currentDef.type === 'boolean') {
+						isStringBool = true;
+						break;
+					} else if (currentDef.type === 'transform') {
+						// Transform doesn't have a nested schema, but we can't traverse further
+						// Check if the transform is inside another pipe
+						break;
+					} else if (currentDef.type === 'pipe') {
+						// Continue traversing the pipe
+						const nestedPipeDef = currentDef as typeof currentDef & { out: any };
+						currentSchema = nestedPipeDef.out;
+					} else {
+						break;
+					}
+				}
+
+				// Also check if outSchema directly is boolean
+				if (!isStringBool && outSchema?._zod?.def.type === 'boolean') {
+					isStringBool = true;
+				}
+
+				if (isStringBool) {
+					// Mark as stringbool so FormData parser knows to handle it as string
+					ctx.jsonSchema.type = 'string';
+					ctx.jsonSchema.format = 'stringbool';
+				}
+			}
 		} else if (def.type === 'set') {
 			// Handle z.set() - convert to array with uniqueItems
 			ctx.jsonSchema.type = 'array';

src/lib/formData.ts

@@ -363,6 +363,10 @@ function parseFormDataEntry(
 			return parseFloat(value ?? '');
 		case 'boolean':
 			return Boolean(value == 'false' ? '' : value).valueOf();
+		case 'stringbool':
+			// Zod's z.stringbool() - keep as string, let Zod validate it
+			// This prevents Superforms from coercing to boolean before Zod can validate
+			return value;
 		case 'unix-time': {
 			// Must return undefined for invalid dates due to https://github.com/Rich-Harris/devalue/issues/51
 			const date = new Date(value ?? '');

src/lib/jsonSchema/schemaDefaults.ts

@@ -217,6 +217,10 @@ export function defaultValue(type: SchemaType, enumType: unknown[] | undefined):
 		case 'int64':
 		case 'bigint':
 			return BigInt(0);
+		case 'stringbool':
+			// For stringbool, return empty string - let Zod validation handle it
+			// The schema should define a default if one is needed
+			return '';
 		case 'set':
 			return new Set();
 		case 'map':
@@ -226,7 +230,6 @@ export function defaultValue(type: SchemaType, enumType: unknown[] | undefined):
 		case 'undefined':
 		case 'any':
 			return undefined;
-
 		default:
 			throw new SchemaError(
 				'Schema type or format not supported, requires explicit default value: ' + type

src/lib/jsonSchema/schemaInfo.ts

@@ -14,7 +14,8 @@ export type SchemaType =
 	| 'set'
 	| 'map'
 	| 'null'
-	| 'undefined';
+	| 'undefined'
+	| 'stringbool';
 
 export type SchemaInfo = {
 	types: Exclude<SchemaType, 'null'>[];
@@ -28,7 +29,16 @@ export type SchemaInfo = {
 	required?: string[];
 };
 
-const conversionFormatTypes = ['unix-time', 'bigint', 'any', 'symbol', 'set', 'map', 'int64'];
+const conversionFormatTypes = [
+	'unix-time',
+	'bigint',
+	'any',
+	'symbol',
+	'set',
+	'map',
+	'int64',
+	'stringbool'
+];
 
 /**
  * Normalizes the different kind of schema variations (anyOf, union, const null, etc)
@@ -131,6 +141,13 @@ function schemaTypes(
 			const i = types.findIndex((t) => t == 'string');
 			types.splice(i, 1);
 		}
+
+		// For stringbool, remove the string type, as the schema format will be used
+		// stringbool should be treated as a special string that validates to boolean
+		if (schema.format == 'stringbool') {
+			const i = types.findIndex((t) => t == 'string');
+			if (i !== -1) types.splice(i, 1);
+		}
 	}
 
 	if (schema.const && schema.const !== null && typeof schema.const !== 'function') {