Skip to content

Commit 8617ea4

Browse files
unrevised6419unrevised6419
committed
docs: document number, object, string, url
1 parent 0620b74 commit 8617ea4

File tree

5 files changed

+245
-30
lines changed

5 files changed

+245
-30
lines changed

‎src/array.ts‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@ import type { Choice, Maybe, Optional, ReadonlyArrayStrict } from './types.js';
55
* Returns the first element of an array or the value itself if it's not an array.
66
*
77
* ```ts
8-
* const singleValue = firstOrSelf('Hello'); // 'Hello'
9-
* const arrayValue = firstOrSelf(['Hello', 'World']); // 'Hello'
10-
* const emptyArray = firstOrSelf([]); // undefined
11-
* const nullValue = firstOrSelf(null); // undefined
12-
* const undefinedValue = firstOrSelf(undefined); // undefined
13-
* const numberValue = firstOrSelf(0); // 0
14-
* const emptyString = firstOrSelf(''); // ''
15-
* const booleanValue = firstOrSelf(false); // false
8+
* firstOrSelf('Hello'); // 'Hello'
9+
* firstOrSelf(['Hello', 'World']); // 'Hello'
10+
* firstOrSelf([]); // undefined
11+
* firstOrSelf(null); // undefined
12+
* firstOrSelf(undefined); // undefined
13+
* firstOrSelf(0); // 0
14+
* firstOrSelf(''); // ''
15+
* firstOrSelf(false); // false
1616
* ```
1717
*/
1818
export function firstOrSelf<T>(value: Maybe<Arrayable<T>>): Optional<T> {
@@ -29,9 +29,7 @@ export function firstOrSelf<T>(value: Maybe<Arrayable<T>>): Optional<T> {
2929
* Inserts a separator between each element of the array.
3030
*
3131
* ```ts
32-
* import { intersperse } from '@jagaad/utils';
33-
*
34-
* const result = intersperse(['a', 'b', 'c'], '-'); // ['a', '-', 'b', '-', 'c']
32+
* intersperse(['a', 'b', 'c'], '-'); // ['a', '-', 'b', '-', 'c']
3533
*/
3634
export function intersperse<T>(array: ReadonlyArray<T>, separator: T): T[] {
3735
return [...Array(2 * array.length - 1)].map((_, i) =>
@@ -43,8 +41,7 @@ export function intersperse<T>(array: ReadonlyArray<T>, separator: T): T[] {
4341
* Returns a random item from the given array.
4442
*
4543
* ```ts
46-
* const items = ['apple', 'banana', 'cherry'];
47-
* const random = randomItem(items); // Could be 'apple', 'banana', or 'cherry'
44+
* randomItem(['apple', 'banana', 'cherry']); // Could be 'apple', 'banana', or 'cherry'
4845
* ```
4946
*
5047
* @deprecated Use `sample` from `es-toolkit` instead.

‎src/number.ts‎

Lines changed: 89 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,40 @@
11
import type { Maybe, Optional } from './types.js';
22

3-
export function parseNumber(value?: Maybe<string>): Optional<number> {
3+
/**
4+
* Parses a string into a number.
5+
* If the string is empty or cannot be parsed, returns undefined.
6+
*
7+
* ```ts
8+
* parseNumber('42'); // 42
9+
* parseNumber('3.14'); // 3.14
10+
* parseNumber(''); // undefined
11+
* parseNumber('abc'); // undefined
12+
* parseNumber('123abc'); // undefined
13+
* parseNumber(null); // undefined
14+
* parseNumber(undefined); // undefined
15+
* parseNumber('NaN'); // undefined
16+
* parseNumber('Infinity'); // Infinity
17+
* parseNumber('0'); // 0
18+
*/
19+
export function parseNumber(value: Maybe<string>): Optional<number> {
420
if (!value) return undefined;
521
const parsed = Number(value);
622
if (Number.isNaN(parsed)) return undefined;
723
return parsed;
824
}
925

26+
/**
27+
* Clamps a number between a minimum and maximum value.
28+
*
29+
* ```ts
30+
* clamp(5, 1, 10); // 5
31+
* clamp(0, 1, 10); // 1
32+
* clamp(15, 1, 10); // 10
33+
* clamp(-5, -10, -1); // -5
34+
* ```
35+
*
36+
* @deprecated Use `clamp` from `es-toolkit` instead.
37+
*/
1038
export function clamp(val: number, min: number, max: number): number {
1139
return Math.max(min, Math.min(max, val));
1240
}
@@ -15,23 +43,79 @@ export function wrap(val: number, min: number, max: number): number {
1543
return ((((val - min) % (max - min)) + (max - min)) % (max - min)) + min;
1644
}
1745

18-
export function inRange(val: number, min: number, max: number) {
46+
/**
47+
* Checks if a value is within a specified range.
48+
*
49+
* ```ts
50+
* inRange(5, 1, 10); // true
51+
* inRange(0, 1, 10); // false
52+
* inRange(15, 1, 10); // false
53+
* inRange(-5, -10, -1); // true
54+
* ```
55+
*
56+
* @deprecated Use `inRange` from `es-toolkit` instead.
57+
*/
58+
export function inRange(val: number, min: number, max: number): boolean {
1959
return Math.min(min, max) <= val && val <= Math.max(min, max);
2060
}
2161

22-
export function percentage(val: number, max: number) {
62+
/**
63+
* Calculates the percentage of a value relative to a maximum.
64+
*
65+
* ```ts
66+
* percentage(50, 200); // 25
67+
* percentage(0, 100); // 0
68+
* percentage(100, 0); // 0 (avoids division by zero)
69+
* percentage(75, 300); // 25
70+
* ```
71+
*/
72+
export function percentage(val: number, max: number): number {
73+
if (max === 0) return 0; // Avoid division by zero
2374
return (val * 100) / max;
2475
}
2576

26-
export function bytesToMegabytes(size: number) {
77+
/**
78+
* Converts a size in bytes to a string representation in megabytes.
79+
*/
80+
export function bytesToMegabytes(size: number): string {
2781
return (size / 1024 / 1024).toFixed(2);
2882
}
2983

84+
/**
85+
* Normalizes a value to a ratio between 0 and 1 based on a minimum and maximum range.
86+
*
87+
* ```ts
88+
* normalizeRatio(5, 0, 10); // 0.5
89+
* normalizeRatio(0, 0, 10); // 0
90+
* normalizeRatio(10, 0, 10); // 1
91+
* normalizeRatio(-5, -10, 0); // 0.5
92+
* normalizeRatio(15, 10, 20); // 0.5
93+
* ```
94+
*/
3095
export function normalizeRatio(val: number, min: number, max: number): number {
3196
return (val - min) / (max - min);
3297
}
3398

34-
export function* range(start: number, end: number, step = 1) {
99+
/**
100+
* Generates a range of numbers from `start` to `end` with an optional `step`.
101+
*
102+
* ```ts
103+
* [...range(1, 5)]; // [1, 2, 3, 4, 5]
104+
* [...range(1, 10, 2)]; // [1, 3, 5, 7, 9]
105+
* [...range(5, 1)]; // [5, 4, 3, 2, 1]
106+
* [...range(5, 5)]; // [5]
107+
* [...range(0, 0)]; // [0]
108+
* [...range(0, 10, 3)]; // [0, 3, 6, 9]
109+
* [...range(10, 0, -2)]; // [10, 8, 6, 4, 2]
110+
* ```
111+
*
112+
* @deprecated Use `range` from `es-toolkit` instead.
113+
*/
114+
export function* range(
115+
start: number,
116+
end: number,
117+
step = 1,
118+
): Generator<number> {
35119
const delta = Math.abs(start - end);
36120
const direction = start < end ? 1 : -1;
37121
for (let i = 0; i <= delta; i += step) {

‎src/object.ts‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
import type { Choice, Maybe } from './types';
22

3+
/**
4+
* Filters out undefined values from an object.
5+
* Returns a new object with only defined values.
6+
*
7+
* ```ts
8+
* const obj = { a: 1, b: undefined, c: 3 };
9+
* const filtered = filterUndefined(obj);
10+
* console.log(filtered); // { a: 1, c: 3 }
11+
* ```
12+
*/
313
export function filterUndefined<T>(
414
obj: Partial<Readonly<Record<string, T>>>,
515
): Record<string, T> {
@@ -10,11 +20,35 @@ export function filterUndefined<T>(
1020
return Object.fromEntries(filtered);
1121
}
1222

23+
/**
24+
* Checks if an object has any own properties.
25+
*
26+
* ```ts
27+
* hasOwnKeys({ a: 1, b: 2 }); // true
28+
* hasOwnKeys({ a: undefined }); // true
29+
* hasOwnKeys({ a: null }); // true
30+
* hasOwnKeys({}); // false
31+
* hasOwnKeys(undefined); // false
32+
* hasOwnKeys(null); // false
33+
* ```
34+
*/
1335
export function hasOwnKeys(obj: Maybe<object>): boolean {
1436
if (!obj) return false;
1537
return Object.keys(obj).length > 0;
1638
}
1739

40+
/**
41+
* Checks if an object has any own properties with defined values.
42+
*
43+
* ```ts
44+
* hasOwnDefinedKeys({ a: 1, b: 2 }); // true
45+
* hasOwnDefinedKeys({ a: undefined }); // false
46+
* hasOwnDefinedKeys({ a: null }); // true
47+
* hasOwnDefinedKeys({}); // false
48+
* hasOwnDefinedKeys(undefined); // false
49+
* hasOwnDefinedKeys(null); // false
50+
* ```
51+
*/
1852
export function hasOwnDefinedKeys(obj: Maybe<object>): boolean {
1953
if (!obj) return false;
2054
return hasOwnKeys(filterUndefined(obj));
@@ -25,6 +59,15 @@ export function isNonEmptyObject(obj: object): boolean {
2559
return hasOwnDefinedKeys(obj);
2660
}
2761

62+
/**
63+
* Converts a record to an array of choices.
64+
*
65+
* ```ts
66+
* const record = { '1': 'Option 1', '2': 'Option 2' };
67+
* const choices = recordToChoices(record);
68+
* console.log(choices); // [{ id: '1', name: 'Option 1' }, { id: '2', name: 'Option 2' }]
69+
* ```
70+
*/
2871
export function recordToChoices(
2972
record: Maybe<Readonly<Record<string, string>>>,
3073
): Choice[] {

‎src/string.ts‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,32 @@
1-
import type { Maybe } from './types';
1+
import type { Maybe, Optional } from './types';
22

3+
/**
4+
* Capitalizes the first letter of a string.
5+
*
6+
* ```ts
7+
* capitalize('hello world'); // 'Hello world'
8+
* ```
9+
*
10+
* @deprecated Use `capitalize` from `es-toolkit` instead.
11+
*/
312
export function capitalize(str: string): string {
413
return `${str.charAt(0).toUpperCase()}${str.slice(1)}`;
514
}
615

7-
export function initials(name: Maybe<string>): string | undefined {
16+
/**
17+
* Generates initials from a name string.
18+
*
19+
* ```ts
20+
* initials('John Doe'); // 'JD'
21+
* initials('Alice Bob'); // 'AB'
22+
* initials(''); // undefined
23+
* initials(null); // undefined
24+
* initials(undefined); // undefined
25+
* initials(' '); // undefined
26+
* initials('Alice'); // 'A'
27+
* initials('Alice Bob Charlie'); // 'ABC'
28+
*/
29+
export function initials(name: Maybe<string>): Optional<string> {
830
if (typeof name !== 'string' || !name.trim()) return undefined;
931

1032
const parts = name

0 commit comments

Comments
 (0)