es-toolkit 1.24.0-dev.778 → 1.24.0-dev.779

package/dist/compat/array/sample.d.mts

@@ -0,0 +1,80 @@
+/**
+ * Returns a random element from an array.
+ *
+ * @template T
+ * @param {T[]} array - The array to sample from.
+ * @returns {T | undefined} A random element from the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = sample(array);
+ * console.log(result); // Output: 1, 2, or 3 (randomly selected)
+ */
+declare function sample<T>(array: readonly T[]): T | undefined;
+/**
+ * Returns a random character from a string.
+ *
+ * @param {string} str - The string to sample from.
+ * @returns {string | undefined} A random character from the string, or `undefined` if the string is empty.
+ *
+ * @example
+ * const str = "hello";
+ * const result = sample(str);
+ * console.log(result); // Output: 'h', 'e', 'l', 'l', or 'o' (randomly selected)
+ */
+declare function sample(str: string): string | undefined;
+/**
+ * Returns a random element from an array.
+ *
+ * @template T
+ * @param {ArrayLike<T>} array - The array-like object to sample from.
+ * @returns {T | undefined} A random element from the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arrayLike: ArrayLike<string> = { 0: 'a', 1: 'b', 2: 'c', length: 3 };
+ * const result = sample(arrayLike);
+ * console.log(result); // Output: 'a', 'b', or 'c' (randomly selected)
+ */
+declare function sample<T>(array: ArrayLike<T>): T | undefined;
+/**
+ * Returns a random value from an object.
+ *
+ * @template T - The type of values in the object.
+ * @param {Record<string, T>} obj - The object to sample from.
+ * @returns {T | undefined} A random value from the object, or `undefined` if the object is empty.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = sample(obj);
+ * console.log(result); // Output: 1, 2, or 3 (randomly selected)
+ */
+declare function sample<T>(obj: Record<string, T>): T | undefined;
+/**
+ * Returns a random element from an array-like object or a regular object.
+ *
+ * This function takes an array-like object (such as an array or string) or a regular object,
+ * and returns a randomly selected element or value. If the collection is empty or invalid, it returns `undefined`.
+ *
+ * @template T - The type of elements in the collection.
+ * @param {ArrayLike<T> | Record<string, T>} collection - The collection to sample from.
+ * @returns {T | string | undefined} A random element from the collection, or `undefined` if the collection is empty or invalid.
+ *
+ * @example
+ * // Array example
+ * const array = [1, 2, 3];
+ * const result = sample(array);
+ * console.log(result); // Output: 1, 2, or 3 (randomly selected)
+ *
+ * // String example
+ * const str = 'abc';
+ * const result2 = sample(str);
+ * console.log(result2); // Output: 'a', 'b', or 'c' (randomly selected)
+ *
+ * // Object example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result3 = sample(obj);
+ * console.log(result3); // Output: 1, 2, or 3 (randomly selected)
+ */
+declare function sample<T>(collection: ArrayLike<T> | Record<string, T>): T | string | undefined;
+
+export { sample };

package/dist/compat/array/sample.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Returns a random element from an array.
+ *
+ * @template T
+ * @param {T[]} array - The array to sample from.
+ * @returns {T | undefined} A random element from the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * const result = sample(array);
+ * console.log(result); // Output: 1, 2, or 3 (randomly selected)
+ */
+declare function sample<T>(array: readonly T[]): T | undefined;
+/**
+ * Returns a random character from a string.
+ *
+ * @param {string} str - The string to sample from.
+ * @returns {string | undefined} A random character from the string, or `undefined` if the string is empty.
+ *
+ * @example
+ * const str = "hello";
+ * const result = sample(str);
+ * console.log(result); // Output: 'h', 'e', 'l', 'l', or 'o' (randomly selected)
+ */
+declare function sample(str: string): string | undefined;
+/**
+ * Returns a random element from an array.
+ *
+ * @template T
+ * @param {ArrayLike<T>} array - The array-like object to sample from.
+ * @returns {T | undefined} A random element from the array, or `undefined` if the array is empty.
+ *
+ * @example
+ * const arrayLike: ArrayLike<string> = { 0: 'a', 1: 'b', 2: 'c', length: 3 };
+ * const result = sample(arrayLike);
+ * console.log(result); // Output: 'a', 'b', or 'c' (randomly selected)
+ */
+declare function sample<T>(array: ArrayLike<T>): T | undefined;
+/**
+ * Returns a random value from an object.
+ *
+ * @template T - The type of values in the object.
+ * @param {Record<string, T>} obj - The object to sample from.
+ * @returns {T | undefined} A random value from the object, or `undefined` if the object is empty.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = sample(obj);
+ * console.log(result); // Output: 1, 2, or 3 (randomly selected)
+ */
+declare function sample<T>(obj: Record<string, T>): T | undefined;
+/**
+ * Returns a random element from an array-like object or a regular object.
+ *
+ * This function takes an array-like object (such as an array or string) or a regular object,
+ * and returns a randomly selected element or value. If the collection is empty or invalid, it returns `undefined`.
+ *
+ * @template T - The type of elements in the collection.
+ * @param {ArrayLike<T> | Record<string, T>} collection - The collection to sample from.
+ * @returns {T | string | undefined} A random element from the collection, or `undefined` if the collection is empty or invalid.
+ *
+ * @example
+ * // Array example
+ * const array = [1, 2, 3];
+ * const result = sample(array);
+ * console.log(result); // Output: 1, 2, or 3 (randomly selected)
+ *
+ * // String example
+ * const str = 'abc';
+ * const result2 = sample(str);
+ * console.log(result2); // Output: 'a', 'b', or 'c' (randomly selected)
+ *
+ * // Object example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result3 = sample(obj);
+ * console.log(result3); // Output: 1, 2, or 3 (randomly selected)
+ */
+declare function sample<T>(collection: ArrayLike<T> | Record<string, T>): T | string | undefined;
+
+export { sample };

package/dist/compat/array/sample.mjs

@@ -0,0 +1,14 @@
+import { sample as sample$1 } from '../../array/sample.mjs';
+import { isArrayLike } from '../predicate/isArrayLike.mjs';
+
+function sample(collection) {
+    if (collection == null) {
+        return undefined;
+    }
+    if (isArrayLike(collection)) {
+        return sample$1(Array.from(collection));
+    }
+    return sample$1(Object.values(collection));
+}
+
+export { sample };

package/dist/compat/index.d.mts

@@ -16,7 +16,6 @@ export { maxBy } from '../array/maxBy.mjs';
 export { minBy } from '../array/minBy.mjs';
 export { partition } from '../array/partition.mjs';
 export { pullAt } from '../array/pullAt.mjs';
-export { sample } from '../array/sample.mjs';
 export { sampleSize } from '../array/sampleSize.mjs';
 export { shuffle } from '../array/shuffle.mjs';
 export { takeRightWhile } from '../array/takeRightWhile.mjs';
@@ -105,6 +104,7 @@ export { indexOf } from './array/indexOf.mjs';
 export { join } from './array/join.mjs';
 export { last } from './array/last.mjs';
 export { orderBy } from './array/orderBy.mjs';
+export { sample } from './array/sample.mjs';
 export { size } from './array/size.mjs';
 export { slice } from './array/slice.mjs';
 export { some } from './array/some.mjs';

package/dist/compat/index.d.ts

@@ -16,7 +16,6 @@ export { maxBy } from '../array/maxBy.js';
 export { minBy } from '../array/minBy.js';
 export { partition } from '../array/partition.js';
 export { pullAt } from '../array/pullAt.js';
-export { sample } from '../array/sample.js';
 export { sampleSize } from '../array/sampleSize.js';
 export { shuffle } from '../array/shuffle.js';
 export { takeRightWhile } from '../array/takeRightWhile.js';
@@ -105,6 +104,7 @@ export { indexOf } from './array/indexOf.js';
 export { join } from './array/join.js';
 export { last } from './array/last.js';
 export { orderBy } from './array/orderBy.js';
+export { sample } from './array/sample.js';
 export { size } from './array/size.js';
 export { slice } from './array/slice.js';
 export { some } from './array/some.js';

package/dist/compat/index.js

@@ -898,6 +898,16 @@ function orderBy(collection, criteria, orders) {
         .map(item => item.original);
 }
 
+function sample(collection) {
+    if (collection == null) {
+        return undefined;
+    }
+    if (isArrayLike(collection)) {
+        return zipWith.sample(Array.from(collection));
+    }
+    return zipWith.sample(Object.values(collection));
+}
+
 function size(target) {
     if (isWeakSet$1.isNil(target)) {
         return 0;
@@ -2172,7 +2182,6 @@ exports.maxBy = zipWith.maxBy;
 exports.minBy = zipWith.minBy;
 exports.partition = zipWith.partition;
 exports.pullAt = zipWith.pullAt;
-exports.sample = zipWith.sample;
 exports.sampleSize = zipWith.sampleSize;
 exports.shuffle = zipWith.shuffle;
 exports.takeRightWhile = zipWith.takeRightWhile;
@@ -2340,6 +2349,7 @@ exports.rearg = rearg;
 exports.repeat = repeat;
 exports.rest = rest;
 exports.round = round;
+exports.sample = sample;
 exports.set = set;
 exports.size = size;
 exports.slice = slice;

package/dist/compat/index.mjs

@@ -16,7 +16,6 @@ export { maxBy } from '../array/maxBy.mjs';
 export { minBy } from '../array/minBy.mjs';
 export { partition } from '../array/partition.mjs';
 export { pullAt } from '../array/pullAt.mjs';
-export { sample } from '../array/sample.mjs';
 export { sampleSize } from '../array/sampleSize.mjs';
 export { shuffle } from '../array/shuffle.mjs';
 export { takeRightWhile } from '../array/takeRightWhile.mjs';
@@ -107,6 +106,7 @@ export { indexOf } from './array/indexOf.mjs';
 export { join } from './array/join.mjs';
 export { last } from './array/last.mjs';
 export { orderBy } from './array/orderBy.mjs';
+export { sample } from './array/sample.mjs';
 export { size } from './array/size.mjs';
 export { slice } from './array/slice.mjs';
 export { some } from './array/some.mjs';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "es-toolkit",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
-  "version": "1.24.0-dev.778+76ec5f1f",
+  "version": "1.24.0-dev.779+be5ba711",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {