@conform-to/dom 1.14.0 → 1.15.0

package/README.md

@@ -7,7 +7,7 @@
  ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
 ```
 
-Version 1.14.0 / License MIT / Copyright (c) 2025 Edmund Hung
+Version 1.15.0 / License MIT / Copyright (c) 2025 Edmund Hung
 
 Progressively enhance HTML forms with React. Build resilient, type-safe forms with no hassle using web standards.
 

package/dist/formdata.d.ts

@@ -1,4 +1,4 @@
-import type { FormValue, JsonPrimitive, Serialize, SerializedValue, Submission, SubmissionResult } from './types';
+import type { FormValue, FieldName, JsonPrimitive, Serialize, SerializedValue, Submission, SubmissionResult, UnknownObject } from './types';
 import type { StandardSchemaIssue } from './standard-schema';
 export declare const DEFAULT_INTENT_NAME = "__INTENT__";
 /**
@@ -285,4 +285,81 @@ formData: FormData | URLSearchParams | FormValue | null, options?: {
  * - anything else -> undefined
  */
 export declare function serialize(value: unknown): SerializedValue | null | undefined;
+/**
+ * Retrieve a field value from FormData with optional type guards.
+ *
+ * @example
+ * // Basic field access: return `unknown`
+ * const email = getFieldValue(formData, 'email');
+ * // String type: returns `string`
+ * const name = getFieldValue(formData, 'name', { type: 'string' });
+ * // File type: returns `File`
+ * const avatar = getFieldValue(formData, 'avatar', { type: 'file' });
+ * // Object type: returns { city: unknown, ... }
+ * const address = getFieldValue<Address>(formData, 'address', { type: 'object' });
+ * // Array: returns `unknown[]`
+ * const tags = getFieldValue(formData, 'tags', { array: true });
+ * // Array with object type: returns `Array<{ name: unknown, ... }>`
+ * const items = getFieldValue<Item[]>(formData, 'items', { type: 'object', array: true });
+ * // Optional string type: returns `string | undefined`
+ * const bio = getFieldValue(formData, 'bio', { type: 'string', optional: true });
+ */
+export declare function getFieldValue<FieldShape extends Array<Record<string, unknown>>>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'object';
+    array: true;
+    optional: true;
+}): FieldShape extends Array<infer Item extends Record<string, unknown>> ? Array<UnknownObject<Item>> | undefined : never;
+export declare function getFieldValue<FieldShape extends Array<Record<string, unknown>>>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'object';
+    array: true;
+}): FieldShape extends Array<infer Item extends Record<string, unknown>> ? Array<UnknownObject<Item>> : never;
+export declare function getFieldValue<FieldShape extends Record<string, unknown> = Record<string, unknown>>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'object';
+    optional: true;
+}): UnknownObject<FieldShape> | undefined;
+export declare function getFieldValue<FieldShape extends Record<string, unknown> = Record<string, unknown>>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'object';
+}): UnknownObject<FieldShape>;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'string';
+    array: true;
+    optional: true;
+}): string[] | undefined;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'string';
+    array: true;
+}): string[];
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'string';
+    optional: true;
+}): string | undefined;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'string';
+}): string;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'file';
+    array: true;
+    optional: true;
+}): File[] | undefined;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'file';
+    array: true;
+}): File[];
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'file';
+    optional: true;
+}): File | undefined;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    type: 'file';
+}): File;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    array: true;
+    optional: true;
+}): Array<unknown> | undefined;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
+    array: true;
+}): Array<unknown>;
+export declare function getFieldValue<FieldShape>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options?: {
+    optional?: boolean;
+}): unknown;
 //# sourceMappingURL=formdata.d.ts.map

package/dist/formdata.js

@@ -576,9 +576,81 @@ function serialize(value) {
   return serializePrimitive(value);
 }
 
+/**
+ * Retrieve a field value from FormData with optional type guards.
+ *
+ * @example
+ * // Basic field access: return `unknown`
+ * const email = getFieldValue(formData, 'email');
+ * // String type: returns `string`
+ * const name = getFieldValue(formData, 'name', { type: 'string' });
+ * // File type: returns `File`
+ * const avatar = getFieldValue(formData, 'avatar', { type: 'file' });
+ * // Object type: returns { city: unknown, ... }
+ * const address = getFieldValue<Address>(formData, 'address', { type: 'object' });
+ * // Array: returns `unknown[]`
+ * const tags = getFieldValue(formData, 'tags', { array: true });
+ * // Array with object type: returns `Array<{ name: unknown, ... }>`
+ * const items = getFieldValue<Item[]>(formData, 'items', { type: 'object', array: true });
+ * // Optional string type: returns `string | undefined`
+ * const bio = getFieldValue(formData, 'bio', { type: 'string', optional: true });
+ */
+
+function getFieldValue(formData, name, options) {
+  var {
+    type,
+    array,
+    optional
+  } = options !== null && options !== void 0 ? options : {};
+  var value;
+
+  // Check if formData has a direct entry
+  if (formData.has(name)) {
+    // Get value based on array option
+    value = array ? formData.getAll(name) : formData.get(name);
+  } else {
+    // Parse formData and use getValueAtPath
+    var _submission = parseSubmission(formData, {
+      stripEmptyValues: false
+    });
+    value = getValueAtPath(_submission.payload, name);
+  }
+
+  // If optional and value is undefined, skip validation and return early
+  if (optional && value === undefined) {
+    return;
+  }
+
+  // Type guards - validate the value matches the expected type
+  if (array && !Array.isArray(value)) {
+    throw new Error("Expected field \"".concat(name, "\" to be an array, but got ").concat(util.getTypeName(value)));
+  }
+  if (type) {
+    var items = array ? value : [value];
+    var predicate = {
+      string: v => typeof v === 'string',
+      file: v => v instanceof File,
+      object: util.isPlainObject
+    }[type];
+    var typeName = {
+      string: 'a string',
+      file: 'a File',
+      object: 'an object'
+    }[type];
+    for (var i = 0; i < items.length; i++) {
+      if (!predicate(items[i])) {
+        var field = array ? "".concat(name, "[").concat(i, "]") : name;
+        throw new Error("Expected field \"".concat(field, "\" to be ").concat(typeName, ", but got ").concat(util.getTypeName(items[i])));
+      }
+    }
+  }
+  return value;
+}
+
 exports.DEFAULT_INTENT_NAME = DEFAULT_INTENT_NAME;
 exports.appendPathSegment = appendPathSegment;
 exports.formatPathSegments = formatPathSegments;
+exports.getFieldValue = getFieldValue;
 exports.getFormData = getFormData;
 exports.getPathSegments = getPathSegments;
 exports.getRelativePath = getRelativePath;

package/dist/formdata.mjs

@@ -1,6 +1,6 @@
 import { objectSpread2 as _objectSpread2 } from './_virtual/_rollupPluginBabelHelpers.mjs';
 import { isSubmitter, isGlobalInstance } from './dom.mjs';
-import { isPlainObject, stripFiles, deepEqual } from './util.mjs';
+import { isPlainObject, stripFiles, deepEqual, getTypeName } from './util.mjs';
 import { formatIssues } from './standard-schema.mjs';
 
 var DEFAULT_INTENT_NAME = '__INTENT__';
@@ -572,4 +572,75 @@ function serialize(value) {
   return serializePrimitive(value);
 }
 
-export { DEFAULT_INTENT_NAME, appendPathSegment, formatPathSegments, getFormData, getPathSegments, getRelativePath, getValueAtPath, isDirty, isPrefix, parseSubmission, report, serialize, setValueAtPath };
+/**
+ * Retrieve a field value from FormData with optional type guards.
+ *
+ * @example
+ * // Basic field access: return `unknown`
+ * const email = getFieldValue(formData, 'email');
+ * // String type: returns `string`
+ * const name = getFieldValue(formData, 'name', { type: 'string' });
+ * // File type: returns `File`
+ * const avatar = getFieldValue(formData, 'avatar', { type: 'file' });
+ * // Object type: returns { city: unknown, ... }
+ * const address = getFieldValue<Address>(formData, 'address', { type: 'object' });
+ * // Array: returns `unknown[]`
+ * const tags = getFieldValue(formData, 'tags', { array: true });
+ * // Array with object type: returns `Array<{ name: unknown, ... }>`
+ * const items = getFieldValue<Item[]>(formData, 'items', { type: 'object', array: true });
+ * // Optional string type: returns `string | undefined`
+ * const bio = getFieldValue(formData, 'bio', { type: 'string', optional: true });
+ */
+
+function getFieldValue(formData, name, options) {
+  var {
+    type,
+    array,
+    optional
+  } = options !== null && options !== void 0 ? options : {};
+  var value;
+
+  // Check if formData has a direct entry
+  if (formData.has(name)) {
+    // Get value based on array option
+    value = array ? formData.getAll(name) : formData.get(name);
+  } else {
+    // Parse formData and use getValueAtPath
+    var _submission = parseSubmission(formData, {
+      stripEmptyValues: false
+    });
+    value = getValueAtPath(_submission.payload, name);
+  }
+
+  // If optional and value is undefined, skip validation and return early
+  if (optional && value === undefined) {
+    return;
+  }
+
+  // Type guards - validate the value matches the expected type
+  if (array && !Array.isArray(value)) {
+    throw new Error("Expected field \"".concat(name, "\" to be an array, but got ").concat(getTypeName(value)));
+  }
+  if (type) {
+    var items = array ? value : [value];
+    var predicate = {
+      string: v => typeof v === 'string',
+      file: v => v instanceof File,
+      object: isPlainObject
+    }[type];
+    var typeName = {
+      string: 'a string',
+      file: 'a File',
+      object: 'an object'
+    }[type];
+    for (var i = 0; i < items.length; i++) {
+      if (!predicate(items[i])) {
+        var field = array ? "".concat(name, "[").concat(i, "]") : name;
+        throw new Error("Expected field \"".concat(field, "\" to be ").concat(typeName, ", but got ").concat(getTypeName(items[i])));
+      }
+    }
+  }
+  return value;
+}
+
+export { DEFAULT_INTENT_NAME, appendPathSegment, formatPathSegments, getFieldValue, getFormData, getPathSegments, getRelativePath, getValueAtPath, isDirty, isPrefix, parseSubmission, report, serialize, setValueAtPath };

package/dist/future/index.d.ts

@@ -1,5 +1,5 @@
-export type { Serialize, FormValue, FormError, Submission, SubmissionResult, ValidationAttributes, } from '../types';
-export { DEFAULT_INTENT_NAME, getFormData, isDirty, parseSubmission, getPathSegments, formatPathSegments, appendPathSegment, getRelativePath, getValueAtPath, setValueAtPath, report, serialize, } from '../formdata';
+export type { Serialize, FieldName, FormValue, FormError, Submission, SubmissionResult, ValidationAttributes, } from '../types';
+export { DEFAULT_INTENT_NAME, getFormData, isDirty, parseSubmission, getPathSegments, formatPathSegments, appendPathSegment, getRelativePath, getValueAtPath, setValueAtPath, report, serialize, getFieldValue, } from '../formdata';
 export { isPlainObject, deepEqual } from '../util';
 export { isFieldElement, isGlobalInstance, updateField, createFileList, createSubmitEvent, createGlobalFormsObserver, focus, change, blur, getFormAction, getFormEncType, getFormMethod, requestSubmit, requestIntent, } from '../dom';
 export { formatIssues } from '../standard-schema';

package/dist/future/index.js

@@ -12,6 +12,7 @@ var standardSchema = require('../standard-schema.js');
 exports.DEFAULT_INTENT_NAME = formdata.DEFAULT_INTENT_NAME;
 exports.appendPathSegment = formdata.appendPathSegment;
 exports.formatPathSegments = formdata.formatPathSegments;
+exports.getFieldValue = formdata.getFieldValue;
 exports.getFormData = formdata.getFormData;
 exports.getPathSegments = formdata.getPathSegments;
 exports.getRelativePath = formdata.getRelativePath;

package/dist/future/index.mjs

@@ -1,4 +1,4 @@
-export { DEFAULT_INTENT_NAME, appendPathSegment, formatPathSegments, getFormData, getPathSegments, getRelativePath, getValueAtPath, isDirty, parseSubmission, report, serialize, setValueAtPath } from '../formdata.mjs';
+export { DEFAULT_INTENT_NAME, appendPathSegment, formatPathSegments, getFieldValue, getFormData, getPathSegments, getRelativePath, getValueAtPath, isDirty, parseSubmission, report, serialize, setValueAtPath } from '../formdata.mjs';
 export { deepEqual, isPlainObject } from '../util.mjs';
 export { blur, change, createFileList, createGlobalFormsObserver, createSubmitEvent, focus, getFormAction, getFormEncType, getFormMethod, isFieldElement, isGlobalInstance, requestIntent, requestSubmit, updateField } from '../dom.mjs';
 export { formatIssues } from '../standard-schema.mjs';

package/dist/types.d.ts

@@ -76,6 +76,10 @@ export type SubmissionResult<ErrorShape = string, ValueType extends JsonPrimitiv
      */
     reset?: boolean;
 };
+/** The name of an input field with type information for TypeScript inference. */
+export type FieldName<FieldShape> = string & {
+    '~shape'?: FieldShape;
+};
 /**
  * The input attributes with related to the Constraint Validation API
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
@@ -115,4 +119,14 @@ export type Serialize = (value: unknown) => SerializedValue | null | undefined;
  * - Arrays allow representing multi-value fields.
  */
 export type SerializedValue = string | string[] | File | File[];
+/**
+ * Flatten a discriminated union into a single type with all properties.
+ */
+export type Combine<T, K extends PropertyKey = T extends unknown ? keyof T : never> = T extends unknown ? T & Partial<Record<Exclude<K, keyof T>, never>> : never;
+/**
+ * Maps all keys of T (including all keys from discriminated unions) to unknown.
+ */
+export type UnknownObject<T> = [T] extends [Record<string, any>] ? {
+    [K in keyof Combine<T>]-?: unknown;
+} : never;
 //# sourceMappingURL=types.d.ts.map

package/dist/util.d.ts

@@ -12,4 +12,8 @@ export declare function isPlainObject(obj: unknown): obj is Record<string | numb
  */
 export declare function deepEqual(left: unknown, right: unknown): boolean;
 export declare function stripFiles<Type extends string | number | boolean | File | null>(value: Record<string, FormValue<Type>>): Record<string, FormValue<Exclude<Type, File>>>;
+/**
+ * Helper to get readable type name for error messages
+ */
+export declare function getTypeName(value: unknown): string;
 //# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -78,9 +78,23 @@ function stripFiles(value) {
   return JSON.parse(json);
 }
 
+/**
+ * Helper to get readable type name for error messages
+ */
+function getTypeName(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'Array';
+  if (typeof value === 'object') {
+    var _value$constructor$na, _value$constructor;
+    return (_value$constructor$na = (_value$constructor = value.constructor) === null || _value$constructor === void 0 ? void 0 : _value$constructor.name) !== null && _value$constructor$na !== void 0 ? _value$constructor$na : 'Object';
+  }
+  return typeof value;
+}
+
 exports.clone = clone;
 exports.deepEqual = deepEqual;
 exports.generateId = generateId;
+exports.getTypeName = getTypeName;
 exports.invariant = invariant;
 exports.isPlainObject = isPlainObject;
 exports.stripFiles = stripFiles;

package/dist/util.mjs

@@ -74,4 +74,17 @@ function stripFiles(value) {
   return JSON.parse(json);
 }
 
-export { clone, deepEqual, generateId, invariant, isPlainObject, stripFiles };
+/**
+ * Helper to get readable type name for error messages
+ */
+function getTypeName(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'Array';
+  if (typeof value === 'object') {
+    var _value$constructor$na, _value$constructor;
+    return (_value$constructor$na = (_value$constructor = value.constructor) === null || _value$constructor === void 0 ? void 0 : _value$constructor.name) !== null && _value$constructor$na !== void 0 ? _value$constructor$na : 'Object';
+  }
+  return typeof value;
+}
+
+export { clone, deepEqual, generateId, getTypeName, invariant, isPlainObject, stripFiles };

package/package.json

@@ -3,7 +3,7 @@
   "description": "A set of opinionated helpers built on top of the Constraint Validation API",
   "homepage": "https://conform.guide",
   "license": "MIT",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",