@duplojs/utils 1.5.8 → 1.5.10

package/dist/array/includes.d.ts

@@ -38,5 +38,5 @@
  * @namespace A
  * 
  */
-export declare function includes<GenericArrayValue extends unknown>(value: NoInfer<GenericArrayValue>): (array: readonly GenericArrayValue[]) => boolean;
-export declare function includes<GenericArrayValue extends unknown>(array: readonly GenericArrayValue[], value: NoInfer<GenericArrayValue>): boolean;
+export declare function includes<GenericArray extends readonly unknown[], GenericArrayValue extends GenericArray[number]>(value: GenericArrayValue): (array: GenericArray) => boolean;
+export declare function includes<GenericArray extends readonly unknown[], GenericArrayValue extends GenericArray[number]>(array: GenericArray, value: GenericArrayValue): boolean;

package/dist/array/index.cjs

@@ -44,6 +44,7 @@ var insert$2 = require('./insert.cjs');
 var isLastIndex = require('./isLastIndex.cjs');
 var select = require('./select.cjs');
 var lengthEqual = require('./lengthEqual.cjs');
+var mapTuple = require('./mapTuple.cjs');
 var _delete = require('./splice/delete.cjs');
 var insert = require('./splice/insert.cjs');
 var replace = require('./splice/replace.cjs');
@@ -108,6 +109,7 @@ exports.isLastIndex = isLastIndex.isLastIndex;
 exports.select = select.select;
 exports.selectTools = select.selectTools;
 exports.lengthEqual = lengthEqual.lengthEqual;
+exports.mapTuple = mapTuple.mapTuple;
 exports.spliceDelete = _delete.spliceDelete;
 exports.spliceInsert = insert.spliceInsert;
 exports.spliceReplace = replace.spliceReplace;

package/dist/array/index.d.ts

@@ -74,3 +74,4 @@ export * from "./insert";
 export * from "./isLastIndex";
 export * from "./select";
 export * from "./lengthEqual";
+export * from "./mapTuple";

package/dist/array/index.mjs

@@ -42,6 +42,7 @@ export { insert } from './insert.mjs';
 export { isLastIndex } from './isLastIndex.mjs';
 export { select, selectTools } from './select.mjs';
 export { lengthEqual } from './lengthEqual.mjs';
+export { mapTuple } from './mapTuple.mjs';
 export { spliceDelete } from './splice/delete.mjs';
 export { spliceInsert } from './splice/insert.mjs';
 export { spliceReplace } from './splice/replace.mjs';

package/dist/array/mapTuple.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+function mapTuple(...args) {
+    if (args.length === 1) {
+        const [theFunction] = args;
+        return (input) => mapTuple(input, theFunction);
+    }
+    const [input, theFunction] = args;
+    return input.map((element, index) => theFunction(element, {
+        index,
+        self: input,
+    }));
+}
+
+exports.mapTuple = mapTuple;

package/dist/array/mapTuple.d.ts

@@ -0,0 +1,45 @@
+import type { MapTuple } from "./types";
+interface ArrayMapTupleParams<GenericInputTuple extends readonly unknown[]> {
+    index: number;
+    self: GenericInputTuple;
+}
+/**
+ * Transforms each element of an array while preserving tuple length in types.
+ * 
+ * **Supported call styles:**
+ * - Classic: `mapTuple(input, theFunction)` -> returns a new array
+ * - Curried: `mapTuple(theFunction)` -> returns a function waiting for the input
+ * 
+ * The mapping function receives `(element, { index, self })`, where `index` is the element position and `self` is the original array.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.mapTuple(
+ * 	<const>[1, 2, 3],
+ * 	(value) => value * 2,
+ * ); // [2, 4, 6]
+ * 
+ * pipe(
+ * 	<const>["alpha", "beta"],
+ * 	A.mapTuple((value, { index }) => `${index}:${value}`),
+ * ); // ["0:alpha", "1:beta"]
+ * 
+ * A.mapTuple(
+ * 	[10, 20, 30],
+ * 	(value, { self }) => value / self.length,
+ * ); // [3.333..., 6.666..., 10]
+ * ```
+ * 
+ * @remarks
+ * - For tuple inputs (`as const`), the output keeps the same tuple length.
+ * - For non-tuple arrays, the output type is `GenericOutput[]`.
+ * 
+ * @see [`A.map`](https://utils.duplojs.dev/en/v1/api/array/map) For generic array mapping
+ * @see https://utils.duplojs.dev/en/v1/api/array/mapTuple
+ * 
+ * @namespace A
+ * 
+ */
+export declare function mapTuple<GenericInput extends readonly unknown[], GenericOutput extends unknown>(theFunction: (element: GenericInput[number], params: ArrayMapTupleParams<GenericInput>) => GenericOutput): (input: GenericInput) => MapTuple<GenericInput, GenericOutput>;
+export declare function mapTuple<GenericInput extends readonly unknown[], GenericOutput extends unknown>(input: GenericInput, theFunction: (element: GenericInput[number], params: ArrayMapTupleParams<GenericInput>) => GenericOutput): MapTuple<GenericInput, GenericOutput>;
+export {};

package/dist/array/mapTuple.mjs

@@ -0,0 +1,13 @@
+function mapTuple(...args) {
+    if (args.length === 1) {
+        const [theFunction] = args;
+        return (input) => mapTuple(input, theFunction);
+    }
+    const [input, theFunction] = args;
+    return input.map((element, index) => theFunction(element, {
+        index,
+        self: input,
+    }));
+}
+
+export { mapTuple };

package/dist/array/notIncludes.d.ts

@@ -1,5 +1,7 @@
 import { type RemoveFromUnion } from "../common";
-export type NotIncludeValue = string | null | undefined | boolean | number | bigint | symbol;
+import { type MapTuple } from "./types";
+type EligibleValue = string | null | undefined | boolean | number | bigint | symbol;
+type TooLargeType = string | number | boolean | bigint | symbol;
 /**
  * Checks that an array does not include a value.
  * 
@@ -41,5 +43,8 @@ export type NotIncludeValue = string | null | undefined | boolean | number | big
  * @namespace A
  * 
  */
-export declare function notIncludes<GenericArrayValue extends unknown, const GenericNotIncludeValue extends RemoveFromUnion<Extract<GenericArrayValue, NotIncludeValue>, Exclude<NotIncludeValue, null | undefined>>>(value: GenericNotIncludeValue): (input: readonly GenericArrayValue[]) => input is Exclude<GenericArrayValue, GenericNotIncludeValue>[];
-export declare function notIncludes<GenericArrayValue extends unknown, const GenericNotIncludeValue extends RemoveFromUnion<Extract<GenericArrayValue, NotIncludeValue>, Exclude<NotIncludeValue, null | undefined>>>(input: readonly GenericArrayValue[], value: GenericNotIncludeValue): input is Exclude<GenericArrayValue, GenericNotIncludeValue>[];
+export declare function notIncludes<GenericArray extends readonly unknown[], const GenericNotIncludeValue extends RemoveFromUnion<Extract<GenericArray[number], EligibleValue>, TooLargeType>>(value: GenericNotIncludeValue): (input: GenericArray) => input is MapTuple<GenericArray, Exclude<GenericArray[number], GenericNotIncludeValue>>;
+export declare function notIncludes<GenericArray extends readonly unknown[]>(value: NoInfer<GenericArray[number]>): (input: GenericArray) => boolean;
+export declare function notIncludes<GenericArray extends readonly unknown[], const GenericNotIncludeValue extends RemoveFromUnion<Extract<GenericArray[number], EligibleValue>, TooLargeType>>(input: GenericArray, value: GenericNotIncludeValue): input is MapTuple<GenericArray, Exclude<GenericArray[number], GenericNotIncludeValue>>;
+export declare function notIncludes<GenericArray extends readonly unknown[]>(input: GenericArray, value: NoInfer<GenericArray[number]>): boolean;
+export {};

package/dist/array/types/index.d.ts

@@ -9,3 +9,4 @@ export * from "./excludeTuple";
 export * from "./createTuple";
 export * from "./arrayCoalescing";
 export * from "./joinTuple";
+export * from "./mapTuple";

package/dist/array/types/mapTuple.d.ts

@@ -0,0 +1 @@
+export type MapTuple<GenericArray extends readonly unknown[], GenericOutput extends unknown> = GenericArray extends readonly [] ? [] : GenericArray extends readonly [infer _InferredFirst, ...infer InferredRest] ? MapTuple<InferredRest, GenericOutput> extends infer InferredResult extends readonly any[] ? [GenericOutput, ...InferredResult] : never : GenericOutput[];

package/dist/clean/entity/index.cjs

@@ -86,6 +86,7 @@ createEntity.overrideHandler = override.createOverride("@duplojs/utils/clean/ent
 exports.entityPropertyArrayKind = property.entityPropertyArrayKind;
 exports.entityPropertyDefinitionToDataParser = property.entityPropertyDefinitionToDataParser;
 exports.entityPropertyDefinitionTools = property.entityPropertyDefinitionTools;
+exports.entityPropertyIdentifierKind = property.entityPropertyIdentifierKind;
 exports.entityPropertyNullableKind = property.entityPropertyNullableKind;
 exports.entityPropertyStructureKind = property.entityPropertyStructureKind;
 exports.entityPropertyUnionKind = property.entityPropertyUnionKind;

package/dist/clean/entity/index.d.ts

@@ -35,6 +35,7 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
      * Builds an entity from already typed properties.
      * 
      * ```ts
+     * 		nick: nullable(Name),
      * 		preferences: structure({
      * 			theme: PreferencesTheme,
      * 			pinnedNick: nullable(Name),
@@ -43,7 +44,6 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
      * 	export type Entity = C.GetEntity<typeof Entity>;
      * 
      * 	const defaultRole = Role.createOrThrow("client");
-     * 
      * ```
      * 
      */
@@ -52,15 +52,15 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
      * Validates permissive raw properties and returns an Either with the typed entity.
      * 
      * ```ts
+     * 				pinnedNick: null,
+     * 			},
      * 		});
      * 	}
      * }
      * 
      * const mapped = User.Entity.mapOrThrow({
+     * 	kind: "user",
      * 	id: 2,
-     * 	name: "Bob",
-     * 	roles: ["client"],
-     * 	nick: "Bobby",
      * ```
      * 
      */
@@ -69,12 +69,12 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
      * Validates permissive raw properties and throws on error.
      * 
      * ```ts
+     * 		name: Name;
      * 	}) {
      * 		return Entity.new({
      * 			...params,
+     * 			kind: "user",
      * 			nick: null,
-     * 			roles: [defaultRole],
-     * 			preferences: {
      * ```
      * 
      */
@@ -83,10 +83,10 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
     * Checks if a value is an entity of this handler (type guard).
     * 
     * ```ts
+    * 			preferences: {
+    * 				theme: PreferencesTheme.createOrThrow("light"),
     * 				pinnedNick: null,
     * 			},
-    * 		});
-    * 	}
     * ```
     * 
     */
@@ -95,10 +95,10 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
      * Updates an entity by merging typed properties into an existing entity.
      * 
      * ```ts
-     * const result = true ? mapped : null;
+     * 	},
+     * });
      * 
-     * if (User.Entity.is(result)) {
-     * 	// result: C.Entity<"User">
+     * const result = true ? mapped : null;
      * ```
      * 
      */
@@ -133,7 +133,8 @@ export declare class CreateEntityError extends CreateEntityError_base {
  * 		DP.literal(["light", "dark"]),
  * 	);
  * 
- * 	export const Entity = C.createEntity("User", ({ array, nullable, structure }) => ({
+ * 	export const Entity = C.createEntity("User", ({ array, nullable, structure, identifier }) => ({
+ * 		kind: identifier("user"),
  * 		id: Id,
  * 		name: Name,
  * 		roles: array(Role, { min: 1 }),
@@ -153,6 +154,7 @@ export declare class CreateEntityError extends CreateEntityError_base {
  * 	}) {
  * 		return Entity.new({
  * 			...params,
+ * 			kind: "user",
  * 			nick: null,
  * 			roles: [defaultRole],
  * 			preferences: {
@@ -164,6 +166,7 @@ export declare class CreateEntityError extends CreateEntityError_base {
  * }
  * 
  * const mapped = User.Entity.mapOrThrow({
+ * 	kind: "user",
  * 	id: 2,
  * 	name: "Bob",
  * 	roles: ["client"],
@@ -181,6 +184,7 @@ export declare class CreateEntityError extends CreateEntityError_base {
  * }
  * 
  * const mappedResult = User.Entity.map({
+ * 	kind: "user",
  * 	id: 3,
  * 	name: "Eve",
  * 	roles: ["manager"],
@@ -202,7 +206,8 @@ export declare class CreateEntityError extends CreateEntityError_base {
  * ```
  * 
  * @remarks
- * - The definition callback can use helpers like `array`, `nullable`, `union`, and `structure` to enrich properties.
+ * - The definition callback can use helpers like `array`, `nullable`, `union`, `structure`, and `identifier` to enrich properties.
+ * - `identifier` is intended for technical string literals (discriminators/tags), not free-form business text values.
  * - Use `map`/`mapOrThrow` to build from raw inputs (with runtime constraint checks); `new` expects already typed values.
  * 
  * @see https://utils.duplojs.dev/en/v1/api/clean/entity

package/dist/clean/entity/index.mjs

@@ -1,7 +1,7 @@
 import { createCleanKind } from '../kind.mjs';
 import { newTypeKind } from '../newType.mjs';
 import { entityPropertyDefinitionTools, entityPropertyDefinitionToDataParser } from './property.mjs';
-export { entityPropertyArrayKind, entityPropertyNullableKind, entityPropertyStructureKind, entityPropertyUnionKind } from './property.mjs';
+export { entityPropertyArrayKind, entityPropertyIdentifierKind, entityPropertyNullableKind, entityPropertyStructureKind, entityPropertyUnionKind } from './property.mjs';
 import { kindHeritage } from '../../common/kind.mjs';
 import { pipe } from '../../common/pipe.mjs';
 import { map } from '../../array/map.mjs';

package/dist/clean/entity/property.cjs

@@ -14,6 +14,7 @@ var index = require('../../dataParser/parsers/object/index.cjs');
 var index$1 = require('../../dataParser/parsers/array/index.cjs');
 var min = require('../../dataParser/parsers/array/checkers/min.cjs');
 var max = require('../../dataParser/parsers/array/checkers/max.cjs');
+var literal = require('../../dataParser/parsers/literal.cjs');
 var nullable = require('../../dataParser/parsers/nullable.cjs');
 var union = require('../../dataParser/parsers/union.cjs');
 var exhaustive = require('../../pattern/exhaustive.cjs');
@@ -22,6 +23,7 @@ const entityPropertyUnionKind = kind.createCleanKind("entity-property-union");
 const entityPropertyNullableKind = kind.createCleanKind("entity-property-nullable");
 const entityPropertyArrayKind = kind.createCleanKind("entity-property-array");
 const entityPropertyStructureKind = kind.createCleanKind("entity-property-structure");
+const entityPropertyIdentifierKind = kind.createCleanKind("entity-property-identifier");
 const entityPropertyDefinitionTools = {
     union(...definitions) {
         return pipe.pipe(definitions, wrapValue.wrapValue, entityPropertyUnionKind.setTo);
@@ -35,6 +37,9 @@ const entityPropertyDefinitionTools = {
     structure(definition) {
         return pipe.pipe(definition, wrapValue.wrapValue, entityPropertyStructureKind.setTo);
     },
+    identifier(definition) {
+        return pipe.pipe(definition, wrapValue.wrapValue, entityPropertyIdentifierKind.setTo);
+    },
 };
 function entityPropertyDefinitionToDataParser(propertyDefinition, treatNewTypeHandler) {
     return pipe.pipe(propertyDefinition, when.when(newType.newTypeHandlerKind.has, treatNewTypeHandler), when.when(entityPropertyUnionKind.has, (union$1) => {
@@ -43,7 +48,7 @@ function entityPropertyDefinitionToDataParser(propertyDefinition, treatNewTypeHa
             entityPropertyDefinitionToDataParser(firstInnerProperty, treatNewTypeHandler),
             ...map.map(restInnerProperty, (innerProperty) => entityPropertyDefinitionToDataParser(innerProperty, treatNewTypeHandler)),
         ]);
-    }), when.when(entityPropertyNullableKind.has, (nullable$1) => nullable.nullable(entityPropertyDefinitionToDataParser(unwrap.unwrap(nullable$1), treatNewTypeHandler))), when.when(entityPropertyArrayKind.has, (array) => {
+    }), when.when(entityPropertyNullableKind.has, (nullable$1) => nullable.nullable(entityPropertyDefinitionToDataParser(unwrap.unwrap(nullable$1), treatNewTypeHandler))), when.when(entityPropertyIdentifierKind.has, (identifier) => literal.literal(unwrap.unwrap(identifier))), when.when(entityPropertyArrayKind.has, (array) => {
         const params = entityPropertyArrayKind.getValue(array);
         return index$1.array(entityPropertyDefinitionToDataParser(unwrap.unwrap(array), treatNewTypeHandler), {
             checkers: [
@@ -61,6 +66,7 @@ function entityPropertyDefinitionToDataParser(propertyDefinition, treatNewTypeHa
 exports.entityPropertyArrayKind = entityPropertyArrayKind;
 exports.entityPropertyDefinitionToDataParser = entityPropertyDefinitionToDataParser;
 exports.entityPropertyDefinitionTools = entityPropertyDefinitionTools;
+exports.entityPropertyIdentifierKind = entityPropertyIdentifierKind;
 exports.entityPropertyNullableKind = entityPropertyNullableKind;
 exports.entityPropertyStructureKind = entityPropertyStructureKind;
 exports.entityPropertyUnionKind = entityPropertyUnionKind;

package/dist/clean/entity/property.d.ts

@@ -2,7 +2,7 @@ import { type GetNewType, type NewTypeHandler } from "../newType";
 import { type WrappedValue, type Kind, type AnyTuple, type Unwrap, type GetKindValue, type IsEqual } from "../../common";
 import * as DDataParser from "../../dataParser";
 import * as DArray from "../../array";
-export type EntityPropertyDefinition = (NewTypeHandler | EntityPropertyDefinitionUnion | EntityPropertyDefinitionNullable | EntityPropertyDefinitionArray | EntityPropertyDefinitionStructure);
+export type EntityPropertyDefinition = (NewTypeHandler | EntityPropertyDefinitionUnion | EntityPropertyDefinitionNullable | EntityPropertyDefinitionArray | EntityPropertyDefinitionStructure | EntityPropertyDefinitionIdentifier);
 export declare const entityPropertyUnionKind: import("../../common").KindHandler<import("../../common").KindDefinition<"@DuplojsUtilsClean/entity-property-union", unknown>>;
 export interface EntityPropertyDefinitionUnion<GenericPropertyDefinition extends AnyTuple<EntityPropertyDefinition> = AnyTuple<EntityPropertyDefinition>> extends Kind<typeof entityPropertyUnionKind.definition>, WrappedValue<GenericPropertyDefinition> {
 }
@@ -19,19 +19,22 @@ export interface EntityPropertyDefinitionArray<GenericPropertyDefinition extends
 export declare const entityPropertyStructureKind: import("../../common").KindHandler<import("../../common").KindDefinition<"@DuplojsUtilsClean/entity-property-structure", unknown>>;
 export interface EntityPropertyDefinitionStructure<GenericPropertyDefinition extends Record<string, EntityPropertyDefinition> = Record<string, EntityPropertyDefinition>> extends Kind<typeof entityPropertyStructureKind.definition>, WrappedValue<GenericPropertyDefinition> {
 }
-export type EntityProperty<GenericProperty extends EntityPropertyDefinition = EntityPropertyDefinition> = IsEqual<GenericProperty, EntityPropertyDefinition> extends true ? unknown : GenericProperty extends NewTypeHandler ? GetNewType<GenericProperty> : GenericProperty extends EntityPropertyDefinitionUnion ? EntityProperty<Unwrap<GenericProperty>[number]> : GenericProperty extends EntityPropertyDefinitionNullable ? EntityProperty<Unwrap<GenericProperty>> | null : GenericProperty extends EntityPropertyDefinitionArray ? GetKindValue<typeof entityPropertyArrayKind, GenericProperty>["min"] extends number ? EntityProperty<Unwrap<GenericProperty>> extends infer InferredEntityProperty ? readonly [
+export declare const entityPropertyIdentifierKind: import("../../common").KindHandler<import("../../common").KindDefinition<"@DuplojsUtilsClean/entity-property-identifier", unknown>>;
+export interface EntityPropertyDefinitionIdentifier<GenericPropertyDefinition extends string = string> extends Kind<typeof entityPropertyIdentifierKind.definition>, WrappedValue<GenericPropertyDefinition> {
+}
+export type EntityProperty<GenericProperty extends EntityPropertyDefinition = EntityPropertyDefinition> = IsEqual<GenericProperty, EntityPropertyDefinition> extends true ? unknown : GenericProperty extends NewTypeHandler ? GetNewType<GenericProperty> : GenericProperty extends EntityPropertyDefinitionUnion ? EntityProperty<Unwrap<GenericProperty>[number]> : GenericProperty extends EntityPropertyDefinitionNullable ? EntityProperty<Unwrap<GenericProperty>> | null : GenericProperty extends EntityPropertyDefinitionIdentifier ? Unwrap<GenericProperty> : GenericProperty extends EntityPropertyDefinitionArray ? GetKindValue<typeof entityPropertyArrayKind, GenericProperty>["min"] extends number ? EntityProperty<Unwrap<GenericProperty>> extends infer InferredEntityProperty ? readonly [
     ...DArray.CreateTuple<InferredEntityProperty, GetKindValue<typeof entityPropertyArrayKind, GenericProperty>["min"]>,
     ...InferredEntityProperty[]
 ] : never : readonly EntityProperty<Unwrap<GenericProperty>>[] : GenericProperty extends EntityPropertyDefinitionStructure ? Unwrap<GenericProperty> extends infer InferredShape extends Record<string, any> ? {
     readonly [Prop in keyof InferredShape]: EntityProperty<InferredShape[Prop]>;
 } : never : never;
-export type EntityRawProperty<GenericProperty extends EntityPropertyDefinition = EntityPropertyDefinition> = IsEqual<GenericProperty, EntityPropertyDefinition> extends true ? any : GenericProperty extends NewTypeHandler ? Unwrap<GetNewType<GenericProperty>> : GenericProperty extends EntityPropertyDefinitionUnion ? EntityRawProperty<Unwrap<GenericProperty>[number]> : GenericProperty extends EntityPropertyDefinitionNullable ? EntityRawProperty<Unwrap<GenericProperty>> | null : GenericProperty extends EntityPropertyDefinitionArray ? GetKindValue<typeof entityPropertyArrayKind, GenericProperty>["min"] extends number ? EntityRawProperty<Unwrap<GenericProperty>> extends infer InferredEntityProperty ? readonly [
+export type EntityRawProperty<GenericProperty extends EntityPropertyDefinition = EntityPropertyDefinition> = IsEqual<GenericProperty, EntityPropertyDefinition> extends true ? any : GenericProperty extends NewTypeHandler ? Unwrap<GetNewType<GenericProperty>> : GenericProperty extends EntityPropertyDefinitionUnion ? EntityRawProperty<Unwrap<GenericProperty>[number]> : GenericProperty extends EntityPropertyDefinitionNullable ? EntityRawProperty<Unwrap<GenericProperty>> | null : GenericProperty extends EntityPropertyDefinitionIdentifier ? Unwrap<GenericProperty> : GenericProperty extends EntityPropertyDefinitionArray ? GetKindValue<typeof entityPropertyArrayKind, GenericProperty>["min"] extends number ? EntityRawProperty<Unwrap<GenericProperty>> extends infer InferredEntityProperty ? readonly [
     ...DArray.CreateTuple<InferredEntityProperty, GetKindValue<typeof entityPropertyArrayKind, GenericProperty>["min"]>,
     ...InferredEntityProperty[]
 ] : never : readonly EntityRawProperty<Unwrap<GenericProperty>>[] : GenericProperty extends EntityPropertyDefinitionStructure ? Unwrap<GenericProperty> extends infer InferredEntityShape extends Record<string, any> ? {
     readonly [Prop in keyof InferredEntityShape]: EntityRawProperty<InferredEntityShape[Prop]>;
 } : never : never;
-export type EntityInputRawProperty<GenericProperty extends EntityPropertyDefinition = EntityPropertyDefinition> = IsEqual<GenericProperty, EntityPropertyDefinition> extends true ? any : GenericProperty extends NewTypeHandler<any, infer InferredValue, any, infer InferredInput> ? IsEqual<InferredInput, never> extends true ? InferredValue : InferredInput : GenericProperty extends EntityPropertyDefinitionUnion ? EntityInputRawProperty<Unwrap<GenericProperty>[number]> : GenericProperty extends EntityPropertyDefinitionNullable ? EntityInputRawProperty<Unwrap<GenericProperty>> | null : GenericProperty extends EntityPropertyDefinitionArray ? readonly EntityInputRawProperty<Unwrap<GenericProperty>>[] : GenericProperty extends EntityPropertyDefinitionStructure ? Unwrap<GenericProperty> extends infer InferredShape extends Record<string, any> ? {
+export type EntityInputRawProperty<GenericProperty extends EntityPropertyDefinition = EntityPropertyDefinition> = IsEqual<GenericProperty, EntityPropertyDefinition> extends true ? any : GenericProperty extends NewTypeHandler<any, infer InferredValue, any, infer InferredInput> ? IsEqual<InferredInput, never> extends true ? InferredValue : InferredInput : GenericProperty extends EntityPropertyDefinitionUnion ? EntityInputRawProperty<Unwrap<GenericProperty>[number]> : GenericProperty extends EntityPropertyDefinitionNullable ? EntityInputRawProperty<Unwrap<GenericProperty>> | null : GenericProperty extends EntityPropertyDefinitionIdentifier ? Unwrap<GenericProperty> : GenericProperty extends EntityPropertyDefinitionArray ? readonly EntityInputRawProperty<Unwrap<GenericProperty>>[] : GenericProperty extends EntityPropertyDefinitionStructure ? Unwrap<GenericProperty> extends infer InferredShape extends Record<string, any> ? {
     readonly [Prop in keyof InferredShape]: EntityInputRawProperty<InferredShape[Prop]>;
 } : never : never;
 export declare const entityPropertyDefinitionTools: {
@@ -39,5 +42,6 @@ export declare const entityPropertyDefinitionTools: {
     nullable<const GenericDefinitionValue extends EntityPropertyDefinition>(definition: GenericDefinitionValue): EntityPropertyDefinitionNullable<GenericDefinitionValue>;
     array<const GenericDefinitionValue extends EntityPropertyDefinition, const GenericParams extends EntityPropertyDefinitionArrayParams = {}>(definition: GenericDefinitionValue, params?: GenericParams): EntityPropertyDefinitionArray<GenericDefinitionValue, GenericParams>;
     structure<const GenericDefinitionValue extends Record<string, EntityPropertyDefinition>>(definition: GenericDefinitionValue): EntityPropertyDefinitionStructure<GenericDefinitionValue>;
+    identifier<const GenericDefinitionValue extends string>(definition: GenericDefinitionValue): EntityPropertyDefinitionIdentifier<GenericDefinitionValue>;
 };
 export declare function entityPropertyDefinitionToDataParser(propertyDefinition: EntityPropertyDefinition, treatNewTypeHandler: (newTypeHandler: NewTypeHandler) => DDataParser.DataParser): DDataParser.DataParser;

package/dist/clean/entity/property.mjs

@@ -12,6 +12,7 @@ import { object } from '../../dataParser/parsers/object/index.mjs';
 import { array } from '../../dataParser/parsers/array/index.mjs';
 import { checkerArrayMin } from '../../dataParser/parsers/array/checkers/min.mjs';
 import { checkerArrayMax } from '../../dataParser/parsers/array/checkers/max.mjs';
+import { literal } from '../../dataParser/parsers/literal.mjs';
 import { nullable } from '../../dataParser/parsers/nullable.mjs';
 import { union } from '../../dataParser/parsers/union.mjs';
 import { exhaustive } from '../../pattern/exhaustive.mjs';
@@ -20,6 +21,7 @@ const entityPropertyUnionKind = createCleanKind("entity-property-union");
 const entityPropertyNullableKind = createCleanKind("entity-property-nullable");
 const entityPropertyArrayKind = createCleanKind("entity-property-array");
 const entityPropertyStructureKind = createCleanKind("entity-property-structure");
+const entityPropertyIdentifierKind = createCleanKind("entity-property-identifier");
 const entityPropertyDefinitionTools = {
     union(...definitions) {
         return pipe(definitions, wrapValue, entityPropertyUnionKind.setTo);
@@ -33,6 +35,9 @@ const entityPropertyDefinitionTools = {
     structure(definition) {
         return pipe(definition, wrapValue, entityPropertyStructureKind.setTo);
     },
+    identifier(definition) {
+        return pipe(definition, wrapValue, entityPropertyIdentifierKind.setTo);
+    },
 };
 function entityPropertyDefinitionToDataParser(propertyDefinition, treatNewTypeHandler) {
     return pipe(propertyDefinition, when(newTypeHandlerKind.has, treatNewTypeHandler), when(entityPropertyUnionKind.has, (union$1) => {
@@ -41,7 +46,7 @@ function entityPropertyDefinitionToDataParser(propertyDefinition, treatNewTypeHa
             entityPropertyDefinitionToDataParser(firstInnerProperty, treatNewTypeHandler),
             ...map(restInnerProperty, (innerProperty) => entityPropertyDefinitionToDataParser(innerProperty, treatNewTypeHandler)),
         ]);
-    }), when(entityPropertyNullableKind.has, (nullable$1) => nullable(entityPropertyDefinitionToDataParser(unwrap(nullable$1), treatNewTypeHandler))), when(entityPropertyArrayKind.has, (array$1) => {
+    }), when(entityPropertyNullableKind.has, (nullable$1) => nullable(entityPropertyDefinitionToDataParser(unwrap(nullable$1), treatNewTypeHandler))), when(entityPropertyIdentifierKind.has, (identifier) => literal(unwrap(identifier))), when(entityPropertyArrayKind.has, (array$1) => {
         const params = entityPropertyArrayKind.getValue(array$1);
         return array(entityPropertyDefinitionToDataParser(unwrap(array$1), treatNewTypeHandler), {
             checkers: [
@@ -56,4 +61,4 @@ function entityPropertyDefinitionToDataParser(propertyDefinition, treatNewTypeHa
     }), when(entityPropertyStructureKind.has, (structure) => pipe(structure, unwrap, entries, map(([key, value]) => entry(key, entityPropertyDefinitionToDataParser(value, treatNewTypeHandler))), fromEntries, object)), exhaustive);
 }
 
-export { entityPropertyArrayKind, entityPropertyDefinitionToDataParser, entityPropertyDefinitionTools, entityPropertyNullableKind, entityPropertyStructureKind, entityPropertyUnionKind };
+export { entityPropertyArrayKind, entityPropertyDefinitionToDataParser, entityPropertyDefinitionTools, entityPropertyIdentifierKind, entityPropertyNullableKind, entityPropertyStructureKind, entityPropertyUnionKind };

package/dist/clean/entity/unwrap.cjs

@@ -17,6 +17,9 @@ function unwrapEntityProperty(property, params) {
     else if (property === null) {
         return property;
     }
+    else if (typeof property === "string") {
+        return property;
+    }
     else if (property instanceof Array) {
         const length = property.length;
         const result = [];

package/dist/clean/entity/unwrap.d.ts

@@ -1,7 +1,7 @@
 import { type Unwrap, type WrappedValue, type IsEqual, type Transformer, type TransformerFunction, type SimplifyTopLevel, type DeepReadonly, type GetKindValue, type Kind } from "../../common";
 import { entityKind, type Entity } from ".";
 import { flagKind } from "../flag";
-export type UnwrapEntityProperty<GenericProperty extends unknown, GenericTransformer extends TransformerFunction = never> = GenericProperty extends WrappedValue ? IsEqual<GenericTransformer, never> extends true ? Unwrap<GenericProperty> : GenericTransformer extends TransformerFunction<infer InferredMethodName> ? Transformer<Unwrap<GenericProperty>, InferredMethodName> : never : GenericProperty extends null ? null : GenericProperty extends readonly [infer InferredFirst, ...infer InferredRest] ? readonly [
+export type UnwrapEntityProperty<GenericProperty extends unknown, GenericTransformer extends TransformerFunction = never> = GenericProperty extends WrappedValue ? IsEqual<GenericTransformer, never> extends true ? Unwrap<GenericProperty> : GenericTransformer extends TransformerFunction<infer InferredMethodName> ? Transformer<Unwrap<GenericProperty>, InferredMethodName> : never : GenericProperty extends null ? null : GenericProperty extends string ? GenericProperty : GenericProperty extends readonly [infer InferredFirst, ...infer InferredRest] ? readonly [
     UnwrapEntityProperty<InferredFirst, GenericTransformer>,
     ...UnwrapEntityProperty<InferredRest, GenericTransformer>
 ] : GenericProperty extends readonly [] ? readonly [] : GenericProperty extends readonly unknown[] ? readonly UnwrapEntityProperty<GenericProperty[number], GenericTransformer>[] : GenericProperty extends Record<string, unknown> ? {

package/dist/clean/entity/unwrap.mjs

@@ -15,6 +15,9 @@ function unwrapEntityProperty(property, params) {
     else if (property === null) {
         return property;
     }
+    else if (typeof property === "string") {
+        return property;
+    }
     else if (property instanceof Array) {
         const length = property.length;
         const result = [];

package/dist/clean/index.cjs

@@ -65,6 +65,7 @@ exports.some = maybe.some;
 exports.entityPropertyArrayKind = property.entityPropertyArrayKind;
 exports.entityPropertyDefinitionToDataParser = property.entityPropertyDefinitionToDataParser;
 exports.entityPropertyDefinitionTools = property.entityPropertyDefinitionTools;
+exports.entityPropertyIdentifierKind = property.entityPropertyIdentifierKind;
 exports.entityPropertyNullableKind = property.entityPropertyNullableKind;
 exports.entityPropertyStructureKind = property.entityPropertyStructureKind;
 exports.entityPropertyUnionKind = property.entityPropertyUnionKind;

package/dist/clean/index.mjs

@@ -5,7 +5,7 @@ export { createRepository, repositoryHandlerKind } from './repository.mjs';
 export { createUseCase, useCaseHandlerKind, useCaseInstances } from './useCase.mjs';
 export { createFlag, flagKind } from './flag.mjs';
 export { none, some } from './maybe.mjs';
-export { entityPropertyArrayKind, entityPropertyDefinitionToDataParser, entityPropertyDefinitionTools, entityPropertyNullableKind, entityPropertyStructureKind, entityPropertyUnionKind } from './entity/property.mjs';
+export { entityPropertyArrayKind, entityPropertyDefinitionToDataParser, entityPropertyDefinitionTools, entityPropertyIdentifierKind, entityPropertyNullableKind, entityPropertyStructureKind, entityPropertyUnionKind } from './entity/property.mjs';
 export { unwrapEntity, unwrapEntityProperty } from './entity/unwrap.mjs';
 export { CreateConstrainedTypeError, constrainedTypeKind, constraintHandlerKind, createConstraint } from './constraint/base.mjs';
 export { Int, Negative, NumberMax, NumberMin, Positive, PositiveInt } from './constraint/defaultConstraint/number.mjs';

package/dist/common/types/bivariantFunction.d.ts

@@ -0,0 +1,9 @@
+import type { AnyFunction } from "./anyFunction";
+/**
+ * @remarks allows you to bypass the `strictFunctionTypes` rule.
+ * @link https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-function-parameters-bivariant
+ * @link https://www.typescriptlang.org/tsconfig/#strictFunctionTypes
+ */
+export type BivariantFunction<GenericFunction extends AnyFunction> = {
+    bivariantFunction(...args: Parameters<GenericFunction>): ReturnType<GenericFunction>;
+}["bivariantFunction"];

package/dist/common/types/index.d.ts

@@ -46,3 +46,4 @@ export * from "./falsyValue";
 export * from "./DeepReadonly";
 export * from "./json";
 export * from "./predicate";
+export * from "./bivariantFunction";

package/dist/dataParser/parsers/record/findRecordRequiredKey.cjs

@@ -17,6 +17,7 @@ var isType = require('../../../common/isType.cjs');
 var map = require('../../../array/map.cjs');
 var concat = require('../../../string/concat.cjs');
 var flatMap = require('../../../array/flatMap.cjs');
+var prepend = require('../../../string/prepend.cjs');
 var exhaustive = require('../../../pattern/exhaustive.cjs');
 var innerPipe = require('../../../common/innerPipe.cjs');
 var notIncludes = require('../../../array/notIncludes.cjs');
@@ -37,7 +38,7 @@ function findRecordRequiredKeyOnTemplateLiteralPart(templatePart) {
         isType.isType("number"),
         isType.isType("string"),
         isType.isType("undefined"),
-    ]), innerPipe.innerPipe(when$1.when(isType.isType("bigint"), (value) => `${value}n`), String)), when.when(literal.literalKind.has, (value) => findRecordRequiredKey(value)), when.when(index.templateLiteralKind.has, (value) => findRecordRequiredKeyOnTemplateLiteralPart(value.definition.template)), when.when(boolean.booleanKind.has, justReturn.justReturn(["true", "false"])), when.when(empty.emptyKind.has, justReturn.justReturn("undefined")), when.when(nil.nilKind.has, justReturn.justReturn("null")), when.when(union.unionKind.has, (dataParser) => pipe.pipe(dataParser.definition.options, map.map((element) => findRecordRequiredKeyOnTemplateLiteralPart([element])), when.when(notIncludes.notIncludes(null), flat.flat), otherwise.otherwise(justReturn.justReturn(null)))), exhaustive.exhaustive)), reduce.reduce(reduce.reduceFrom([""]), ({ lastValue, element, exit, next }) => pipe.pipe(element, when.when(isType.isType("null"), justReturn.justReturn(exit(null))), when.when(isType.isType("string"), (element) => next(map.map(lastValue, (value) => concat.concat(value, element)))), when.when(isType.isType("array"), (elements) => next(flatMap.flatMap(lastValue, (value) => map.map(elements, (subValue) => concat.concat(value, subValue))))), exhaustive.exhaustive)));
+    ]), innerPipe.innerPipe(when$1.when(isType.isType("bigint"), (value) => `${value}n`), String)), when.when(literal.literalKind.has, (value) => findRecordRequiredKey(value)), when.when(index.templateLiteralKind.has, (value) => findRecordRequiredKeyOnTemplateLiteralPart(value.definition.template)), when.when(boolean.booleanKind.has, justReturn.justReturn(["true", "false"])), when.when(empty.emptyKind.has, justReturn.justReturn("undefined")), when.when(nil.nilKind.has, justReturn.justReturn("null")), when.when(union.unionKind.has, (dataParser) => pipe.pipe(dataParser.definition.options, map.map((element) => findRecordRequiredKeyOnTemplateLiteralPart([element])), when.when(notIncludes.notIncludes(null), flat.flat), otherwise.otherwise(justReturn.justReturn(null)))), exhaustive.exhaustive)), reduce.reduce(reduce.reduceFrom([""]), ({ lastValue, element, exit, next }) => pipe.pipe(element, when.when(isType.isType("null"), justReturn.justReturn(exit(null))), when.when(isType.isType("string"), (element) => next(map.map(lastValue, concat.concat(element)))), when.when(isType.isType("array"), (elements) => next(flatMap.flatMap(lastValue, (value) => map.map(elements, prepend.prepend(value))))), exhaustive.exhaustive)));
 }
 function findRecordRequiredKey(keyParser) {
     return pipe.pipe(keyParser, when.when((value) => index$1.stringKind.has(value) || index$2.numberKind.has(value), justReturn.justReturn(null)), when.when(literal.literalKind.has, (dataParser) => pipe.pipe(dataParser.definition.value, map.map(innerPipe.innerPipe(when$1.when(isType.isType("bigint"), (value) => `${value}n`), String)))), when.when(union.unionKind.has, (dataParser) => pipe.pipe(dataParser.definition.options, map.map(findRecordRequiredKey), when.when(includes.includes(null), justReturn.justReturn(null)), otherwise.otherwise(innerPipe.innerPipe(filter.filter(isType.isType("array")), flat.flat)))), when.when(index.templateLiteralKind.has, (dataParser) => findRecordRequiredKeyOnTemplateLiteralPart(dataParser.definition.template)), exhaustive.exhaustive);

package/dist/dataParser/parsers/record/findRecordRequiredKey.mjs

@@ -15,6 +15,7 @@ import { isType } from '../../../common/isType.mjs';
 import { map } from '../../../array/map.mjs';
 import { concat } from '../../../string/concat.mjs';
 import { flatMap } from '../../../array/flatMap.mjs';
+import { prepend } from '../../../string/prepend.mjs';
 import { exhaustive } from '../../../pattern/exhaustive.mjs';
 import { innerPipe } from '../../../common/innerPipe.mjs';
 import { notIncludes } from '../../../array/notIncludes.mjs';
@@ -35,7 +36,7 @@ function findRecordRequiredKeyOnTemplateLiteralPart(templatePart) {
         isType("number"),
         isType("string"),
         isType("undefined"),
-    ]), innerPipe(when$1(isType("bigint"), (value) => `${value}n`), String)), when(literalKind.has, (value) => findRecordRequiredKey(value)), when(templateLiteralKind.has, (value) => findRecordRequiredKeyOnTemplateLiteralPart(value.definition.template)), when(booleanKind.has, justReturn(["true", "false"])), when(emptyKind.has, justReturn("undefined")), when(nilKind.has, justReturn("null")), when(unionKind.has, (dataParser) => pipe(dataParser.definition.options, map((element) => findRecordRequiredKeyOnTemplateLiteralPart([element])), when(notIncludes(null), flat), otherwise(justReturn(null)))), exhaustive)), reduce(reduceFrom([""]), ({ lastValue, element, exit, next }) => pipe(element, when(isType("null"), justReturn(exit(null))), when(isType("string"), (element) => next(map(lastValue, (value) => concat(value, element)))), when(isType("array"), (elements) => next(flatMap(lastValue, (value) => map(elements, (subValue) => concat(value, subValue))))), exhaustive)));
+    ]), innerPipe(when$1(isType("bigint"), (value) => `${value}n`), String)), when(literalKind.has, (value) => findRecordRequiredKey(value)), when(templateLiteralKind.has, (value) => findRecordRequiredKeyOnTemplateLiteralPart(value.definition.template)), when(booleanKind.has, justReturn(["true", "false"])), when(emptyKind.has, justReturn("undefined")), when(nilKind.has, justReturn("null")), when(unionKind.has, (dataParser) => pipe(dataParser.definition.options, map((element) => findRecordRequiredKeyOnTemplateLiteralPart([element])), when(notIncludes(null), flat), otherwise(justReturn(null)))), exhaustive)), reduce(reduceFrom([""]), ({ lastValue, element, exit, next }) => pipe(element, when(isType("null"), justReturn(exit(null))), when(isType("string"), (element) => next(map(lastValue, concat(element)))), when(isType("array"), (elements) => next(flatMap(lastValue, (value) => map(elements, prepend(value))))), exhaustive)));
 }
 function findRecordRequiredKey(keyParser) {
     return pipe(keyParser, when((value) => stringKind.has(value) || numberKind.has(value), justReturn(null)), when(literalKind.has, (dataParser) => pipe(dataParser.definition.value, map(innerPipe(when$1(isType("bigint"), (value) => `${value}n`), String)))), when(unionKind.has, (dataParser) => pipe(dataParser.definition.options, map(findRecordRequiredKey), when(includes(null), justReturn(null)), otherwise(innerPipe(filter(isType("array")), flat)))), when(templateLiteralKind.has, (dataParser) => findRecordRequiredKeyOnTemplateLiteralPart(dataParser.definition.template)), exhaustive);

package/dist/date/index.cjs

@@ -84,6 +84,7 @@ var less = require('./operators/less.cjs');
 var lessThan = require('./operators/lessThan.cjs');
 var lessThanTime = require('./operators/lessThanTime.cjs');
 var lessTime = require('./operators/lessTime.cjs');
+var equal = require('./operators/equal.cjs');
 
 /**
  * {@include date/index.md}
@@ -192,3 +193,4 @@ exports.less = less.less;
 exports.lessThan = lessThan.lessThan;
 exports.lessThanTime = lessThanTime.lessThanTime;
 exports.lessTime = lessTime.lessTime;
+exports.equal = equal.equal;

package/dist/date/index.mjs

@@ -82,6 +82,7 @@ export { less } from './operators/less.mjs';
 export { lessThan } from './operators/lessThan.mjs';
 export { lessThanTime } from './operators/lessThanTime.mjs';
 export { lessTime } from './operators/lessTime.mjs';
+export { equal } from './operators/equal.mjs';
 
 /**
  * {@include date/index.md}

package/dist/date/operators/equal.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var toTimestamp = require('../toTimestamp.cjs');
+
+function equal(...args) {
+    if (args.length === 1) {
+        const [second] = args;
+        return (first) => equal(first, second);
+    }
+    const [first, second] = args;
+    return toTimestamp.toTimestamp(first) === toTimestamp.toTimestamp(second);
+}
+
+exports.equal = equal;

package/dist/date/operators/equal.d.ts

@@ -0,0 +1,35 @@
+import type { TheDate } from "../theDate";
+import type { SerializedTheDate } from "../types";
+/**
+ * Checks whether two dates point to the same timestamp.
+ * 
+ * **Supported call styles:**
+ * - Classic: `equal(first, second)` -> `boolean`
+ * - Curried: `equal(second)` -> `(first) => boolean`
+ * 
+ * All parameters accept `TheDate` or `SerializedTheDate`.
+ * 
+ * ```ts
+ * const first = D.create("2024-06-20");
+ * const second = D.create("2024-06-20");
+ * 
+ * if (D.equal(first, second)) {
+ * 	// is equal
+ * }
+ * 
+ * const serialized = D.serialize(second);
+ * D.equal(first, serialized); // true
+ * ```
+ * 
+ * @remarks
+ * - Equality is based on normalized timestamps.
+ * 
+ * @see [`D.greater`](https://utils.duplojs.dev/en/v1/api/date/greater) For inclusive greater-than comparison
+ * @see [`D.less`](https://utils.duplojs.dev/en/v1/api/date/less) For inclusive less-than comparison
+ * @see https://utils.duplojs.dev/en/v1/api/date/equal
+ * 
+ * @namespace D
+ * 
+ */
+export declare function equal(second: TheDate | SerializedTheDate): (first: TheDate | SerializedTheDate) => boolean;
+export declare function equal(first: TheDate | SerializedTheDate, second: TheDate | SerializedTheDate): boolean;

package/dist/date/operators/equal.mjs

@@ -0,0 +1,12 @@
+import { toTimestamp } from '../toTimestamp.mjs';
+
+function equal(...args) {
+    if (args.length === 1) {
+        const [second] = args;
+        return (first) => equal(first, second);
+    }
+    const [first, second] = args;
+    return toTimestamp(first) === toTimestamp(second);
+}
+
+export { equal };

package/dist/date/operators/index.d.ts

@@ -28,3 +28,4 @@ export * from "./less";
 export * from "./lessThan";
 export * from "./lessThanTime";
 export * from "./lessTime";
+export * from "./equal";

package/dist/generator/createExternalAsyncGenerator.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+const exitExternalAsync = Symbol("exitExternalAsync");
+/**
+ * {@include generator/createExternalAsyncGenerator/index.md}
+ */
+function createExternalAsyncGenerator() {
+    let externalResolve = undefined;
+    return {
+        asyncGenerator: (async function* () {
+            const result = await new Promise((resolve) => {
+                externalResolve = resolve;
+            });
+            if (result === exitExternalAsync) {
+                return;
+            }
+            else {
+                yield result;
+            }
+        })(),
+        next: (value) => void externalResolve?.(value),
+        exit: () => void externalResolve?.(exitExternalAsync),
+    };
+}
+
+exports.createExternalAsyncGenerator = createExternalAsyncGenerator;

package/dist/generator/createExternalAsyncGenerator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Creates an externally controlled async generator that emits at most one value.
+ * 
+ * Signature: `createExternalAsyncGenerator()` -> returns `{ asyncGenerator, next, exit }`
+ * 
+ * Use `next(value)` to resolve the pending iteration with a value, or `exit()` to stop it without yielding.
+ * 
+ * ```ts
+ * const first = G.createExternalAsyncGenerator<number>();
+ * const firstPending = first.asyncGenerator.next();
+ * first.next(42);
+ * const firstResult = await firstPending;
+ * // firstResult: { done: false, value: 42 }
+ * 
+ * const second = G.createExternalAsyncGenerator<string>();
+ * const secondPending = second.asyncGenerator.next();
+ * second.exit();
+ * const secondResult = await secondPending;
+ * // secondResult: { done: true, value: undefined }
+ * 
+ * const third = G.createExternalAsyncGenerator<string>();
+ * const collected: string[] = [];
+ * const consume = (async() => {
+ * 	for await (const value of third.asyncGenerator) {
+ * 		collected.push(value);
+ * 	}
+ * })();
+ * third.next("hello");
+ * await consume;
+ * // collected: ["hello"]
+ * ```
+ * 
+ * @remarks
+ * - The returned async generator waits for one external resolution.
+ * - The first call to `next` or `exit` settles that pending resolution.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/generator/createExternalAsyncGenerator
+ * 
+ * @namespace G
+ * 
+ */
+export declare function createExternalAsyncGenerator<GenericValue extends unknown>(): {
+    asyncGenerator: AsyncGenerator<Awaited<GenericValue>, void, unknown>;
+    next: (value: GenericValue) => undefined;
+    exit: () => undefined;
+};

package/dist/generator/createExternalAsyncGenerator.mjs

@@ -0,0 +1,24 @@
+const exitExternalAsync = Symbol("exitExternalAsync");
+/**
+ * {@include generator/createExternalAsyncGenerator/index.md}
+ */
+function createExternalAsyncGenerator() {
+    let externalResolve = undefined;
+    return {
+        asyncGenerator: (async function* () {
+            const result = await new Promise((resolve) => {
+                externalResolve = resolve;
+            });
+            if (result === exitExternalAsync) {
+                return;
+            }
+            else {
+                yield result;
+            }
+        })(),
+        next: (value) => void externalResolve?.(value),
+        exit: () => void externalResolve?.(exitExternalAsync),
+    };
+}
+
+export { createExternalAsyncGenerator };

package/dist/generator/index.cjs

@@ -13,6 +13,7 @@ var chunk = require('./chunk.cjs');
 var asyncChunk = require('./asyncChunk.cjs');
 var group = require('./group.cjs');
 var asyncGroup = require('./asyncGroup.cjs');
+var createExternalAsyncGenerator = require('./createExternalAsyncGenerator.cjs');
 
 /**
  * {@include generator/index.md}
@@ -33,3 +34,4 @@ exports.asyncChunk = asyncChunk.asyncChunk;
 exports.group = group.group;
 exports.groupOutput = group.groupOutput;
 exports.asyncGroup = asyncGroup.asyncGroup;
+exports.createExternalAsyncGenerator = createExternalAsyncGenerator.createExternalAsyncGenerator;

package/dist/generator/index.d.ts

@@ -38,3 +38,4 @@ export * from "./chunk";
 export * from "./asyncChunk";
 export * from "./group";
 export * from "./asyncGroup";
+export * from "./createExternalAsyncGenerator";

package/dist/generator/index.mjs

@@ -11,6 +11,7 @@ export { chunk } from './chunk.mjs';
 export { asyncChunk } from './asyncChunk.mjs';
 export { group, groupOutput } from './group.mjs';
 export { asyncGroup } from './asyncGroup.mjs';
+export { createExternalAsyncGenerator } from './createExternalAsyncGenerator.mjs';
 
 /**
  * {@include generator/index.md}

package/dist/metadata.json

@@ -159,6 +159,9 @@
             {
               "name": "joinTuple.d.ts"
             },
+            {
+              "name": "mapTuple.d.ts"
+            },
             {
               "name": "mergeUnionTuple.d.ts"
             },
@@ -410,6 +413,15 @@
         {
           "name": "map.mjs"
         },
+        {
+          "name": "mapTuple.cjs"
+        },
+        {
+          "name": "mapTuple.d.ts"
+        },
+        {
+          "name": "mapTuple.mjs"
+        },
         {
           "name": "maxElements.cjs"
         },
@@ -1070,6 +1082,9 @@
             {
               "name": "anyValue.d.ts"
             },
+            {
+              "name": "bivariantFunction.d.ts"
+            },
             {
               "name": "breakGenericLink.d.ts"
             },
@@ -2890,6 +2905,15 @@
             {
               "name": "betweenTime.mjs"
             },
+            {
+              "name": "equal.cjs"
+            },
+            {
+              "name": "equal.d.ts"
+            },
+            {
+              "name": "equal.mjs"
+            },
             {
               "name": "greater.cjs"
             },
@@ -3944,6 +3968,15 @@
         {
           "name": "chunk.mjs"
         },
+        {
+          "name": "createExternalAsyncGenerator.cjs"
+        },
+        {
+          "name": "createExternalAsyncGenerator.d.ts"
+        },
+        {
+          "name": "createExternalAsyncGenerator.mjs"
+        },
         {
           "name": "execute.cjs"
         },
@@ -4808,9 +4841,15 @@
             {
               "name": "number.d.ts"
             },
+            {
+              "name": "pop.d.ts"
+            },
             {
               "name": "replace.d.ts"
             },
+            {
+              "name": "shift.d.ts"
+            },
             {
               "name": "split.d.ts"
             },
@@ -4987,6 +5026,24 @@
         {
           "name": "padStart.mjs"
         },
+        {
+          "name": "pop.cjs"
+        },
+        {
+          "name": "pop.d.ts"
+        },
+        {
+          "name": "pop.mjs"
+        },
+        {
+          "name": "prepend.cjs"
+        },
+        {
+          "name": "prepend.d.ts"
+        },
+        {
+          "name": "prepend.mjs"
+        },
         {
           "name": "repeat.cjs"
         },
@@ -5023,6 +5080,15 @@
         {
           "name": "search.mjs"
         },
+        {
+          "name": "shift.cjs"
+        },
+        {
+          "name": "shift.d.ts"
+        },
+        {
+          "name": "shift.mjs"
+        },
         {
           "name": "slice.cjs"
         },

package/dist/number/types/absolute.d.ts

@@ -1,5 +1,3 @@
 import type * as DString from "../../string";
-import type * as DArray from "../../array";
-import { type AnyTuple, type Adaptor } from "../../common";
 import { type IsPositive } from "./isPositive";
-export type Absolute<GenericValue extends number> = IsPositive<GenericValue> extends true ? GenericValue : DArray.JoinTuple<DArray.ShiftTuple<Adaptor<DString.Split<`${GenericValue}`, "">, AnyTuple<string>>>, ""> extends `${infer InferredResult extends number}` ? InferredResult : never;
+export type Absolute<GenericValue extends number> = IsPositive<GenericValue> extends true ? GenericValue : DString.Shift<`${GenericValue}`> extends `${infer InferredResult extends number}` ? InferredResult : never;

package/dist/string/index.cjs

@@ -32,6 +32,9 @@ var sortCompare = require('./sortCompare.cjs');
 var to = require('./to.cjs');
 var extract = require('./extract.cjs');
 var extractAll = require('./extractAll.cjs');
+var shift = require('./shift.cjs');
+var pop = require('./pop.cjs');
+var prepend = require('./prepend.cjs');
 var _default = require('./at/default.cjs');
 var first = require('./at/first.cjs');
 var last = require('./at/last.cjs');
@@ -75,6 +78,9 @@ exports.sortCompare = sortCompare.sortCompare;
 exports.to = to.to;
 exports.extract = extract.extract;
 exports.extractAll = extractAll.extractAll;
+exports.shift = shift.shift;
+exports.pop = pop.pop;
+exports.prepend = prepend.prepend;
 exports.at = _default.at;
 exports.first = first.first;
 exports.last = last.last;

package/dist/string/index.d.ts

@@ -60,3 +60,6 @@ export * from "./sortCompare";
 export * from "./to";
 export * from "./extract";
 export * from "./extractAll";
+export * from "./shift";
+export * from "./pop";
+export * from "./prepend";

package/dist/string/index.mjs

@@ -30,6 +30,9 @@ export { sortCompare } from './sortCompare.mjs';
 export { to } from './to.mjs';
 export { extract } from './extract.mjs';
 export { extractAll } from './extractAll.mjs';
+export { shift } from './shift.mjs';
+export { pop } from './pop.mjs';
+export { prepend } from './prepend.mjs';
 export { at } from './at/default.mjs';
 export { first } from './at/first.mjs';
 export { last } from './at/last.mjs';

package/dist/string/pop.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+/**
+ * {@include string/pop/index.md}
+ */
+function pop(input) {
+    return input.slice(0, -1);
+}
+
+exports.pop = pop;

package/dist/string/pop.d.ts

@@ -0,0 +1,26 @@
+import type { Pop } from "./types";
+/**
+ * Removes the last character from a string.
+ * 
+ * Signature: `pop(input)` -> returns a new string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.pop("Duplo"); // "Dupl"
+ * 
+ * S.pop("A"); // ""
+ * 
+ * S.pop(""); // ""
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with literal strings: return type removes the last character when possible.
+ * 
+ * @see [`S.shift`](https://utils.duplojs.dev/en/v1/api/string/shift) For removing the first character
+ * @see https://utils.duplojs.dev/en/v1/api/string/pop
+ * 
+ * @namespace S
+ * 
+ */
+export declare function pop<GenericInput extends string>(input: GenericInput): Pop<GenericInput>;

package/dist/string/pop.mjs

@@ -0,0 +1,8 @@
+/**
+ * {@include string/pop/index.md}
+ */
+function pop(input) {
+    return input.slice(0, -1);
+}
+
+export { pop };

package/dist/string/prepend.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+function prepend(...args) {
+    if (args.length === 1) {
+        const [text] = args;
+        return (input) => prepend(input, text);
+    }
+    const [input, ...textsRest] = args;
+    return "".concat(...textsRest, input);
+}
+
+exports.prepend = prepend;

package/dist/string/prepend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Prepends one or more strings to an input string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `prepend(input, text, ...textsRest)` -> returns a new string
+ * - Curried: `prepend(text)` -> returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.prepend(
+ * 	"Utils",
+ * 	"Duplo",
+ * 	"JS ",
+ * ); // "DuploJS Utils"
+ * 
+ * pipe(
+ * 	"world",
+ * 	S.prepend("hello "),
+ * ); // "hello world"
+ * 
+ * S.prepend(
+ * 	"value",
+ * 	"[",
+ * 	"] ",
+ * ); // "[] value"
+ * ```
+ * 
+ * @remarks
+ * - Classic style supports multiple prefix strings with rest parameters.
+ * - Curried style prepends a single `text` value.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/prepend
+ * @see [`S.concat`](https://utils.duplojs.dev/en/v1/api/string/concat) For appending strings
+ * 
+ * @namespace S
+ * 
+ */
+export declare function prepend(text: string): (input: string) => string;
+export declare function prepend(input: string, ...textsRest: string[]): string;

package/dist/string/prepend.mjs

@@ -0,0 +1,10 @@
+function prepend(...args) {
+    if (args.length === 1) {
+        const [text] = args;
+        return (input) => prepend(input, text);
+    }
+    const [input, ...textsRest] = args;
+    return "".concat(...textsRest, input);
+}
+
+export { prepend };

package/dist/string/shift.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+/**
+ * {@include string/shift/index.md}
+ */
+function shift(input) {
+    return input.slice(1);
+}
+
+exports.shift = shift;

package/dist/string/shift.d.ts

@@ -0,0 +1,26 @@
+import type { Shift } from "./types";
+/**
+ * Removes the first character from a string.
+ * 
+ * Signature: `shift(input)` -> returns a new string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.shift("Duplo"); // "uplo"
+ * 
+ * S.shift("A"); // ""
+ * 
+ * S.shift(""); // ""
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with literal strings: return type removes the first character when possible.
+ * 
+ * @see [`S.pop`](https://utils.duplojs.dev/en/v1/api/string/pop) For removing the last character
+ * @see https://utils.duplojs.dev/en/v1/api/string/shift
+ * 
+ * @namespace S
+ * 
+ */
+export declare function shift<GenericInput extends string>(input: GenericInput): Shift<GenericInput>;

package/dist/string/shift.mjs

@@ -0,0 +1,8 @@
+/**
+ * {@include string/shift/index.md}
+ */
+function shift(input) {
+    return input.slice(1);
+}
+
+export { shift };

package/dist/string/types/index.d.ts

@@ -11,3 +11,5 @@ export * from "./number";
 export * from "./digit";
 export * from "./templateLiteralContainLargeType";
 export * from "./replace";
+export * from "./shift";
+export * from "./pop";

package/dist/string/types/pop.d.ts

@@ -0,0 +1,3 @@
+import type { IsEqual } from "../../common";
+import type { TemplateLiteralContainLargeType } from "./templateLiteralContainLargeType";
+export type Pop<GenericValue extends string> = TemplateLiteralContainLargeType<GenericValue> extends true ? string : IsEqual<GenericValue, ""> extends true ? "" : GenericValue extends `${infer InferredFirst}${infer InferredRest}` ? IsEqual<InferredRest, ""> extends true ? "" : Pop<InferredRest> extends infer InferredResult extends string ? `${InferredFirst}${InferredResult}` : never : string;

package/dist/string/types/shift.d.ts

@@ -0,0 +1,3 @@
+import type { IsEqual } from "../../common";
+import type { TemplateLiteralContainLargeType } from "./templateLiteralContainLargeType";
+export type Shift<GenericValue extends string> = TemplateLiteralContainLargeType<GenericValue> extends true ? string : IsEqual<GenericValue, ""> extends true ? "" : GenericValue extends `${infer _InferredFirst}${infer InferredRest}` ? InferredRest : string;

package/dist/string/types/split.d.ts

@@ -1,6 +1,7 @@
 import { type Or, type IsEqual } from "../../common";
 import { type Includes } from "./includes";
-export type Split<GenericString extends string, GenericSeparator extends string, GenericLimit extends number = number, GenericLastResult extends string[] = []> = Or<[
-    IsEqual<GenericString, string>,
-    IsEqual<GenericSeparator, string>
-]> extends true ? string[] : GenericString extends `${infer InferredBefore}${GenericSeparator}${infer InferredAfter}` ? [...GenericLastResult, InferredBefore] extends infer InferredResult extends any[] ? IsEqual<InferredAfter, ""> extends true ? InferredResult : IsEqual<InferredResult["length"], 250> extends true ? Includes<InferredAfter, GenericSeparator> extends true ? [...InferredResult, ...string[]] : InferredResult : IsEqual<InferredResult["length"], GenericLimit> extends true ? InferredResult : Split<InferredAfter, GenericSeparator, GenericLimit, InferredResult> : never : [...GenericLastResult, GenericString];
+import { type TemplateLiteralContainLargeType } from "./templateLiteralContainLargeType";
+export type Split<GenericString extends string, GenericSeparator extends string, GenericLimit extends number = number, GenericLastResult extends string[] = []> = IsEqual<GenericLimit, 0> extends true ? [] : Or<[
+    TemplateLiteralContainLargeType<GenericString>,
+    TemplateLiteralContainLargeType<GenericSeparator>
+]> extends true ? [string, ...string[]] : GenericString extends `${infer InferredBefore}${GenericSeparator}${infer InferredAfter}` ? [...GenericLastResult, InferredBefore] extends infer InferredResult extends any[] ? IsEqual<InferredAfter, ""> extends true ? InferredResult : IsEqual<InferredResult["length"], 250> extends true ? Includes<InferredAfter, GenericSeparator> extends true ? [...InferredResult, ...string[]] : InferredResult : IsEqual<InferredResult["length"], GenericLimit> extends true ? InferredResult : Split<InferredAfter, GenericSeparator, GenericLimit, InferredResult> : never : [...GenericLastResult, GenericString];

package/dist/string/types/templateLiteralContainLargeType.d.ts

@@ -1,5 +1,6 @@
 import { type IsEqual, type Or } from "../../common";
 export type TemplateLiteralContainLargeType<GenericValue extends string> = (GenericValue extends `${infer InferredFirst}${infer InferredLast}` ? Or<[
     IsEqual<InferredFirst, `${number}`>,
-    IsEqual<InferredFirst, `${bigint}`>
+    IsEqual<InferredFirst, `${bigint}`>,
+    IsEqual<InferredFirst, string>
 ]> extends false ? TemplateLiteralContainLargeType<InferredLast> : true : GenericValue extends "" ? false : true) extends false ? false : true;

package/package.json

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