@gostack-framework/react 0.0.0-stage → 0.1.0

package/dist/utils/toFormData.d.ts

@@ -0,0 +1,152 @@
+/**
+ * toFormData Utility
+ *
+ * Converts JavaScript objects to FormData with support for:
+ * - Nested objects (flattened with bracket notation)
+ * - Arrays (configurable format: brackets[], indices[0], or flat)
+ * - Files and Blobs (passed through directly)
+ * - Dates (converted to ISO string)
+ * - Booleans (converted to "1"/"0" or "true"/"false")
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const formData = toFormData({
+ *     title: "My Report",
+ *     attachments: [file1, file2],
+ *     meta: { tags: ["urgent", "review"] }
+ * });
+ *
+ * // With options
+ * const formData = toFormData(payload, {
+ *     arrayFormat: 'indices',  // Use [0], [1] instead of []
+ *     booleanFormat: 'string', // Use "true"/"false" instead of "1"/"0"
+ * });
+ * ```
+ */
+/**
+ * Supported value types for FormData conversion
+ */
+export type FormDataValue = string | number | boolean | null | undefined | File | Blob | FileList | Date | FormDataValue[] | {
+    [key: string]: FormDataValue;
+};
+/**
+ * Array format options
+ * - `brackets`: key[]=value (PHP/Laravel default)
+ * - `indices`: key[0]=value (Java/.NET)
+ * - `flat`: key=value repeated (some REST APIs)
+ */
+export type ArrayFormat = "brackets" | "indices" | "flat";
+/**
+ * Boolean format options
+ * - `numeric`: "1" for true, "0" for false (PHP default)
+ * - `string`: "true" or "false"
+ */
+export type BooleanFormat = "numeric" | "string";
+/**
+ * Date format options
+ * - `iso`: ISO 8601 string (default)
+ * - `timestamp`: Unix timestamp in milliseconds
+ * - `date`: YYYY-MM-DD format
+ */
+export type DateFormat = "iso" | "timestamp" | "date";
+/**
+ * Options for toFormData conversion
+ */
+export interface ToFormDataOptions {
+    /**
+     * How to format array keys
+     * @default 'brackets'
+     */
+    arrayFormat?: ArrayFormat;
+    /**
+     * How to format boolean values
+     * @default 'numeric'
+     */
+    booleanFormat?: BooleanFormat;
+    /**
+     * How to format Date values
+     * @default 'iso'
+     */
+    dateFormat?: DateFormat;
+    /**
+     * Skip null and undefined values
+     * @default true
+     */
+    skipNull?: boolean;
+    /**
+     * Skip empty string values
+     * @default false
+     */
+    skipEmpty?: boolean;
+    /**
+     * Skip empty arrays
+     * @default true
+     */
+    skipEmptyArrays?: boolean;
+}
+/**
+ * Convert a JavaScript object to FormData
+ *
+ * @param payload - The object to convert
+ * @param options - Conversion options
+ * @returns FormData instance
+ *
+ * @example
+ * ```ts
+ * // Example 1: Simple form with file
+ * const formData = toFormData({
+ *     title: "My Document",
+ *     file: selectedFile,
+ *     isActive: true
+ * });
+ * // Result:
+ * // title: "My Document"
+ * // file: [File object]
+ * // isActive: "1"
+ *
+ * // Example 2: Nested object with arrays
+ * const formData = toFormData({
+ *     title: "Report",
+ *     attachments: [file1, file2],
+ *     meta: {
+ *         tags: ["urgent", "review"],
+ *         priority: 1
+ *     }
+ * });
+ * // Result (brackets format - default):
+ * // title: "Report"
+ * // attachments[]: [File1]
+ * // attachments[]: [File2]
+ * // meta[tags][]: "urgent"
+ * // meta[tags][]: "review"
+ * // meta[priority]: "1"
+ *
+ * // Example 3: Using indices format for .NET backend
+ * const formData = toFormData({
+ *     items: ["a", "b", "c"]
+ * }, { arrayFormat: 'indices' });
+ * // Result:
+ * // items[0]: "a"
+ * // items[1]: "b"
+ * // items[2]: "c"
+ * ```
+ */
+export declare const toFormData: (payload: Record<string, FormDataValue>, options?: ToFormDataOptions) => FormData;
+/**
+ * Debug helper to log FormData contents
+ */
+export declare const logFormDataContents: (formData: FormData, label?: string) => void;
+/**
+ * Type-safe wrapper for React Hook Form integration
+ *
+ * @example
+ * ```ts
+ * const onSubmit = handleSubmit((data) => {
+ *     const formData = formDataFromRHF(data);
+ *     await api.post('/upload', formData, { meta: { multipart: true } });
+ * });
+ * ```
+ */
+export declare const formDataFromRHF: <T extends Record<string, unknown>>(data: T, options?: ToFormDataOptions) => FormData;
+export default toFormData;

package/dist/utils/toFormData.js

@@ -0,0 +1,250 @@
+/**
+ * toFormData Utility
+ *
+ * Converts JavaScript objects to FormData with support for:
+ * - Nested objects (flattened with bracket notation)
+ * - Arrays (configurable format: brackets[], indices[0], or flat)
+ * - Files and Blobs (passed through directly)
+ * - Dates (converted to ISO string)
+ * - Booleans (converted to "1"/"0" or "true"/"false")
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const formData = toFormData({
+ *     title: "My Report",
+ *     attachments: [file1, file2],
+ *     meta: { tags: ["urgent", "review"] }
+ * });
+ *
+ * // With options
+ * const formData = toFormData(payload, {
+ *     arrayFormat: 'indices',  // Use [0], [1] instead of []
+ *     booleanFormat: 'string', // Use "true"/"false" instead of "1"/"0"
+ * });
+ * ```
+ */
+const defaultOptions = {
+    arrayFormat: "brackets",
+    booleanFormat: "numeric",
+    dateFormat: "iso",
+    skipNull: true,
+    skipEmpty: false,
+    skipEmptyArrays: true,
+};
+/**
+ * Build the key for nested properties
+ */
+const buildKey = (prefix, key, isArrayItem, arrayFormat, index) => {
+    if (!prefix) {
+        return key;
+    }
+    if (isArrayItem) {
+        switch (arrayFormat) {
+            case "indices":
+                return `${prefix}[${index}]`;
+            case "flat":
+                return prefix;
+            case "brackets":
+            default:
+                return `${prefix}[]`;
+        }
+    }
+    return `${prefix}[${key}]`;
+};
+/**
+ * Format a boolean value based on options
+ */
+const formatBoolean = (value, format) => {
+    if (format === "string") {
+        return value ? "true" : "false";
+    }
+    return value ? "1" : "0";
+};
+/**
+ * Format a Date value based on options
+ */
+const formatDate = (value, format) => {
+    switch (format) {
+        case "timestamp":
+            return String(value.getTime());
+        case "date":
+            return value.toISOString().split("T")[0];
+        case "iso":
+        default:
+            return value.toISOString();
+    }
+};
+/**
+ * Recursively append values to FormData
+ */
+const appendToFormData = (formData, key, value, options, seen) => {
+    // Handle null/undefined
+    if (value === null || value === undefined) {
+        if (!options.skipNull) {
+            formData.append(key, "");
+        }
+        return;
+    }
+    // Handle empty strings
+    if (value === "" && options.skipEmpty) {
+        return;
+    }
+    // Handle FileList (convert to array of files)
+    if (typeof FileList !== "undefined" && value instanceof FileList) {
+        Array.from(value).forEach((file, index) => {
+            const fileKey = buildKey(key, "", true, options.arrayFormat, index);
+            formData.append(fileKey, file);
+        });
+        return;
+    }
+    // Handle File/Blob (passthrough)
+    if (value instanceof File || value instanceof Blob) {
+        formData.append(key, value);
+        return;
+    }
+    // Handle Date
+    if (value instanceof Date) {
+        // Skip invalid dates
+        if (Number.isNaN(value.getTime())) {
+            console.warn(`[toFormData] Invalid Date value for key "${key}", skipping`);
+            return;
+        }
+        formData.append(key, formatDate(value, options.dateFormat));
+        return;
+    }
+    // Handle boolean
+    if (typeof value === "boolean") {
+        formData.append(key, formatBoolean(value, options.booleanFormat));
+        return;
+    }
+    // Handle number
+    if (typeof value === "number") {
+        // Skip NaN and Infinity as they're not valid form values
+        if (Number.isNaN(value) || !Number.isFinite(value)) {
+            console.warn(`[toFormData] Invalid number value for key "${key}" (${value}), skipping`);
+            return;
+        }
+        formData.append(key, String(value));
+        return;
+    }
+    // Handle string
+    if (typeof value === "string") {
+        formData.append(key, value);
+        return;
+    }
+    // Handle arrays
+    if (Array.isArray(value)) {
+        if (value.length === 0 && options.skipEmptyArrays) {
+            return;
+        }
+        value.forEach((item, index) => {
+            const arrayKey = buildKey(key, "", true, options.arrayFormat, index);
+            appendToFormData(formData, arrayKey, item, options, seen);
+        });
+        return;
+    }
+    // Handle objects (nested)
+    if (typeof value === "object") {
+        // Circular reference protection
+        if (seen.has(value)) {
+            console.warn(`[toFormData] Circular reference detected for key "${key}", skipping`);
+            return;
+        }
+        seen.add(value);
+        Object.entries(value).forEach(([nestedKey, nestedValue]) => {
+            const fullKey = buildKey(key, nestedKey, false, options.arrayFormat);
+            appendToFormData(formData, fullKey, nestedValue, options, seen);
+        });
+        return;
+    }
+};
+/**
+ * Convert a JavaScript object to FormData
+ *
+ * @param payload - The object to convert
+ * @param options - Conversion options
+ * @returns FormData instance
+ *
+ * @example
+ * ```ts
+ * // Example 1: Simple form with file
+ * const formData = toFormData({
+ *     title: "My Document",
+ *     file: selectedFile,
+ *     isActive: true
+ * });
+ * // Result:
+ * // title: "My Document"
+ * // file: [File object]
+ * // isActive: "1"
+ *
+ * // Example 2: Nested object with arrays
+ * const formData = toFormData({
+ *     title: "Report",
+ *     attachments: [file1, file2],
+ *     meta: {
+ *         tags: ["urgent", "review"],
+ *         priority: 1
+ *     }
+ * });
+ * // Result (brackets format - default):
+ * // title: "Report"
+ * // attachments[]: [File1]
+ * // attachments[]: [File2]
+ * // meta[tags][]: "urgent"
+ * // meta[tags][]: "review"
+ * // meta[priority]: "1"
+ *
+ * // Example 3: Using indices format for .NET backend
+ * const formData = toFormData({
+ *     items: ["a", "b", "c"]
+ * }, { arrayFormat: 'indices' });
+ * // Result:
+ * // items[0]: "a"
+ * // items[1]: "b"
+ * // items[2]: "c"
+ * ```
+ */
+export const toFormData = (payload, options) => {
+    const formData = new FormData();
+    const mergedOptions = { ...defaultOptions, ...options };
+    const seen = new WeakSet();
+    Object.entries(payload).forEach(([key, value]) => {
+        appendToFormData(formData, key, value, mergedOptions, seen);
+    });
+    return formData;
+};
+/**
+ * Debug helper to log FormData contents
+ */
+export const logFormDataContents = (formData, label) => {
+    console.log(label ? `${label}:` : "FormData contents:");
+    formData.forEach((value, key) => {
+        if (value instanceof File) {
+            console.log(`  ${key}: [File] ${value.name} (${value.size} bytes)`);
+        }
+        else if (typeof value === "object" && value !== null) {
+            console.log(`  ${key}: [Blob] (${value.size} bytes)`);
+        }
+        else {
+            console.log(`  ${key}: ${value}`);
+        }
+    });
+};
+/**
+ * Type-safe wrapper for React Hook Form integration
+ *
+ * @example
+ * ```ts
+ * const onSubmit = handleSubmit((data) => {
+ *     const formData = formDataFromRHF(data);
+ *     await api.post('/upload', formData, { meta: { multipart: true } });
+ * });
+ * ```
+ */
+export const formDataFromRHF = (data, options) => {
+    return toFormData(data, options);
+};
+export default toFormData;
+//# sourceMappingURL=toFormData.js.map

package/dist/utils/toFormData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toFormData.js","sourceRoot":"","sources":["../../src/utils/toFormData.ts"],"names":[],"mappings":"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"}