@duplojs/utils 1.4.49 → 1.4.51

package/dist/common/index.d.ts

@@ -42,6 +42,7 @@ export * from "./toJSON";
 export * from "./toTransform";
 export * from "./toWrappedValue";
 export * from "./unwrap";
+export * from "./unwrapGroup";
 export * from "./asyncLoop";
 export * from "./asyncRetry";
 export * from "./wrapValue";
@@ -59,6 +60,7 @@ export * from "./or";
 export * from "./whenElse";
 export * from "./justReturn";
 export * from "./memo";
+export * from "./memoPromise";
 export * from "./instanceOf";
 export * from "./globalStore";
 export * from "./builder";

package/dist/common/memo.d.ts

@@ -1,13 +1,12 @@
-import { type AnyValue } from "./types";
 export interface Memoized<GenericValue extends unknown> {
     readonly value: GenericValue;
 }
 /**
- * The memo() function evaluates a function only once then memorizes the result. Subsequent calls return the same value without recalculation.
+ * The memo() function evaluates a function only once then memorizes the result. The first access to `value` triggers the evaluation.
  * 
- * Signature: `memo(theFunction)` → returns a value
+ * Signature: `memo(theFunction)` → returns a memoized object
  * 
- * The input value is not mutated.
+ * The input function is called only once.
  * 
  * ```ts
  * let calls = 0;
@@ -25,4 +24,4 @@ export interface Memoized<GenericValue extends unknown> {
  * @see https://utils.duplojs.dev/en/v1/api/common/memo
  * 
  */
-export declare function memo<GenericOutput extends AnyValue>(theFunction: () => GenericOutput): Memoized<GenericOutput>;
+export declare function memo<GenericOutput extends unknown>(theFunction: () => GenericOutput): Memoized<GenericOutput>;

package/dist/common/memoPromise.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+var externalPromise = require('./externalPromise.cjs');
+var forward = require('./forward.cjs');
+
+/**
+ * {@include common/memoPromise/index.md}
+ */
+function memoPromise(theFunction) {
+    let externalPromise$1 = forward.forward(undefined);
+    const payload = {
+        get value() {
+            if (externalPromise$1) {
+                return externalPromise$1.promise;
+            }
+            externalPromise$1 = externalPromise.createExternalPromise();
+            const { resolve, reject } = externalPromise$1;
+            const promise = theFunction();
+            void (promise instanceof Promise
+                ? promise
+                : Promise.resolve(promise))
+                .then((result) => {
+                Object.defineProperty(payload, "value", {
+                    value: result,
+                });
+                resolve(result);
+            })
+                .catch(reject);
+            return externalPromise$1.promise;
+        },
+    };
+    return payload;
+}
+
+exports.memoPromise = memoPromise;

package/dist/common/memoPromise.d.ts

@@ -0,0 +1,25 @@
+import { type MaybePromise } from "./types";
+export interface MemoizedPromise<GenericValue extends unknown> {
+    readonly value: MaybePromise<GenericValue>;
+}
+/**
+ * The memoPromise() function lazily evaluates a function that returns a value or a promise, then memoizes the resolved result.
+ * 
+ * Signature: `memoPromise(theFunction)` → returns a memoized object
+ * 
+ * The input function is called only once, and concurrent reads share the same promise.
+ * 
+ * ```ts
+ * const memoizedValue = memoPromise(() => "ready");
+ * const first = await memoizedValue.value;
+ * // "ready"
+ * 
+ * const memoizedPromise = memoPromise(() => Promise.resolve("ok"));
+ * const okValue = await memoizedPromise.value;
+ * // "ok"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/memoPromise
+ * 
+ */
+export declare function memoPromise<GenericOutput extends unknown>(theFunction: () => MaybePromise<GenericOutput>): MemoizedPromise<GenericOutput>;

package/dist/common/memoPromise.mjs

@@ -0,0 +1,33 @@
+import { createExternalPromise } from './externalPromise.mjs';
+import { forward } from './forward.mjs';
+
+/**
+ * {@include common/memoPromise/index.md}
+ */
+function memoPromise(theFunction) {
+    let externalPromise = forward(undefined);
+    const payload = {
+        get value() {
+            if (externalPromise) {
+                return externalPromise.promise;
+            }
+            externalPromise = createExternalPromise();
+            const { resolve, reject } = externalPromise;
+            const promise = theFunction();
+            void (promise instanceof Promise
+                ? promise
+                : Promise.resolve(promise))
+                .then((result) => {
+                Object.defineProperty(payload, "value", {
+                    value: result,
+                });
+                resolve(result);
+            })
+                .catch(reject);
+            return externalPromise.promise;
+        },
+    };
+    return payload;
+}
+
+export { memoPromise };

package/dist/common/path.cjs

@@ -78,9 +78,7 @@ exports.Path = void 0;
                 clearedPath = segment;
                 continue;
             }
-            const formattedSegment = segment
-                .replace(Path.segmentTrailingRegex, "")
-                .replace(Path.segmentRelativeRegex, "");
+            const formattedSegment = fix(segment);
             if (formattedSegment.startsWith("/")) {
                 clearedPath = formattedSegment;
                 continue;
@@ -111,4 +109,13 @@ exports.Path = void 0;
         return `${dotResult.join("/")}/${result.join("/")}`;
     }
     Path.resolveRelative = resolveRelative;
+    /**
+     * {@include common/path/fix/index.md}
+     */
+    function fix(path) {
+        return path
+            .replace(Path.segmentTrailingRegex, "")
+            .replace(Path.segmentRelativeRegex, "");
+    }
+    Path.fix = fix;
 })(exports.Path || (exports.Path = {}));

package/dist/common/path.d.ts

@@ -142,4 +142,25 @@ export declare namespace Path {
      * 
      */
     function resolveRelative<GenericSegment extends string>(segments: AnyTuple<GenericSegment>): string;
+    /**
+     * Cleans a POSIX path by removing a trailing slash and a leading `./` prefix.
+     * 
+     * **Supported call styles:**
+     * - Classic: `fix(path)` -> returns a cleaned path
+     * 
+     * The function does not resolve `..` segments and only removes a single trailing slash and a single leading `./`.
+     * 
+     * ```ts
+     * const trimmedTrailing = Path.fix("alpha/beta/");
+     * // trimmedTrailing: "alpha/beta"
+     * const trimmedRelative = Path.fix("./alpha/beta");
+     * // trimmedRelative: "alpha/beta"
+     * const cleanedBoth = Path.fix("./alpha/");
+     * // cleanedBoth: "alpha"
+     * ```
+     * 
+     * @see https://utils.duplojs.dev/en/v1/api/common/path/fix
+     * 
+     */
+    function fix(path: string): string;
 }

package/dist/common/path.mjs

@@ -76,9 +76,7 @@ var Path;
                 clearedPath = segment;
                 continue;
             }
-            const formattedSegment = segment
-                .replace(Path.segmentTrailingRegex, "")
-                .replace(Path.segmentRelativeRegex, "");
+            const formattedSegment = fix(segment);
             if (formattedSegment.startsWith("/")) {
                 clearedPath = formattedSegment;
                 continue;
@@ -109,6 +107,15 @@ var Path;
         return `${dotResult.join("/")}/${result.join("/")}`;
     }
     Path.resolveRelative = resolveRelative;
+    /**
+     * {@include common/path/fix/index.md}
+     */
+    function fix(path) {
+        return path
+            .replace(Path.segmentTrailingRegex, "")
+            .replace(Path.segmentRelativeRegex, "");
+    }
+    Path.fix = fix;
 })(Path || (Path = {}));
 
 export { Path };

package/dist/common/unwrapGroup.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var unwrap = require('./unwrap.cjs');
+
+/**
+ * {@include common/unwrapGroup/index.md}
+ */
+function unwrapGroup(group) {
+    const result = {};
+    for (const key in group) {
+        result[key] = unwrap.unwrap(group[key]);
+    }
+    return result;
+}
+
+exports.unwrapGroup = unwrapGroup;

package/dist/common/unwrapGroup.d.ts

@@ -0,0 +1,36 @@
+import { type SimplifyTopLevel } from "./types";
+import { type Unwrap } from "./unwrap";
+type ComputeResult<GenericGroup extends Record<string, unknown>> = SimplifyTopLevel<{
+    [Prop in keyof GenericGroup]: Unwrap<GenericGroup[Prop]>;
+}>;
+/**
+ * The unwrapGroup() function unwraps every value of an object using unwrap(), returning a new object with the same keys.
+ * 
+ * Signature: `unwrapGroup(group)` → returns an object
+ * 
+ * The input object is not mutated.
+ * 
+ * ```ts
+ * const first = unwrapGroup({
+ * 	value: wrapValue(1),
+ * });
+ * // { value: 1 }
+ * 
+ * const mixed = unwrapGroup({
+ * 	count: wrapValue(2),
+ * 	label: "ok",
+ * });
+ * // { count: 2, label: "ok" }
+ * 
+ * const user = unwrapGroup({
+ * 	firstName: wrapValue("Ada"),
+ * 	lastName: "Lovelace",
+ * });
+ * // { firstName: "Ada", lastName: "Lovelace" }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/unwrapGroup
+ * 
+ */
+export declare function unwrapGroup<const GenericGroup extends Record<string, unknown>>(group: GenericGroup): ComputeResult<GenericGroup>;
+export {};

package/dist/common/unwrapGroup.mjs

@@ -0,0 +1,14 @@
+import { unwrap } from './unwrap.mjs';
+
+/**
+ * {@include common/unwrapGroup/index.md}
+ */
+function unwrapGroup(group) {
+    const result = {};
+    for (const key in group) {
+        result[key] = unwrap(group[key]);
+    }
+    return result;
+}
+
+export { unwrapGroup };

package/dist/either/left/fail.d.ts

@@ -5,7 +5,7 @@ export declare const failKind: import("../../common/kind").KindHandler<import(".
  * @deprecated use failKind
  */
 export declare const eitherFailKind: import("../../common/kind").KindHandler<import("../../common/kind").KindDefinition<"@DuplojsUtilsEither/fail", unknown>>;
-type _Fail = (Left<"fail", never> & Kind<typeof failKind.definition>);
+type _Fail = (Left<"fail", void> & Kind<typeof failKind.definition>);
 export interface Fail extends _Fail {
 }
 /**
@@ -13,7 +13,7 @@ export interface Fail extends _Fail {
  */
 export type EitherFail = Fail;
 /**
- * Returns an Left<"fail", never>: perfect to signal a failure without carrying extra data.
+ * Returns an Left<"fail", void>: perfect to signal a failure without carrying extra data.
  * 
  * Signature: `fail()` → returns a value
  * 

package/dist/either/right/ok.d.ts

@@ -5,7 +5,7 @@ export declare const okKind: import("../../common/kind").KindHandler<import("../
  * @deprecated use okKind
  */
 export declare const eitherOkKind: import("../../common/kind").KindHandler<import("../../common/kind").KindDefinition<"@DuplojsUtilsEither/ok", unknown>>;
-type _Ok = (Right<"ok", never> & Kind<typeof okKind.definition>);
+type _Ok = (Right<"ok", void> & Kind<typeof okKind.definition>);
 export interface Ok extends _Ok {
 }
 /**
@@ -13,7 +13,7 @@ export interface Ok extends _Ok {
  */
 export type EitherOk = Ok;
 /**
- * Returns an Right<"ok", never>: an empty success that confirms an operation went fine without extra data.
+ * Returns an Right<"ok", void>: an empty success that confirms an operation went fine without extra data.
  * 
  * Signature: `ok()` → returns a value
  * 

package/dist/index.cjs

@@ -31,6 +31,7 @@ var toJSON = require('./common/toJSON.cjs');
 var toTransform = require('./common/toTransform.cjs');
 var toWrappedValue = require('./common/toWrappedValue.cjs');
 var unwrap = require('./common/unwrap.cjs');
+var unwrapGroup = require('./common/unwrapGroup.cjs');
 var asyncLoop = require('./common/asyncLoop.cjs');
 var asyncRetry = require('./common/asyncRetry.cjs');
 var wrapValue = require('./common/wrapValue.cjs');
@@ -48,6 +49,7 @@ var or = require('./common/or.cjs');
 var whenElse = require('./common/whenElse.cjs');
 var justReturn = require('./common/justReturn.cjs');
 var memo = require('./common/memo.cjs');
+var memoPromise = require('./common/memoPromise.cjs');
 var instanceOf = require('./common/instanceOf.cjs');
 var globalStore = require('./common/globalStore.cjs');
 var builder = require('./common/builder.cjs');
@@ -115,6 +117,7 @@ exports.toJSON = toJSON.toJSON;
 exports.toTransform = toTransform.toTransform;
 exports.toWrappedValue = toWrappedValue.toWrappedValue;
 exports.unwrap = unwrap.unwrap;
+exports.unwrapGroup = unwrapGroup.unwrapGroup;
 exports.asyncLoop = asyncLoop.asyncLoop;
 exports.createAsyncRetry = asyncRetry.createAsyncRetry;
 exports.useAsyncRetry = asyncRetry.useAsyncRetry;
@@ -136,6 +139,7 @@ exports.or = or.or;
 exports.whenElse = whenElse.whenElse;
 exports.justReturn = justReturn.justReturn;
 exports.memo = memo.memo;
+exports.memoPromise = memoPromise.memoPromise;
 exports.instanceOf = instanceOf.instanceOf;
 exports.createGlobalStore = globalStore.createGlobalStore;
 exports.MissingBuilderMethodsError = builder.MissingBuilderMethodsError;

package/dist/index.mjs

@@ -53,6 +53,7 @@ export { toJSON } from './common/toJSON.mjs';
 export { toTransform } from './common/toTransform.mjs';
 export { toWrappedValue } from './common/toWrappedValue.mjs';
 export { unwrap } from './common/unwrap.mjs';
+export { unwrapGroup } from './common/unwrapGroup.mjs';
 export { asyncLoop } from './common/asyncLoop.mjs';
 export { createAsyncRetry, useAsyncRetry } from './common/asyncRetry.mjs';
 export { isRuntimeWrappedValueKey, isWrappedValue, keyWrappedValue, wrapValue } from './common/wrapValue.mjs';
@@ -70,6 +71,7 @@ export { or } from './common/or.mjs';
 export { whenElse } from './common/whenElse.mjs';
 export { justReturn } from './common/justReturn.mjs';
 export { memo } from './common/memo.mjs';
+export { memoPromise } from './common/memoPromise.mjs';
 export { instanceOf } from './common/instanceOf.mjs';
 export { createGlobalStore } from './common/globalStore.mjs';
 export { MissingBuilderMethodsError, builderKind, createBuilder } from './common/builder.mjs';

package/dist/metadata.json

@@ -1415,6 +1415,15 @@
         {
           "name": "memo.mjs"
         },
+        {
+          "name": "memoPromise.cjs"
+        },
+        {
+          "name": "memoPromise.d.ts"
+        },
+        {
+          "name": "memoPromise.mjs"
+        },
         {
           "name": "mimeType.cjs"
         },
@@ -1577,6 +1586,15 @@
         {
           "name": "unwrap.mjs"
         },
+        {
+          "name": "unwrapGroup.cjs"
+        },
+        {
+          "name": "unwrapGroup.d.ts"
+        },
+        {
+          "name": "unwrapGroup.mjs"
+        },
         {
           "name": "when.cjs"
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duplojs/utils",
-  "version": "1.4.49",
+  "version": "1.4.51",
   "author": {
     "name": "mathcovax",
     "url": "https://github.com/mathcovax"
@@ -27,8 +27,8 @@
     "test:tu:watch": "vitest --coverage --watch",
     "test:tu:update": "vitest --coverage --update",
     "test:types": "tsc -p tsconfig.test.json && npm -w docs run test:types",
-    "test:lint": "eslint",
-    "test:lint:fix": "eslint --fix",
+    "test:lint": "eslint --quiet",
+    "test:lint:fix": "eslint --fix --quiet",
     "prepare": "husky"
   },
   "sideEffects": false,