@lacspace/form 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+
+# @lacspace/form
+
+**Typed, validated, spam-protected form handling — built for Next.js Server Actions.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/form?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/form)
+[![license](https://img.shields.io/npm/l/@lacspace/form?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Take a `FormData`, validate it against a schema, block bots with a honeypot + timing check, and get back **either your typed data or per-field errors ready to re-render**. Framework-agnostic, zero dependencies.
+
+## Install
+
+```bash
+npm i @lacspace/form @lacspace/validate
+```
+
+`@lacspace/validate` is optional — any object with a `safeParse` (including zod) works.
+
+## Use it — a complete contact form
+
+```ts
+// app/actions.ts
+"use server";
+import { createForm } from "@lacspace/form";
+import { v } from "@lacspace/validate";
+
+const contact = createForm({
+  schema: v.object({
+    name: v.string().min(2),
+    email: v.string().email(),
+    message: v.string().min(10),
+  }),
+  honeypot: "company",   // hidden field bots fill; humans never see it
+  minSubmitMs: 800,      // reject sub-second (bot-speed) submissions
+});
+
+export async function submit(prev: unknown, formData: FormData) {
+  const r = contact.action(prev, formData);
+  if (!r.ok) return r;              // { errors, values } → re-render form
+  await sendEmail(r.data);          // ✅ { name, email, message } fully typed
+  return { ok: true as const };
+}
+```
+
+```tsx
+// app/contact/page.tsx
+"use client";
+import { useActionState } from "react";
+import { submit } from "../actions";
+import { honeypotProps, timestampValue } from "@lacspace/form";
+
+export default function Contact() {
+  const [state, action] = useActionState(submit, null);
+  return (
+    <form action={action}>
+      <input name="name" defaultValue={state?.values?.name as string} />
+      {state?.errors?.name && <p>{state.errors.name}</p>}
+
+      <input name="email" defaultValue={state?.values?.email as string} />
+      {state?.errors?.email && <p>{state.errors.email}</p>}
+
+      <textarea name="message" defaultValue={state?.values?.message as string} />
+      {state?.errors?.message && <p>{state.errors.message}</p>}
+
+      {/* spam protection — one line each */}
+      <input {...honeypotProps("company")} />
+      <input type="hidden" name="_ts" defaultValue={timestampValue()} />
+
+      <button>Send</button>
+      {state?.ok && <p>Thanks — we'll be in touch!</p>}
+    </form>
+  );
+}
+```
+
+## What you get
+
+- **`createForm(opts)`** → `{ handle, action }` — `action` matches the `(prev, formData)` shape of `useActionState`, so it drops in with zero glue.
+- **Typed result** — `{ ok: true, data }` or `{ ok: false, errors, values, spam? }`. `values` echoes what the user typed so re-renders keep their input.
+- **`formDataToObject(fd)`** — repeated keys → arrays, files passed through, empty strings preserved.
+- **Spam guard** — `honeypot` field + `minSubmitMs` timing heuristic, both optional. Internal fields (`_ts`, honeypot) are stripped before validation so your schema can stay `.strict()`.
+- **`honeypotProps(name)`** + **`timestampValue()`** — client helpers, no React dependency.
+
+Pairs with [`@lacspace/validate`](https://www.npmjs.com/package/@lacspace/validate), [`@lacspace/rate-limit`](https://www.npmjs.com/package/@lacspace/rate-limit) and [`@lacspace/mailer`](https://www.npmjs.com/package/@lacspace/mailer).
+
+## Licensing
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice. See the **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+---
+
+<div align="center">
+
+**Part of the Lacspace ecosystem — zero-dependency, isomorphic TypeScript packages.**
+
+[All packages ↗](https://lacspace.com/packages) · [npm org ↗](https://www.npmjs.com/org/lacspace) · [Licence Centre ↗](https://lacspace.com/licenses) · [GitHub ↗](https://github.com/lacspace/npm-packages)
+
+</div>
+
+<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · Lacspace Free Licence · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>

package/dist/index.cjs

@@ -0,0 +1,104 @@
+'use strict';
+
+// src/index.ts
+var DEFAULT_TS_FIELD = "_ts";
+var DEFAULT_FORM_KEY = "_form";
+var DEFAULT_SPAM_MSG = "Your submission could not be processed. Please try again.";
+function isFormData(x) {
+  return typeof x === "object" && x !== null && typeof x.entries === "function" && typeof x.append === "function";
+}
+function formDataToObject(fd) {
+  const out = {};
+  for (const [key, value] of fd.entries()) {
+    if (key in out) {
+      const existing = out[key];
+      if (Array.isArray(existing)) existing.push(value);
+      else out[key] = [existing, value];
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function toObject(input) {
+  return isFormData(input) ? formDataToObject(input) : { ...input };
+}
+function handleForm(input, opts) {
+  const values = toObject(input);
+  const formKey = opts.formErrorKey ?? DEFAULT_FORM_KEY;
+  if (opts.honeypot) {
+    const trap = values[opts.honeypot];
+    if (typeof trap === "string" ? trap.trim() !== "" : trap != null && trap !== "") {
+      return spam(opts, values, formKey);
+    }
+  }
+  if (opts.minSubmitMs && opts.minSubmitMs > 0) {
+    const tsField = opts.timestampField ?? DEFAULT_TS_FIELD;
+    const raw = values[tsField];
+    const ts = typeof raw === "string" ? Number(raw) : typeof raw === "number" ? raw : NaN;
+    if (Number.isFinite(ts)) {
+      const elapsed = Date.now() - ts;
+      if (elapsed >= 0 && elapsed < opts.minSubmitMs) {
+        return spam(opts, values, formKey);
+      }
+    }
+  }
+  const cleaned = stripInternal(values, opts);
+  const r = opts.schema.safeParse(cleaned);
+  if (r.success) return { ok: true, data: r.data };
+  return { ok: false, errors: r.error.flatten(), values: cleaned };
+}
+function stripInternal(values, opts) {
+  const drop = /* @__PURE__ */ new Set();
+  if (opts.honeypot) drop.add(opts.honeypot);
+  drop.add(opts.timestampField ?? DEFAULT_TS_FIELD);
+  if (drop.size === 0) return values;
+  const out = {};
+  for (const k of Object.keys(values)) if (!drop.has(k)) out[k] = values[k];
+  return out;
+}
+function spam(opts, values, formKey) {
+  return {
+    ok: false,
+    spam: true,
+    values,
+    errors: { [formKey]: opts.spamMessage ?? DEFAULT_SPAM_MSG }
+  };
+}
+function createForm(opts) {
+  return {
+    handle: (input) => handleForm(input, opts),
+    action: (_prev, formData) => handleForm(formData, opts)
+  };
+}
+function honeypotProps(name) {
+  return {
+    type: "text",
+    name,
+    tabIndex: -1,
+    autoComplete: "off",
+    "aria-hidden": "true",
+    style: {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0 0 0 0)",
+      whiteSpace: "nowrap",
+      border: "0"
+    }
+  };
+}
+function timestampValue() {
+  return String(Date.now());
+}
+
+exports.createForm = createForm;
+exports.formDataToObject = formDataToObject;
+exports.handleForm = handleForm;
+exports.honeypotProps = honeypotProps;
+exports.timestampValue = timestampValue;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/form\n * End-to-end form handling for the server — turn a `FormData` (or a plain\n * object) into typed, validated data with built-in spam protection, and get\n * back either your data or per-field errors ready to re-render.\n *\n * Framework-agnostic, but shaped for Next.js Server Actions.\n *\n * ```ts\n * \"use server\";\n * import { createForm } from \"@lacspace/form\";\n * import { v } from \"@lacspace/validate\";\n *\n * const contact = createForm({\n *   schema: v.object({\n *     name: v.string().min(2),\n *     email: v.string().email(),\n *     message: v.string().min(10),\n *   }),\n *   honeypot: \"company\",   // a hidden field bots love to fill\n * });\n *\n * export async function submit(prev, formData) {\n *   const r = contact.action(prev, formData);\n *   if (!r.ok) return r;                       // { errors, values } → re-render\n *   await sendEmail(r.data);                   // fully typed\n *   return { ok: true };\n * }\n * ```\n *\n * Zero dependencies · isomorphic · fully typed.\n */\n\n/* ------------------------------------------------------------------ *\n * Validator contract — structurally compatible with @lacspace/validate\n * (and, in practice, with zod). No hard dependency either way.\n * ------------------------------------------------------------------ */\n\nexport interface Validator<T> {\n  safeParse(input: unknown):\n    | { success: true; data: T }\n    | { success: false; error: { flatten(): Record<string, string> } };\n}\n\n/* ------------------------------------------------------------------ *\n * Options & results\n * ------------------------------------------------------------------ */\n\nexport interface FormOptions<T> {\n  /** A schema with `safeParse` — e.g. `v.object({...})` from @lacspace/validate. */\n  schema: Validator<T>;\n  /**\n   * Name of a hidden \"honeypot\" field that real users never see and never fill.\n   * If it arrives non-empty, the submission is treated as spam.\n   */\n  honeypot?: string;\n  /**\n   * Reject submissions that arrive faster than this many ms after the form was\n   * rendered. Requires a hidden timestamp field (see `timestampField`).\n   */\n  minSubmitMs?: number;\n  /** Hidden field holding the render time in ms. Default `\"_ts\"`. */\n  timestampField?: string;\n  /** Message returned when a submission is flagged as spam. */\n  spamMessage?: string;\n  /** Key used for form-level (non-field) errors. Default `\"_form\"`. */\n  formErrorKey?: string;\n}\n\nexport type FormResult<T> =\n  | { ok: true; data: T }\n  | {\n      ok: false;\n      /** `{ email: \"Invalid email\", _form: \"...\" }` — render next to inputs. */\n      errors: Record<string, string>;\n      /** The raw submitted values, so the form can be re-rendered as typed. */\n      values: Record<string, unknown>;\n      /** True when the failure was a spam/bot heuristic, not user error. */\n      spam?: boolean;\n    };\n\nconst DEFAULT_TS_FIELD = \"_ts\";\nconst DEFAULT_FORM_KEY = \"_form\";\nconst DEFAULT_SPAM_MSG = \"Your submission could not be processed. Please try again.\";\n\n/* ------------------------------------------------------------------ *\n * FormData → plain object\n * ------------------------------------------------------------------ */\n\n/** Minimal structural shape of the parts of FormData we use. */\ninterface FormDataLike {\n  entries(): IterableIterator<[string, unknown]>;\n}\n\nfunction isFormData(x: unknown): x is FormDataLike {\n  return (\n    typeof x === \"object\" &&\n    x !== null &&\n    typeof (x as { entries?: unknown }).entries === \"function\" &&\n    typeof (x as { append?: unknown }).append === \"function\"\n  );\n}\n\n/**\n * Convert a `FormData` into a plain object. Repeated keys become arrays; File\n * values are passed through untouched. Empty strings are preserved (validation\n * decides what \"required\" means).\n */\nexport function formDataToObject(fd: FormDataLike): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of fd.entries()) {\n    if (key in out) {\n      const existing = out[key];\n      if (Array.isArray(existing)) existing.push(value);\n      else out[key] = [existing, value];\n    } else {\n      out[key] = value;\n    }\n  }\n  return out;\n}\n\n/** Normalise any accepted input to a plain object. */\nfunction toObject(input: FormDataLike | Record<string, unknown>): Record<string, unknown> {\n  return isFormData(input) ? formDataToObject(input) : { ...input };\n}\n\n/* ------------------------------------------------------------------ *\n * Core handler\n * ------------------------------------------------------------------ */\n\n/**\n * Validate an input (FormData or object) against a schema, applying spam\n * heuristics first. Returns typed data or per-field errors + the raw values.\n */\nexport function handleForm<T>(\n  input: FormDataLike | Record<string, unknown>,\n  opts: FormOptions<T>,\n): FormResult<T> {\n  const values = toObject(input);\n  const formKey = opts.formErrorKey ?? DEFAULT_FORM_KEY;\n\n  // 1. Honeypot — a non-empty hidden field means a bot.\n  if (opts.honeypot) {\n    const trap = values[opts.honeypot];\n    if (typeof trap === \"string\" ? trap.trim() !== \"\" : trap != null && trap !== \"\") {\n      return spam(opts, values, formKey);\n    }\n  }\n\n  // 2. Timing — submitted implausibly fast after render.\n  if (opts.minSubmitMs && opts.minSubmitMs > 0) {\n    const tsField = opts.timestampField ?? DEFAULT_TS_FIELD;\n    const raw = values[tsField];\n    const ts = typeof raw === \"string\" ? Number(raw) : typeof raw === \"number\" ? raw : NaN;\n    if (Number.isFinite(ts)) {\n      const elapsed = Date.now() - ts;\n      if (elapsed >= 0 && elapsed < opts.minSubmitMs) {\n        return spam(opts, values, formKey);\n      }\n    }\n  }\n\n  // 3. Strip internal fields before validation so schemas can stay `.strict()`.\n  const cleaned = stripInternal(values, opts);\n\n  // 4. Validate.\n  const r = opts.schema.safeParse(cleaned);\n  if (r.success) return { ok: true, data: r.data };\n  return { ok: false, errors: r.error.flatten(), values: cleaned };\n}\n\nfunction stripInternal<T>(values: Record<string, unknown>, opts: FormOptions<T>): Record<string, unknown> {\n  const drop = new Set<string>();\n  if (opts.honeypot) drop.add(opts.honeypot);\n  drop.add(opts.timestampField ?? DEFAULT_TS_FIELD);\n  if (drop.size === 0) return values;\n  const out: Record<string, unknown> = {};\n  for (const k of Object.keys(values)) if (!drop.has(k)) out[k] = values[k];\n  return out;\n}\n\nfunction spam<T>(opts: FormOptions<T>, values: Record<string, unknown>, formKey: string): FormResult<T> {\n  return {\n    ok: false,\n    spam: true,\n    values,\n    errors: { [formKey]: opts.spamMessage ?? DEFAULT_SPAM_MSG },\n  };\n}\n\n/* ------------------------------------------------------------------ *\n * createForm — reusable handler bound to one schema\n * ------------------------------------------------------------------ */\n\nexport interface Form<T> {\n  /** Validate any input; returns typed data or errors. */\n  handle(input: FormDataLike | Record<string, unknown>): FormResult<T>;\n  /**\n   * Next.js Server Action signature `(prevState, formData) => result`.\n   * The previous state is ignored; it exists so this drops straight into\n   * `useActionState`.\n   */\n  action(prevState: unknown, formData: FormDataLike): FormResult<T>;\n}\n\n/** Bind a schema + spam options once and reuse the handler across requests. */\nexport function createForm<T>(opts: FormOptions<T>): Form<T> {\n  return {\n    handle: (input) => handleForm(input, opts),\n    action: (_prev, formData) => handleForm(formData, opts),\n  };\n}\n\n/* ------------------------------------------------------------------ *\n * Client helpers (framework-agnostic, no React needed)\n * ------------------------------------------------------------------ */\n\n/**\n * Attributes for a visually-hidden honeypot input. Spread onto an `<input>`:\n * `<input {...honeypotProps(\"company\")} />`.\n */\nexport function honeypotProps(name: string): {\n  type: \"text\";\n  name: string;\n  tabIndex: -1;\n  autoComplete: \"off\";\n  \"aria-hidden\": \"true\";\n  style: Record<string, string>;\n} {\n  return {\n    type: \"text\",\n    name,\n    tabIndex: -1,\n    autoComplete: \"off\",\n    \"aria-hidden\": \"true\",\n    style: {\n      position: \"absolute\",\n      width: \"1px\",\n      height: \"1px\",\n      padding: \"0\",\n      margin: \"-1px\",\n      overflow: \"hidden\",\n      clip: \"rect(0 0 0 0)\",\n      whiteSpace: \"nowrap\",\n      border: \"0\",\n    },\n  };\n}\n\n/** A `<input type=\"hidden\">`-ready render timestamp for the timing check. */\nexport function timestampValue(): string {\n  return String(Date.now());\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+/**
+ * @lacspace/form
+ * End-to-end form handling for the server — turn a `FormData` (or a plain
+ * object) into typed, validated data with built-in spam protection, and get
+ * back either your data or per-field errors ready to re-render.
+ *
+ * Framework-agnostic, but shaped for Next.js Server Actions.
+ *
+ * ```ts
+ * "use server";
+ * import { createForm } from "@lacspace/form";
+ * import { v } from "@lacspace/validate";
+ *
+ * const contact = createForm({
+ *   schema: v.object({
+ *     name: v.string().min(2),
+ *     email: v.string().email(),
+ *     message: v.string().min(10),
+ *   }),
+ *   honeypot: "company",   // a hidden field bots love to fill
+ * });
+ *
+ * export async function submit(prev, formData) {
+ *   const r = contact.action(prev, formData);
+ *   if (!r.ok) return r;                       // { errors, values } → re-render
+ *   await sendEmail(r.data);                   // fully typed
+ *   return { ok: true };
+ * }
+ * ```
+ *
+ * Zero dependencies · isomorphic · fully typed.
+ */
+interface Validator<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            flatten(): Record<string, string>;
+        };
+    };
+}
+interface FormOptions<T> {
+    /** A schema with `safeParse` — e.g. `v.object({...})` from @lacspace/validate. */
+    schema: Validator<T>;
+    /**
+     * Name of a hidden "honeypot" field that real users never see and never fill.
+     * If it arrives non-empty, the submission is treated as spam.
+     */
+    honeypot?: string;
+    /**
+     * Reject submissions that arrive faster than this many ms after the form was
+     * rendered. Requires a hidden timestamp field (see `timestampField`).
+     */
+    minSubmitMs?: number;
+    /** Hidden field holding the render time in ms. Default `"_ts"`. */
+    timestampField?: string;
+    /** Message returned when a submission is flagged as spam. */
+    spamMessage?: string;
+    /** Key used for form-level (non-field) errors. Default `"_form"`. */
+    formErrorKey?: string;
+}
+type FormResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    /** `{ email: "Invalid email", _form: "..." }` — render next to inputs. */
+    errors: Record<string, string>;
+    /** The raw submitted values, so the form can be re-rendered as typed. */
+    values: Record<string, unknown>;
+    /** True when the failure was a spam/bot heuristic, not user error. */
+    spam?: boolean;
+};
+/** Minimal structural shape of the parts of FormData we use. */
+interface FormDataLike {
+    entries(): IterableIterator<[string, unknown]>;
+}
+/**
+ * Convert a `FormData` into a plain object. Repeated keys become arrays; File
+ * values are passed through untouched. Empty strings are preserved (validation
+ * decides what "required" means).
+ */
+declare function formDataToObject(fd: FormDataLike): Record<string, unknown>;
+/**
+ * Validate an input (FormData or object) against a schema, applying spam
+ * heuristics first. Returns typed data or per-field errors + the raw values.
+ */
+declare function handleForm<T>(input: FormDataLike | Record<string, unknown>, opts: FormOptions<T>): FormResult<T>;
+interface Form<T> {
+    /** Validate any input; returns typed data or errors. */
+    handle(input: FormDataLike | Record<string, unknown>): FormResult<T>;
+    /**
+     * Next.js Server Action signature `(prevState, formData) => result`.
+     * The previous state is ignored; it exists so this drops straight into
+     * `useActionState`.
+     */
+    action(prevState: unknown, formData: FormDataLike): FormResult<T>;
+}
+/** Bind a schema + spam options once and reuse the handler across requests. */
+declare function createForm<T>(opts: FormOptions<T>): Form<T>;
+/**
+ * Attributes for a visually-hidden honeypot input. Spread onto an `<input>`:
+ * `<input {...honeypotProps("company")} />`.
+ */
+declare function honeypotProps(name: string): {
+    type: "text";
+    name: string;
+    tabIndex: -1;
+    autoComplete: "off";
+    "aria-hidden": "true";
+    style: Record<string, string>;
+};
+/** A `<input type="hidden">`-ready render timestamp for the timing check. */
+declare function timestampValue(): string;
+
+export { type Form, type FormOptions, type FormResult, type Validator, createForm, formDataToObject, handleForm, honeypotProps, timestampValue };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @lacspace/form
+ * End-to-end form handling for the server — turn a `FormData` (or a plain
+ * object) into typed, validated data with built-in spam protection, and get
+ * back either your data or per-field errors ready to re-render.
+ *
+ * Framework-agnostic, but shaped for Next.js Server Actions.
+ *
+ * ```ts
+ * "use server";
+ * import { createForm } from "@lacspace/form";
+ * import { v } from "@lacspace/validate";
+ *
+ * const contact = createForm({
+ *   schema: v.object({
+ *     name: v.string().min(2),
+ *     email: v.string().email(),
+ *     message: v.string().min(10),
+ *   }),
+ *   honeypot: "company",   // a hidden field bots love to fill
+ * });
+ *
+ * export async function submit(prev, formData) {
+ *   const r = contact.action(prev, formData);
+ *   if (!r.ok) return r;                       // { errors, values } → re-render
+ *   await sendEmail(r.data);                   // fully typed
+ *   return { ok: true };
+ * }
+ * ```
+ *
+ * Zero dependencies · isomorphic · fully typed.
+ */
+interface Validator<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            flatten(): Record<string, string>;
+        };
+    };
+}
+interface FormOptions<T> {
+    /** A schema with `safeParse` — e.g. `v.object({...})` from @lacspace/validate. */
+    schema: Validator<T>;
+    /**
+     * Name of a hidden "honeypot" field that real users never see and never fill.
+     * If it arrives non-empty, the submission is treated as spam.
+     */
+    honeypot?: string;
+    /**
+     * Reject submissions that arrive faster than this many ms after the form was
+     * rendered. Requires a hidden timestamp field (see `timestampField`).
+     */
+    minSubmitMs?: number;
+    /** Hidden field holding the render time in ms. Default `"_ts"`. */
+    timestampField?: string;
+    /** Message returned when a submission is flagged as spam. */
+    spamMessage?: string;
+    /** Key used for form-level (non-field) errors. Default `"_form"`. */
+    formErrorKey?: string;
+}
+type FormResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    /** `{ email: "Invalid email", _form: "..." }` — render next to inputs. */
+    errors: Record<string, string>;
+    /** The raw submitted values, so the form can be re-rendered as typed. */
+    values: Record<string, unknown>;
+    /** True when the failure was a spam/bot heuristic, not user error. */
+    spam?: boolean;
+};
+/** Minimal structural shape of the parts of FormData we use. */
+interface FormDataLike {
+    entries(): IterableIterator<[string, unknown]>;
+}
+/**
+ * Convert a `FormData` into a plain object. Repeated keys become arrays; File
+ * values are passed through untouched. Empty strings are preserved (validation
+ * decides what "required" means).
+ */
+declare function formDataToObject(fd: FormDataLike): Record<string, unknown>;
+/**
+ * Validate an input (FormData or object) against a schema, applying spam
+ * heuristics first. Returns typed data or per-field errors + the raw values.
+ */
+declare function handleForm<T>(input: FormDataLike | Record<string, unknown>, opts: FormOptions<T>): FormResult<T>;
+interface Form<T> {
+    /** Validate any input; returns typed data or errors. */
+    handle(input: FormDataLike | Record<string, unknown>): FormResult<T>;
+    /**
+     * Next.js Server Action signature `(prevState, formData) => result`.
+     * The previous state is ignored; it exists so this drops straight into
+     * `useActionState`.
+     */
+    action(prevState: unknown, formData: FormDataLike): FormResult<T>;
+}
+/** Bind a schema + spam options once and reuse the handler across requests. */
+declare function createForm<T>(opts: FormOptions<T>): Form<T>;
+/**
+ * Attributes for a visually-hidden honeypot input. Spread onto an `<input>`:
+ * `<input {...honeypotProps("company")} />`.
+ */
+declare function honeypotProps(name: string): {
+    type: "text";
+    name: string;
+    tabIndex: -1;
+    autoComplete: "off";
+    "aria-hidden": "true";
+    style: Record<string, string>;
+};
+/** A `<input type="hidden">`-ready render timestamp for the timing check. */
+declare function timestampValue(): string;
+
+export { type Form, type FormOptions, type FormResult, type Validator, createForm, formDataToObject, handleForm, honeypotProps, timestampValue };

package/dist/index.js

@@ -0,0 +1,98 @@
+// src/index.ts
+var DEFAULT_TS_FIELD = "_ts";
+var DEFAULT_FORM_KEY = "_form";
+var DEFAULT_SPAM_MSG = "Your submission could not be processed. Please try again.";
+function isFormData(x) {
+  return typeof x === "object" && x !== null && typeof x.entries === "function" && typeof x.append === "function";
+}
+function formDataToObject(fd) {
+  const out = {};
+  for (const [key, value] of fd.entries()) {
+    if (key in out) {
+      const existing = out[key];
+      if (Array.isArray(existing)) existing.push(value);
+      else out[key] = [existing, value];
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function toObject(input) {
+  return isFormData(input) ? formDataToObject(input) : { ...input };
+}
+function handleForm(input, opts) {
+  const values = toObject(input);
+  const formKey = opts.formErrorKey ?? DEFAULT_FORM_KEY;
+  if (opts.honeypot) {
+    const trap = values[opts.honeypot];
+    if (typeof trap === "string" ? trap.trim() !== "" : trap != null && trap !== "") {
+      return spam(opts, values, formKey);
+    }
+  }
+  if (opts.minSubmitMs && opts.minSubmitMs > 0) {
+    const tsField = opts.timestampField ?? DEFAULT_TS_FIELD;
+    const raw = values[tsField];
+    const ts = typeof raw === "string" ? Number(raw) : typeof raw === "number" ? raw : NaN;
+    if (Number.isFinite(ts)) {
+      const elapsed = Date.now() - ts;
+      if (elapsed >= 0 && elapsed < opts.minSubmitMs) {
+        return spam(opts, values, formKey);
+      }
+    }
+  }
+  const cleaned = stripInternal(values, opts);
+  const r = opts.schema.safeParse(cleaned);
+  if (r.success) return { ok: true, data: r.data };
+  return { ok: false, errors: r.error.flatten(), values: cleaned };
+}
+function stripInternal(values, opts) {
+  const drop = /* @__PURE__ */ new Set();
+  if (opts.honeypot) drop.add(opts.honeypot);
+  drop.add(opts.timestampField ?? DEFAULT_TS_FIELD);
+  if (drop.size === 0) return values;
+  const out = {};
+  for (const k of Object.keys(values)) if (!drop.has(k)) out[k] = values[k];
+  return out;
+}
+function spam(opts, values, formKey) {
+  return {
+    ok: false,
+    spam: true,
+    values,
+    errors: { [formKey]: opts.spamMessage ?? DEFAULT_SPAM_MSG }
+  };
+}
+function createForm(opts) {
+  return {
+    handle: (input) => handleForm(input, opts),
+    action: (_prev, formData) => handleForm(formData, opts)
+  };
+}
+function honeypotProps(name) {
+  return {
+    type: "text",
+    name,
+    tabIndex: -1,
+    autoComplete: "off",
+    "aria-hidden": "true",
+    style: {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: "0",
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0 0 0 0)",
+      whiteSpace: "nowrap",
+      border: "0"
+    }
+  };
+}
+function timestampValue() {
+  return String(Date.now());
+}
+
+export { createForm, formDataToObject, handleForm, honeypotProps, timestampValue };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/form\n * End-to-end form handling for the server — turn a `FormData` (or a plain\n * object) into typed, validated data with built-in spam protection, and get\n * back either your data or per-field errors ready to re-render.\n *\n * Framework-agnostic, but shaped for Next.js Server Actions.\n *\n * ```ts\n * \"use server\";\n * import { createForm } from \"@lacspace/form\";\n * import { v } from \"@lacspace/validate\";\n *\n * const contact = createForm({\n *   schema: v.object({\n *     name: v.string().min(2),\n *     email: v.string().email(),\n *     message: v.string().min(10),\n *   }),\n *   honeypot: \"company\",   // a hidden field bots love to fill\n * });\n *\n * export async function submit(prev, formData) {\n *   const r = contact.action(prev, formData);\n *   if (!r.ok) return r;                       // { errors, values } → re-render\n *   await sendEmail(r.data);                   // fully typed\n *   return { ok: true };\n * }\n * ```\n *\n * Zero dependencies · isomorphic · fully typed.\n */\n\n/* ------------------------------------------------------------------ *\n * Validator contract — structurally compatible with @lacspace/validate\n * (and, in practice, with zod). No hard dependency either way.\n * ------------------------------------------------------------------ */\n\nexport interface Validator<T> {\n  safeParse(input: unknown):\n    | { success: true; data: T }\n    | { success: false; error: { flatten(): Record<string, string> } };\n}\n\n/* ------------------------------------------------------------------ *\n * Options & results\n * ------------------------------------------------------------------ */\n\nexport interface FormOptions<T> {\n  /** A schema with `safeParse` — e.g. `v.object({...})` from @lacspace/validate. */\n  schema: Validator<T>;\n  /**\n   * Name of a hidden \"honeypot\" field that real users never see and never fill.\n   * If it arrives non-empty, the submission is treated as spam.\n   */\n  honeypot?: string;\n  /**\n   * Reject submissions that arrive faster than this many ms after the form was\n   * rendered. Requires a hidden timestamp field (see `timestampField`).\n   */\n  minSubmitMs?: number;\n  /** Hidden field holding the render time in ms. Default `\"_ts\"`. */\n  timestampField?: string;\n  /** Message returned when a submission is flagged as spam. */\n  spamMessage?: string;\n  /** Key used for form-level (non-field) errors. Default `\"_form\"`. */\n  formErrorKey?: string;\n}\n\nexport type FormResult<T> =\n  | { ok: true; data: T }\n  | {\n      ok: false;\n      /** `{ email: \"Invalid email\", _form: \"...\" }` — render next to inputs. */\n      errors: Record<string, string>;\n      /** The raw submitted values, so the form can be re-rendered as typed. */\n      values: Record<string, unknown>;\n      /** True when the failure was a spam/bot heuristic, not user error. */\n      spam?: boolean;\n    };\n\nconst DEFAULT_TS_FIELD = \"_ts\";\nconst DEFAULT_FORM_KEY = \"_form\";\nconst DEFAULT_SPAM_MSG = \"Your submission could not be processed. Please try again.\";\n\n/* ------------------------------------------------------------------ *\n * FormData → plain object\n * ------------------------------------------------------------------ */\n\n/** Minimal structural shape of the parts of FormData we use. */\ninterface FormDataLike {\n  entries(): IterableIterator<[string, unknown]>;\n}\n\nfunction isFormData(x: unknown): x is FormDataLike {\n  return (\n    typeof x === \"object\" &&\n    x !== null &&\n    typeof (x as { entries?: unknown }).entries === \"function\" &&\n    typeof (x as { append?: unknown }).append === \"function\"\n  );\n}\n\n/**\n * Convert a `FormData` into a plain object. Repeated keys become arrays; File\n * values are passed through untouched. Empty strings are preserved (validation\n * decides what \"required\" means).\n */\nexport function formDataToObject(fd: FormDataLike): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of fd.entries()) {\n    if (key in out) {\n      const existing = out[key];\n      if (Array.isArray(existing)) existing.push(value);\n      else out[key] = [existing, value];\n    } else {\n      out[key] = value;\n    }\n  }\n  return out;\n}\n\n/** Normalise any accepted input to a plain object. */\nfunction toObject(input: FormDataLike | Record<string, unknown>): Record<string, unknown> {\n  return isFormData(input) ? formDataToObject(input) : { ...input };\n}\n\n/* ------------------------------------------------------------------ *\n * Core handler\n * ------------------------------------------------------------------ */\n\n/**\n * Validate an input (FormData or object) against a schema, applying spam\n * heuristics first. Returns typed data or per-field errors + the raw values.\n */\nexport function handleForm<T>(\n  input: FormDataLike | Record<string, unknown>,\n  opts: FormOptions<T>,\n): FormResult<T> {\n  const values = toObject(input);\n  const formKey = opts.formErrorKey ?? DEFAULT_FORM_KEY;\n\n  // 1. Honeypot — a non-empty hidden field means a bot.\n  if (opts.honeypot) {\n    const trap = values[opts.honeypot];\n    if (typeof trap === \"string\" ? trap.trim() !== \"\" : trap != null && trap !== \"\") {\n      return spam(opts, values, formKey);\n    }\n  }\n\n  // 2. Timing — submitted implausibly fast after render.\n  if (opts.minSubmitMs && opts.minSubmitMs > 0) {\n    const tsField = opts.timestampField ?? DEFAULT_TS_FIELD;\n    const raw = values[tsField];\n    const ts = typeof raw === \"string\" ? Number(raw) : typeof raw === \"number\" ? raw : NaN;\n    if (Number.isFinite(ts)) {\n      const elapsed = Date.now() - ts;\n      if (elapsed >= 0 && elapsed < opts.minSubmitMs) {\n        return spam(opts, values, formKey);\n      }\n    }\n  }\n\n  // 3. Strip internal fields before validation so schemas can stay `.strict()`.\n  const cleaned = stripInternal(values, opts);\n\n  // 4. Validate.\n  const r = opts.schema.safeParse(cleaned);\n  if (r.success) return { ok: true, data: r.data };\n  return { ok: false, errors: r.error.flatten(), values: cleaned };\n}\n\nfunction stripInternal<T>(values: Record<string, unknown>, opts: FormOptions<T>): Record<string, unknown> {\n  const drop = new Set<string>();\n  if (opts.honeypot) drop.add(opts.honeypot);\n  drop.add(opts.timestampField ?? DEFAULT_TS_FIELD);\n  if (drop.size === 0) return values;\n  const out: Record<string, unknown> = {};\n  for (const k of Object.keys(values)) if (!drop.has(k)) out[k] = values[k];\n  return out;\n}\n\nfunction spam<T>(opts: FormOptions<T>, values: Record<string, unknown>, formKey: string): FormResult<T> {\n  return {\n    ok: false,\n    spam: true,\n    values,\n    errors: { [formKey]: opts.spamMessage ?? DEFAULT_SPAM_MSG },\n  };\n}\n\n/* ------------------------------------------------------------------ *\n * createForm — reusable handler bound to one schema\n * ------------------------------------------------------------------ */\n\nexport interface Form<T> {\n  /** Validate any input; returns typed data or errors. */\n  handle(input: FormDataLike | Record<string, unknown>): FormResult<T>;\n  /**\n   * Next.js Server Action signature `(prevState, formData) => result`.\n   * The previous state is ignored; it exists so this drops straight into\n   * `useActionState`.\n   */\n  action(prevState: unknown, formData: FormDataLike): FormResult<T>;\n}\n\n/** Bind a schema + spam options once and reuse the handler across requests. */\nexport function createForm<T>(opts: FormOptions<T>): Form<T> {\n  return {\n    handle: (input) => handleForm(input, opts),\n    action: (_prev, formData) => handleForm(formData, opts),\n  };\n}\n\n/* ------------------------------------------------------------------ *\n * Client helpers (framework-agnostic, no React needed)\n * ------------------------------------------------------------------ */\n\n/**\n * Attributes for a visually-hidden honeypot input. Spread onto an `<input>`:\n * `<input {...honeypotProps(\"company\")} />`.\n */\nexport function honeypotProps(name: string): {\n  type: \"text\";\n  name: string;\n  tabIndex: -1;\n  autoComplete: \"off\";\n  \"aria-hidden\": \"true\";\n  style: Record<string, string>;\n} {\n  return {\n    type: \"text\",\n    name,\n    tabIndex: -1,\n    autoComplete: \"off\",\n    \"aria-hidden\": \"true\",\n    style: {\n      position: \"absolute\",\n      width: \"1px\",\n      height: \"1px\",\n      padding: \"0\",\n      margin: \"-1px\",\n      overflow: \"hidden\",\n      clip: \"rect(0 0 0 0)\",\n      whiteSpace: \"nowrap\",\n      border: \"0\",\n    },\n  };\n}\n\n/** A `<input type=\"hidden\">`-ready render timestamp for the timing check. */\nexport function timestampValue(): string {\n  return String(Date.now());\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@lacspace/form",
+  "version": "1.0.0",
+  "description": "End-to-end form handling for the server — turn FormData into typed, validated data with a honeypot + timing spam guard, and get back your data or per-field errors ready to re-render. Shaped for Next.js Server Actions. Zero-dependency, isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "form",
+    "form-handling",
+    "form-validation",
+    "formdata",
+    "server-actions",
+    "nextjs",
+    "honeypot",
+    "spam-protection",
+    "useactionstate",
+    "contact-form",
+    "typescript",
+    "zero-dependency",
+    "isomorphic",
+    "type-safe",
+    "validation"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://lacspace.com/packages",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "form"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}