@duplojs/utils 1.4.57 → 1.4.59

package/dist/clean/primitive/operations/date/dateAddTime.d.ts

@@ -1,33 +1,29 @@
 import { type Date, type Time } from "../../base";
 import { type TheTime } from "../../../../date";
 /**
- * Adds a time duration to a Date and returns a new wrapped Date.
+ * Adds a duration to a wrapped `Date` and returns a wrapped `Date`.
  * 
  * **Supported call styles:**
- * - Classic: `dateAddTime(date, time)` -> returns a Date
- * - Curried: `dateAddTime(time)` -> returns a function waiting for the date
+ * - Classic: `dateAddTime(date, time)` → `Date`
+ * - Curried: `dateAddTime(time)` → function waiting for the date
  * 
- * Use it to move dates forward while keeping values wrapped.
+ * `time` accepts wrapped `Time` or raw `TheTime`.
  * 
  * ```ts
  * const date = C.Date.createOrThrow(D.create("2024-01-01"));
- * const oneHour = C.Time.createOrThrow(D.createTheTime(3_600_000));
+ * const oneHour = C.Time.createOrThrow(D.createTime(1, "hour"));
  * 
  * const later = C.dateAddTime(date, oneHour);
  * // later: C.Date
  * 
  * const curried = pipe(
  * 	date,
- * 	C.dateAddTime(D.createTheTime(60_000)),
+ * 	C.dateAddTime(D.createTime(1, "minute")),
  * );
  * // curried: C.Date
  * 
- * const mixed = C.dateAddTime(
- * 	C.Date.createOrThrow(D.create("2024-01-02")),
- * 	D.createTheTime(500),
- * );
+ * const mixed = C.dateAddTime(date, D.createTime(500, "millisecond"));
  * // mixed: C.Date
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/dateAddTime

package/dist/clean/primitive/operations/date/dateGreaterThan.d.ts

@@ -1,22 +1,24 @@
 import { type Date } from "../../base";
 import { type TheDate } from "../../../../date";
 /**
- * Checks whether a Date is after a threshold.
+ * Checks whether a wrapped `Date` is strictly after a threshold.
  * 
  * **Supported call styles:**
- * - Classic: `dateGreaterThan(date, threshold)` -> returns a boolean
- * - Curried: `dateGreaterThan(threshold)` -> returns a function waiting for the date
+ * - Classic: `dateGreaterThan(date, threshold)` → `boolean`
+ * - Curried: `dateGreaterThan(threshold)` → function waiting for the date
  * 
- * Use it to compare wrapped dates or raw TheDate values.
+ * `threshold` accepts wrapped `Date` or raw `TheDate`.
  * 
  * ```ts
  * const date = C.Date.createOrThrow(D.create("2024-03-01"));
  * const threshold = D.create("2024-02-29");
  * 
- * if (C.dateGreaterThan(date, threshold)) {
- * 	// date is after threshold
- * }
+ * const result = C.dateGreaterThan(date, threshold);
+ * // result: true
  * 
+ * pipe(
+ * 	date,
+ * 	C.dateGreaterThan(threshold),
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/dateGreaterThan

package/dist/clean/primitive/operations/date/dateLessThan.d.ts

@@ -1,22 +1,24 @@
 import { type Date } from "../../base";
 import { type TheDate } from "../../../../date";
 /**
- * Checks whether a Date is before a threshold.
+ * Checks whether a wrapped `Date` is strictly before a threshold.
  * 
  * **Supported call styles:**
- * - Classic: `dateLessThan(date, threshold)` -> returns a boolean
- * - Curried: `dateLessThan(threshold)` -> returns a function waiting for the date
+ * - Classic: `dateLessThan(date, threshold)` → `boolean`
+ * - Curried: `dateLessThan(threshold)` → function waiting for the date
  * 
- * Use it to compare wrapped dates or raw TheDate values.
+ * `threshold` accepts wrapped `Date` or raw `TheDate`.
  * 
  * ```ts
  * const date = C.Date.createOrThrow(D.create("2024-02-29"));
  * const threshold = D.create("2024-03-01");
  * 
- * if (C.dateLessThan(date, threshold)) {
- * 	// date is before threshold
- * }
+ * const result = C.dateLessThan(date, threshold);
+ * // result: true
  * 
+ * pipe(
+ * 	date,
+ * 	C.dateLessThan(threshold),
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/dateLessThan

package/dist/clean/primitive/operations/date/dateMax.d.ts

@@ -2,12 +2,12 @@ import { type TheDate } from "../../../../date";
 import { type Date } from "../../base";
 import { type AnyTuple } from "../../../../common";
 /**
- * Returns the latest date from a tuple of Date values.
+ * Returns the latest wrapped `Date` from a tuple.
  * 
  * **Supported call styles:**
- * - Classic: `dateMax(input)` -> returns a Date
+ * - Classic: `dateMax(input)` → `Date`
  * 
- * The input can mix wrapped Dates and raw TheDate values.
+ * `input` can mix wrapped `Date` and raw `TheDate` values.
  * 
  * ```ts
  * const latest = C.dateMax([
@@ -17,13 +17,6 @@ import { type AnyTuple } from "../../../../common";
  * ]);
  * // latest: C.Date
  * 
- * const fromRaw = C.dateMax([
- * 	D.create("2024-01-05"),
- * 	D.create("2024-01-03"),
- * 	D.create("2024-01-10"),
- * ]);
- * // fromRaw: C.Date
- * 
  * const mixed = C.dateMax([
  * 	C.Date.createOrThrow(D.create("2024-01-08")),
  * 	D.create("2024-01-07"),

package/dist/clean/primitive/operations/date/dateMin.d.ts

@@ -2,12 +2,12 @@ import { type TheDate } from "../../../../date";
 import { type Date } from "../../base";
 import { type AnyTuple } from "../../../../common";
 /**
- * Returns the earliest date from a tuple of Date values.
+ * Returns the earliest wrapped `Date` from a tuple.
  * 
  * **Supported call styles:**
- * - Classic: `dateMin(input)` -> returns a Date
+ * - Classic: `dateMin(input)` → `Date`
  * 
- * The input can mix wrapped Dates and raw TheDate values.
+ * `input` can mix wrapped `Date` and raw `TheDate` values.
  * 
  * ```ts
  * const earliest = C.dateMin([
@@ -17,13 +17,6 @@ import { type AnyTuple } from "../../../../common";
  * ]);
  * // earliest: C.Date
  * 
- * const fromRaw = C.dateMin([
- * 	D.create("2024-01-05"),
- * 	D.create("2024-01-03"),
- * 	D.create("2024-01-10"),
- * ]);
- * // fromRaw: C.Date
- * 
  * const mixed = C.dateMin([
  * 	C.Date.createOrThrow(D.create("2024-01-08")),
  * 	D.create("2024-01-07"),

package/dist/clean/primitive/operations/date/dateSubtractTime.d.ts

@@ -1,33 +1,29 @@
 import { type Date, type Time } from "../../base";
 import { type TheTime } from "../../../../date";
 /**
- * Subtracts a time duration from a Date and returns a new wrapped Date.
+ * Subtracts a duration from a wrapped `Date` and returns a wrapped `Date`.
  * 
  * **Supported call styles:**
- * - Classic: `dateSubtractTime(date, time)` -> returns a Date
- * - Curried: `dateSubtractTime(time)` -> returns a function waiting for the date
+ * - Classic: `dateSubtractTime(date, time)` → `Date`
+ * - Curried: `dateSubtractTime(time)` → function waiting for the date
  * 
- * Use it to move dates backward while keeping values wrapped.
+ * `time` accepts wrapped `Time` or raw `TheTime`.
  * 
  * ```ts
  * const date = C.Date.createOrThrow(D.create("2024-01-02"));
- * const halfMinute = C.Time.createOrThrow(D.createTheTime(30_000));
+ * const halfMinute = C.Time.createOrThrow(D.createTime(30, "second"));
  * 
  * const earlier = C.dateSubtractTime(date, halfMinute);
  * // earlier: C.Date
  * 
  * const curried = pipe(
  * 	date,
- * 	C.dateSubtractTime(D.createTheTime(1_000)),
+ * 	C.dateSubtractTime(D.createTime(1, "second")),
  * );
  * // curried: C.Date
  * 
- * const mixed = C.dateSubtractTime(
- * 	C.Date.createOrThrow(D.create("2024-01-01")),
- * 	D.createTheTime(500),
- * );
+ * const mixed = C.dateSubtractTime(date, D.createTime(500, "millisecond"));
  * // mixed: C.Date
- * 
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/dateSubtractTime

package/dist/clean/primitive/operations/equal.cjs

@@ -8,7 +8,7 @@ function equal(...args) {
         return (input) => equal(input, value);
     }
     const [input, value] = args;
-    return unwrap.unwrap(input) === unwrap.unwrap(value);
+    return unwrap.unwrap(input).toString() === unwrap.unwrap(value).toString();
 }
 
 exports.equal = equal;

package/dist/clean/primitive/operations/equal.d.ts

@@ -1,5 +1,5 @@
 import { type ToLargeEnsemble, type Unwrap } from "../../../common";
-import { type Primitive, type Primitives, type Date, type Time } from "../base";
+import { type Primitive, type Primitives } from "../base";
 /**
  * Compares two wrapped primitives (or a primitive and a raw value) with a type guard.
  * 
@@ -34,5 +34,5 @@ import { type Primitive, type Primitives, type Date, type Time } from "../base";
  * @namespace C
  * 
  */
-export declare function equal<GenericInput extends Primitives, GenericValue extends (GenericInput extends Date ? (Date | Unwrap<Date>) : GenericInput extends Time ? (Time | Unwrap<Time>) : (Primitive<ToLargeEnsemble<Unwrap<GenericInput>>> | ToLargeEnsemble<Unwrap<GenericInput>>))>(value: GenericValue): (input: GenericInput) => input is GenericInput & Primitive<Unwrap<GenericValue>>;
-export declare function equal<GenericInput extends Primitives, GenericValue extends (GenericInput extends Date ? (Date | Unwrap<Date>) : GenericInput extends Time ? (Time | Unwrap<Time>) : (Primitive<ToLargeEnsemble<Unwrap<GenericInput>>> | ToLargeEnsemble<Unwrap<GenericInput>>))>(input: GenericInput, value: GenericValue): input is GenericInput & Primitive<Unwrap<GenericValue>>;
+export declare function equal<GenericInput extends Primitives, GenericValue extends (Primitive<ToLargeEnsemble<Unwrap<GenericInput>>> | ToLargeEnsemble<Unwrap<GenericInput>>)>(value: GenericValue): (input: GenericInput) => input is GenericInput & Primitive<Unwrap<GenericValue>>;
+export declare function equal<GenericInput extends Primitives, GenericValue extends (Primitive<ToLargeEnsemble<Unwrap<GenericInput>>> | ToLargeEnsemble<Unwrap<GenericInput>>)>(input: GenericInput, value: GenericValue): input is GenericInput & Primitive<Unwrap<GenericValue>>;

package/dist/clean/primitive/operations/equal.mjs

@@ -6,7 +6,7 @@ function equal(...args) {
         return (input) => equal(input, value);
     }
     const [input, value] = args;
-    return unwrap(input) === unwrap(value);
+    return unwrap(input).toString() === unwrap(value).toString();
 }
 
 export { equal };

package/dist/clean/primitive/operations/sort.d.ts

@@ -2,13 +2,11 @@ import { type Date, type Number, type String, type Time } from "../base";
 import { type ToWrappedValue, type SortType } from "../../../common";
 import * as DDate from "../../../date";
 /**
- * Sorts an array of primitives (String, Number, Date, Time) in ascending or descending order.
+ * Sorts arrays of wrapped primitives (`String`, `Number`, `Date`, `Time`).
  * 
  * **Supported call styles:**
- * - Classic: `sort(input, type)` -> returns a new array
- * - Curried: `sort(type)` -> returns a function waiting for the input
- * 
- * The output array contains wrapped primitives.
+ * - Classic: `sort(input, type)` → wrapped array
+ * - Curried: `sort(type)` → function waiting for the input
  * 
  * ```ts
  * const numbers = [
@@ -27,13 +25,13 @@ import * as DDate from "../../../date";
  * // desc: C.Number[]
  * 
  * const dates = C.sort([
- * 	D.createTheDate(2),
- * 	D.createTheDate(1),
- * ], "ASC");
- * // dates: C.Date[]
- * 
+ * 	D.create("2024-01-02"),
+ * 	D.create("2024-01-01"),
  * ```
  * 
+ * @remarks
+ * - Supports mixed wrapped/raw values in the same primitive family.
+ * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/sort
  * 
  * @namespace C

package/dist/clean/primitive/operations/time/timeGreaterThan.d.ts

@@ -1,22 +1,24 @@
 import { type Time } from "../../base";
 import { type TheTime } from "../../../../date";
 /**
- * Checks whether a Time is greater than a threshold.
+ * Checks whether a wrapped `Time` is strictly greater than a threshold.
  * 
  * **Supported call styles:**
- * - Classic: `timeGreaterThan(time, threshold)` -> returns a boolean
- * - Curried: `timeGreaterThan(threshold)` -> returns a function waiting for the time
+ * - Classic: `timeGreaterThan(time, threshold)` → `boolean`
+ * - Curried: `timeGreaterThan(threshold)` → function waiting for the time
  * 
- * Use it to compare wrapped durations or raw TheTime values.
+ * `threshold` accepts wrapped `Time` or raw `TheTime`.
  * 
  * ```ts
- * const duration = C.Time.createOrThrow(D.createTheTime(3_600_000));
- * const threshold = D.createTheTime(1_800_000);
+ * const duration = C.Time.createOrThrow(D.createTime(1, "hour"));
+ * const threshold = D.createTime(30, "minute");
  * 
- * if (C.timeGreaterThan(duration, threshold)) {
- * 	// duration is greater than threshold
- * }
+ * const result = C.timeGreaterThan(duration, threshold);
+ * // result: true
  * 
+ * pipe(
+ * 	duration,
+ * 	C.timeGreaterThan(threshold),
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/timeGreaterThan

package/dist/clean/primitive/operations/time/timeLessThan.d.ts

@@ -1,22 +1,24 @@
 import { type Time } from "../../base";
 import { type TheTime } from "../../../../date";
 /**
- * Checks whether a Time is less than a threshold.
+ * Checks whether a wrapped `Time` is strictly less than a threshold.
  * 
  * **Supported call styles:**
- * - Classic: `timeLessThan(time, threshold)` -> returns a boolean
- * - Curried: `timeLessThan(threshold)` -> returns a function waiting for the time
+ * - Classic: `timeLessThan(time, threshold)` → `boolean`
+ * - Curried: `timeLessThan(threshold)` → function waiting for the time
  * 
- * Use it to compare wrapped durations or raw TheTime values.
+ * `threshold` accepts wrapped `Time` or raw `TheTime`.
  * 
  * ```ts
- * const duration = C.Time.createOrThrow(D.createTheTime(3_600_000));
- * const threshold = D.createTheTime(7_200_000);
+ * const duration = C.Time.createOrThrow(D.createTime(1, "hour"));
+ * const threshold = D.createTime(2, "hour");
  * 
- * if (C.timeLessThan(duration, threshold)) {
- * 	// duration is less than threshold
- * }
+ * const result = C.timeLessThan(duration, threshold);
+ * // result: true
  * 
+ * pipe(
+ * 	duration,
+ * 	C.timeLessThan(threshold),
  * ```
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/primitives/operators/timeLessThan

package/dist/clean/primitive/operations/time/timeMax.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var wrapValue = require('../../../../common/wrapValue.cjs');
-var createTheTime = require('../../../../date/createTheTime.cjs');
+var theTime = require('../../../../date/theTime.cjs');
 var unwrap = require('../../../../common/unwrap.cjs');
 var toTimeValue = require('../../../../date/toTimeValue.cjs');
 
@@ -9,7 +9,7 @@ var toTimeValue = require('../../../../date/toTimeValue.cjs');
  * {@include clean/timeMax/index.md}
  */
 function timeMax(input) {
-    return wrapValue.wrapValue(createTheTime.createTheTime(Math.max(...input.map(unwrap.unwrap).map(toTimeValue.toTimeValue))));
+    return wrapValue.wrapValue(theTime.TheTime.new(Math.max(...input.map(unwrap.unwrap).map(toTimeValue.toTimeValue))));
 }
 
 exports.timeMax = timeMax;

package/dist/clean/primitive/operations/time/timeMax.d.ts

@@ -1,32 +1,25 @@
-import { type TheTime } from "../../../../date";
-import { type Time } from "../../base";
+import { TheTime } from "../../../../date";
 import { type AnyTuple } from "../../../../common";
+import { type Time } from "../../base";
 /**
- * Returns the largest duration from a tuple of Time values.
+ * Returns the largest wrapped `Time` from a tuple.
  * 
  * **Supported call styles:**
- * - Classic: `timeMax(input)` -> returns a Time
+ * - Classic: `timeMax(input)` → `Time`
  * 
- * The input can mix wrapped Times and raw TheTime values.
+ * `input` can mix wrapped `Time` and raw `TheTime` values.
  * 
  * ```ts
  * const largest = C.timeMax([
- * 	C.Time.createOrThrow(D.createTheTime(1_000)),
- * 	D.createTheTime(500),
- * 	D.createTheTime(2_000),
+ * 	C.Time.createOrThrow(D.createTime(1_000, "millisecond")),
+ * 	D.createTime(500, "millisecond"),
+ * 	D.createTime(2_000, "millisecond"),
  * ]);
  * // largest: C.Time
  * 
- * const fromRaw = C.timeMax([
- * 	D.createTheTime(10),
- * 	D.createTheTime(5),
- * 	D.createTheTime(20),
- * ]);
- * // fromRaw: C.Time
- * 
  * const mixed = C.timeMax([
- * 	C.Time.createOrThrow(D.createTheTime(100)),
- * 	D.createTheTime(50),
+ * 	C.Time.createOrThrow(D.createTime(100, "millisecond")),
+ * 	D.createTime(50, "millisecond"),
  * ]);
  * // mixed: C.Time
  * 

package/dist/clean/primitive/operations/time/timeMax.mjs

@@ -1,5 +1,5 @@
 import { wrapValue } from '../../../../common/wrapValue.mjs';
-import { createTheTime } from '../../../../date/createTheTime.mjs';
+import { TheTime } from '../../../../date/theTime.mjs';
 import { unwrap } from '../../../../common/unwrap.mjs';
 import { toTimeValue } from '../../../../date/toTimeValue.mjs';
 
@@ -7,7 +7,7 @@ import { toTimeValue } from '../../../../date/toTimeValue.mjs';
  * {@include clean/timeMax/index.md}
  */
 function timeMax(input) {
-    return wrapValue(createTheTime(Math.max(...input.map(unwrap).map(toTimeValue))));
+    return wrapValue(TheTime.new(Math.max(...input.map(unwrap).map(toTimeValue))));
 }
 
 export { timeMax };

package/dist/clean/primitive/operations/time/timeMin.cjs

@@ -1,15 +1,15 @@
 'use strict';
 
-var toTimeValue = require('../../../../date/toTimeValue.cjs');
 var wrapValue = require('../../../../common/wrapValue.cjs');
-var createTheTime = require('../../../../date/createTheTime.cjs');
+var theTime = require('../../../../date/theTime.cjs');
 var unwrap = require('../../../../common/unwrap.cjs');
+var toTimeValue = require('../../../../date/toTimeValue.cjs');
 
 /**
  * {@include clean/timeMin/index.md}
  */
 function timeMin(input) {
-    return wrapValue.wrapValue(createTheTime.createTheTime(Math.min(...input.map(unwrap.unwrap).map(toTimeValue.toTimeValue))));
+    return wrapValue.wrapValue(theTime.TheTime.new(Math.min(...input.map(unwrap.unwrap).map(toTimeValue.toTimeValue))));
 }
 
 exports.timeMin = timeMin;

package/dist/clean/primitive/operations/time/timeMin.d.ts

@@ -1,32 +1,25 @@
-import { type TheTime } from "../../../../date";
-import { type Time } from "../../base";
 import { type AnyTuple } from "../../../../common";
+import { TheTime } from "../../../../date";
+import { type Time } from "../../base";
 /**
- * Returns the smallest duration from a tuple of Time values.
+ * Returns the smallest wrapped `Time` from a tuple.
  * 
  * **Supported call styles:**
- * - Classic: `timeMin(input)` -> returns a Time
+ * - Classic: `timeMin(input)` → `Time`
  * 
- * The input can mix wrapped Times and raw TheTime values.
+ * `input` can mix wrapped `Time` and raw `TheTime` values.
  * 
  * ```ts
  * const smallest = C.timeMin([
- * 	C.Time.createOrThrow(D.createTheTime(1_000)),
- * 	D.createTheTime(500),
- * 	D.createTheTime(2_000),
+ * 	C.Time.createOrThrow(D.createTime(1_000, "millisecond")),
+ * 	D.createTime(500, "millisecond"),
+ * 	D.createTime(2_000, "millisecond"),
  * ]);
  * // smallest: C.Time
  * 
- * const fromRaw = C.timeMin([
- * 	D.createTheTime(10),
- * 	D.createTheTime(5),
- * 	D.createTheTime(20),
- * ]);
- * // fromRaw: C.Time
- * 
  * const mixed = C.timeMin([
- * 	C.Time.createOrThrow(D.createTheTime(100)),
- * 	D.createTheTime(50),
+ * 	C.Time.createOrThrow(D.createTime(100, "millisecond")),
+ * 	D.createTime(50, "millisecond"),
  * ]);
  * // mixed: C.Time
  * 

package/dist/clean/primitive/operations/time/timeMin.mjs

@@ -1,13 +1,13 @@
-import { toTimeValue } from '../../../../date/toTimeValue.mjs';
 import { wrapValue } from '../../../../common/wrapValue.mjs';
-import { createTheTime } from '../../../../date/createTheTime.mjs';
+import { TheTime } from '../../../../date/theTime.mjs';
 import { unwrap } from '../../../../common/unwrap.mjs';
+import { toTimeValue } from '../../../../date/toTimeValue.mjs';
 
 /**
  * {@include clean/timeMin/index.md}
  */
 function timeMin(input) {
-    return wrapValue(createTheTime(Math.min(...input.map(unwrap).map(toTimeValue))));
+    return wrapValue(TheTime.new(Math.min(...input.map(unwrap).map(toTimeValue))));
 }
 
 export { timeMin };

package/dist/clean/unwrapEntity.cjs

@@ -2,9 +2,14 @@
 
 var entity = require('./entity.cjs');
 var flag = require('./flag.cjs');
+var forward = require('../common/forward.cjs');
 var unwrap = require('../common/unwrap.cjs');
 
-function unwrapEntity(entity$1) {
+/**
+ * {@include clean/unwrapEntity/index.md}
+ */
+function unwrapEntity(entity$1, params) {
+    const transformer = params?.transformer ?? forward.forward;
     const unwrapEntity = {};
     for (const prop in entity$1) {
         if (prop === entity.entityKind.runTimeKey) {
@@ -14,10 +19,15 @@ function unwrapEntity(entity$1) {
             unwrapEntity._flags = entity$1[prop];
         }
         else if (entity$1[prop] instanceof Array) {
-            unwrapEntity[prop] = entity$1[prop].map(unwrap.unwrap);
+            const length = entity$1[prop].length;
+            const result = [];
+            for (let index = 0; index < length; index++) {
+                result[index] = transformer(unwrap.unwrap(entity$1[prop][index]));
+            }
+            unwrapEntity[prop] = result;
         }
         else {
-            unwrapEntity[prop] = unwrap.unwrap(entity$1[prop]);
+            unwrapEntity[prop] = transformer(unwrap.unwrap(entity$1[prop]));
         }
     }
     return unwrapEntity;

package/dist/clean/unwrapEntity.d.ts

@@ -1,13 +1,65 @@
-import { type GetKindValue, type SimplifyTopLevel, type Kind, type Unwrap, type DeepReadonly } from "../common";
+import { type GetKindValue, type SimplifyTopLevel, type Kind, type Unwrap, type DeepReadonly, type TransformerFunction, type IsEqual, type Transformer } from "../common";
 import { entityKind, type Entity } from "./entity";
 import { flagKind } from "./flag";
-type UnwrapArrayProperties<GenericValue extends readonly any[]> = GenericValue extends readonly [infer InferredFirst, ...infer InferredRest] ? (InferredRest extends readonly [] ? readonly [] : UnwrapArrayProperties<InferredRest>) extends infer InferredResult extends readonly any[] ? readonly [Unwrap<InferredFirst>, ...InferredResult] : never : readonly Unwrap<GenericValue[number]>[];
-export type UnwrapEntity<GenericEntity extends Entity> = SimplifyTopLevel<DeepReadonly<{
-    [Prop in Extract<keyof GenericEntity, string>]: GenericEntity[Prop] extends readonly any[] ? UnwrapArrayProperties<GenericEntity[Prop]> : Unwrap<GenericEntity[Prop]>;
+type ApplyTransformer<GenericValue extends unknown, GenericTransformer extends TransformerFunction> = IsEqual<GenericTransformer, never> extends true ? GenericValue : GenericTransformer extends TransformerFunction<infer InferredMethodName> ? Transformer<GenericValue, InferredMethodName> : never;
+type UnwrapArrayProperties<GenericValue extends readonly any[], GenericTransformer extends TransformerFunction> = GenericValue extends readonly [infer InferredFirst, ...infer InferredRest] ? (InferredRest extends readonly [] ? readonly [] : UnwrapArrayProperties<InferredRest, GenericTransformer>) extends infer InferredResult extends readonly any[] ? readonly [
+    ApplyTransformer<Unwrap<InferredFirst>, GenericTransformer>,
+    ...InferredResult
+] : never : readonly ApplyTransformer<Unwrap<GenericValue[number]>, GenericTransformer>[];
+export type UnwrapEntity<GenericEntity extends Entity, GenericTransformer extends TransformerFunction = never> = SimplifyTopLevel<DeepReadonly<{
+    [Prop in Extract<keyof GenericEntity, string>]: GenericEntity[Prop] extends readonly any[] ? UnwrapArrayProperties<GenericEntity[Prop], GenericTransformer> : ApplyTransformer<Unwrap<GenericEntity[Prop]>, GenericTransformer>;
 } & {
     [Prop in "_entityName"]: GetKindValue<typeof entityKind, GenericEntity>;
 } & (GenericEntity extends Kind<typeof flagKind.definition, any> ? {
     [Prop in "_flags"]: SimplifyTopLevel<GetKindValue<typeof flagKind, GenericEntity>>;
 } : {})>>;
-export declare function unwrapEntity<GenericEntity extends Entity>(entity: GenericEntity): UnwrapEntity<GenericEntity>;
+/**
+ * Unwraps a `Clean` entity into a readonly plain object.
+ * 
+ * Signature: `unwrapEntity(entity, params?)` → unwrapped object
+ * 
+ * By default, wrapped values are unwrapped as-is. You can pass a transformer (for example `toNative` or `toJSON`) to project values during unwrapping.
+ * 
+ * ```ts
+ * const Id = C.createNewType("userId", DP.number());
+ * const Name = C.createNewType("userName", DP.string());
+ * const Birth = C.createNewType("userBirth", DP.date());
+ * const TimeSpent = C.createNewType("userTimeSpent", DP.time());
+ * 
+ * const User = C.createEntity("User", () => ({
+ * 	id: Id,
+ * 	name: Name,
+ * 	birth: Birth,
+ * 	timeSpent: TimeSpent,
+ * }));
+ * 
+ * const entity = User.new({
+ * 	id: Id.createOrThrow(1),
+ * 	name: Name.createOrThrow("Ada"),
+ * 	birth: Birth.createOrThrow(D.create("2024-01-01")),
+ * 	timeSpent: TimeSpent.createOrThrow(D.createTime(30, "minute")),
+ * });
+ * 
+ * const unwrapped = C.unwrapEntity(entity);
+ * // unwrapped.birth: TheDate, unwrapped.timeSpent: TheTime
+ * 
+ * const asJSON = C.unwrapEntity(entity, { transformer: toJSON });
+ * // asJSON.birth: SerializedTheDate, asJSON.timeSpent: SerializedTheTime
+ * 
+ * const asNative = C.unwrapEntity(entity, { transformer: toNative });
+ * // asNative.birth: Date, asNative.timeSpent: number
+ * ```
+ * 
+ * @remarks
+ * - The result always contains `_entityName`.
+ * - If the entity has flags, `_flags` is also included.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/clean/unwrapEntity
+ * 
+ * @namespace C
+ * 
+ */
+export declare function unwrapEntity<GenericEntity extends Entity, GenericTransformer extends TransformerFunction = never>(entity: GenericEntity, params?: {
+    transformer?: GenericTransformer;
+}): UnwrapEntity<GenericEntity, GenericTransformer>;
 export {};