@duplojs/utils 1.4.32 → 1.4.34

package/dist/string/padStart.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Pads a string at the start to reach a target length.
+ * 
+ * **Supported call styles:**
+ * - Classic: `padStart(input, targetLength, padString)` → returns a padded string
+ * - Curried: `padStart(targetLength, padString)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.padStart("7", 3, "0"); // "007"
+ * 
+ * pipe(
+ * 	"42",
+ * 	S.padStart(4, "0"),
+ * ); // "0042"
+ * 
+ * S.padStart("abc", 5, "."); // "..abc"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.padStart`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/padStart)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/padStart
+ * 
+ * @namespace S
+ * 
+ */
 export declare function padStart<GenericInput extends string>(targetLength: number, padString: string): (input: GenericInput) => string;
 export declare function padStart<GenericInput extends string>(input: GenericInput, targetLength: number, padString: string): string;

package/dist/string/repeat.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Repeats a string a number of times.
+ * 
+ * **Supported call styles:**
+ * - Classic: `repeat(input, count)` → returns a repeated string
+ * - Curried: `repeat(count)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.repeat("abc", 3); // "abcabcabc"
+ * 
+ * pipe(
+ * 	"-",
+ * 	S.repeat(5),
+ * ); // "-----"
+ * 
+ * S.repeat("Duplo", 2); // "DuploDuplo"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.repeat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/repeat
+ * 
+ * @namespace S
+ * 
+ */
 export declare function repeat<GenericInput extends string>(count: number): (input: GenericInput) => string;
 export declare function repeat<GenericInput extends string>(input: GenericInput, count: number): string;

package/dist/string/replace.d.ts

@@ -6,5 +6,35 @@ export interface StringReplacerParams {
     self: string;
 }
 export type StringReplacer = (params: StringReplacerParams) => string;
+/**
+ * Replaces the first match in a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `replace(input, pattern, replacement)` → returns a new string
+ * - Curried: `replace(pattern, replacement)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.replace("DuploJS is the best.", "best", "most complete"); // "DuploJS is the most complete."
+ * 
+ * S.replace("Order 1234 is ready.", /\d/, "*"); // "Order *234 is ready."
+ * 
+ * pipe(
+ * 	"Hello world",
+ * 	S.replace("world", "team"),
+ * ); // "Hello team"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Only the first occurrence is replaced
+ * - Uses the same semantics as [`String.prototype.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/replace
+ * 
+ * @namespace S
+ * 
+ */
 export declare function replace<GenericInput extends string>(pattern: string | RegExp, replacement: string | StringReplacer): (input: GenericInput) => string;
 export declare function replace<GenericInput extends string>(input: GenericInput, pattern: string | RegExp, replacement: string | StringReplacer): string;

package/dist/string/replaceAll.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Replaces all matches in a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `replaceAll(input, pattern, replacement)` → returns a new string
+ * - Curried: `replaceAll(pattern, replacement)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.replaceAll("Hello world, how are you?", " ", "-"); // "Hello-world,-how-are-you?"
+ * 
+ * S.replaceAll("My code is 1234", /\d/g, "*"); // "My code is ****"
+ * 
+ * pipe(
+ * 	"a b c",
+ * 	S.replaceAll(" ", ""),
+ * ); // "abc"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.replaceAll`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/replaceAll
+ * 
+ * @namespace S
+ * 
+ */
 export declare function replaceAll<GenericInput extends string>(pattern: string | RegExp, replacement: string): (input: GenericInput) => string;
 export declare function replaceAll(input: string, pattern: string | RegExp, replacement: string): string;

package/dist/string/search.d.ts

@@ -1,2 +1,32 @@
+/**
+ * Searches a string for a pattern and returns the index.
+ * 
+ * **Supported call styles:**
+ * - Classic: `search(input, pattern)` → returns an index or `undefined`
+ * - Curried: `search(pattern)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.search("DuploJS Utils", "JS"); // 5
+ * 
+ * S.search("DuploJS Utils", "js"); // undefined
+ * 
+ * pipe(
+ * 	"DuploJS Utils",
+ * 	S.search(/Utils/),
+ * ); // 8
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when the pattern is not found
+ * - Uses the same semantics as [`String.prototype.search`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/search
+ * 
+ * @namespace S
+ * 
+ */
 export declare function search<GenericInput extends string>(pattern: string | RegExp): (input: GenericInput) => number | undefined;
 export declare function search<GenericInput extends string>(input: GenericInput, pattern: string | RegExp): number | undefined;

package/dist/string/slice.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Slices a portion of a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `slice(input, start, end?)` → returns a substring
+ * - Curried: `slice(start, end?)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.slice("DuploJS Utils", 0, 7); // "DuploJS"
+ * 
+ * S.slice("DuploJS Utils", -5); // "Utils"
+ * 
+ * pipe(
+ * 	"DuploJS Utils",
+ * 	S.slice(0, 7),
+ * ); // "DuploJS"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/slice
+ * 
+ * @namespace S
+ * 
+ */
 export declare function slice<GenericInput extends string>(start: number, end: number): (input: GenericInput) => string;
 export declare function slice<GenericInput extends string>(input: GenericInput, start: number, end: number): string;

package/dist/string/sort.d.ts

@@ -1,3 +1,45 @@
 import { type SortType } from "../common";
+/**
+ * Sorts an array of strings in ascending or descending order.
+ * 
+ * **Supported call styles:**
+ * - Classic: `sort(array, type)` → returns a new sorted array
+ * - Curried: `sort(type)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * S.sort(
+ * 	[
+ * 		"zeta",
+ * 		"alpha",
+ * 		"beta",
+ * 	],
+ * 	"ASC",
+ * ); // ["alpha", "beta", "zeta"]
+ * 
+ * pipe(
+ * 	[
+ * 		"zeta",
+ * 		"alpha",
+ * 	],
+ * 	S.sort("DSC"),
+ * ); // ["zeta", "alpha"]
+ * 
+ * S.sort(
+ * 	[
+ * 		"beta",
+ * 		"alpha",
+ * 	],
+ * 	"ASC",
+ * ); // ["alpha", "beta"]
+ * 
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/sort
+ * 
+ * @namespace S
+ * 
+ */
 export declare function sort<GenericArray extends readonly string[]>(type: SortType): (array: GenericArray) => string[];
 export declare function sort<GenericArray extends readonly string[]>(array: GenericArray, type: SortType): string[];

package/dist/string/sortCompare.d.ts

@@ -1,2 +1,35 @@
+/**
+ * Compares two strings for sorting.
+ * 
+ * **Supported call styles:**
+ * - Classic: `sortCompare(valueA, valueB)` → returns a number
+ * - Curried: `sortCompare(valueB)` → returns a function waiting for valueA
+ * 
+ * The comparison uses a locale-aware collator.
+ * 
+ * ```ts
+ * S.sortCompare("alpha", "beta"); // -1
+ * 
+ * pipe(
+ * 	"beta",
+ * 	S.sortCompare("alpha"),
+ * ); // 1
+ * 
+ * [
+ * 	"beta",
+ * 	"alpha",
+ * 	"gamma",
+ * ].sort((left, right) => S.sortCompare(left, right)); // ["alpha", "beta", "gamma"]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses `Intl.Collator` with locale "en-US-u-kn-true" and sort-specific options
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/sortCompare
+ * 
+ * @namespace S
+ * 
+ */
 export declare function sortCompare(valueB: string): (valueA: string) => number;
 export declare function sortCompare(valueB: string, valueA: string): number;

package/dist/string/split.d.ts

@@ -2,6 +2,35 @@ import type { Split } from "./types/split";
 interface StringSplitParams<GenericLimit extends number> {
     limit: GenericLimit;
 }
+/**
+ * Splits a string into an array of substrings.
+ * 
+ * **Supported call styles:**
+ * - Classic: `split(input, separator, params?)` → returns an array of strings
+ * - Curried: `split(separator)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.split("apple,banana,cherry", ","); // ["apple", "banana", "cherry"]
+ * 
+ * pipe(
+ * 	"aa.bb.cc",
+ * 	S.split("."),
+ * ); // ["aa", "bb", "cc"]
+ * 
+ * S.split("alpha-beta-gamma", "-", { limit: 2 }); // ["alpha", "beta"]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/split
+ * 
+ * @namespace S
+ * 
+ */
 export declare function split<GenericString extends string, GenericSeparator extends string>(separator: GenericSeparator | RegExp): (input: GenericString) => Split<GenericString, GenericSeparator>;
 export declare function split<GenericString extends string, GenericSeparator extends string, GenericLimit extends number>(input: GenericString, separator: GenericSeparator | RegExp, params?: StringSplitParams<GenericLimit>): Split<GenericString, GenericSeparator, GenericLimit>;
 export {};

package/dist/string/startsWith.d.ts

@@ -1,5 +1,46 @@
 import { type IsEqual } from "../common";
 type ComputeResult<GenericString extends string, GenericSearchString extends string> = Extract<GenericString, `${GenericSearchString}${string}`> extends infer InferredResult extends GenericString ? IsEqual<InferredResult, never> extends true ? GenericString & `${GenericSearchString}${string}` : InferredResult : never;
+/**
+ * Checks whether a string starts with a substring.
+ * 
+ * **Supported call styles:**
+ * - Classic: `startsWith(input, searchString)` → returns a boolean
+ * - Curried: `startsWith(searchString)` → returns a function waiting for the input
+ * - Classic predicate: `startsWith(input, searchString)` → narrows the string type
+ * - Curried predicate: `startsWith(searchString)` → narrows the string type
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * const maybeValue = true ? "DuploJS" : "NestJS";
+ * 
+ * if (S.startsWith(maybeValue, "Du")) {
+ * 	// maybeValue is "DuploJS"
+ * }
+ * 
+ * pipe(
+ * 	maybeValue,
+ * 	when(
+ * 		S.startsWith("Du"),
+ * 		(value) => {
+ * 			// value is "DuploJS"
+ * 		},
+ * 	),
+ * );
+ * 
+ * S.startsWith("DuploJS", "Du"); // true
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type
+ * - Uses the same semantics as [`String.prototype.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/startsWith
+ * 
+ * @namespace S
+ * 
+ */
 export declare function startsWith<GenericString extends string, GenericSearchString extends string>(searchString: GenericSearchString): (input: GenericString) => input is ComputeResult<GenericString, GenericSearchString>;
 export declare function startsWith<GenericString extends string, GenericSearchString extends string>(input: GenericString, searchString: GenericSearchString): input is ComputeResult<GenericString, GenericSearchString>;
 export {};

package/dist/string/substring.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Extracts a substring from a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `substring(input, start, end?)` → returns a substring
+ * - Curried: `substring(start, end?)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.substring("DuploJS Utils", 7); // " Utils"
+ * 
+ * S.substring("DuploJS Utils", 0, 6); // "DuploJ"
+ * 
+ * pipe(
+ * 	"DuploJS Utils",
+ * 	S.substring(0, 6),
+ * ); // "DuploJ"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/substring
+ * 
+ * @namespace S
+ * 
+ */
 export declare function substring<GenericInput extends string>(start: number, end?: number): (input: GenericInput) => string;
 export declare function substring<GenericInput extends string>(input: GenericInput, start: number, end?: number): string;

package/dist/string/test.d.ts

@@ -1,2 +1,31 @@
+/**
+ * Tests a string against a regular expression.
+ * 
+ * **Supported call styles:**
+ * - Classic: `test(input, regExp)` → returns a boolean
+ * - Curried: `test(regExp)` → returns a function waiting for the input
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.test("DuploJS", /JS$/); // true
+ * 
+ * pipe(
+ * 	"DuploTS",
+ * 	S.test(/JS$/),
+ * ); // false
+ * 
+ * S.test("alpha", /ph/); // true
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`RegExp.prototype.test`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/test
+ * 
+ * @namespace S
+ * 
+ */
 export declare function test<GenericInput extends string>(regExp: RegExp): (input: GenericInput) => boolean;
 export declare function test<GenericInput extends string>(input: GenericInput, regExp: RegExp): boolean;

package/dist/string/toLowerCase.cjs

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

package/dist/string/toLowerCase.d.ts

@@ -1 +1,28 @@
+/**
+ * Lowercases all characters in a string.
+ * 
+ * Signature: `toLowerCase(input)` → returns the lowercased string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.toLowerCase("ZERIIX"); // "zeriix"
+ * 
+ * pipe(
+ * 	"HELLO",
+ * 	S.toLowerCase,
+ * ); // "hello"
+ * 
+ * S.toLowerCase("DUPlO"); // "duplo"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.toLowerCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/toLowerCase
+ * 
+ * @namespace S
+ * 
+ */
 export declare function toLowerCase<GenericString extends string>(input: GenericString): Lowercase<GenericString>;

package/dist/string/toLowerCase.mjs

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

package/dist/string/toUpperCase.cjs

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

package/dist/string/toUpperCase.d.ts

@@ -1 +1,28 @@
+/**
+ * Uppercases all characters in a string.
+ * 
+ * Signature: `toUpperCase(input)` → returns the uppercased string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.toUpperCase("duplojs"); // "DUPLOJS"
+ * 
+ * pipe(
+ * 	"hello",
+ * 	S.toUpperCase,
+ * ); // "HELLO"
+ * 
+ * S.toUpperCase("zeriix"); // "ZERIIX"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.toUpperCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/toUpperCase
+ * 
+ * @namespace S
+ * 
+ */
 export declare function toUpperCase<GenericString extends string>(input: GenericString): Uppercase<GenericString>;

package/dist/string/toUpperCase.mjs

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

package/dist/string/trim/default.cjs

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

package/dist/string/trim/default.d.ts

@@ -1 +1,28 @@
+/**
+ * Removes whitespace from both ends of a string.
+ * 
+ * Signature: `trim(input)` → returns the trimmed string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.trim("  DuploJS  "); // "DuploJS"
+ * 
+ * pipe(
+ * 	"  hello  ",
+ * 	S.trim,
+ * ); // "hello"
+ * 
+ * S.trim("\ntext\t"); // "text"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trim)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/trim
+ * 
+ * @namespace S
+ * 
+ */
 export declare function trim<GenericInput extends string>(input: GenericInput): string;

package/dist/string/trim/default.mjs

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

package/dist/string/trim/end.cjs

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

package/dist/string/trim/end.d.ts

@@ -1 +1,28 @@
+/**
+ * Removes whitespace from the end of a string.
+ * 
+ * Signature: `trimEnd(input)` → returns the trimmed string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.trimEnd("  DuploJS  "); // "  DuploJS"
+ * 
+ * pipe(
+ * 	"  hello  ",
+ * 	S.trimEnd,
+ * ); // "  hello"
+ * 
+ * S.trimEnd("\ntext\t"); // "\ntext"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.trimEnd`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimEnd)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/trimEnd
+ * 
+ * @namespace S
+ * 
+ */
 export declare function trimEnd<GenericInput extends string>(input: GenericInput): string;

package/dist/string/trim/end.mjs

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

package/dist/string/trim/start.cjs

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

package/dist/string/trim/start.d.ts

@@ -1 +1,28 @@
+/**
+ * Removes whitespace from the start of a string.
+ * 
+ * Signature: `trimStart(input)` → returns the trimmed string
+ * 
+ * The input string is not mutated.
+ * 
+ * ```ts
+ * S.trimStart("  DuploJS  "); // "DuploJS  "
+ * 
+ * pipe(
+ * 	"  hello  ",
+ * 	S.trimStart,
+ * ); // "hello  "
+ * 
+ * S.trimStart("\ntext\t"); // "text\t"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`String.prototype.trimStart`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimStart)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/string/trimStart
+ * 
+ * @namespace S
+ * 
+ */
 export declare function trimStart<GenericInput extends string>(input: GenericInput): string;

package/dist/string/trim/start.mjs

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

package/dist/string/uncapitalize.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include string/uncapitalize/index.md}
+ */
 function uncapitalize(input) {
     return `${input.charAt(0).toLowerCase()}${input.slice(1)}`;
 }