@duplojs/utils 1.4.32 → 1.4.33

package/dist/number/max.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/max/index.md}
+ */
 function max(input) {
     return Math.max(...input);
 }

package/dist/number/min.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/min/index.md}
+ */
 function min(input) {
     return Math.min(...input);
 }

package/dist/number/min.d.ts

@@ -1,2 +1,28 @@
 import { type AnyTuple } from "../common";
+/**
+ * Returns the smallest value in a number tuple.
+ * 
+ * Signature: `min(tuple)` → returns a number
+ * 
+ * ```ts
+ * N.min([1, 5, 2]); // 1
+ * 
+ * pipe(
+ * 	<const>[-1, -3],
+ * 	N.min,
+ * ); // -3
+ * 
+ * N.min([0]); // 0
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min)
+ * 
+ * @see [`N.max`](https://utils.duplojs.dev/en/v1/api/number/max) For the maximum value
+ * @see https://utils.duplojs.dev/en/v1/api/number/min
+ * 
+ * @namespace N
+ * 
+ */
 export declare function min<GenericInput extends AnyTuple<number>>(input: GenericInput): number;

package/dist/number/min.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/min/index.md}
+ */
 function min(input) {
     return Math.min(...input);
 }

package/dist/number/modulo.d.ts

@@ -1,2 +1,32 @@
+/**
+ * Computes the remainder of a division.
+ * 
+ * **Supported call styles:**
+ * - Classic: `modulo(value, operand)` → returns a number
+ * - Curried: `modulo(operand)` → returns a function waiting for the value
+ * 
+ * ```ts
+ * N.modulo(
+ * 	10,
+ * 	3,
+ * ); // 1
+ * 
+ * pipe(
+ * 	10,
+ * 	N.modulo(4),
+ * ); // 2
+ * 
+ * N.modulo(
+ * 	7,
+ * 	2,
+ * ); // 1
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/modulo
+ * 
+ * @namespace N
+ * 
+ */
 export declare function modulo<GenericValue extends number>(divisor: number): (value: GenericValue) => number;
 export declare function modulo<GenericValue extends number>(value: GenericValue, divisor: number): number;

package/dist/number/multiply.d.ts

@@ -1,2 +1,32 @@
+/**
+ * Multiplies two numbers.
+ * 
+ * **Supported call styles:**
+ * - Classic: `multiply(value, operand)` → returns a number
+ * - Curried: `multiply(operand)` → returns a function waiting for the value
+ * 
+ * ```ts
+ * N.multiply(
+ * 	3,
+ * 	4,
+ * ); // 12
+ * 
+ * pipe(
+ * 	3,
+ * 	N.multiply(2),
+ * ); // 6
+ * 
+ * N.multiply(
+ * 	-2,
+ * 	5,
+ * ); // -10
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/multiply
+ * 
+ * @namespace N
+ * 
+ */
 export declare function multiply<GenericValue extends number>(operand: number): (value: GenericValue) => number;
 export declare function multiply<GenericValue extends number>(value: GenericValue, operand: number): number;

package/dist/number/negate.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/negate/index.md}
+ */
 function negate(value) {
     return -value;
 }

package/dist/number/negate.d.ts

@@ -1 +1,26 @@
+/**
+ * Negates a number.
+ * 
+ * Signature: `negate(value)` → returns a number
+ * 
+ * ```ts
+ * N.negate(5); // -5
+ * 
+ * pipe(
+ * 	-3,
+ * 	N.negate,
+ * ); // 3
+ * 
+ * N.negate(0); // 0
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Equivalent to multiplying the number by `-1`
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/negate
+ * 
+ * @namespace N
+ * 
+ */
 export declare function negate<GenericValue extends number>(value: GenericValue): number;

package/dist/number/negate.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/negate/index.md}
+ */
 function negate(value) {
     return -value;
 }

package/dist/number/power.d.ts

@@ -1,2 +1,32 @@
+/**
+ * Raises a number to a given exponent.
+ * 
+ * **Supported call styles:**
+ * - Classic: `power(value, operand)` → returns a number
+ * - Curried: `power(operand)` → returns a function waiting for the value
+ * 
+ * ```ts
+ * N.power(
+ * 	2,
+ * 	3,
+ * ); // 8
+ * 
+ * pipe(
+ * 	3,
+ * 	N.power(2),
+ * ); // 9
+ * 
+ * N.power(
+ * 	9,
+ * 	0,
+ * ); // 1
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/power
+ * 
+ * @namespace N
+ * 
+ */
 export declare function power<GenericValue extends number>(exponent: number): (value: GenericValue) => number;
 export declare function power<GenericValue extends number>(value: GenericValue, exponent: number): number;

package/dist/number/round.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/round/index.md}
+ */
 function round(value) {
     return Math.round(value);
 }

package/dist/number/round.d.ts

@@ -1 +1,28 @@
+/**
+ * Rounds a number to the nearest integer.
+ * 
+ * Signature: `round(value)` → returns a number
+ * 
+ * ```ts
+ * N.round(1.4); // 1
+ * 
+ * pipe(
+ * 	1.4,
+ * 	N.round,
+ * ); // 1
+ * 
+ * N.round(1.5); // 2
+ * 
+ * N.round(-1.6); // -2
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.round`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/round
+ * 
+ * @namespace N
+ * 
+ */
 export declare function round<GenericValue extends number>(value: GenericValue): number;

package/dist/number/round.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/round/index.md}
+ */
 function round(value) {
     return Math.round(value);
 }

package/dist/number/sin.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/sin/index.md}
+ */
 function sin(value) {
     return Math.sin(value);
 }

package/dist/number/sin.d.ts

@@ -1 +1,28 @@
+/**
+ * Returns the sine of a number (in radians).
+ * 
+ * Signature: `sin(value)` → returns a number
+ * 
+ * ```ts
+ * N.sin(0); // 0
+ * 
+ * pipe(
+ * 	0,
+ * 	N.sin,
+ * ); // 0
+ * 
+ * N.sin(Math.PI / 2); // 1
+ * 
+ * N.sin(Math.PI); // ~0
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.sin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sin)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/sin
+ * 
+ * @namespace N
+ * 
+ */
 export declare function sin<GenericValue extends number>(value: GenericValue): number;

package/dist/number/sin.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/sin/index.md}
+ */
 function sin(value) {
     return Math.sin(value);
 }

package/dist/number/sort.d.ts

@@ -1,3 +1,35 @@
 import { type SortType } from "../common";
+/**
+ * Sorts numbers in ascending or descending order.
+ * 
+ * **Supported call styles:**
+ * - Classic: `sort(array, type)` → returns a new array
+ * - Curried: `sort(type)` → returns a function waiting for the array
+ * 
+ * ```ts
+ * N.sort(
+ * 	[3, 1, 2],
+ * 	"ASC",
+ * ); // [1, 2, 3]
+ * 
+ * pipe(
+ * 	[3, 1, 2],
+ * 	N.sort("DSC"),
+ * ); // [3, 2, 1]
+ * 
+ * N.sort(
+ * 	[1, 2, 3],
+ * 	"DSC",
+ * ); // [3, 2, 1]
+ * 
+ * ```
+ * @remarks
+ * - Does not mutate the input array
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/sort
+ * 
+ * @namespace N
+ * 
+ */
 export declare function sort<GenericArray extends readonly number[]>(type: SortType): (array: GenericArray) => number[];
 export declare function sort<GenericArray extends readonly number[]>(array: GenericArray, type: SortType): number[];

package/dist/number/sqrt.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/sqrt/index.md}
+ */
 function sqrt(value) {
     return Math.sqrt(value);
 }

package/dist/number/sqrt.d.ts

@@ -1 +1,28 @@
+/**
+ * Returns the square root of a number.
+ * 
+ * Signature: `sqrt(value)` → returns a number
+ * 
+ * ```ts
+ * N.sqrt(9); // 3
+ * 
+ * pipe(
+ * 	9,
+ * 	N.sqrt,
+ * ); // 3
+ * 
+ * N.sqrt(2); // ~1.414
+ * 
+ * N.sqrt(0); // 0
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.sqrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sqrt)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/sqrt
+ * 
+ * @namespace N
+ * 
+ */
 export declare function sqrt<GenericValue extends number>(value: GenericValue): number;

package/dist/number/sqrt.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/sqrt/index.md}
+ */
 function sqrt(value) {
     return Math.sqrt(value);
 }

package/dist/number/subtract.d.ts

@@ -1,2 +1,32 @@
+/**
+ * Subtracts a number from another.
+ * 
+ * **Supported call styles:**
+ * - Classic: `subtract(value, operand)` → returns a number
+ * - Curried: `subtract(operand)` → returns a function waiting for the value
+ * 
+ * ```ts
+ * N.subtract(
+ * 	10,
+ * 	3,
+ * ); // 7
+ * 
+ * pipe(
+ * 	10,
+ * 	N.subtract(2),
+ * ); // 8
+ * 
+ * N.subtract(
+ * 	5,
+ * 	8,
+ * ); // -3
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/subtract
+ * 
+ * @namespace N
+ * 
+ */
 export declare function subtract<GenericValue extends number>(subtrahend: number): (value: GenericValue) => number;
 export declare function subtract<GenericValue extends number>(value: GenericValue, subtrahend: number): number;

package/dist/number/tan.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/tan/index.md}
+ */
 function tan(value) {
     return Math.tan(value);
 }

package/dist/number/tan.d.ts

@@ -1 +1,28 @@
+/**
+ * Returns the tangent of a number (in radians).
+ * 
+ * Signature: `tan(value)` → returns a number
+ * 
+ * ```ts
+ * N.tan(0); // 0
+ * 
+ * pipe(
+ * 	0,
+ * 	N.tan,
+ * ); // 0
+ * 
+ * N.tan(Math.PI / 4); // 1
+ * 
+ * N.tan(1); // ~1.557
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.tan`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/tan)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/tan
+ * 
+ * @namespace N
+ * 
+ */
 export declare function tan<GenericValue extends number>(value: GenericValue): number;

package/dist/number/tan.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/tan/index.md}
+ */
 function tan(value) {
     return Math.tan(value);
 }

package/dist/number/toFixed.d.ts

@@ -1,2 +1,35 @@
+/**
+ * Formats a number using fixed-point notation.
+ * 
+ * **Supported call styles:**
+ * - Classic: `toFixed(value, digits)` → returns a string
+ * - Curried: `toFixed(digits)` → returns a function waiting for the value
+ * 
+ * ```ts
+ * N.toFixed(
+ * 	3.1415,
+ * 	2,
+ * ); // "3.14"
+ * 
+ * pipe(
+ * 	3.1415,
+ * 	N.toFixed(1),
+ * ); // "3.1"
+ * 
+ * N.toFixed(
+ * 	10,
+ * 	0,
+ * ); // "10"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Number.prototype.toFixed`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/toFixed
+ * 
+ * @namespace N
+ * 
+ */
 export declare function toFixed<GenericValue extends number>(digits: number): (value: GenericValue) => string;
 export declare function toFixed<GenericValue extends number>(value: GenericValue, digits: number): string;

package/dist/number/trunc.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/trunc/index.md}
+ */
 function trunc(value) {
     return Math.trunc(value);
 }

package/dist/number/trunc.d.ts

@@ -1 +1,28 @@
+/**
+ * Removes the fractional part of a number.
+ * 
+ * Signature: `trunc(value)` → returns a number
+ * 
+ * ```ts
+ * N.trunc(1.9); // 1
+ * 
+ * pipe(
+ * 	1.9,
+ * 	N.trunc,
+ * ); // 1
+ * 
+ * N.trunc(-1.9); // -1
+ * 
+ * N.trunc(2.0); // 2
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/trunc
+ * 
+ * @namespace N
+ * 
+ */
 export declare function trunc<GenericValue extends number>(value: GenericValue): number;

package/dist/number/trunc.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/trunc/index.md}
+ */
 function trunc(value) {
     return Math.trunc(value);
 }

package/dist/object/assign.d.ts

@@ -1,4 +1,44 @@
 import { type AnyObject } from "../common/types/anyObject";
 import { type AssignObjects } from "./types";
+/**
+ * Assigns properties from one object to another.
+ * 
+ * **Supported call styles:**
+ * - Classic: `assign(input, value)` → returns a new object
+ * - Curried: `assign(value)` → returns a function waiting for the input
+ * 
+ * The input object is not mutated.
+ * 
+ * ```ts
+ * O.assign(
+ * 	{
+ * 		name: "Alice",
+ * 		age: 30,
+ * 	},
+ * 	{
+ * 		age: 31,
+ * 		city: "Paris",
+ * 	},
+ * ); // { name: "Alice", age: 31, city: "Paris" }
+ * 
+ * pipe(
+ * 	{
+ * 		name: "William",
+ * 		age: 24,
+ * 	},
+ * 	O.assign({
+ * 		age: 25,
+ * 		role: "client",
+ * 	}),
+ * ); // // { name: "William", age: 25, role: "client" }
+ * 
+ * ```
+ * 
+ * @see [`O.override`](https://utils.duplojs.dev/en/v1/api/object/override) For skipping undefined values
+ * @see https://utils.duplojs.dev/en/v1/api/object/assign
+ * 
+ * @namespace O
+ * 
+ */
 export declare function assign<GenericInput extends object, GenericValue extends Partial<Record<keyof GenericInput, unknown>> & AnyObject>(value: GenericValue): (input: GenericInput) => AssignObjects<GenericInput, GenericValue>;
 export declare function assign<GenericInput extends object, GenericValue extends Partial<Record<keyof GenericInput, unknown>> & AnyObject>(input: GenericInput, value: GenericValue): AssignObjects<GenericInput, GenericValue>;

package/dist/object/deepDiscriminate.d.ts

@@ -2,6 +2,60 @@ import { type EligibleEqual, type MaybeArray } from "../common";
 import { type UnFlatObject, type FlatObject } from "./types";
 import { type GetPropsWithValueExtends } from "./types/getPropsWithValueExtends";
 type ObjectProjection<GenericInput extends object> = FlatObject<GenericInput> extends infer InferredResult extends object ? Omit<Pick<InferredResult, GetPropsWithValueExtends<InferredResult, EligibleEqual>>, `${string}[${string}]${string}`> : never;
+/**
+ * Checks a deep property value and narrows the object type.
+ * 
+ * **Supported call styles:**
+ * - Classic: `deepDiscriminate(input, path, value)` → returns a boolean
+ * - Curried: `deepDiscriminate(path, value)` → returns a function waiting for the input
+ * - Classic predicate: `deepDiscriminate(input, path, value)` → narrows the object type
+ * - Curried predicate: `deepDiscriminate(path, value)` → narrows the object type
+ * 
+ * The input object is not mutated.
+ * 
+ * ```ts
+ * const userObj = {
+ * 	profile: {
+ * 		status: "active",
+ * 	},
+ * };
+ * 
+ * if (O.deepDiscriminate(userObj, "profile.status", "active")) {
+ * 	// userObj is active
+ * }
+ * 
+ * pipe(
+ * 	userObj,
+ * 	when(
+ * 		O.deepDiscriminate("profile.status", "disabled"),
+ * 		(value) => {
+ * 			// value is disabled
+ * 		},
+ * 	),
+ * );
+ * 
+ * O.deepDiscriminate(
+ * 	{
+ * 		meta: {
+ * 			level: 2,
+ * 		},
+ * 	},
+ * 	"meta.level",
+ * 	[1, 2], // or
+ * ); // true
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type
+ * - The discriminated value can be an array, acting as an "or" list
+ * 
+ * @see [`O.discriminate`](https://utils.duplojs.dev/en/v1/api/object/discriminate) For top-level keys
+ * @see https://utils.duplojs.dev/en/v1/api/object/deepDiscriminate
+ * 
+ * @namespace O
+ * 
+ */
 export declare function deepDiscriminate<GenericInput extends object, GenericObjectProjection extends ObjectProjection<GenericInput>, GenericPath extends keyof GenericObjectProjection, GenericValue extends EligibleEqual>(path: GenericPath, value: (MaybeArray<(GenericValue & GenericObjectProjection[GenericPath])> | MaybeArray<GenericObjectProjection[GenericPath]>)): (input: GenericInput) => input is Extract<GenericInput, UnFlatObject<{
     [Prop in GenericPath]: GenericValue;
 }>>;