atomic-fns 1.2.0 → 2.0.0

package/dist/object/reshape.d.ts

@@ -0,0 +1,73 @@
+/**
+ * New objects from old ones: `flattenObject`, `invert`, `mapKeys`, `mapValues`.
+ */
+/** Options of {@link flattenObject}. */
+export interface FlattenOptions {
+    /** What joins the keys of nested objects; `'.'` by default. Array indices are written `[0]`. */
+    delimiter?: string;
+}
+/**
+ * A one-level object whose keys are the paths to the leaves of `obj`: nested plain-object keys
+ * joined by `delimiter`, array elements as `[index]`, so with the default delimiter every key is a
+ * path {@link get} reads. An own key of an array that is not an index (the `index` of a RegExp
+ * match) is joined by `delimiter` like an object key. A leaf is any value that is not a plain object
+ * or array (`null`, a `Date` and class instances included); empty containers give no key.
+ * @param obj A plain object or array.
+ * @param options `delimiter`, `'.'` by default.
+ * @returns A new plain object.
+ * @throws {TypeError} when `delimiter` is not a non-empty string, or `obj` is not a plain object or
+ * array; for a cycle; for a key that is empty or holds the delimiter, `[` or `]`, since its path
+ * would read as another one; and when two paths flatten to the same key (a delimiter of several
+ * characters can join different keys alike), which is the same unrepresentable-key case.
+ * @throws {RangeError} past 1000 levels of nesting, when shared objects repeat past 250000 units
+ * of work, or for output keys over 2^27 characters in all.
+ * @example
+ * ```ts
+ * flattenObject({ a: { b: 1, c: [2, { d: 3 }] } }) // { 'a.b': 1, 'a.c[0]': 2, 'a.c[1].d': 3 }
+ * flattenObject({ a: { b: 1 } }, { delimiter: '/' }) // { 'a/b': 1 }
+ * ```
+ */
+export declare function flattenObject(obj: object, options?: FlattenOptions): Record<string, unknown>;
+/**
+ * A new object whose keys are the values of `obj` and whose values are its keys, as lodash's
+ * `invert` builds it; a later key wins when two values are the same. A primitive value becomes a
+ * key as property keys do, so `1` and `'1'` are one key, and a symbol stays a symbol key.
+ * @param obj The object to read; its own enumerable string keys. `null` and `undefined` give `{}`.
+ * @returns A new plain object.
+ * @throws {TypeError} for a value that is an object or a function, since turning it into a key
+ * would call its own `toString`.
+ * @example
+ * ```ts
+ * invert({ a: 'x', b: 'y' }) // { x: 'a', y: 'b' }
+ * ```
+ */
+export declare function invert(obj: object | null | undefined): Record<PropertyKey, string>;
+/**
+ * A new object with the values of `obj` under the keys `keyOf` returns.
+ * @param obj The object to read; its own enumerable string keys. `null` and `undefined` give `{}`.
+ * @param keyOf Called with `(value, key, obj)`; returns the new key.
+ * @returns A new plain object; a later entry wins when two keys are the same.
+ * @example
+ * ```ts
+ * mapKeys({ a: 1, b: 2 }, (_value, key) => key.toUpperCase()) // { A: 1, B: 2 }
+ * ```
+ */
+export declare function mapKeys<V, K extends PropertyKey>(obj: readonly V[] | null | undefined, keyOf: (value: V, key: string, obj: readonly V[]) => K): Record<K, V>;
+/** {@link mapKeys} for an object: `keyOf` gets each own enumerable string key and its value. */
+export declare function mapKeys<T extends object, K extends PropertyKey>(obj: T | null | undefined, keyOf: (value: T[keyof T], key: keyof T & string, obj: T) => K): Record<K, T[keyof T]>;
+/**
+ * A new object with the keys of `obj` and the values `valueOf` returns, as lodash's `mapValues`
+ * builds it. For an array the result is a plain object keyed by index, not an array.
+ * @param obj The object to read; its own enumerable string keys. `null` and `undefined` give `{}`.
+ * @param valueOf Called with `(value, key, obj)`; returns the new value.
+ * @returns A new plain object.
+ * @example
+ * ```ts
+ * mapValues({ a: 1, b: 2 }, (value) => value * 10) // { a: 10, b: 20 }
+ * ```
+ */
+export declare function mapValues<V, R>(obj: readonly V[] | null | undefined, valueOf: (value: V, key: string, obj: readonly V[]) => R): Record<number, R>;
+/** {@link mapValues} for an object: the result keeps its own enumerable string keys. */
+export declare function mapValues<T extends object, R>(obj: T | null | undefined, valueOf: (value: T[keyof T], key: keyof T & string, obj: T) => R): {
+    [K in keyof T as K extends symbol ? never : K]: R;
+};

package/dist/object/reshape.js

@@ -0,0 +1,144 @@
+/**
+ * New objects from old ones: `flattenObject`, `invert`, `mapKeys`, `mapValues`.
+ */
+import { isPlainObject } from '../is/isPlainObject.js';
+import { isCanonicalArrayIndex } from '../internal/sparse.js';
+import { truncateForError } from '../internal/truncate.js';
+import { Ancestors, guardDepth, RevisitBudget } from '../internal/walk.js';
+import { writeKey } from './parsePath.js';
+const FLATTEN_BUDGET = 250_000;
+const MAX_KEY_CHARS = 2 ** 27;
+/**
+ * A one-level object whose keys are the paths to the leaves of `obj`: nested plain-object keys
+ * joined by `delimiter`, array elements as `[index]`, so with the default delimiter every key is a
+ * path {@link get} reads. An own key of an array that is not an index (the `index` of a RegExp
+ * match) is joined by `delimiter` like an object key. A leaf is any value that is not a plain object
+ * or array (`null`, a `Date` and class instances included); empty containers give no key.
+ * @param obj A plain object or array.
+ * @param options `delimiter`, `'.'` by default.
+ * @returns A new plain object.
+ * @throws {TypeError} when `delimiter` is not a non-empty string, or `obj` is not a plain object or
+ * array; for a cycle; for a key that is empty or holds the delimiter, `[` or `]`, since its path
+ * would read as another one; and when two paths flatten to the same key (a delimiter of several
+ * characters can join different keys alike), which is the same unrepresentable-key case.
+ * @throws {RangeError} past 1000 levels of nesting, when shared objects repeat past 250000 units
+ * of work, or for output keys over 2^27 characters in all.
+ * @example
+ * ```ts
+ * flattenObject({ a: { b: 1, c: [2, { d: 3 }] } }) // { 'a.b': 1, 'a.c[0]': 2, 'a.c[1].d': 3 }
+ * flattenObject({ a: { b: 1 } }, { delimiter: '/' }) // { 'a/b': 1 }
+ * ```
+ */
+export function flattenObject(obj, options = {}) {
+    const delimiter = options.delimiter ?? '.';
+    if (typeof delimiter !== 'string' || delimiter === '') {
+        throw new TypeError('delimiter must be a non-empty string');
+    }
+    if (!Array.isArray(obj) && !isPlainObject(obj)) {
+        throw new TypeError('flattenObject takes a plain object or array');
+    }
+    return guardDepth(() => {
+        const out = {};
+        const ancestors = new Ancestors();
+        const budget = new RevisitBudget(FLATTEN_BUDGET, `input repeats shared objects beyond ${String(FLATTEN_BUDGET)} containers`);
+        const stack = [];
+        let chars = 0;
+        const emit = (key, value) => {
+            chars += key.length;
+            if (chars > MAX_KEY_CHARS)
+                throw new RangeError(`output keys exceed ${String(MAX_KEY_CHARS)} characters`);
+            if (Object.hasOwn(out, key))
+                throw new TypeError(`two paths flatten to ${truncateForError(key)}`);
+            writeKey(out, key, value);
+        };
+        const open = (container, prefix) => {
+            if (ancestors.has(container))
+                throw new TypeError(`cycle at ${truncateForError(prefix)}`);
+            const keys = Object.keys(container);
+            budget.note(container, keys.length);
+            ancestors.enter(container);
+            stack.push({ obj: container, prefix, keys, index: 0 });
+        };
+        try {
+            open(obj, '');
+            while (stack.length > 0) {
+                const frame = stack[stack.length - 1];
+                if (frame.index >= frame.keys.length) {
+                    stack.pop();
+                    ancestors.leave(frame.obj);
+                    continue;
+                }
+                const key = frame.keys[frame.index++];
+                const isIndex = Array.isArray(frame.obj) && isCanonicalArrayIndex(key);
+                if (!isIndex &&
+                    (key === '' || key.includes(delimiter) || key.includes('[') || key.includes(']'))) {
+                    throw new TypeError(`flattenObject cannot represent the key ${truncateForError(key)}`);
+                }
+                const path = isIndex
+                    ? `${frame.prefix}[${key}]`
+                    : frame.prefix
+                        ? frame.prefix + delimiter + key
+                        : key;
+                const child = frame.obj[key];
+                if (Array.isArray(child) || isPlainObject(child))
+                    open(child, path);
+                else
+                    emit(path, child);
+            }
+            return out;
+        }
+        finally {
+            // A throw leaves frames open; leave them so a walk this one runs inside keeps its depth count.
+            for (let i = stack.length - 1; i >= 0; i--)
+                ancestors.leave(stack[i].obj);
+        }
+    });
+}
+/**
+ * A new object whose keys are the values of `obj` and whose values are its keys, as lodash's
+ * `invert` builds it; a later key wins when two values are the same. A primitive value becomes a
+ * key as property keys do, so `1` and `'1'` are one key, and a symbol stays a symbol key.
+ * @param obj The object to read; its own enumerable string keys. `null` and `undefined` give `{}`.
+ * @returns A new plain object.
+ * @throws {TypeError} for a value that is an object or a function, since turning it into a key
+ * would call its own `toString`.
+ * @example
+ * ```ts
+ * invert({ a: 'x', b: 'y' }) // { x: 'a', y: 'b' }
+ * ```
+ */
+export function invert(obj) {
+    const out = {};
+    if (obj === null || obj === undefined)
+        return out;
+    for (const [key, value] of Object.entries(obj)) {
+        if ((typeof value === 'object' && value !== null) || typeof value === 'function') {
+            throw new TypeError(`invert cannot make a key of the value at ${truncateForError(key)}`);
+        }
+        writeKey(out, typeof value === 'symbol' ? value : String(value), key);
+    }
+    return out;
+}
+export function mapKeys(obj, keyOf) {
+    const out = {};
+    if (obj === null || obj === undefined)
+        return out;
+    const keyOfEntry = keyOf;
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        writeKey(out, keyOfEntry(value, key, obj), value);
+    }
+    return out;
+}
+export function mapValues(obj, valueOf) {
+    const out = {};
+    if (obj === null || obj === undefined)
+        return out;
+    const valueOfEntry = valueOf;
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        writeKey(out, key, valueOfEntry(record[key], key, obj));
+    }
+    return out;
+}

package/dist/random/index.d.ts

@@ -1,42 +1,106 @@
+import type { Collection, CollectionValue } from '../collections/shape.js';
+/** The random source option every function in `fns/random` takes. */
+export interface RandomOptions {
+    /** Returns numbers in `[0, 1)`, as `Math.random` does (the default). */
+    random?: () => number;
+}
+/** Options for {@link random}. */
+export interface RandomNumberOptions extends RandomOptions {
+    /** Return a float in `[min, max)` even when both bounds are integers. */
+    float?: boolean;
+}
 /**
- * This module implements pseudo-random generators for various distributions.
- *
- * @module random
+ * Returns a uniform random integer from `min` to `max`, both included, across any span of safe
+ * integers.
+ * @param min The lower bound (included).
+ * @param max The upper bound (included).
+ * @param options `random`, the source of randomness.
+ * @returns The integer.
+ * @throws {TypeError} when a bound is not a number, `random` is not a function or it returns a
+ *   value that is not a number.
+ * @throws {RangeError} when a bound is not a safe integer, `max < min`, or `random` returns a
+ *   number outside `[0, 1)`.
+ * @example
+ * ```ts
+ * randomInt(1, 6) // a die roll
+ * ```
  */
+export declare function randomInt(min: number, max: number, options?: RandomOptions): number;
 /**
- * Returns a random float between a [min, max) value (max exclusive).
- * @param {number} min
- * @param {number} max
- * @returns {number}
+ * Returns a random number from `min` (default 0) to `max` (default 1), as lodash does: an integer
+ * with both bounds included, or a float in `[min, max)` when `float` is set or a bound is not a
+ * safe integer. One number is `max`.
+ * @param min The lower bound, or `max` when it is the only number.
+ * @param max The upper bound.
+ * @param options `float` and `random`.
+ * @returns The random number.
+ * @throws {TypeError} when a bound is not a number, `random` is not a function or it returns a
+ *   value that is not a number.
+ * @throws {RangeError} when a bound is not finite, `max < min`, or `random` returns a number
+ *   outside `[0, 1)`.
+ * @example
+ * ```ts
+ * random(5) // an integer from 0 to 5
+ * random(1.5, 2.5) // a float in [1.5, 2.5)
+ * random(0, 1, { float: true }) // a float in [0, 1)
+ * ```
  */
-export declare function random(min?: number, max?: number): number;
+export declare function random(options?: RandomNumberOptions): number;
+/** A random number from 0 to `max`. */
+export declare function random(max: number, options?: RandomNumberOptions): number;
+/** A random number from `min` to `max`. */
+export declare function random(min: number, max: number, options?: RandomNumberOptions): number;
 /**
- * Returns a random integer between a [min, max] value (inclusive).
- * @param {number} min
- * @param {number} max
- * @returns {number}
+ * Returns a random value of a collection, or `undefined` when it has none. Collections follow the
+ * fns/collection shapes: an object gives its own enumerable values, an array its elements (holes
+ * skipped), a string its code points, a `Map` or `Set` its values, and any other iterable its
+ * items. Arrays and typed arrays read only selected positions unless an array hole triggers a
+ * full scan. Sparse arrays may consume extra draws, so their seeded results can differ from
+ * sampling their collected values.
+ * @param collection The collection to draw from.
+ * @param options `random`, the source of randomness.
+ * @returns The value drawn.
+ * @throws {TypeError} when `random` is not a function or returns a value that is not a number.
+ * @throws {RangeError} when `random` returns a number outside `[0, 1)`.
+ * @example
+ * ```ts
+ * sample([1, 2, 3]) // 1, 2 or 3
+ * sample({ a: 1, b: 2 }) // 1 or 2
+ * ```
  */
-export declare function randomInt(min?: number, max?: number): number;
+export declare function sample<C extends Collection>(collection: C, options?: RandomOptions): CollectionValue<C> | undefined;
 /**
- * Returns the item at some random index in a sequence.
- * @returns {T}
- * @template T
+ * Returns `n` values of a collection at distinct positions, in random order, or every value when
+ * it has fewer than `n`. Sampling follows {@link sample}, including its collection shapes and
+ * sparse-array behavior. Full samples, and samples of at least five values covering at least half
+ * an array or typed array, copy its values before drawing. Smaller partial samples read only
+ * selected positions unless a missing position triggers a full scan. An `n` of 0 reads no values.
+ * @param collection The collection to draw from.
+ * @param n How many values to draw.
+ * @param options `random`, the source of randomness.
+ * @returns The values drawn.
+ * @throws {TypeError} when `n` is not a number, `random` is not a function or it returns a value
+ *   that is not a number.
+ * @throws {RangeError} when `n` is not a non-negative integer or `random` returns a number outside
+ *   `[0, 1)`.
+ * @example
+ * ```ts
+ * sampleSize([1, 2, 3], 2) // two of them, such as [3, 1]
+ * sampleSize([1, 2, 3], 4) // all three, shuffled
+ * ```
  */
-export declare function choice<T>(arr: T[]): T;
+export declare function sampleSize<C extends Collection>(collection: C, n: number, options?: RandomOptions): CollectionValue<C>[];
 /**
- * Returns a random sample of size k from a list of items.
- * @param {Array} arr
- * @param {number} size
- * @returns A new array with `size` random elements from `arr`.
- * @template T
+ * Returns the values of a collection in random order, with a Fisher-Yates shuffle. It never
+ * changes `collection`; collections follow the shapes of {@link sample}.
+ * @param collection The collection to shuffle.
+ * @param options `random`, the source of randomness.
+ * @returns A new array of the values.
+ * @throws {TypeError} when `random` is not a function or returns a value that is not a number.
+ * @throws {RangeError} when `random` returns a number outside `[0, 1)`.
+ * @example
+ * ```ts
+ * shuffle([1, 2, 3, 4]) // such as [3, 1, 4, 2]
+ * ```
  */
-export declare function sample<T>(arr: T[], size: number): T[];
-/**
- * Shuffles a collection elements in-place. Uses the Fisher-Yates algorithm for uniform shuffling. If collection is an Object it returns shuffled `Object.values()`.
- *
- * @param {Array} arr
- * @param {number} size
- * @returns The shuffled array.
- * @template T
- */
-export declare function shuffle<T>(arr: T[], size?: number): T[];
+export declare function shuffle<C extends Collection>(collection: C, options?: RandomOptions): CollectionValue<C>[];

package/dist/random/index.js

@@ -1,72 +1,234 @@
 /**
- * This module implements pseudo-random generators for various distributions.
- *
+ * Random numbers and draws: `random`, `randomInt`, `sample`, `sampleSize` and `shuffle`. Every
+ * function uses `Math.random` unless given `{ random }`, a function that returns numbers in
+ * `[0, 1)`. `Math.random` is not cryptographically secure, so do not draw tokens, keys or anything
+ * secret with it: use `fns/id` or `crypto.getRandomValues` for those.
  * @module random
  */
-import { isObject } from '../globals/index.js';
+import { values } from '../collections/entries.js';
+import { isEnumerable } from '../internal/keys.js';
+import { typedArrayLength } from '../internal/kind.js';
+const TWO_32 = 2 ** 32;
+const TWO_53 = 2 ** 53;
+/** Redraws before accepting that a stubbed source keeps repeating a rejected draw. */
+const MAX_DRAWS = 64;
+function isRandomNumberOptions(x) {
+    return typeof x === 'object' && x !== null;
+}
+/** The source `options` names, checked on every draw against the `[0, 1)` contract. */
+function sourceOf(options) {
+    const source = options?.random ?? Math.random;
+    if (typeof source !== 'function')
+        throw new TypeError('random must be a function');
+    return () => {
+        const r = source();
+        if (typeof r !== 'number')
+            throw new TypeError('random must return a number');
+        if (!(r >= 0 && r < 1))
+            throw new RangeError('random must return a number in [0, 1)');
+        return r;
+    };
+}
+/** The top 32 bits of one draw, which every source with at least 32 bits of precision fills. */
+function draw32(source) {
+    return Math.floor(source() * TWO_32);
+}
+/** 53 random bits from two 32-bit chunks, so no bit depends on the precision of the source. */
+function draw53(source) {
+    const high21 = Math.floor(draw32(source) / 2 ** 11);
+    return high21 * TWO_32 + draw32(source);
+}
+function uniformInt(min, max, source) {
+    // A span of up to 2^32 values takes one 32-bit draw, a wider one a 53-bit draw, and a span wider
+    // than 2^53 adds a coin flip for the top bit.
+    const narrow = max - min < TWO_32;
+    const wide = max - min >= TWO_53;
+    const range = narrow ? TWO_32 : TWO_53;
+    const span = wide ? TWO_53 : max - min + 1;
+    const bucket = (range - (range % span)) / span;
+    for (let draws = 0; draws < MAX_DRAWS; draws++) {
+        const draw = narrow ? draw32(source) : draw53(source);
+        const top = wide && source() >= 0.5 ? TWO_53 : 0;
+        const value = min + top + (draw - (draw % bucket)) / bucket;
+        if (value <= max)
+            return value;
+    }
+    return max;
+}
+/** Moves `size` uniformly drawn items to the front of `items` (Fisher-Yates) and keeps those. */
+function drawInPlace(items, size, source) {
+    for (let i = 0; i < size && i < items.length - 1; i++) {
+        const j = uniformInt(i, items.length - 1, source);
+        [items[i], items[j]] = [items[j], items[i]];
+    }
+    items.length = size;
+    return items;
+}
+function indexedLength(collection) {
+    if (Array.isArray(collection))
+        return collection.length;
+    if (typeof collection === 'object' && collection !== null)
+        return typedArrayLength(collection);
+    return undefined;
+}
+function drawIndices(collection, length, size, source) {
+    const indices = [];
+    const displaced = new Map();
+    for (let i = 0; i < size; i++) {
+        const j = i < length - 1 ? uniformInt(i, length - 1, source) : i;
+        const index = displaced.get(j) ?? j;
+        if (Array.isArray(collection) && !isEnumerable(collection, index)) {
+            return undefined;
+        }
+        displaced.set(j, displaced.get(i) ?? i);
+        indices.push(index);
+    }
+    return indices;
+}
 /**
- * Returns a random float between a [min, max) value (max exclusive).
- * @param {number} min
- * @param {number} max
- * @returns {number}
+ * Returns a uniform random integer from `min` to `max`, both included, across any span of safe
+ * integers.
+ * @param min The lower bound (included).
+ * @param max The upper bound (included).
+ * @param options `random`, the source of randomness.
+ * @returns The integer.
+ * @throws {TypeError} when a bound is not a number, `random` is not a function or it returns a
+ *   value that is not a number.
+ * @throws {RangeError} when a bound is not a safe integer, `max < min`, or `random` returns a
+ *   number outside `[0, 1)`.
+ * @example
+ * ```ts
+ * randomInt(1, 6) // a die roll
+ * ```
  */
-export function random(min = 0, max = 1) {
-    const value = Math.random() * (max - min) + min;
-    return value === max ? min : value;
+export function randomInt(min, max, options) {
+    if (typeof min !== 'number' || typeof max !== 'number') {
+        throw new TypeError('min and max must be numbers');
+    }
+    if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max)) {
+        throw new RangeError('min and max must be safe integers');
+    }
+    if (max < min)
+        throw new RangeError('max must be >= min');
+    return uniformInt(min, max, sourceOf(options));
 }
 /**
- * Returns a random integer between a [min, max] value (inclusive).
- * @param {number} min
- * @param {number} max
- * @returns {number}
+ * @param first `min`, `max`, or the options.
+ * @param second `max`, or the options.
+ * @param third The options.
  */
-export function randomInt(min = 0, max = 1) {
-    const low = Math.ceil(Math.min(min, max));
-    const high = Math.floor(Math.max(min, max));
-    return low + Math.floor(random(0, high - low + 1));
+export function random(first, second, third) {
+    const options = [first, second, third].find(isRandomNumberOptions);
+    const bounds = [];
+    for (const bound of [first, second]) {
+        if (bound === undefined || isRandomNumberOptions(bound))
+            continue;
+        if (typeof bound !== 'number')
+            throw new TypeError('min and max must be numbers');
+        bounds.push(bound);
+    }
+    const [min, max] = bounds.length === 2 ? bounds : [0, bounds[0] ?? 1];
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+        throw new RangeError('min and max must be finite');
+    }
+    if (max < min)
+        throw new RangeError('max must be >= min');
+    const source = sourceOf(options);
+    if (!options?.float && Number.isSafeInteger(min) && Number.isSafeInteger(max)) {
+        return uniformInt(min, max, source);
+    }
+    const r = source();
+    const value = min * (1 - r) + max * r;
+    return value >= min && value < max ? value : min;
 }
 /**
- * Returns the item at some random index in a sequence.
- * @returns {T}
- * @template T
+ * Returns a random value of a collection, or `undefined` when it has none. Collections follow the
+ * fns/collection shapes: an object gives its own enumerable values, an array its elements (holes
+ * skipped), a string its code points, a `Map` or `Set` its values, and any other iterable its
+ * items. Arrays and typed arrays read only selected positions unless an array hole triggers a
+ * full scan. Sparse arrays may consume extra draws, so their seeded results can differ from
+ * sampling their collected values.
+ * @param collection The collection to draw from.
+ * @param options `random`, the source of randomness.
+ * @returns The value drawn.
+ * @throws {TypeError} when `random` is not a function or returns a value that is not a number.
+ * @throws {RangeError} when `random` returns a number outside `[0, 1)`.
+ * @example
+ * ```ts
+ * sample([1, 2, 3]) // 1, 2 or 3
+ * sample({ a: 1, b: 2 }) // 1 or 2
+ * ```
  */
-export function choice(arr) {
-    if (!arr?.length)
-        return;
-    return arr[randomInt(0, arr.length - 1)];
+export function sample(collection, options) {
+    const source = sourceOf(options);
+    const length = indexedLength(collection);
+    if (length !== undefined) {
+        if (length === 0)
+            return undefined;
+        const index = uniformInt(0, length - 1, source);
+        if (!Array.isArray(collection) || isEnumerable(collection, index)) {
+            return collection[index];
+        }
+    }
+    const items = values(collection);
+    if (items.length === 0)
+        return undefined;
+    return items[uniformInt(0, items.length - 1, source)];
 }
 /**
- * Returns a random sample of size k from a list of items.
- * @param {Array} arr
- * @param {number} size
- * @returns A new array with `size` random elements from `arr`.
- * @template T
+ * Returns `n` values of a collection at distinct positions, in random order, or every value when
+ * it has fewer than `n`. Sampling follows {@link sample}, including its collection shapes and
+ * sparse-array behavior. Full samples, and samples of at least five values covering at least half
+ * an array or typed array, copy its values before drawing. Smaller partial samples read only
+ * selected positions unless a missing position triggers a full scan. An `n` of 0 reads no values.
+ * @param collection The collection to draw from.
+ * @param n How many values to draw.
+ * @param options `random`, the source of randomness.
+ * @returns The values drawn.
+ * @throws {TypeError} when `n` is not a number, `random` is not a function or it returns a value
+ *   that is not a number.
+ * @throws {RangeError} when `n` is not a non-negative integer or `random` returns a number outside
+ *   `[0, 1)`.
+ * @example
+ * ```ts
+ * sampleSize([1, 2, 3], 2) // two of them, such as [3, 1]
+ * sampleSize([1, 2, 3], 4) // all three, shuffled
+ * ```
  */
-export function sample(arr, size) {
-    if (!arr?.length || arr.length < size)
+export function sampleSize(collection, n, options) {
+    if (typeof n !== 'number')
+        throw new TypeError('n must be a number');
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new RangeError('n must be a non-negative integer');
+    const source = sourceOf(options);
+    if (n === 0)
         return [];
-    return shuffle(arr.slice()).slice(0, size);
+    const length = indexedLength(collection);
+    if (length !== undefined && n < length && (n < 5 || n < length / 2)) {
+        const indices = drawIndices(collection, length, Math.min(n, length), source);
+        if (indices !== undefined) {
+            const items = collection;
+            return indices.map((index) => items[index]);
+        }
+    }
+    const items = values(collection);
+    return drawInPlace(items, Math.min(n, items.length), source);
 }
 /**
- * Shuffles a collection elements in-place. Uses the Fisher-Yates algorithm for uniform shuffling. If collection is an Object it returns shuffled `Object.values()`.
- *
- * @param {Array} arr
- * @param {number} size
- * @returns The shuffled array.
- * @template T
+ * Returns the values of a collection in random order, with a Fisher-Yates shuffle. It never
+ * changes `collection`; collections follow the shapes of {@link sample}.
+ * @param collection The collection to shuffle.
+ * @param options `random`, the source of randomness.
+ * @returns A new array of the values.
+ * @throws {TypeError} when `random` is not a function or returns a value that is not a number.
+ * @throws {RangeError} when `random` returns a number outside `[0, 1)`.
+ * @example
+ * ```ts
+ * shuffle([1, 2, 3, 4]) // such as [3, 1, 4, 2]
+ * ```
  */
-export function shuffle(arr, size) {
-    if (isObject(arr))
-        arr = Object.values(arr);
-    if (!arr?.length)
-        return arr;
-    if (size == null || size >= arr.length)
-        size = arr.length - 1;
-    for (let i = 0; i <= size; i++) {
-        const j = randomInt(i, size);
-        const temp = arr[j];
-        arr[j] = arr[i];
-        arr[i] = temp;
-    }
-    return arr;
+export function shuffle(collection, options) {
+    const source = sourceOf(options);
+    const items = values(collection);
+    return drawInPlace(items, items.length, source);
 }