@duplojs/utils 1.5.2 → 1.5.3

package/dist/clean/primitive/base.d.ts

@@ -239,7 +239,7 @@ export type Boolean = ReturnType<typeof Boolean["createWithUnknownOrThrow"]>;
  * @namespace C
  * 
  */
-export declare const Date: PrimitiveHandler<DDate.TheDate, DDate.TheDate | globalThis.Date | `date${number}-` | `date${number}+`>;
+export declare const Date: PrimitiveHandler<DDate.TheDate, `date${number}-` | `date${number}+` | DDate.TheDate | globalThis.Date>;
 export type Date = ReturnType<typeof Date["createWithUnknownOrThrow"]>;
 /**
  * Business primitive for duration values (`TheTime`).

package/dist/common/formData.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 var escapeRegExp = require('./escapeRegExp.cjs');
+var theTime = require('../date/theTime.cjs');
+var theDate = require('../date/theDate.cjs');
 
 const separator = "/*\\";
 const firstElementInPathRegex = new RegExp(`^((?:(?!${escapeRegExp.escapeRegExp(separator)}).)*)(?:${escapeRegExp.escapeRegExp(separator)})?`);
@@ -17,9 +19,18 @@ class TheFormData extends FormData {
     }
     static *toFlatEntries(value, path) {
         if (typeof value === "string"
-            || value instanceof File) {
+            || value instanceof theTime.TheTime
+            || value instanceof theDate.TheDate
+            || typeof value === "number"
+            || typeof value === "boolean") {
+            yield [path ?? "", value.toString()];
+        }
+        else if (value instanceof File) {
             yield [path ?? "", value];
         }
+        else if (value === null) {
+            yield [path ?? "", "null"];
+        }
         else if (value === undefined) {
             return;
         }
@@ -83,6 +94,9 @@ class TheFormData extends FormData {
         return new TheFormData(inputValues);
     }
 }
+/**
+ * {@include common/createFormData/index.md}
+ */
 function createFormData(inputValues) {
     return TheFormData.new(inputValues);
 }

package/dist/common/formData.d.ts

@@ -1,11 +1,69 @@
-type EligibleFormDataValue = (string | File | undefined | {
+import * as DDate from "../date";
+export type EligibleFormDataValue = (boolean | number | null | string | File | undefined | DDate.TheDate | DDate.TheTime | {
     [key: string]: EligibleFormDataValue;
 } | EligibleFormDataValue[]);
 export declare class TheFormData<GenericValues extends Record<string, EligibleFormDataValue>> extends FormData {
     readonly inputValues: GenericValues;
     private constructor();
-    static toFlatEntries(value: EligibleFormDataValue, path?: string): Iterable<[string, string | File]>;
+    static toFlatEntries(value: EligibleFormDataValue, path?: string): Iterable<[string, string | File], void>;
     static fromEntries(iterable: Iterable<[string, unknown]>, arrayMaxIndex: number): object;
 }
+/**
+ * Creates an extended `FormData` instance from nested values and provides helpers to flatten or rebuild entries.
+ * 
+ * **Supported call styles:**
+ * - Classic: `createFormData(inputValues)` -> returns a `TheFormData` instance
+ * 
+ * The returned instance extends native `FormData` and stores the original object in `inputValues`.
+ * Supported values are `string`, `File`, `boolean`, `number`, `null`, `undefined`, `DDate.TheDate`, `DDate.TheTime`, objects, and arrays.
+ * At flatten time, non-`File` values are serialized to strings (`null` becomes `"null"`).
+ * For backend reconstruction, use `TheFormData.fromEntries(...)` to rebuild nested objects from flattened form-data keys.
+ * 
+ * ```ts
+ * const created = createFormData(
+ * 	{
+ * 		profile: {
+ * 			name: "Ada",
+ * 			tags: ["core", "utils"],
+ * 		},
+ * 		enabled: true,
+ * 		retryCount: 2,
+ * 		optionalValue: null,
+ * 		createdDate: DDate.createOrThrow(1735689600000),
+ * 		createdTime: DDate.createTimeOrThrow(45000000),
+ * 	},
+ * );
+ * const flattenedName = created.get("profile/*\\name");
+ * // flattenedName: "Ada"
+ * const flattenedEnabled = created.get("enabled");
+ * // flattenedEnabled: "true"
+ * const flattenedNull = created.get("optionalValue");
+ * // flattenedNull: "null"
+ * 
+ * const flatEntries = Array.from(
+ * 	TheFormData.toFlatEntries({
+ * 		tags: ["core", "utils"],
+ * 		time: DDate.createTimeOrThrow(31500000),
+ * 	}),
+ * );
+ * // flatEntries: [["tags/*\\[0]", "core"], ["tags/*\\[1]", "utils"], ["time", "time31500000+"]]
+ * 
+ * const rebuilt = TheFormData.fromEntries(
+ * 	[
+ * 		["profile/*\\name", "Ada"],
+ * 		["profile/*\\tags/*\\[0]", "core"],
+ * 		["enabled", "true"],
+ * 	],
+ * 	10,
+ * );
+ * // rebuilt: { profile: { name: "Ada", tags: ["core"] }, enabled: "true" }
+ * ```
+ * 
+ * @remarks
+ * - `TheFormData.toFlatEntries(...)` flattens nested objects/arrays into path keys using the `/*\` separator.
+ * - `TheFormData.fromEntries(...)` ignores `__proto__`, `constructor`, and `prototype` paths for safety.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/createFormData
+ * 
+ */
 export declare function createFormData<GenericValues extends Record<string, EligibleFormDataValue>>(inputValues: GenericValues): TheFormData<GenericValues>;
-export {};

package/dist/common/formData.mjs

@@ -1,4 +1,6 @@
 import { escapeRegExp } from './escapeRegExp.mjs';
+import { TheTime } from '../date/theTime.mjs';
+import { TheDate } from '../date/theDate.mjs';
 
 const separator = "/*\\";
 const firstElementInPathRegex = new RegExp(`^((?:(?!${escapeRegExp(separator)}).)*)(?:${escapeRegExp(separator)})?`);
@@ -15,9 +17,18 @@ class TheFormData extends FormData {
     }
     static *toFlatEntries(value, path) {
         if (typeof value === "string"
-            || value instanceof File) {
+            || value instanceof TheTime
+            || value instanceof TheDate
+            || typeof value === "number"
+            || typeof value === "boolean") {
+            yield [path ?? "", value.toString()];
+        }
+        else if (value instanceof File) {
             yield [path ?? "", value];
         }
+        else if (value === null) {
+            yield [path ?? "", "null"];
+        }
         else if (value === undefined) {
             return;
         }
@@ -81,6 +92,9 @@ class TheFormData extends FormData {
         return new TheFormData(inputValues);
     }
 }
+/**
+ * {@include common/createFormData/index.md}
+ */
 function createFormData(inputValues) {
     return TheFormData.new(inputValues);
 }

package/dist/dataParser/identifier.d.ts

@@ -42,7 +42,7 @@ export declare const identifier: {
         input: boolean;
         output: boolean;
     }>> | import("../common").KindHandler<import("../common").KindDefinition<"@DuplojsUtilsDataParser/base", {
-        input: import("../date").TheDate | Date | `date${number}-` | `date${number}+`;
+        input: `date${number}-` | `date${number}+` | import("../date").TheDate | Date;
         output: import("../date").TheDate;
     }>> | import("../common").KindHandler<import("../common").KindDefinition<"@DuplojsUtilsDataParser/base", {
         input: number | import("../date").TheTime | `time${number}-` | `time${number}+`;
@@ -91,7 +91,7 @@ export declare const identifier: {
         input: boolean;
         output: boolean;
     }>> | import("../common").KindHandler<import("../common").KindDefinition<"@DuplojsUtilsDataParser/base", {
-        input: import("../date").TheDate | Date | `date${number}-` | `date${number}+`;
+        input: `date${number}-` | `date${number}+` | import("../date").TheDate | Date;
         output: import("../date").TheDate;
     }>> | import("../common").KindHandler<import("../common").KindDefinition<"@DuplojsUtilsDataParser/base", {
         input: number | import("../date").TheTime | `time${number}-` | `time${number}+`;

package/dist/date/createOrThrow.cjs

@@ -2,9 +2,9 @@
 
 var create = require('./create.cjs');
 var kind = require('../common/kind.cjs');
+var errorKindNamespace = require('../common/errorKindNamespace.cjs');
 var is = require('../either/left/is.cjs');
 var unwrap = require('../common/unwrap.cjs');
-var errorKindNamespace = require('../common/errorKindNamespace.cjs');
 
 class CreateTheDateError extends kind.kindHeritage("create-the-date-error", errorKindNamespace.createErrorKind("create-the-date-error"), Error) {
     input;

package/dist/date/createOrThrow.mjs

@@ -1,8 +1,8 @@
 import { create } from './create.mjs';
 import { kindHeritage } from '../common/kind.mjs';
+import { createErrorKind } from '../common/errorKindNamespace.mjs';
 import { isLeft } from '../either/left/is.mjs';
 import { unwrap } from '../common/unwrap.mjs';
-import { createErrorKind } from '../common/errorKindNamespace.mjs';
 
 class CreateTheDateError extends kindHeritage("create-the-date-error", createErrorKind("create-the-date-error"), Error) {
     input;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duplojs/utils",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "author": {
     "name": "mathcovax",
     "url": "https://github.com/mathcovax"