@kikiutils/shared 15.0.2 → 15.1.0

package/src/crypto-hash.ts

@@ -16,7 +16,7 @@ import type {
  * ```typescript
  * import { cryptoMd5 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoMd5('test')); // 33ed9a05a10b21f0...
+ * console.log(cryptoMd5('test')); // 098f6bcd4621d373cade4e832627b4f6
  * ```
  */
 export function cryptoMd5(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -53,7 +53,7 @@ export function cryptoMd5ToBuffer(data: BinaryLike) {
  * ```typescript
  * import { cryptoSha3224 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YX...
+ * console.log(cryptoSha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
  * ```
  */
 export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -71,7 +71,7 @@ export function cryptoSha3224(data: BinaryLike, outputEncoding: BinaryToTextEnco
  * ```typescript
  * import { cryptoSha3224ToBuffer } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3224ToBuffer('test')); // <Buffer 0q W8 Fo ...>
+ * console.log(cryptoSha3224ToBuffer('test')); // <Buffer 37 97 bf 0a ...>
  * ```
  */
 export function cryptoSha3224ToBuffer(data: BinaryLike) {
@@ -127,7 +127,7 @@ export function cryptoSha3256ToBuffer(data: BinaryLike) {
  * ```typescript
  * import { cryptoSha3384 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
+ * console.log(cryptoSha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
  * ```
  */
 export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -145,7 +145,7 @@ export function cryptoSha3384(data: BinaryLike, outputEncoding: BinaryToTextEnco
  * ```typescript
  * import { cryptoSha3384ToBuffer } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3384ToBuffer('test')); // <Buffer 1Q 2w QZ ...>
+ * console.log(cryptoSha3384ToBuffer('test')); // <Buffer e5 16 da bb ...>
  * ```
  */
 export function cryptoSha3384ToBuffer(data: BinaryLike) {
@@ -164,7 +164,7 @@ export function cryptoSha3384ToBuffer(data: BinaryLike) {
  * ```typescript
  * import { cryptoSha3512 } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3512('test')); // b_NQJ8FJBY9dIjm1q7...
+ * console.log(cryptoSha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
  * ```
  */
 export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEncoding = 'hex') {
@@ -182,7 +182,7 @@ export function cryptoSha3512(data: BinaryLike, outputEncoding: BinaryToTextEnco
  * ```typescript
  * import { cryptoSha3512ToBuffer } from '@kikiutils/shared/crypto-hash';
  *
- * console.log(cryptoSha3512ToBuffer('test')); // <Buffer b_ NQ ...>
+ * console.log(cryptoSha3512ToBuffer('test')); // <Buffer 9e ce 08 6e ...>
  * ```
  */
 export function cryptoSha3512ToBuffer(data: BinaryLike) {

package/src/hash.ts

@@ -20,7 +20,7 @@ import {
  * ```typescript
  * import { sha3224 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3224('test')); // 0qW8FoqDcFmkpuqR9J3uT8YXVb3pWnLYgA4JqyprhqZ5H...
+ * console.log(sha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
  * ```
  */
 export function sha3224(data: string | Uint8Array) {
@@ -56,7 +56,7 @@ export function sha3256(data: string | Uint8Array) {
  * ```typescript
  * import { sha3384 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3384('test')); // 1Q2wQAYaZ4o8vWX5bEB2n3Y...
+ * console.log(sha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
  * ```
  */
 export function sha3384(data: string | Uint8Array) {
@@ -74,7 +74,7 @@ export function sha3384(data: string | Uint8Array) {
  * ```typescript
  * import { sha3512 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3512('test')); // b_NQJ8FJBY9dIjm1q7...
+ * console.log(sha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
  * ```
  */
 export function sha3512(data: string | Uint8Array) {

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

@@ -9,7 +9,7 @@ import type { LRUCache } from 'lru-cache';
  *
  * @returns {(keyFn: (...args: P) => string) => Readonly<{
  *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem
- * }>} A keyed store factory that takes a key resolution function
+ * }>} A factory that accepts a key resolver and returns a frozen keyed cache facade
  *
  * @example
  * ```typescript
@@ -18,8 +18,8 @@ import type { LRUCache } from 'lru-cache';
  *
  * const lru = new LRUCache({ max: 100 });
  * const keyedStore = createLruKeyedStore(lru)((userId: string) => `user:${userId}`);
- * await keyedStore.setItem({ name: 'Alice' }, 'user-123');
- * const user = await keyedStore.getItem('user-123'); // { name: 'Alice' }
+ * keyedStore.setItem({ name: 'Alice' }, 'user-123');
+ * const user = keyedStore.getItem('user-123'); // { name: 'Alice' }
  * ```
  */
 export function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {

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

@@ -11,7 +11,7 @@ import type { RedisLikeStorage } from './types';
  *
  * @returns {(keyFn: (...args: P) => string) => Readonly<{
  *   getItem, getItemTtl, hasItem, removeItem, resolveKey, setItem, setItemWithTtl
- * }>} A keyed store factory that takes a key resolution function
+ * }>} A factory that accepts a key resolver and returns a frozen Redis keyed-store facade
  *
  * @example
  * ```typescript

package/src/string.ts

@@ -1,3 +1,6 @@
+/**
+ * Character-set presets supported by `randomString`.
+ */
 export type RandomStringMode =
   | 'alphabetic'
   | 'alphanumeric'
@@ -21,10 +24,13 @@ const CHARSETS: Record<RandomStringMode, string> = {
 };
 
 /**
- * Generates a random string of a given length using a specified character set.
+ * Generates a random string of a given length using a predefined character set.
+ *
+ * Uses `Math.random`, so this helper is suitable for display tokens, placeholders,
+ * and test data, but not for passwords, API keys, or other cryptographic secrets.
  *
- * @param {number} length - The length of the string to generate. Must be a positive integer
- * @param {RandomStringMode} [mode] - The character set to use
+ * @param {number} length - The positive integer length of the string to generate
+ * @param {RandomStringMode} [mode] - The character set to use (default: `'alphabetic'`)
  *
  * @returns {string} The generated random string
  *
@@ -34,9 +40,9 @@ const CHARSETS: Record<RandomStringMode, string> = {
  * ```typescript
  * import { randomString } from '@kikiutils/shared/string';
  *
- * console.log(randomString(8)); // e.g. 'aZbXwTyQ' (alphabetic)
- * console.log(randomString(6, 'numeric')); // e.g. '402398'
- * console.log(randomString(10, 'alphanumeric')); // e.g. 'a9Z4pQ8xY2'
+ * randomString(8); // e.g. 'aZbXwTyQ'
+ * randomString(6, 'numeric'); // e.g. '402398'
+ * randomString(10, 'alphanumeric'); // e.g. 'a9Z4pQ8xY2'
  * ```
  */
 export function randomString(length: number, mode: RandomStringMode = 'alphabetic') {

package/src/types/index.ts

@@ -6,13 +6,52 @@ import type {
 
 export type { FilteredKeyPath } from './filtered-key-path';
 
+/**
+ * A generic string-keyed object for utility APIs that intentionally accept any value shape.
+ */
 export type AnyRecord = Record<string, any>;
+
+/**
+ * Binary-like inputs accepted by `toBuffer` across browser and Node.js runtimes.
+ */
 export type BinaryInput = ArrayBuffer | Blob | Buffer | File | NodeBlob | NodeFile | Uint8Array;
+
+/**
+ * Boolean values represented either as booleans or common string literals.
+ */
 export type Booleanish = 'false' | 'true' | boolean;
+
+/**
+ * Accepts either a full object or a partial patch of that object.
+ */
 export type MaybePartial<T> = Partial<T> | T;
+
+/**
+ * Accepts either a mutable value or a readonly view of that value.
+ */
 export type MaybeReadonly<T> = Readonly<T> | T;
+
+/**
+ * Explicitly nullable value helper.
+ */
 export type Nullable<T> = null | T;
+
+/**
+ * Number-like value represented as a number or a numeric string.
+ */
 export type Numberish = number | string;
+
+/**
+ * A `Record` where every key is optional.
+ */
 export type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>;
+
+/**
+ * A readonly `PartialRecord`.
+ */
 export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialRecord<K, T>>;
+
+/**
+ * A readonly `Record`.
+ */
 export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;