@duplojs/utils 1.4.42 → 1.4.44

package/dist/clean/entity.cjs

@@ -116,6 +116,15 @@ function createEntity(name, getPropertiesDefinition) {
     function is$1(input) {
         return entityKind.has(input) && entityKind.getValue(input) === name;
     }
+    function update(entity, newProperties) {
+        const updatedEntity = {};
+        for (const key in propertiesDefinition) {
+            updatedEntity[key] = newProperties[key] !== undefined
+                ? newProperties[key]
+                : entity[key];
+        }
+        return entityKind.setTo(updatedEntity, name);
+    }
     return entityHandlerKind.setTo({
         name,
         propertiesDefinition,
@@ -124,6 +133,7 @@ function createEntity(name, getPropertiesDefinition) {
         map: map$1,
         mapOrThrow,
         is: is$1,
+        update,
     });
 }
 

package/dist/clean/entity.d.ts

@@ -1,4 +1,4 @@
-import { type SimplifyTopLevel, type Kind, type Unwrap, type IsEqual, type IsExtends, type Or, type NeverCoalescing } from "../common";
+import { type SimplifyTopLevel, type Kind, type Unwrap, type IsEqual, type IsExtends, type Or, type NeverCoalescing, type RemoveKind } from "../common";
 import { type GetNewType, type NewTypeHandler } from "./newType";
 import * as DEither from "../either";
 import * as DDataParser from "../dataParser";
@@ -112,6 +112,18 @@ export interface EntityHandler<GenericName extends string = string, GenericPrope
     * 
     */
     is<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, Entity<GenericName>>;
+    /**
+     * Updates an entity by merging typed properties into an existing entity.
+     * 
+     * ```ts
+     * const updated = User.Entity.update(mapped, {
+     * 	name: User.Name.createOrThrow("Bobby"),
+     * 	nick: null,
+     * });
+     * ```
+     * 
+     */
+    update<const GenericEntity extends Entity<GenericName>, const GenericProperties extends Partial<EntityProperties<GenericPropertiesDefinition>>>(entity: GenericEntity, properties: GenericProperties): Entity<GenericName> & DObject.AssignObjects<RemoveKind<GenericEntity>, GenericProperties>;
 }
 declare const CreateEntityError_base: new (params: {
     "@DuplojsUtilsError/create-entity-error"?: unknown;

package/dist/clean/entity.mjs

@@ -114,6 +114,15 @@ function createEntity(name, getPropertiesDefinition) {
     function is(input) {
         return entityKind.has(input) && entityKind.getValue(input) === name;
     }
+    function update(entity, newProperties) {
+        const updatedEntity = {};
+        for (const key in propertiesDefinition) {
+            updatedEntity[key] = newProperties[key] !== undefined
+                ? newProperties[key]
+                : entity[key];
+        }
+        return entityKind.setTo(updatedEntity, name);
+    }
     return entityHandlerKind.setTo({
         name,
         propertiesDefinition,
@@ -122,6 +131,7 @@ function createEntity(name, getPropertiesDefinition) {
         map: map$1,
         mapOrThrow,
         is,
+        update,
     });
 }
 

package/dist/common/isType.d.ts

@@ -1,4 +1,4 @@
-import { type IsEqual, type AnyFunction } from "./types";
+import { type IsEqual, type AnyFunction, type BreakGenericLink } from "./types";
 interface Type {
     string: [string, never];
     number: [number, never];
@@ -50,6 +50,6 @@ type EligibleType<GenericInput extends unknown> = {
  * @see https://utils.duplojs.dev/en/v1/api/common/isType
  * 
  */
-export declare function isType<GenericInput extends unknown, GenericType extends EligibleType<GenericInput>>(type: GenericType): (input: GenericInput) => input is ComputeResult<GenericInput, Type[GenericType]>;
+export declare function isType<GenericInput extends unknown, GenericType extends EligibleType<GenericInput>>(type: GenericType): (input: GenericInput) => input is ComputeResult<BreakGenericLink<GenericInput>, Type[GenericType]>;
 export declare function isType<GenericInput extends unknown, GenericType extends EligibleType<GenericInput>>(input: GenericInput, type: GenericType): input is ComputeResult<GenericInput, Type[GenericType]>;
 export {};

package/dist/common/pipeCall.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/pipeCall/index.md}
+ */
 function pipeCall(theFunction) {
     return theFunction;
 }

package/dist/common/pipeCall.d.ts

@@ -1 +1,10 @@
+/**
+ * The pipeCall() function returns the same function it receives. It is used to adapt a function to a pipe-friendly shape without changing behavior.
+ * 
+ * **Supported call styles:**
+ * - Direct: `pipeCall(theFunction)` -> returns the same function
+ * 
+ * The input function is not mutated.
+ * 
+ */
 export declare function pipeCall<GenericInput extends unknown, GenericOutput extends unknown>(theFunction: (input: NoInfer<GenericInput>) => GenericOutput): (input: GenericInput) => NoInfer<GenericOutput>;

package/dist/common/pipeCall.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/pipeCall/index.md}
+ */
 function pipeCall(theFunction) {
     return theFunction;
 }

package/dist/common/toCurriedPredicate.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/toCurriedPredicate/index.md}
+ */
 function toCurriedPredicate(thePredicate) {
     return thePredicate;
 }

package/dist/common/toCurriedPredicate.d.ts

@@ -1 +1,10 @@
+/**
+ * The toCurriedPredicate() function returns the same predicate it receives. It exists to force type inference when a single-argument predicate is passed to a pipe and inference can go wrong.
+ * 
+ * **Supported call styles:**
+ * - Direct: `toCurriedPredicate(thePredicate)` -> returns the same predicate
+ * 
+ * The input predicate is not mutated.
+ * 
+ */
 export declare function toCurriedPredicate<GenericInput extends unknown, GenericPredicate extends GenericInput>(thePredicate: (input: GenericInput) => input is GenericPredicate): (input: GenericInput) => input is GenericPredicate;

package/dist/common/toCurriedPredicate.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/toCurriedPredicate/index.md}
+ */
 function toCurriedPredicate(thePredicate) {
     return thePredicate;
 }

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

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

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

@@ -1 +1 @@
-export type MaybeArray<GenericValue extends unknown> = GenericValue | GenericValue[];
+export type MaybeArray<GenericValue extends unknown> = GenericValue | readonly GenericValue[];

package/dist/dataParser/base.cjs

@@ -5,7 +5,9 @@ var kind = require('./kind.cjs');
 var simpleClone = require('../common/simpleClone.cjs');
 var wrapValue = require('../common/wrapValue.cjs');
 var override = require('../common/override.cjs');
+var kind$1 = require('../common/kind.cjs');
 var pipe = require('../common/pipe.cjs');
+var errorKindNamespace = require('../common/errorKindNamespace.cjs');
 var error$1 = require('../either/left/error.cjs');
 var success = require('../either/right/success.cjs');
 
@@ -27,6 +29,13 @@ const DPE = error.createError();
 const EE = error$1.error(null);
 const ES = success.success(null);
 const KWV = wrapValue.keyWrappedValue;
+class DataParserThrowError extends kind$1.kindHeritage("dataParserThrowError", errorKindNamespace.createErrorKind("dataParserThrowError"), Error) {
+    value;
+    constructor(value) {
+        super({}, ["Parse Error."]);
+        this.value = value;
+    }
+}
 function dataParserInit(kind, definition, exec, specificOverrideHandler) {
     const formattedExec = typeof exec === "object"
         ? exec
@@ -130,11 +139,36 @@ function dataParserInit(kind, definition, exec, specificOverrideHandler) {
         }), exec, specificOverrideHandler),
         clone: () => dataParserInit(kind, simpleClone.simpleClone(definition), exec, specificOverrideHandler),
         contract: () => self,
+        parseOrThrow(data) {
+            const error = {
+                ...DPE,
+                issues: [],
+                currentPath: [],
+            };
+            const result = middleExec(data, error);
+            if (result === SDPE) {
+                throw new DataParserThrowError(error);
+            }
+            return result;
+        },
+        async asyncParseOrThrow(data) {
+            const error = {
+                ...DPE,
+                issues: [],
+                currentPath: [],
+            };
+            const result = await middleAsyncExec(data, error);
+            if (result === SDPE) {
+                throw new DataParserThrowError(error);
+            }
+            return result;
+        },
     }, (value) => dataParserKind.setTo(value, null), kind.setTo, (value) => dataParserInit.overrideHandler.apply(value), (value) => specificOverrideHandler.apply(value));
     return self;
 }
 dataParserInit.overrideHandler = override.createOverride("@duplojs/utils/data-parser/base");
 
+exports.DataParserThrowError = DataParserThrowError;
 exports.SymbolDataParserError = SymbolDataParserError;
 exports.SymbolDataParserErrorLabel = SymbolDataParserErrorLabel;
 exports.checkerKind = checkerKind;

package/dist/dataParser/base.d.ts

@@ -76,13 +76,6 @@ export interface DataParser<GenericDefinition extends DataParserDefinition = Dat
      * 
      * It executes the async parser path, applies all registered checkers, and never mutates the input.
      * 
-     * ```ts
-     * // TODO: add asyncParse examples.
-     * ```
-     * 
-     * @remarks 
-     * - TODO: complete this documentation and examples.
-     * 
      * @namespace DP
      * 
      */
@@ -169,11 +162,60 @@ export interface DataParser<GenericDefinition extends DataParserDefinition = Dat
     contract<GenericValue extends unknown>(...args: IsEqual<Output<this>, GenericValue> extends true ? [] : [] & {
         [SymbolContractError]: "Contract error.";
     }): Contract<GenericValue>;
+    /**
+     * The parseOrThrow() method runs a data parser synchronously and returns the parsed value or throws a DataParserThrowError.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.parseOrThrow(input)` -> returns the parsed value
+     * 
+     * It executes the parser, applies all registered checkers, and never mutates the input.
+     * 
+     * ```ts
+     * const stringSchema = DP.string({
+     * 	checkers: [DP.checkerStringMin(3)],
+     * });
+     * 
+     * const value = stringSchema.parseOrThrow("DuploJS");
+     * // value: string
+     * 
+     * try {
+     * 	stringSchema.parseOrThrow("ok");
+     * } catch (error) {
+     * 	if (error instanceof DP.DataParserThrowError) {
+     * 		// parseError: DP.DataParserError
+     * 	}
+     * }
+     * 
+     * ```
+     * 
+     * @namespace DP
+     * 
+     */
+    parseOrThrow(data: unknown): GenericOutput;
+    /**
+     * The asyncParseOrThrow() method runs a data parser asynchronously and resolves to the parsed value or rejects with a DataParserThrowError.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.asyncParseOrThrow(input)` -> returns a promise
+     * 
+     * It executes the async parser path, applies all registered checkers, and never mutates the input.
+     * 
+     * @namespace DP
+     * 
+     */
+    asyncParseOrThrow(data: unknown): Promise<GenericOutput>;
 }
 interface DataParserInitExecParams<GenericDataParser extends DataParser> {
     sync(...args: [...Parameters<GenericDataParser["exec"]>, self: GenericDataParser]): (GetKindValue<typeof dataParserKind, GenericDataParser>["output"] | SymbolDataParserErrorIssue | SymbolDataParserErrorPromiseIssue);
     async(...args: [...Parameters<GenericDataParser["exec"]>, self: GenericDataParser]): Promise<GetKindValue<typeof dataParserKind, GenericDataParser>["output"] | SymbolDataParserErrorIssue | SymbolDataParserErrorPromiseIssue>;
 }
+declare const DataParserThrowError_base: new (params: {
+    "@DuplojsUtilsError/dataParserThrowError"?: unknown;
+}, parentParams: readonly [message?: string | undefined, options?: ErrorOptions | undefined]) => Error & Kind<import("../common").KindDefinition<"dataParserThrowError", unknown>, unknown> & Kind<import("../common").KindDefinition<"@DuplojsUtilsError/dataParserThrowError", unknown>, unknown>;
+export declare class DataParserThrowError extends DataParserThrowError_base {
+    value: unknown;
+    constructor(value: unknown);
+}
 export declare function dataParserInit<GenericDataParser extends DataParser>(kind: Exclude<GetKindHandler<GenericDataParser>, typeof dataParserKind>, definition: GenericDataParser["definition"], exec: (DataParserInitExecParams<GenericDataParser> | DataParserInitExecParams<GenericDataParser>["sync"]), specificOverrideHandler: OverrideHandler<GenericDataParser>): GenericDataParser;
 export declare namespace dataParserInit {
     var overrideHandler: OverrideHandler<DataParser<DataParserDefinition<DataParserChecker<DataParserCheckerDefinition, unknown>>, unknown, unknown>>;

package/dist/dataParser/base.mjs

@@ -3,7 +3,9 @@ import { createDataParserKind } from './kind.mjs';
 import { simpleClone } from '../common/simpleClone.mjs';
 import { keyWrappedValue } from '../common/wrapValue.mjs';
 import { createOverride } from '../common/override.mjs';
+import { kindHeritage } from '../common/kind.mjs';
 import { pipe } from '../common/pipe.mjs';
+import { createErrorKind } from '../common/errorKindNamespace.mjs';
 import { error } from '../either/left/error.mjs';
 import { success } from '../either/right/success.mjs';
 
@@ -25,6 +27,13 @@ const DPE = createError();
 const EE = error(null);
 const ES = success(null);
 const KWV = keyWrappedValue;
+class DataParserThrowError extends kindHeritage("dataParserThrowError", createErrorKind("dataParserThrowError"), Error) {
+    value;
+    constructor(value) {
+        super({}, ["Parse Error."]);
+        this.value = value;
+    }
+}
 function dataParserInit(kind, definition, exec, specificOverrideHandler) {
     const formattedExec = typeof exec === "object"
         ? exec
@@ -128,9 +137,33 @@ function dataParserInit(kind, definition, exec, specificOverrideHandler) {
         }), exec, specificOverrideHandler),
         clone: () => dataParserInit(kind, simpleClone(definition), exec, specificOverrideHandler),
         contract: () => self,
+        parseOrThrow(data) {
+            const error = {
+                ...DPE,
+                issues: [],
+                currentPath: [],
+            };
+            const result = middleExec(data, error);
+            if (result === SDPE) {
+                throw new DataParserThrowError(error);
+            }
+            return result;
+        },
+        async asyncParseOrThrow(data) {
+            const error = {
+                ...DPE,
+                issues: [],
+                currentPath: [],
+            };
+            const result = await middleAsyncExec(data, error);
+            if (result === SDPE) {
+                throw new DataParserThrowError(error);
+            }
+            return result;
+        },
     }, (value) => dataParserKind.setTo(value, null), kind.setTo, (value) => dataParserInit.overrideHandler.apply(value), (value) => specificOverrideHandler.apply(value));
     return self;
 }
 dataParserInit.overrideHandler = createOverride("@duplojs/utils/data-parser/base");
 
-export { SymbolDataParserError, SymbolDataParserErrorLabel, checkerKind, dataParserCheckerInit, dataParserInit, dataParserKind };
+export { DataParserThrowError, SymbolDataParserError, SymbolDataParserErrorLabel, checkerKind, dataParserCheckerInit, dataParserInit, dataParserKind };

package/dist/dataParser/baseExtended.d.ts

@@ -54,17 +54,49 @@ export interface DataParserExtended<GenericDefinition extends DataParserDefiniti
      * 
      * It executes the async parser path, applies all registered checkers, and keeps the extended API available on the parser instance.
      * 
+     * @namespace DPE
+     * 
+     */
+    asyncParse(data: unknown): Promise<DEither.EitherSuccess<GenericOutput> | DEither.EitherError<DataParserError>>;
+    /**
+     * The parseOrThrow() method runs an extended data parser synchronously and returns the parsed value or throws a DataParserThrowError.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.parseOrThrow(input)` -> returns the parsed value
+     * 
+     * It executes the parser, applies all registered checkers, and keeps the extended API available on the parser instance.
+     * 
      * ```ts
-     * // TODO: add asyncParse examples.
+     * const stringSchema = DPE.string().min(3);
+     * 
+     * const value = stringSchema.parseOrThrow("DuploJS");
+     * // value: string
+     * 
+     * try {
+     * 	stringSchema.parseOrThrow("ok");
+     * } catch (error) {
+     * 	if (error instanceof DP.DataParserThrowError) {
+     * 		// DP.DataParserError
+     * 	}
+     * }
      * ```
      * 
-     * @remarks 
-     * - TODO: complete this documentation and examples.
+     * @namespace DPE
+     * 
+     */
+    parseOrThrow(data: unknown): GenericOutput;
+    /**
+     * The asyncParseOrThrow() method runs an extended data parser asynchronously and resolves to the parsed value or rejects with a DataParserThrowError.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.asyncParseOrThrow(input)` -> returns a promise
+     * 
+     * It executes the async parser path, applies all registered checkers, and keeps the extended API available on the parser instance.
      * 
      * @namespace DPE
      * 
      */
-    asyncParse(data: unknown): Promise<DEither.EitherSuccess<GenericOutput> | DEither.EitherError<DataParserError>>;
+    asyncParseOrThrow(data: unknown): Promise<GenericOutput>;
     /**
      * The addChecker() method returns a new extended data parser with one or more additional checkers appended.
      * 

package/dist/dataParser/index.cjs

@@ -53,6 +53,7 @@ var recover = require('./parsers/recover.cjs');
 
 
 
+exports.DataParserThrowError = base.DataParserThrowError;
 exports.SymbolDataParserError = base.SymbolDataParserError;
 exports.SymbolDataParserErrorLabel = base.SymbolDataParserErrorLabel;
 exports.checkerKind = base.checkerKind;

package/dist/dataParser/index.mjs

@@ -1,4 +1,4 @@
-export { SymbolDataParserError, SymbolDataParserErrorLabel, checkerKind, dataParserCheckerInit, dataParserInit, dataParserKind } from './base.mjs';
+export { DataParserThrowError, SymbolDataParserError, SymbolDataParserErrorLabel, checkerKind, dataParserCheckerInit, dataParserInit, dataParserKind } from './base.mjs';
 export { dataParserExtendedInit, extendedKind } from './baseExtended.mjs';
 export { SymbolDataParserErrorIssue, SymbolDataParserErrorIssueLabel, SymbolDataParserErrorPromiseIssue, SymbolDataParserErrorPromiseIssueLabel, addIssue, addPromiseIssue, createError, errorIssueKind, errorKind, errorPromiseIssueKind, popErrorPath, setErrorPath } from './error.mjs';
 import * as index from './extended/index.mjs';

package/dist/metadata.json

@@ -4771,6 +4771,24 @@
         {
           "name": "endsWith.mjs"
         },
+        {
+          "name": "extract.cjs"
+        },
+        {
+          "name": "extract.d.ts"
+        },
+        {
+          "name": "extract.mjs"
+        },
+        {
+          "name": "extractAll.cjs"
+        },
+        {
+          "name": "extractAll.d.ts"
+        },
+        {
+          "name": "extractAll.mjs"
+        },
         {
           "name": "includes.cjs"
         },

package/dist/pattern/match/builder.cjs

@@ -33,6 +33,16 @@ matchBuilder.set("when", ({ args: [predicate, theFunction], accumulator, next, }
         },
     ],
 }));
+matchBuilder.set("whenNot", ({ args: [predicate, theFunction], accumulator, next, }) => next({
+    ...accumulator,
+    matchers: [
+        ...accumulator.matchers,
+        {
+            isMatch: (value) => !predicate(value),
+            theFunction,
+        },
+    ],
+}));
 matchBuilder.set("exhaustive", ({ accumulator: { input, matchers, }, }) => {
     // eslint-disable-next-line @typescript-eslint/prefer-for-of
     for (let index = 0; index < matchers.length; index++) {

package/dist/pattern/match/builder.d.ts

@@ -13,6 +13,8 @@ export interface MatchBuilder<GenericValue extends unknown = never, GenericResul
     with<const GenericPattern extends Pattern<GenericValue>, GenericOutput extends unknown>(pattern: FixDeepFunctionInfer<Pattern<GenericValue>, GenericPattern>, theFunction: (value: ComplexMatchedValue<GenericValue, PatternValue<GenericPattern>>) => GenericOutput): MatchBuilder<ComplexUnMatchedValue<GenericValue, PatternValue<GenericPattern>>, GenericOutput | GenericResult>;
     when<GenericPredicatedInput extends GenericValue, GenericOutput extends unknown>(predicate: (input: GenericValue) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput): MatchBuilder<Exclude<GenericValue, GenericPredicatedInput>, GenericOutput | GenericResult>;
     when<GenericOutput extends unknown>(predicate: (input: GenericValue) => boolean, theFunction: (predicatedInput: GenericValue) => GenericOutput): MatchBuilder<GenericValue, GenericOutput | GenericResult>;
+    whenNot<GenericPredicatedInput extends GenericValue, GenericOutput extends unknown>(predicate: (input: GenericValue) => input is GenericPredicatedInput, theFunction: (predicatedInput: Exclude<GenericValue, GenericPredicatedInput>) => GenericOutput): MatchBuilder<Extract<GenericValue, GenericPredicatedInput>, GenericOutput | GenericResult>;
+    whenNot<GenericOutput extends unknown>(predicate: (input: GenericValue) => boolean, theFunction: (predicatedInput: GenericValue) => GenericOutput): MatchBuilder<GenericValue, GenericOutput | GenericResult>;
     exhaustive: IsEqual<GenericValue, never> extends true ? () => GenericResult : {
         [SymbolErrorMatchExhaustive]: "Pattern are not exhaustive.";
         restValue: GenericValue;

package/dist/pattern/match/builder.mjs

@@ -31,6 +31,16 @@ matchBuilder.set("when", ({ args: [predicate, theFunction], accumulator, next, }
         },
     ],
 }));
+matchBuilder.set("whenNot", ({ args: [predicate, theFunction], accumulator, next, }) => next({
+    ...accumulator,
+    matchers: [
+        ...accumulator.matchers,
+        {
+            isMatch: (value) => !predicate(value),
+            theFunction,
+        },
+    ],
+}));
 matchBuilder.set("exhaustive", ({ accumulator: { input, matchers, }, }) => {
     // eslint-disable-next-line @typescript-eslint/prefer-for-of
     for (let index = 0; index < matchers.length; index++) {

package/dist/pattern/when.d.ts

@@ -1,5 +1,6 @@
 import { type AnyValue, type BreakGenericLink, type IsEqual, type EscapeVoid } from "../common";
 import { type PatternResult } from "./result";
+type ComputePredicateInput<GenericValue extends unknown> = Exclude<IsEqual<GenericValue, unknown> extends true ? AnyValue : GenericValue, PatternResult>;
 /**
  * Applies a handler when a predicate matches.
  * 
@@ -43,7 +44,8 @@ import { type PatternResult } from "./result";
  * @namespace P
  * 
  */
-export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericPredicatedInput extends GenericInputValue, GenericOutput extends AnyValue | EscapeVoid>(predicate: (input: GenericInputValue) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput): (input: (GenericInput | GenericInputPatternResult | GenericInputValue)) => (GenericInputPatternResult | Exclude<BreakGenericLink<GenericInput>, GenericPredicatedInput | PatternResult> | PatternResult<GenericOutput>);
-export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericOutput extends AnyValue | EscapeVoid>(predicate: (input: GenericInputValue) => boolean, theFunction: (predicatedInput: GenericInputValue) => GenericOutput): (input: (GenericInput | GenericInputPatternResult | GenericInputValue)) => (GenericInputPatternResult | GenericInputValue | PatternResult<GenericOutput>);
+export declare function when<GenericInput extends unknown, GenericInputValue extends ComputePredicateInput<GenericInput>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericPredicatedInput extends GenericInputValue, GenericOutput extends AnyValue | EscapeVoid>(predicate: (((input: GenericInputValue) => input is GenericPredicatedInput) & (IsEqual<ComputePredicateInput<GenericInput>, GenericInputValue> extends true ? unknown : (input: ComputePredicateInput<NoInfer<GenericInput>>) => input is GenericPredicatedInput)), theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput): (input: (GenericInput | GenericInputPatternResult | GenericInputValue)) => (GenericInputPatternResult | Exclude<BreakGenericLink<GenericInput>, GenericPredicatedInput | PatternResult> | PatternResult<GenericOutput>);
+export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericOutput extends AnyValue | EscapeVoid>(predicate: (((input: GenericInputValue) => boolean) & (IsEqual<ComputePredicateInput<GenericInput>, GenericInputValue> extends true ? unknown : (input: ComputePredicateInput<NoInfer<GenericInput>>) => boolean)), theFunction: (predicatedInput: GenericInputValue) => GenericOutput): (input: (GenericInput | GenericInputPatternResult | GenericInputValue)) => (GenericInputPatternResult | GenericInputValue | PatternResult<GenericOutput>);
 export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericPredicatedInput extends GenericInputValue, GenericOutput extends AnyValue | EscapeVoid>(input: (GenericInput | GenericInputPatternResult | GenericInputValue), predicate: (input: GenericInputValue) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput): (GenericInputPatternResult | Exclude<BreakGenericLink<GenericInput>, GenericPredicatedInput | PatternResult> | PatternResult<GenericOutput>);
 export declare function when<GenericInput extends unknown, GenericInputValue extends Exclude<IsEqual<GenericInput, unknown> extends true ? AnyValue : GenericInput, PatternResult>, GenericInputPatternResult extends Extract<GenericInput, PatternResult>, GenericOutput extends AnyValue | EscapeVoid>(input: (GenericInput | GenericInputPatternResult | GenericInputValue), predicate: (input: GenericInputValue) => boolean, theFunction: (predicatedInput: GenericInputValue) => GenericOutput): (GenericInputPatternResult | GenericInputValue | PatternResult<GenericOutput>);
+export {};

package/dist/string/extract.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+function extract(...args) {
+    if (args.length === 1) {
+        const [pattern] = args;
+        return (input) => extract(input, pattern);
+    }
+    const [input, pattern] = args;
+    const result = input.match(pattern);
+    if (!result) {
+        return undefined;
+    }
+    return {
+        matchedValue: result[0],
+        groups: result.slice(1),
+        namedGroups: result.groups ? { ...result.groups } : undefined,
+        offset: result.index ?? 0,
+        self: result.input ?? input,
+    };
+}
+
+exports.extract = extract;

package/dist/string/extract.d.ts

@@ -0,0 +1,45 @@
+export interface ExtractResult {
+    matchedValue: string;
+    groups: string[];
+    namedGroups?: Record<string, string>;
+    offset: number;
+    self: string;
+}
+/**
+ * Extracts details about the first match of a pattern in a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `extract(input, pattern)` → returns an ExtractResult or `undefined`
+ * - Curried: `extract(pattern)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.extract("id=order-42", /(?<name>\w+)-(\d+)/);
+ * // {
+ * //   matchedValue: "order-42",
+ * //   groups: ["order", "42"],
+ * //   namedGroups: { name: "order" },
+ * //   offset: 3,
+ * //   self: "id=order-42",
+ * // }
+ * 
+ * S.extract("hello", /\d+/); // undefined
+ * 
+ * pipe(
+ * 	"user-7",
+ * 	S.extract(/(\w+)-(\d+)/),
+ * ); // ExtractResult | undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.match`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/extract
+ * 
+ * @namespace S
+ * 
+ */
+export declare function extract<GenericInput extends string>(pattern: string | RegExp): (input: GenericInput) => ExtractResult | undefined;
+export declare function extract<GenericInput extends string>(input: GenericInput, pattern: string | RegExp): ExtractResult | undefined;

package/dist/string/extract.mjs

@@ -0,0 +1,20 @@
+function extract(...args) {
+    if (args.length === 1) {
+        const [pattern] = args;
+        return (input) => extract(input, pattern);
+    }
+    const [input, pattern] = args;
+    const result = input.match(pattern);
+    if (!result) {
+        return undefined;
+    }
+    return {
+        matchedValue: result[0],
+        groups: result.slice(1),
+        namedGroups: result.groups ? { ...result.groups } : undefined,
+        offset: result.index ?? 0,
+        self: result.input ?? input,
+    };
+}
+
+export { extract };

package/dist/string/extractAll.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var map = require('../generator/map.cjs');
+
+function extractAll(...args) {
+    if (args.length === 1) {
+        const [pattern] = args;
+        return (input) => extractAll(input, pattern);
+    }
+    const [input, pattern] = args;
+    return map.map(input.matchAll(pattern), (value) => ({
+        matchedValue: value[0],
+        groups: value.slice(1),
+        namedGroups: value.groups ? { ...value.groups } : undefined,
+        offset: value.index ?? 0,
+        self: value.input ?? input,
+    }));
+}
+
+exports.extractAll = extractAll;

package/dist/string/extractAll.d.ts

@@ -0,0 +1,38 @@
+import type { ExtractResult } from "./extract";
+/**
+ * Extracts details about all matches of a pattern in a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `extractAll(input, pattern)` → returns a generator of ExtractResult
+ * - Curried: `extractAll(pattern)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * pipe(
+ * 	"id=1; id=2",
+ * 	S.extractAll(/id=(\d+)/g),
+ * 	A.from,
+ * ); // [{ ... }, { ... }]
+ * 
+ * S.extractAll("hello", /\d+/g); // Generator
+ * 
+ * pipe(
+ * 	"a1b2",
+ * 	S.extractAll(/(\d)/g),
+ * 	A.from,
+ * 	A.map((value) => value.matchedValue),
+ * ); // ["1", "2"]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.matchAll`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/extractAll
+ * 
+ * @namespace S
+ * 
+ */
+export declare function extractAll<GenericInput extends string>(pattern: RegExp): (input: GenericInput) => Generator<ExtractResult>;
+export declare function extractAll<GenericInput extends string>(input: GenericInput, pattern: RegExp): Generator<ExtractResult>;

package/dist/string/extractAll.mjs

@@ -0,0 +1,18 @@
+import { map } from '../generator/map.mjs';
+
+function extractAll(...args) {
+    if (args.length === 1) {
+        const [pattern] = args;
+        return (input) => extractAll(input, pattern);
+    }
+    const [input, pattern] = args;
+    return map(input.matchAll(pattern), (value) => ({
+        matchedValue: value[0],
+        groups: value.slice(1),
+        namedGroups: value.groups ? { ...value.groups } : undefined,
+        offset: value.index ?? 0,
+        self: value.input ?? input,
+    }));
+}
+
+export { extractAll };

package/dist/string/index.cjs

@@ -30,6 +30,8 @@ var length = require('./length.cjs');
 var sort = require('./sort.cjs');
 var sortCompare = require('./sortCompare.cjs');
 var to = require('./to.cjs');
+var extract = require('./extract.cjs');
+var extractAll = require('./extractAll.cjs');
 var _default = require('./at/default.cjs');
 var first = require('./at/first.cjs');
 var last = require('./at/last.cjs');
@@ -71,6 +73,8 @@ exports.length = length.length;
 exports.sort = sort.sort;
 exports.sortCompare = sortCompare.sortCompare;
 exports.to = to.to;
+exports.extract = extract.extract;
+exports.extractAll = extractAll.extractAll;
 exports.at = _default.at;
 exports.first = first.first;
 exports.last = last.last;

package/dist/string/index.d.ts

@@ -14,7 +14,7 @@
  * 
  * What you will find in this namespace:
  * - casing and trimming (`S.toUpperCase`, `S.toLowerCase`, `S.capitalize`, `S.uncapitalize`, `S.trim`)
- * - search and match (`S.includes`, `S.startsWith`, `S.endsWith`, `S.search`, `S.match`, `S.matchAll`, `S.test`)
+ * - search and match (`S.includes`, `S.startsWith`, `S.endsWith`, `S.search`, `S.match`, `S.matchAll`, `S.extract`, `S.extractAll`, `S.test`)
  * - composition and slicing (`S.concat`, `S.slice`, `S.substring`, `S.split`)
  * - indexing (`S.at`, `S.charAt`, `S.indexOf`, `S.lastIndexOf`)
  * - padding and repeat (`S.padStart`, `S.padEnd`, `S.repeat`)
@@ -58,3 +58,5 @@ export * from "./length";
 export * from "./sort";
 export * from "./sortCompare";
 export * from "./to";
+export * from "./extract";
+export * from "./extractAll";

package/dist/string/index.mjs

@@ -28,6 +28,8 @@ export { length } from './length.mjs';
 export { sort } from './sort.mjs';
 export { sortCompare } from './sortCompare.mjs';
 export { to } from './to.mjs';
+export { extract } from './extract.mjs';
+export { extractAll } from './extractAll.mjs';
 export { at } from './at/default.mjs';
 export { first } from './at/first.mjs';
 export { last } from './at/last.mjs';

package/dist/string/match.d.ts

@@ -1,6 +1,8 @@
 /**
  * Finds the first match of a pattern in a string.
  * 
+ * @deprecated Use `extract` instead.
+ * 
  * **Supported call styles:**
  * - Classic: `match(input, pattern)` → returns a match array or `undefined`
  * - Curried: `match(pattern)` → returns a function waiting for the input

package/dist/string/matchAll.d.ts

@@ -1,6 +1,8 @@
 /**
  * Finds all matches of a pattern in a string.
  * 
+ * @deprecated Use `extractAll` instead.
+ * 
  * **Supported call styles:**
  * - Classic: `matchAll(input, pattern)` → returns an iterator of matches
  * - Curried: `matchAll(pattern)` → returns a function waiting for the input

package/package.json

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