Add non-spread overloads for Option.all and Option.any (#247)

Add array parameter overloads as the preferred API for Option.all and
Option.any, matching the pattern already established for Result.all and
Result.any in [1].

The spread overloads (Option.all(a, b, c)) are now deprecated in favor
of passing an array (Option.all([a, b, c])). This avoids potential stack
overflow issues when working with large arrays and provides a more
consistent API.

The spread overloads will be removed in a future version.

[1] 2e03308 ("Add non-spread overload for Result.all (#125)")

Author: jstasiak

CHANGELOG.md

@@ -6,6 +6,16 @@ Backwards incompatible:
 - Removed the `Some.safeUnwrap` and `Ok.safeUnwrap` methods, use the
   `value` property instead.
 
+Added:
+
+- Added array parameter overloads for `Option.all` and `Option.any`,
+  allowing `Option.all([a, b, c])` instead of `Option.all(a, b, c)`.
+
+Deprecated:
+
+- The parameter spread variants of `Option.all` and `Option.any` are now
+  deprecated. Use the new array parameter overloads instead.
+
 # 6.0.0
 
 Backwards incompatible:

docs/reference/option.rst

@@ -25,6 +25,10 @@ Construction:
 
 .. code-block:: typescript
 
+    // Preferred: pass an array
+    static all<T extends Option<any>[]>(options: T): Option<OptionSomeTypes<T>>
+
+    // Deprecated: spread arguments
     static all<T extends Option<any>[]>(...options: T): Option<OptionSomeTypes<T>>
 
 Parse a set of ``Option``'s, returning an array of all ``Some`` values.
@@ -35,17 +39,21 @@ Example:
 .. code-block:: typescript
 
     let options: Option<number>[] = [Some(1), Some(2), Some(3)];
-    Option.all(...options); // Some([1, 2, 3]), type: Option<number[]>
+    Option.all(options); // Some([1, 2, 3]), type: Option<number[]>
 
     // Short-circuits on first None
     let optionsWithNone: Option<number>[] = [Some(1), None, Some(3)];
-    Option.all(...optionsWithNone); // None, type: Option<number[]>
+    Option.all(optionsWithNone); // None, type: Option<number[]>
 
 ``any()``
 ---------
 
 .. code-block:: typescript
 
+    // Preferred: pass an array
+    static any<T extends Option<any>[]>(options: T): Option<OptionSomeTypes<T>[number]>
+
+    // Deprecated: spread arguments
     static any<T extends Option<any>[]>(...options: T): Option<OptionSomeTypes<T>[number]>
 
 Parse a set of ``Option``'s, short-circuits when an input value is ``Some``.
@@ -55,9 +63,11 @@ Example:
 
 .. code-block:: typescript
 
-    Option.any(None, Some(1), Some(2)); // Some(1), type: Option<number>
-    Option.any(None, None, Some(3)); // Some(3), type: Option<number>
-    Option.any(None, None, None); // None, type: Option<never>
+    let options: Option<number>[] = [None, Some(1), Some(2)];
+    Option.any(options); // Some(1), type: Option<number>
+
+    Option.any([None, None, Some(3)]); // Some(3), type: Option<number>
+    Option.any([None, None, None]); // None, type: Option<never>
 
 ``Some.EMPTY``
 --------------

src/option.ts

@@ -300,9 +300,23 @@ export type OptionSomeTypes<T extends Option<any>[]> = {
 export namespace Option {
     /**
      * Parse a set of `Option`s, returning an array of all `Some` values.
-     * Short circuits with the first `None` found, if any
+     * Short circuits with the first `None` found, if any.
      */
-    export function all<T extends Option<any>[]>(...options: T): Option<OptionSomeTypes<T>> {
+    export function all<const T extends Option<any>[]>(options: T): Option<OptionSomeTypes<T>>;
+    /**
+     * Parse a set of `Option`s, returning an array of all `Some` values.
+     * Short circuits with the first `None` found, if any.
+     *
+     * @deprecated Pass an array instead of using spread arguments. This overload
+     * will be removed in a future version.
+     */
+    export function all<T extends Option<any>[]>(...options: T): Option<OptionSomeTypes<T>>;
+    export function all<T extends Option<any>[]>(
+        first?: T | T[number],
+        ...rest: Option<any>[]
+    ): Option<OptionSomeTypes<T>> {
+        const options: Option<any>[] = first === undefined ? [] : Array.isArray(first) ? first : [first, ...rest];
+
         const someOption = [];
         for (let option of options) {
             if (option.isSome()) {
@@ -319,7 +333,21 @@ export namespace Option {
      * Parse a set of `Option`s, short-circuits when an input value is `Some`.
      * If no `Some` is found, returns `None`.
      */
-    export function any<T extends Option<any>[]>(...options: T): Option<OptionSomeTypes<T>[number]> {
+    export function any<const T extends Option<any>[]>(options: T): Option<OptionSomeTypes<T>[number]>;
+    /**
+     * Parse a set of `Option`s, short-circuits when an input value is `Some`.
+     * If no `Some` is found, returns `None`.
+     *
+     * @deprecated Pass an array instead of using spread arguments. This overload
+     * will be removed in a future version.
+     */
+    export function any<T extends Option<any>[]>(...options: T): Option<OptionSomeTypes<T>[number]>;
+    export function any<T extends Option<any>[]>(
+        first?: T | T[number],
+        ...rest: Option<any>[]
+    ): Option<OptionSomeTypes<T>[number]> {
+        const options: Option<any>[] = first === undefined ? [] : Array.isArray(first) ? first : [first, ...rest];
+
         // short-circuits
         for (const option of options) {
             if (option.isSome()) {

test/option.test.ts

@@ -106,22 +106,102 @@ test('mapOr / mapOrElse', () => {
     ).toEqual(22);
 });
 
-test('all / any', () => {
-    const strings = ['foo', 'bar', 'baz'] as const;
-    const options = [Some('foo' as const), Some('bar' as const), Some('baz' as const)] as const;
-
-    const all = Option.all(...options);
-    eq<typeof all, Option<['foo', 'bar', 'baz']>>(true);
-
-    expect(Option.all(...options)).toEqual(Some(strings));
-    expect(Option.all()).toEqual(Some([]));
-    expect(Option.all(...options, None)).toEqual(None);
-
-    expect(Option.any(...options)).toEqual(Some('foo'));
-    expect(Option.any(...options, None)).toEqual(Some('foo'));
-    expect(Option.any(None, None)).toEqual(None);
-    expect(Option.any(None, Some('foo'))).toEqual(Some('foo'));
-    expect(Option.any()).toEqual(None);
+test('Option.all', () => {
+    const some0: Option<number> = Some(3);
+    const some1: Option<boolean> = Some(true);
+    const some2: Option<string> = Some('hello');
+
+    // Empty cases
+    const all0 = Option.all([]);
+    expect(all0).toEqual(Some([]));
+    eq<typeof all0, Option<[]>>(true);
+
+    const all0Spread = Option.all();
+    expect(all0Spread).toEqual(Some([]));
+    eq<typeof all0Spread, Option<[]>>(true);
+
+    // All Some
+    const all1 = Option.all([some0, some1]);
+    expect(all1).toEqual(Some([3, true]));
+    eq<typeof all1, Option<[number, boolean]>>(true);
+
+    const all1Spread = Option.all(some0, some1);
+    expect(all1Spread).toEqual(Some([3, true]));
+    eq<typeof all1Spread, Option<[number, boolean]>>(true);
+
+    // With None
+    const all2 = Option.all([some0, None]);
+    expect(all2).toEqual(None);
+    eq<typeof all2, Option<[number, never]>>(true);
+
+    const all2Spread = Option.all(some0, None);
+    expect(all2Spread).toEqual(None);
+    eq<typeof all2Spread, Option<[number, never]>>(true);
+
+    // Dynamic array
+    const all3 = Option.all([] as Option<string>[]);
+    eq<typeof all3, Option<string[]>>(true);
+
+    const all3Spread = Option.all(...([] as Option<string>[]));
+    eq<typeof all3Spread, Option<string[]>>(true);
+
+    // Multiple with None in middle
+    const all4 = Option.all([some0, some1, some2, None]);
+    expect(all4).toEqual(None);
+    eq<typeof all4, Option<[number, boolean, string, never]>>(true);
+
+    const all4Spread = Option.all(some0, some1, some2, None);
+    expect(all4Spread).toEqual(None);
+    eq<typeof all4Spread, Option<[number, boolean, string, never]>>(true);
+});
+
+test('Option.any', () => {
+    const some0: Option<number> = Some(3);
+    const some1: Option<boolean> = Some(true);
+    const some2: Option<string> = Some('hello');
+
+    // Empty cases
+    const any0 = Option.any([]);
+    expect(any0).toEqual(None);
+    eq<typeof any0, Option<never>>(true);
+
+    const any0Spread = Option.any();
+    expect(any0Spread).toEqual(None);
+    eq<typeof any0Spread, Option<never>>(true);
+
+    // All Some - returns first
+    const any1 = Option.any([some0, some1]);
+    expect(any1).toEqual(Some(3));
+    eq<typeof any1, Option<number | boolean>>(true);
+
+    const any1Spread = Option.any(some0, some1);
+    expect(any1Spread).toEqual(Some(3));
+    eq<typeof any1Spread, Option<number | boolean>>(true);
+
+    // All None
+    const any2 = Option.any([None, None]);
+    expect(any2).toEqual(None);
+    eq<typeof any2, Option<never>>(true);
+
+    const any2Spread = Option.any(None, None);
+    expect(any2Spread).toEqual(None);
+    eq<typeof any2Spread, Option<never>>(true);
+
+    // Dynamic array
+    const any3 = Option.any([] as Option<string>[]);
+    eq<typeof any3, Option<string>>(true);
+
+    const any3Spread = Option.any(...([] as Option<string>[]));
+    eq<typeof any3Spread, Option<string>>(true);
+
+    // None then Some
+    const any4 = Option.any([None, None, some2, some0]);
+    expect(any4).toEqual(Some('hello'));
+    eq<typeof any4, Option<string | number>>(true);
+
+    const any4Spread = Option.any(None, None, some2, some0);
+    expect(any4Spread).toEqual(Some('hello'));
+    eq<typeof any4Spread, Option<string | number>>(true);
 });
 
 test('Type Helpers', () => {