@oomfware/forms 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# @oomfware/forms
+
+form validation middleware.
+
+```sh
+npm install @oomfware/forms
+```
+
+## usage
+
+### basic form
+
+```tsx
+import { asyncContext, createRouter, route } from '@oomfware/fetch-router';
+import { form, forms } from '@oomfware/forms';
+import { render } from '@oomfware/jsx';
+import * as v from 'valibot';
+
+const routes = route({
+	login: '/login',
+});
+
+const router = createRouter({
+	middleware: [asyncContext()],
+});
+
+const loginForm = form(
+	v.object({
+		email: v.pipe(v.string(), v.email()),
+		_password: v.pipe(v.string(), v.minLength(8)),
+	}),
+	async (data, issue) => {
+		const user = await findUserByEmail(data.email);
+
+		if (!user || !(await verifyPassword(user, data._password))) {
+			invalid(issue.email('Invalid email or password'));
+		}
+
+		return { userId: user.id };
+	},
+);
+
+router.map(routes, {
+	middleware: [forms({ loginForm })],
+	actions: {
+		login() {
+			return render(
+				<form {...loginForm}>
+					{loginForm.fields.email.issues()?.[0] && (
+						<p class="error">{loginForm.fields.email.issues()![0].message}</p>
+					)}
+
+					<label>
+						Email
+						<input {...loginForm.fields.email.as('email')} />
+					</label>
+
+					<label>
+						Password
+						<input {...loginForm.fields._password.as('password')} />
+					</label>
+
+					<button>Sign in</button>
+				</form>,
+			);
+		},
+	},
+});
+```
+
+### imperative validation
+
+use `invalid()` to add validation errors after schema validation passes:
+
+```ts
+import { form, invalid } from '@oomfware/forms';
+import * as v from 'valibot';
+
+export const registerForm = form(
+	v.object({
+		username: v.pipe(v.string(), v.minLength(3)),
+		email: v.pipe(v.string(), v.email()),
+		_password: v.pipe(v.string(), v.minLength(8)),
+	}),
+	async (data, issue) => {
+		const issues = [];
+
+		if (await isUsernameTaken(data.username)) {
+			issues.push(issue.username('Username is already taken'));
+		}
+
+		if (await isEmailRegistered(data.email)) {
+			issues.push(issue.email('Email is already registered'));
+		}
+
+		if (issues.length > 0) {
+			invalid(...issues);
+		}
+
+		return await createUser(data);
+	},
+);
+```
+
+### nested and array fields
+
+```tsx
+const profileForm = form(
+	v.object({
+		user: v.object({
+			name: v.string(),
+			bio: v.optional(v.string()),
+		}),
+		socialLinks: v.array(
+			v.object({
+				platform: v.string(),
+				url: v.pipe(v.string(), v.url()),
+			}),
+		),
+	}),
+	async (data) => {
+		return await updateProfile(data);
+	},
+);
+
+// in template:
+<input {...profileForm.fields.user.name.as('text')} />
+<textarea {...profileForm.fields.user.bio.as('text')} />
+
+{socialLinks.map((_, i) => (
+	<>
+		<input {...profileForm.fields.socialLinks[i].platform.as('text')} />
+		<input {...profileForm.fields.socialLinks[i].url.as('url')} />
+	</>
+))}
+```
+
+### input types
+
+the `.as()` method generates appropriate props for different input types:
+
+```tsx
+// text inputs
+<input {...form.fields.name.as('text')} />
+<input {...form.fields.email.as('email')} />
+<input {...form.fields.password.as('password')} />
+
+// numeric inputs (auto-parsed via n: prefix)
+<input {...form.fields.age.as('number')} />
+<input {...form.fields.rating.as('range')} />
+
+// boolean checkbox (auto-parsed via b: prefix)
+<input {...form.fields.subscribe.as('checkbox')} />
+
+// checkbox group (multiple values)
+<input {...form.fields.tags.as('checkbox', 'javascript')} />
+<input {...form.fields.tags.as('checkbox', 'typescript')} />
+
+// radio buttons
+<input {...form.fields.color.as('radio', 'red')} />
+<input {...form.fields.color.as('radio', 'blue')} />
+
+// select
+<select {...form.fields.country.as('select')}>
+	<option value="us">United States</option>
+</select>
+
+// hidden fields (for IDs, tokens, etc.)
+<input {...form.fields.postId.as('hidden', postId)} />
+
+// file uploads
+<input {...form.fields.avatar.as('file')} />
+<input {...form.fields.attachments.as('file multiple')} />
+```
+
+### accessing form result
+
+```tsx
+router.map(routes, {
+	middleware: [forms({ messageForm })],
+	messages() {
+		if (messageForm.result) {
+			return render(<p>Message sent! ID: {messageForm.result.messageId}</p>);
+		}
+
+		return render(<form {...messageForm}>{/* form fields */}</form>);
+	},
+});
+```
+
+### multiple submit actions
+
+use `buttonProps` when a form has multiple submit buttons that trigger different actions:
+
+```tsx
+import { form, forms } from '@oomfware/forms';
+import { render } from '@oomfware/jsx';
+import * as v from 'valibot';
+
+const draftSchema = v.object({
+	title: v.string(),
+	content: v.string(),
+});
+
+const saveDraft = form(draftSchema, async (data) => {
+	return await saveDraftToDb(data);
+});
+
+const publishPost = form(draftSchema, async (data) => {
+	return await publishToDb(data);
+});
+
+router.map(routes, {
+	middleware: [forms({ saveDraft, publishPost })],
+	actions: {
+		editor() {
+			return render(
+				<form {...saveDraft}>
+					<input {...saveDraft.fields.title.as('text')} placeholder="Title" />
+					<textarea {...saveDraft.fields.content.as('text')} />
+
+					<button>Save draft</button>
+					<button {...publishPost.buttonProps}>Publish</button>
+				</form>,
+			);
+		},
+	},
+});
+```
+
+### sensitive field redaction
+
+fields prefixed with `_` are automatically redacted from form state on validation failure:
+
+```tsx
+const loginForm = form(
+	v.object({
+		email: v.pipe(v.string(), v.email()),
+		_password: v.pipe(v.string(), v.minLength(8)), // redacted on error
+	}),
+	async (data) => {
+		// data._password is available here
+	},
+);
+
+// if validation fails, loginForm.fields._password.value() returns undefined
+// this prevents passwords from being echoed back in the form
+```

package/dist/index.d.mts

@@ -0,0 +1,181 @@
+import { RouterMiddleware } from "@oomfware/fetch-router";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/lib/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+//#endregion
+//#region src/lib/form.d.ts
+interface FormInput {
+  [key: string]: MaybeArray<string | number | boolean | File | FormInput>;
+}
+type MaybeArray<T> = T | T[];
+interface FormIssue {
+  message: string;
+  path: (string | number)[];
+}
+/**
+ * the issue creator proxy passed to form callbacks.
+ * allows creating field-specific validation issues via property access.
+ *
+ * @example
+ * ```ts
+ * form(schema, async (data, issue) => {
+ *   if (emailTaken(data.email)) {
+ *     invalid(issue.email('Email already in use'));
+ *   }
+ *   // nested fields: issue.user.profile.name('Invalid name')
+ *   // array fields: issue.items[0].name('Invalid item name')
+ * });
+ * ```
+ */
+type InvalidField<T> = ((message: string) => StandardSchemaV1.Issue) & { [K in keyof T]-?: T[K] extends (infer U)[] ? InvalidFieldArray<U> : T[K] extends object ? InvalidField<T[K]> : (message: string) => StandardSchemaV1.Issue };
+type InvalidFieldArray<T> = {
+  [index: number]: T extends object ? InvalidField<T> : (message: string) => StandardSchemaV1.Issue;
+} & ((message: string) => StandardSchemaV1.Issue);
+/**
+ * internal info attached to a form instance.
+ * used by the forms() middleware to identify and process forms.
+ */
+
+/**
+ * the return value of a form() function.
+ * can be spread onto a <form> element.
+ */
+interface Form<Input extends FormInput | void, Output> {
+  /** HTTP method */
+  readonly method: 'POST';
+  /** the form action URL */
+  readonly action: string;
+  /** the handler result, if submission was successful */
+  readonly result: Output | undefined;
+  /** access form fields using object notation */
+  readonly fields: FormFields<Input>;
+  /** spread this onto a <button> or <input type="submit"> */
+  readonly buttonProps: FormButtonProps;
+}
+interface FormButtonProps {
+  type: 'submit';
+  readonly formaction: string;
+}
+/** valid leaf value types for form fields */
+type FormFieldValue = string | string[] | number | boolean | File | File[];
+/** guard to prevent infinite recursion when T is unknown or has an index signature */
+type WillRecurseIndefinitely<T> = unknown extends T ? true : string extends keyof T ? true : false;
+/** base methods available on all form fields */
+interface FormFieldMethods<T> {
+  /** get the current value */
+  value(): T | undefined;
+  /** set the value */
+  set(value: T): T;
+  /** get validation issues for this field */
+  issues(): FormIssue[] | undefined;
+}
+/** leaf field (primitives, files) with .as() method */
+type FormFieldLeaf<T extends FormFieldValue> = FormFieldMethods<T> & {
+  /** get props for an input element */
+  as(type: string, value?: string): Record<string, unknown>;
+};
+/** container field (objects, arrays) with allIssues() method */
+type FormFieldContainer<T> = FormFieldMethods<T> & {
+  /** get all issues for this field and descendants */
+  allIssues(): FormIssue[] | undefined;
+};
+/** fallback field type when recursion would be infinite */
+type FormFieldUnknown<T> = FormFieldMethods<T> & {
+  /** get all issues for this field and descendants */
+  allIssues(): FormIssue[] | undefined;
+  /** get props for an input element */
+  as(type: string, value?: string): Record<string, unknown>;
+} & {
+  [key: string | number]: FormFieldUnknown<unknown>;
+};
+/**
+ * recursive type to build form fields structure with proxy access.
+ * preserves type information through the object hierarchy.
+ */
+type FormFields<T> = T extends void ? Record<string, never> : WillRecurseIndefinitely<T> extends true ? FormFieldUnknown<T> : NonNullable<T> extends string | number | boolean | File ? FormFieldLeaf<NonNullable<T>> : T extends string[] | File[] ? FormFieldLeaf<T> & { [K in number]: FormFieldLeaf<T[number]> } : T extends Array<infer U> ? FormFieldContainer<T> & { [K in number]: FormFields<U> } : FormFieldContainer<T> & { [K in keyof T]-?: FormFields<T[K]> };
+/**
+ * creates a form without validation.
+ */
+declare function form<Output>(fn: () => MaybePromise<Output>): Form<void, Output>;
+/**
+ * creates a form with unchecked input (no validation).
+ */
+declare function form<Input extends FormInput, Output>(validate: 'unchecked', fn: (data: Input, issue: InvalidField<Input>) => MaybePromise<Output>): Form<Input, Output>;
+/**
+ * creates a form with Standard Schema validation.
+ */
+declare function form<Schema extends StandardSchemaV1<FormInput, Record<string, unknown>>, Output>(validate: Schema, fn: (data: StandardSchemaV1.InferOutput<Schema>, issue: InvalidField<StandardSchemaV1.InferInput<Schema>>) => MaybePromise<Output>): Form<StandardSchemaV1.InferInput<Schema>, Output>;
+//#endregion
+//#region src/lib/middleware.d.ts
+/**
+ * a record of form instances to register with the middleware.
+ */
+type FormDefinitions = Record<string, Form<any, any>>;
+/**
+ * creates a forms middleware that registers forms and handles form submissions.
+ *
+ * @example
+ * ```ts
+ * import { form, forms } from '@oomfware/forms';
+ * import * as v from 'valibot';
+ *
+ * const createUserForm = form(
+ *   v.object({ name: v.string(), password: v.string() }),
+ *   async (input, issue) => {
+ *     // handle form submission
+ *   },
+ * );
+ *
+ * router.map(routes.admin, {
+ *   middleware: [forms({ createUserForm })],
+ *   action() {
+ *     return render(
+ *       <form {...createUserForm}>
+ *         <input {...createUserForm.fields.name.as('text')} required />
+ *       </form>
+ *     );
+ *   },
+ * });
+ * ```
+ */
+declare function forms(definitions: FormDefinitions): RouterMiddleware;
+//#endregion
+//#region src/lib/errors.d.ts
+/**
+ * error thrown when form validation fails imperatively
+ */
+declare class ValidationError extends Error {
+  issues: StandardSchemaV1.Issue[];
+  constructor(issues: StandardSchemaV1.Issue[]);
+}
+/**
+ * use this to throw a validation error to imperatively fail form validation.
+ * can be used in combination with `issue` passed to form actions to create field-specific issues.
+ *
+ * @example
+ * ```ts
+ * import { invalid, form } from '@oomfware/forms';
+ * import * as v from 'valibot';
+ *
+ * export const login = form(
+ *   v.object({ name: v.string(), _password: v.string() }),
+ *   async ({ name, _password }, issue) => {
+ *     const success = tryLogin(name, _password);
+ *     if (!success) {
+ *       invalid('Incorrect username or password');
+ *     }
+ *
+ *     // ...
+ *   }
+ * );
+ * ```
+ */
+declare function invalid(...issues: (StandardSchemaV1.Issue | string)[]): never;
+/**
+ * checks whether this is a validation error thrown by {@link invalid}.
+ */
+declare function isValidationError(e: unknown): e is ValidationError;
+//#endregion
+export { type Form, type FormInput, type FormIssue, ValidationError, form, forms, invalid, isValidationError };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/lib/types.ts","../src/lib/form.ts","../src/lib/middleware.ts","../src/lib/errors.ts"],"sourcesContent":[],"mappings":"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"}