Skip to content

Commit 5e86408

Browse files
kiki-kanrikiki-kanri
committed
docs: standardize JSDoc across src/ and storages/ with import examples
- Add missing JSDoc to time.ts, hash.ts, crypto-hash.ts, storage modules - Remove @see from datetime.ts - Add short docs to RedisLikeAdapter/RedisLikeStorage interface members - Ensure all @example blocks contain import from @kikiutils/shared
1 parent c04c8ef commit 5e86408

9 files changed

Lines changed: 337 additions & 30 deletions

File tree

‎src/crypto-hash.ts‎

Lines changed: 143 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,190 @@
1+
import { createHash } from 'node:crypto';
2+
import type {
3+
BinaryLike,
4+
BinaryToTextEncoding,
5+
} from 'node:crypto';
6+
17
/**
2-
* This file provides a set of functions for creating hash digests using different algorithms and bit lengths.
3-
* It includes functions for generating SHA-3 hash digests with bit lengths of 224, 256, 384, and 512,
4-
* as well as a function for generating MD5 hash digests.
8+
* Computes the MD5 hash of the given data.
9+
*
10+
* @param {BinaryLike} data - The input data to hash
11+
* @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
512
*
6-
* These functions use the Node.js crypto module to generate the hashes.
7-
* Can only be used in Node.js/Deno/Bun runtimes.
13+
* @returns {string | Buffer} The hash digest in the specified encoding
814
*
915
* @example
1016
* ```typescript
11-
* import { cryptoSha3256 } from '@kikiutils/shared/crypto-hash';
17+
* import { cryptoMd5 } from '@kikiutils/shared/crypto-hash';
1218
*
13-
* console.log(cryptoSha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
19+
* console.log(cryptoMd5('test')); // 33ed9a05a10b21f0...
1420
* ```
1521
*/
16-
17-
import { createHash } from 'node:crypto';
18-
import type {
19-
BinaryLike,
20-
BinaryToTextEncoding,
21-
} from 'node:crypto';
22-
2322
export function cryptoMd5(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
2423
return createHash('md5').update(data).digest(outputEncoding);
2524
}
2625

26+
/**
27+
* Computes the MD5 hash of the given data and returns the raw buffer.
28+
*
29+
* @param {BinaryLike} data - The input data to hash
30+
*
31+
* @returns {Buffer} The raw hash digest as a Buffer
32+
*
33+
* @example
34+
* ```typescript
35+
* import { cryptoMd5ToBuffer } from '@kikiutils/shared/crypto-hash';
36+
*
37+
* console.log(cryptoMd5ToBuffer('test')); // <Buffer 33 ed 9a ...>
38+
* ```
39+
*/
2740
export function cryptoMd5ToBuffer(data: BinaryLike) {
2841
return createHash('md5').update(data).digest();
2942
}
3043

44+
/**
45+
* Computes the SHA-3 hash of the given data using the 224-bit digest.
46+
*
47+
* @param {BinaryLike} data - The input data to hash
48+
* @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
49+
*
50+
* @returns {string | Buffer} The hash digest in the specified encoding
51+
*
52+
* @example
53+
* ```typescript
54+
* import { cryptoSha3224 } from '@kikiutils/shared/crypto-hash';
55+
*
56+
* console.log(cryptoSha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YX...
57+
* ```
58+
*/
3159
export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
3260
return createHash('sha3-224').update(data).digest(outputEncoding);
3361
}
3462

63+
/**
64+
* Computes the SHA-3 hash of the given data using the 224-bit digest and returns the raw buffer.
65+
*
66+
* @param {BinaryLike} data - The input data to hash
67+
*
68+
* @returns {Buffer} The raw hash digest as a Buffer
69+
*
70+
* @example
71+
* ```typescript
72+
* import { cryptoSha3224ToBuffer } from '@kikiutils/shared/crypto-hash';
73+
*
74+
* console.log(cryptoSha3224ToBuffer('test')); // <Buffer 0q W8 Fo ...>
75+
* ```
76+
*/
3577
export function cryptoSha3224ToBuffer(data: BinaryLike) {
3678
return createHash('sha3-224').update(data).digest();
3779
}
3880

81+
/**
82+
* Computes the SHA-3 hash of the given data using the 256-bit digest.
83+
*
84+
* @param {BinaryLike} data - The input data to hash
85+
* @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
86+
*
87+
* @returns {string | Buffer} The hash digest in the specified encoding
88+
*
89+
* @example
90+
* ```typescript
91+
* import { cryptoSha3256 } from '@kikiutils/shared/crypto-hash';
92+
*
93+
* console.log(cryptoSha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
94+
* ```
95+
*/
3996
export function cryptoSha3256(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
4097
return createHash('sha3-256').update(data).digest(outputEncoding);
4198
}
4299

100+
/**
101+
* Computes the SHA-3 hash of the given data using the 256-bit digest and returns the raw buffer.
102+
*
103+
* @param {BinaryLike} data - The input data to hash
104+
*
105+
* @returns {Buffer} The raw hash digest as a Buffer
106+
*
107+
* @example
108+
* ```typescript
109+
* import { cryptoSha3256ToBuffer } from '@kikiutils/shared/crypto-hash';
110+
*
111+
* console.log(cryptoSha3256ToBuffer('test')); // <Buffer 36 f0 28 ...>
112+
* ```
113+
*/
43114
export function cryptoSha3256ToBuffer(data: BinaryLike) {
44115
return createHash('sha3-256').update(data).digest();
45116
}
46117

118+
/**
119+
* Computes the SHA-3 hash of the given data using the 384-bit digest.
120+
*
121+
* @param {BinaryLike} data - The input data to hash
122+
* @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
123+
*
124+
* @returns {string | Buffer} The hash digest in the specified encoding
125+
*
126+
* @example
127+
* ```typescript
128+
* import { cryptoSha3384 } from '@kikiutils/shared/crypto-hash';
129+
*
130+
* console.log(cryptoSha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
131+
* ```
132+
*/
47133
export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
48134
return createHash('sha3-384').update(data).digest(outputEncoding);
49135
}
50136

137+
/**
138+
* Computes the SHA-3 hash of the given data using the 384-bit digest and returns the raw buffer.
139+
*
140+
* @param {BinaryLike} data - The input data to hash
141+
*
142+
* @returns {Buffer} The raw hash digest as a Buffer
143+
*
144+
* @example
145+
* ```typescript
146+
* import { cryptoSha3384ToBuffer } from '@kikiutils/shared/crypto-hash';
147+
*
148+
* console.log(cryptoSha3384ToBuffer('test')); // <Buffer 1Q 2w QZ ...>
149+
* ```
150+
*/
51151
export function cryptoSha3384ToBuffer(data: BinaryLike) {
52152
return createHash('sha3-384').update(data).digest();
53153
}
54154

155+
/**
156+
* Computes the SHA-3 hash of the given data using the 512-bit digest.
157+
*
158+
* @param {BinaryLike} data - The input data to hash
159+
* @param {BinaryToTextEncoding} [outputEncoding] - The output encoding (default: `'hex'`)
160+
*
161+
* @returns {string | Buffer} The hash digest in the specified encoding
162+
*
163+
* @example
164+
* ```typescript
165+
* import { cryptoSha3512 } from '@kikiutils/shared/crypto-hash';
166+
*
167+
* console.log(cryptoSha3512('test')); // b_NQJ8FJBY9dIjm1q7...
168+
* ```
169+
*/
55170
export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
56171
return createHash('sha3-512').update(data).digest(outputEncoding);
57172
}
58173

174+
/**
175+
* Computes the SHA-3 hash of the given data using the 512-bit digest and returns the raw buffer.
176+
*
177+
* @param {BinaryLike} data - The input data to hash
178+
*
179+
* @returns {Buffer} The raw hash digest as a Buffer
180+
*
181+
* @example
182+
* ```typescript
183+
* import { cryptoSha3512ToBuffer } from '@kikiutils/shared/crypto-hash';
184+
*
185+
* console.log(cryptoSha3512ToBuffer('test')); // <Buffer b_ NQ ...>
186+
* ```
187+
*/
59188
export function cryptoSha3512ToBuffer(data: BinaryLike) {
60189
return createHash('sha3-512').update(data).digest();
61190
}

‎src/datetime.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,6 @@ export type DateRangeType = 'lastMonth' | 'lastWeek' | 'thisMonth' | 'thisWeek'
4242
* // Format a date string
4343
* console.log(formatDate('2024-07-10T00:00:00Z', 'yyyy-MM-dd')); // 2024-07-10
4444
* ```
45-
*
46-
* @see https://date-fns.org/docs/format
4745
*/
4846
export function formatDate(date: DateArg<Date> & {}, format: string = 'yyyy-MM-dd HH:mm:ss', options?: FormatOptions) {
4947
return dateFnsFormat(date, format, options);

‎src/env.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ export class EnvironmentNotFoundError extends Error {
3535
*
3636
* @example
3737
* ```typescript
38+
* import { checkAndGetEnvValue } from '@kikiutils/shared/env';
39+
*
3840
* process.env.API_KEY = '';
3941
* checkAndGetEnvValue('API_KEY'); // ✅ Returns '' (still considered "defined")
4042
*

‎src/hash.ts‎

Lines changed: 56 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,3 @@
1-
/**
2-
* This file provides a set of functions for creating SHA-3 hash digests
3-
* using different bit lengths (224, 256, 384, 512).
4-
* These functions use the [@noble/hashes](https://github.com/paulmillr/noble-hashes) library to generate the hashes.
5-
* Can be used in the browser, mainly for Nuxt/Vue and other frameworks compiled and executed in the browser.
6-
*
7-
* @example
8-
* ```typescript
9-
* import { sha3256 } from '@kikiutils/shared/hash';
10-
*
11-
* console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
12-
* ```
13-
*/
14-
151
import {
162
sha3_224,
173
sha3_256,
@@ -23,18 +9,74 @@ import {
239
utf8ToBytes,
2410
} from '@noble/hashes/utils.js';
2511

12+
/**
13+
* Computes the SHA-3 hash of the given data using the 224-bit digest.
14+
*
15+
* @param {string | Uint8Array} data - The input data to hash
16+
*
17+
* @returns {string} The hexadecimal hash digest
18+
*
19+
* @example
20+
* ```typescript
21+
* import { sha3224 } from '@kikiutils/shared/hash';
22+
*
23+
* console.log(sha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YXVb3pWnLYgA4JqyprhqZ5H...
24+
* ```
25+
*/
2626
export function sha3224(data: string | Uint8Array) {
2727
return bytesToHex(sha3_224(typeof data === 'string' ? utf8ToBytes(data) : data));
2828
}
2929

30+
/**
31+
* Computes the SHA-3 hash of the given data using the 256-bit digest.
32+
*
33+
* @param {string | Uint8Array} data - The input data to hash
34+
*
35+
* @returns {string} The hexadecimal hash digest
36+
*
37+
* @example
38+
* ```typescript
39+
* import { sha3256 } from '@kikiutils/shared/hash';
40+
*
41+
* console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
42+
* ```
43+
*/
3044
export function sha3256(data: string | Uint8Array) {
3145
return bytesToHex(sha3_256(typeof data === 'string' ? utf8ToBytes(data) : data));
3246
}
3347

48+
/**
49+
* Computes the SHA-3 hash of the given data using the 384-bit digest.
50+
*
51+
* @param {string | Uint8Array} data - The input data to hash
52+
*
53+
* @returns {string} The hexadecimal hash digest
54+
*
55+
* @example
56+
* ```typescript
57+
* import { sha3384 } from '@kikiutils/shared/hash';
58+
*
59+
* console.log(sha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
60+
* ```
61+
*/
3462
export function sha3384(data: string | Uint8Array) {
3563
return bytesToHex(sha3_384(typeof data === 'string' ? utf8ToBytes(data) : data));
3664
}
3765

66+
/**
67+
* Computes the SHA-3 hash of the given data using the 512-bit digest.
68+
*
69+
* @param {string | Uint8Array} data - The input data to hash
70+
*
71+
* @returns {string} The hexadecimal hash digest
72+
*
73+
* @example
74+
* ```typescript
75+
* import { sha3512 } from '@kikiutils/shared/hash';
76+
*
77+
* console.log(sha3512('test')); // b_NQJ8FJBY9dIjm1q7...
78+
* ```
79+
*/
3880
export function sha3512(data: string | Uint8Array) {
3981
return bytesToHex(sha3_512(typeof data === 'string' ? utf8ToBytes(data) : data));
4082
}

‎src/storages/lru/keyed-store.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,27 @@
11
import type { LRUCache } from 'lru-cache';
22

3+
/**
4+
* Creates a keyed store wrapper around an LRU cache instance.
5+
*
6+
* @template D - The data type stored in the keyed store
7+
*
8+
* @param {LRUCache<any, any, any>} lruInstance - The underlying lru-cache instance
9+
*
10+
* @returns {(keyFn: (...args: P) => string) => Readonly<{
11+
* getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem
12+
* }>} A keyed store factory that takes a key resolution function
13+
*
14+
* @example
15+
* ```typescript
16+
* import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';
17+
* import { LRUCache } from 'lru-cache';
18+
*
19+
* const lru = new LRUCache({ max: 100 });
20+
* const keyedStore = createLruKeyedStore(lru)((userId: string) => `user:${userId}`);
21+
* await keyedStore.setItem({ name: 'Alice' }, 'user-123');
22+
* const user = await keyedStore.getItem('user-123'); // { name: 'Alice' }
23+
* ```
24+
*/
325
export function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {
426
return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({
527
/**

‎src/storages/redis/keyed-store.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,31 @@ import type { MaybeReadonly } from '../../types';
22

33
import type { RedisLikeStorage } from './types';
44

5+
/**
6+
* Creates a keyed store wrapper around a Redis-like storage.
7+
*
8+
* @template D - The data type stored in the keyed store
9+
*
10+
* @param {MaybeReadonly<RedisLikeStorage>} storage - The underlying Redis-like storage instance
11+
*
12+
* @returns {(keyFn: (...args: P) => string) => Readonly<{
13+
* getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem, setItemWithTtl
14+
* }>} A keyed store factory that takes a key resolution function
15+
*
16+
* @example
17+
* ```typescript
18+
* import { createRedisKeyedStore } from '@kikiutils/shared/storages/redis/keyed-store';
19+
* import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';
20+
* import { createClient } from 'redis';
21+
*
22+
* const client = createClient();
23+
* await client.connect();
24+
* const storage = createRedisMsgpackStorage(client as unknown as RedisLikeAdapter);
25+
* const keyedStore = createRedisKeyedStore(storage)((userId: string) => `user:${userId}`);
26+
* await keyedStore.setItem({ name: 'Alice' }, 'user-123');
27+
* const user = await keyedStore.getItem('user-123'); // { name: 'Alice' }
28+
* ```
29+
*/
530
export function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>) {
631
return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({
732
getItem: (...args: P) => storage.getItem<D>(keyFn(...args)),

0 commit comments

Comments
 (0)