@duplojs/utils 1.6.1 → 1.6.3

package/dist/flow/throttling.d.ts

@@ -0,0 +1,60 @@
+import { type OnlyLiteralBoolean, type IsEqual } from "../common";
+import { type Throttling } from "./theFlow";
+/**
+ * Throttles repeated runs of the same flow and can return a fallback value when a run happens too early.
+ * 
+ * **Supported call styles:**
+ * - Classic: `throttling(time)` -> yields a throttling effect
+ * - Classic with options: `throttling(time, params)` -> yields a throttling effect with a fallback return value and optional `keepLast`
+ * 
+ * `throttling` lets the runner decide whether the current run should continue or stop early depending on the previous execution time of the same flow.
+ * When a run happens inside the throttling window, the runner can return `params.returnValue`.
+ * With `keepLast: true`, the runner keeps the last skipped async run and resumes it after the delay.
+ * 
+ * ```ts
+ * const searchFlow = F.create(
+ * 	function *(query: string) {
+ * 		yield *F.throttling(
+ * 			300,
+ * 			{ returnValue: "skipped" as const },
+ * 		);
+ * 		return query;
+ * 	},
+ * );
+ * const runSearch = F.toFunction(searchFlow);
+ * 
+ * runSearch("first"); // "first"
+ * 
+ * runSearch("second"); // "skipped"
+ * 
+ * const latestFlow = F.create(
+ * 	async function *(value: string) {
+ * 		yield *F.throttling(
+ * 			500,
+ * 			{
+ * 				returnValue: "ignored" as const,
+ * 				keepLast: true,
+ * 			},
+ * 		);
+ * 		return Promise.resolve(value);
+ * 	},
+ * );
+ * const runLatestFlow = F.toFunction(latestFlow);
+ * await runLatestFlow("latest"); // Promise<"latest" | "ignored">
+ * ```
+ * 
+ * @remarks
+ * - `keepLast: true` changes the helper to an async generator because the runner may resume the latest skipped run later
+ * - Throttling state is attached to the flow reference, so examples should reuse the same created flow or wrapped function
+ * - If the same flow execution yields `throttling(...)` multiple times, only the first yielded effect is applied by the runner
+ * 
+ * @see [`F.run`](https://utils.duplojs.dev/en/v1/api/flow/run) For the throttling behavior implemented by the runner
+ * @see https://utils.duplojs.dev/en/v1/api/flow/throttling
+ * 
+ * @namespace F
+ * 
+ */
+export declare function throttling<GenericValue extends unknown = undefined, GenericKeepLast extends boolean = false>(time: number, params?: {
+    returnValue?: GenericValue;
+    keepLast?: GenericKeepLast & OnlyLiteralBoolean<GenericKeepLast>;
+}): IsEqual<GenericKeepLast, true> extends true ? AsyncGenerator<Throttling<NoInfer<GenericValue>>, undefined> : Generator<Throttling<NoInfer<GenericValue>>, undefined>;

package/dist/flow/throttling.mjs

@@ -0,0 +1,25 @@
+import { createThrottling } from './theFlow/throttling.mjs';
+
+/**
+ * {@include flow/throttling/index.md}
+ */
+function throttling(time, params) {
+    if (params?.keepLast === true) {
+        return (async function* () {
+            yield createThrottling({
+                time,
+                returnValue: params?.returnValue,
+                keepLast: true,
+            });
+        })();
+    }
+    return (function* () {
+        yield createThrottling({
+            time,
+            returnValue: params?.returnValue,
+            keepLast: false,
+        });
+    })();
+}
+
+export { throttling };

package/dist/flow/toFunction.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+var run = require('./run.cjs');
+
+/**
+ * {@include flow/toFunction/index.md}
+ */
+function toFunction(flow, ...[params]) {
+    return (input) => run.run(flow, {
+        ...params,
+        input,
+    });
+}
+
+exports.toFunction = toFunction;

package/dist/flow/toFunction.d.ts

@@ -0,0 +1,56 @@
+import { type SimplifyTopLevel, type IsEqual } from "../common";
+import { type RunResult } from "./run";
+import { type WrapFlow, type TheFlow, type TheFlowFunction, type FlowDependencies, type TheFlowGenerator } from "./theFlow";
+type ComputeToFunctionParams<GenericDependencies extends Record<string, unknown> = Record<string, unknown>> = SimplifyTopLevel<{
+    includeDetails?: boolean;
+} & ({} extends GenericDependencies ? {
+    dependencies?: GenericDependencies;
+} : {
+    dependencies: GenericDependencies;
+})>;
+/**
+ * Converts a flow into a plain callable function that delegates to `F.run(...)`.
+ * 
+ * **Supported call styles:**
+ * - Classic with a flow function: `toFunction(flow, params?)` -> returns a callable function
+ * - Classic with a flow instance: `toFunction(flow, params?)` -> returns a callable function
+ * 
+ * `toFunction` wraps a flow function or a flow created with `F.create(...)` and returns a regular function that accepts only the flow input.
+ * The provided options are forwarded to `F.run(...)`, which means you can preconfigure `includeDetails` and `dependencies`.
+ * Use it when a flow should be exposed as a reusable application function instead of being run manually each time.
+ * 
+ * ```ts
+ * const runUppercase = F.toFunction(
+ * 	function *(input: string) {
+ * 		yield *F.step("uppercase");
+ * 		return input.toUpperCase();
+ * 	},
+ * );
+ * runUppercase("duplo"); // "DUPLO"
+ * 
+ * const runWithDetails = F.toFunction(
+ * 	function *(input: string) {
+ * 		yield *F.step("format");
+ * 		return input.length;
+ * 	},
+ * 	{ includeDetails: true },
+ * );
+ * runWithDetails("hello"); // { result: 5, steps: ["format"] }
+ * 
+ * const service = F.createDependence("service")<string>;
+ * const runWithDependencies = F.toFunction(
+ * 	function *(input: string) {
+ * 		const currentService = yield *F.inject(service);
+ * ```
+ * 
+ * @remarks
+ * - `toFunction` keeps the same sync or async return shape as `F.run(...)` for the wrapped flow
+ * 
+ * @see [`F.run`](https://utils.duplojs.dev/en/v1/api/flow/run) For the execution behavior used internally
+ * @see https://utils.duplojs.dev/en/v1/api/flow/toFunction
+ * 
+ * @namespace F
+ * 
+ */
+export declare function toFunction<GenericInput extends unknown, GenericOutput extends TheFlowGenerator, GenericWrapFlow extends WrapFlow<TheFlowFunction<GenericInput, GenericOutput>>, const GenericParams extends ComputeToFunctionParams<FlowDependencies<GenericWrapFlow>>>(flow: (TheFlowFunction<GenericInput, GenericOutput> | TheFlow<TheFlowFunction<GenericInput, GenericOutput>>), ...[params]: ({} extends GenericParams ? [params?: GenericParams] : [params: GenericParams])): (input: GenericInput) => RunResult<GenericWrapFlow, IsEqual<GenericParams["includeDetails"], true>>;
+export {};

package/dist/flow/toFunction.mjs

@@ -0,0 +1,13 @@
+import { run } from './run.mjs';
+
+/**
+ * {@include flow/toFunction/index.md}
+ */
+function toFunction(flow, ...[params]) {
+    return (input) => run(flow, {
+        ...params,
+        input,
+    });
+}
+
+export { toFunction };

package/dist/index.cjs

@@ -67,6 +67,9 @@ var path = require('./common/path.cjs');
 var transformer = require('./common/transformer.cjs');
 var toRegExp = require('./common/toRegExp.cjs');
 var justExec = require('./common/justExec.cjs');
+var callThen = require('./common/callThen.cjs');
+var queue = require('./common/queue.cjs');
+var printer = require('./common/printer.cjs');
 
 
 
@@ -160,6 +163,7 @@ exports.toCurriedPredicate = toCurriedPredicate.toCurriedPredicate;
 exports.pipeCall = pipeCall.pipeCall;
 exports.AssertsError = asserts.AssertsError;
 exports.asserts = asserts.asserts;
+exports.forwardAsserts = asserts.forwardAsserts;
 Object.defineProperty(exports, "Path", {
 	enumerable: true,
 	get: function () { return path.Path; }
@@ -170,3 +174,10 @@ exports.toNative = transformer.toNative;
 exports.transformer = transformer.transformer;
 exports.toRegExp = toRegExp.toRegExp;
 exports.justExec = justExec.justExec;
+exports.callThen = callThen.callThen;
+exports.createQueue = queue.createQueue;
+exports.queueKind = queue.queueKind;
+Object.defineProperty(exports, "Printer", {
+	enumerable: true,
+	get: function () { return printer.Printer; }
+});

package/dist/index.mjs

@@ -86,8 +86,11 @@ export { hasSomeKinds } from './common/hasSomeKinds.mjs';
 export { hasKinds } from './common/hasKinds.mjs';
 export { toCurriedPredicate } from './common/toCurriedPredicate.mjs';
 export { pipeCall } from './common/pipeCall.mjs';
-export { AssertsError, asserts } from './common/asserts.mjs';
+export { AssertsError, asserts, forwardAsserts } from './common/asserts.mjs';
 export { Path } from './common/path.mjs';
 export { createTransformer, toJSON, toNative, transformer } from './common/transformer.mjs';
 export { toRegExp } from './common/toRegExp.mjs';
 export { justExec } from './common/justExec.mjs';
+export { callThen } from './common/callThen.mjs';
+export { createQueue, queueKind } from './common/queue.mjs';
+export { Printer } from './common/printer.mjs';

package/dist/metadata.json

@@ -645,6 +645,15 @@
             {
               "name": "base.mjs"
             },
+            {
+              "name": "cast.cjs"
+            },
+            {
+              "name": "cast.d.ts"
+            },
+            {
+              "name": "cast.mjs"
+            },
             {
               "name": "index.d.ts"
             },
@@ -1038,6 +1047,15 @@
         {
           "name": "repository.mjs"
         },
+        {
+          "name": "toMapDataParser.cjs"
+        },
+        {
+          "name": "toMapDataParser.d.ts"
+        },
+        {
+          "name": "toMapDataParser.mjs"
+        },
         {
           "name": "useCase.cjs"
         },
@@ -1279,6 +1297,15 @@
         {
           "name": "builder.mjs"
         },
+        {
+          "name": "callThen.cjs"
+        },
+        {
+          "name": "callThen.d.ts"
+        },
+        {
+          "name": "callThen.mjs"
+        },
         {
           "name": "clone.cjs"
         },
@@ -1552,6 +1579,15 @@
         {
           "name": "pipeCall.mjs"
         },
+        {
+          "name": "printer.cjs"
+        },
+        {
+          "name": "printer.d.ts"
+        },
+        {
+          "name": "printer.mjs"
+        },
         {
           "name": "promiseObject.cjs"
         },
@@ -1561,6 +1597,15 @@
         {
           "name": "promiseObject.mjs"
         },
+        {
+          "name": "queue.cjs"
+        },
+        {
+          "name": "queue.d.ts"
+        },
+        {
+          "name": "queue.mjs"
+        },
         {
           "name": "simpleClone.cjs"
         },
@@ -3917,6 +3962,24 @@
             {
               "name": "break.mjs"
             },
+            {
+              "name": "calledByNext.cjs"
+            },
+            {
+              "name": "calledByNext.d.ts"
+            },
+            {
+              "name": "calledByNext.mjs"
+            },
+            {
+              "name": "debounce.cjs"
+            },
+            {
+              "name": "debounce.d.ts"
+            },
+            {
+              "name": "debounce.mjs"
+            },
             {
               "name": "defer.cjs"
             },
@@ -3971,6 +4034,15 @@
             {
               "name": "injection.mjs"
             },
+            {
+              "name": "queue.cjs"
+            },
+            {
+              "name": "queue.d.ts"
+            },
+            {
+              "name": "queue.mjs"
+            },
             {
               "name": "step.cjs"
             },
@@ -3979,6 +4051,15 @@
             },
             {
               "name": "step.mjs"
+            },
+            {
+              "name": "throttling.cjs"
+            },
+            {
+              "name": "throttling.d.ts"
+            },
+            {
+              "name": "throttling.mjs"
             }
           ]
         },
@@ -3999,6 +4080,24 @@
         {
           "name": "breakIf.mjs"
         },
+        {
+          "name": "calledByNext.cjs"
+        },
+        {
+          "name": "calledByNext.d.ts"
+        },
+        {
+          "name": "calledByNext.mjs"
+        },
+        {
+          "name": "debounce.cjs"
+        },
+        {
+          "name": "debounce.d.ts"
+        },
+        {
+          "name": "debounce.mjs"
+        },
         {
           "name": "defer.cjs"
         },
@@ -4071,6 +4170,15 @@
         {
           "name": "kind.mjs"
         },
+        {
+          "name": "queue.cjs"
+        },
+        {
+          "name": "queue.d.ts"
+        },
+        {
+          "name": "queue.mjs"
+        },
         {
           "name": "run.cjs"
         },
@@ -4088,6 +4196,24 @@
         },
         {
           "name": "step.mjs"
+        },
+        {
+          "name": "throttling.cjs"
+        },
+        {
+          "name": "throttling.d.ts"
+        },
+        {
+          "name": "throttling.mjs"
+        },
+        {
+          "name": "toFunction.cjs"
+        },
+        {
+          "name": "toFunction.d.ts"
+        },
+        {
+          "name": "toFunction.mjs"
         }
       ]
     },

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

@@ -25,10 +25,33 @@ type CheckIsGreater<GreaterSplitValue extends AnyTuple<DString.Digit>, GreaterTa
     infer InferredRestSplitValue extends AnyTuple<DString.Digit>,
     infer InferredRestSplitReference extends AnyTuple<FigureGreaterThanTableValue>
 ] ? CheckIsGreater<InferredRestSplitValue, InferredRestSplitReference> : never : false;
-export type IsGreater<GenericValue extends number, GenericReference extends number> = IsEqual<GenericValue, GenericReference> extends true ? true : [
-    `${GenericValue}`,
-    `${GenericReference}`
+type toStringDecimal<GenericValue extends number> = `${GenericValue}` extends `${DString.Number}.${DString.Number}` ? `${GenericValue}` : `${GenericValue}.0`;
+type PrepareValues<GenericValue extends number, GenericReference extends number> = [
+    toStringDecimal<GenericValue>,
+    toStringDecimal<GenericReference>
 ] extends [
+    `${infer InferredValueInteger extends DString.Number}.${infer InferredValueDecimals extends DString.Number}`,
+    `${infer InferredReferenceInteger extends DString.Number}.${infer InferredReferenceDecimals extends DString.Number}`
+] ? And<[
+    IsEqual<InferredValueDecimals, "0">,
+    IsEqual<InferredReferenceDecimals, "0">
+]> extends true ? [InferredValueInteger, InferredReferenceInteger] : IsEqual<InferredValueInteger, InferredReferenceInteger> extends true ? [
+    DString.Split<InferredValueDecimals, "">,
+    DString.Split<InferredReferenceDecimals, "">
+] extends [
+    infer InferredSplitValue extends AnyTuple<DString.Digit>,
+    infer InferredSplitReference extends AnyTuple<DString.Digit>
+] ? (IsEqual<InferredSplitValue["length"], InferredSplitReference["length"]> extends true ? [
+    DArray.JoinTuple<InferredSplitValue, "">,
+    DArray.JoinTuple<InferredSplitReference, "">
+] : (DArray.CreateTuple<any, InferredSplitValue["length"]> extends [...DArray.CreateTuple<any, InferredSplitReference["length"]>, ...any[]] ? InferredSplitValue["length"] : InferredSplitReference["length"]) extends infer InferredLength extends number ? [
+    DArray.JoinTuple<Extract<IsEqual<InferredLength, InferredSplitValue["length"]> extends true ? InferredSplitValue : DArray.CreateTuple<"0", InferredLength, InferredSplitValue>, AnyTuple<string>>, "">,
+    DArray.JoinTuple<Extract<IsEqual<InferredLength, InferredSplitReference["length"]> extends true ? InferredSplitReference : DArray.CreateTuple<"0", InferredLength, InferredSplitReference>, AnyTuple<string>>, "">
+] : never) extends [
+    `${infer InferredResultValue}`,
+    `${infer InferredResultReference}`
+] ? [`${InferredResultValue}`, `${InferredResultReference}`] : never : never : [InferredValueInteger, InferredReferenceInteger] : never;
+export type IsGreater<GenericValue extends number, GenericReference extends number> = IsEqual<GenericValue, GenericReference> extends true ? true : PrepareValues<GenericValue, GenericReference> extends [
     infer InferredValue extends DString.Number,
     infer InferredReference extends DString.Number
 ] ? And<[

package/dist/object/types/getPropsWithValue.d.ts

@@ -1,4 +1,4 @@
 import { type IsEqual } from "../../common";
 export type GetPropsWithValue<GenericObject extends object, GenericValue extends unknown> = {
-    [Prop in keyof GenericObject]: IsEqual<GenericObject[Prop], GenericValue> extends true ? Prop : never;
+    [Prop in keyof GenericObject]-?: IsEqual<GenericObject[Prop], GenericValue> extends true ? Prop : never;
 }[keyof GenericObject];

package/dist/object/types/getPropsWithValueExtends.d.ts

@@ -1,3 +1,3 @@
 export type GetPropsWithValueExtends<GenericObject extends object, GenericValue extends unknown> = {
-    [Prop in keyof GenericObject]: GenericObject[Prop] extends infer InferredValue ? InferredValue extends GenericValue ? Prop : never : never;
+    [Prop in keyof GenericObject]-?: GenericObject[Prop] extends infer InferredValue ? InferredValue extends GenericValue ? Prop : never : never;
 }[keyof GenericObject];

package/dist/string/length.d.ts

@@ -1,4 +1,4 @@
-import { type StringLength } from "./types/stringLength";
+import { type TemplateLiteralContainLargeType, type StringLength } from "./types";
 /**
  * Returns the length of a string.
  * 
@@ -23,4 +23,4 @@ import { type StringLength } from "./types/stringLength";
  * @namespace S
  * 
  */
-export declare function length<GenericInput extends string>(input: GenericInput): StringLength<GenericInput>;
+export declare function length<GenericInput extends string>(input: GenericInput): TemplateLiteralContainLargeType<GenericInput> extends true ? number : StringLength<GenericInput>;

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

@@ -1,9 +1,10 @@
-import { type Or, type IsEqual } from "../../common";
+import { type IsEqual } from "../../common";
 import { type Includes } from "./includes";
 import { type TemplateLiteralContainLargeType } from "./templateLiteralContainLargeType";
+import { type CreateTuple } from "../../array";
 type _Split<GenericString extends string, GenericSeparator extends string, GenericLimit extends number = number, GenericLastResult extends 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];
-export type Split<GenericString extends string, GenericSeparator extends string, GenericLimit extends number = number> = IsEqual<GenericLimit, 0> extends true ? [] : Or<[
-    TemplateLiteralContainLargeType<GenericString>,
-    TemplateLiteralContainLargeType<GenericSeparator>
-]> extends true ? [string, ...string[]] : _Split<GenericString, GenericSeparator, GenericLimit>;
+export type Split<GenericString extends string, GenericSeparator extends string, GenericLimit extends number = number> = IsEqual<GenericLimit, 0> extends true ? [] : TemplateLiteralContainLargeType<GenericSeparator> extends true ? [string, ...string[]] : TemplateLiteralContainLargeType<GenericString> extends true ? [
+    ...CreateTuple<string, _Split<GenericString, GenericSeparator, GenericLimit>["length"]>,
+    ...string[]
+] : _Split<GenericString, GenericSeparator, GenericLimit>;
 export {};

package/package.json

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