feat: Export the checkOneOrMore and isOneOrMore utility functions. (#113)

* feat: Export the `checkOneOrMore` and `isOneOrMore` utility functions.

* chore: update docs

Author: pavadeli

etc/types.api.md

@@ -110,6 +110,9 @@ export type Branded<T, BrandName extends string> = T extends WithBrands<infer Ba
 // @public
 export const brands: unique symbol;
 
+// @public
+export function checkOneOrMore<T>(arr: T[]): OneOrMore<T>;
+
 // @public
 export function createType<Impl extends BaseTypeImpl<any, any>>(impl: Impl, override?: Partial<Record<keyof BaseTypeImpl<any, any> | 'typeValidator' | 'typeParser' | 'customValidators', PropertyDescriptor>>): TypeImpl<Impl>;
 
@@ -233,6 +236,9 @@ export class IntersectionType<Types extends OneOrMore<BaseObjectLikeTypeImpl<unk
     protected typeValidator(input: unknown, options: ValidationOptions): Result<IntersectionOfTypeTuple<Types>>;
 }
 
+// @public
+export function isOneOrMore<T>(arr: T[]): arr is OneOrMore<T>;
+
 // @public
 export function isType(value: unknown): value is Type<unknown>;
 

markdown/types.checkoneormore.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [checkOneOrMore](./types.checkoneormore.md)
+
+## checkOneOrMore() function
+
+Returns the original array if and only if it has at least one element.
+
+**Signature:**
+
+```typescript
+declare function checkOneOrMore<T>(arr: T[]): OneOrMore<T>;
+```
+
+## Parameters
+
+| Parameter | Type  | Description |
+| --------- | ----- | ----------- |
+| arr       | T\[\] |             |
+
+**Returns:**
+
+[OneOrMore](./types.oneormore.md)<!-- -->&lt;T&gt;

markdown/types.isoneormore.md

@@ -0,0 +1,27 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [isOneOrMore](./types.isoneormore.md)
+
+## isOneOrMore() function
+
+Type guard for `OneOrMore`
+
+**Signature:**
+
+```typescript
+declare function isOneOrMore<T>(arr: T[]): arr is OneOrMore<T>;
+```
+
+## Parameters
+
+| Parameter | Type  | Description |
+| --------- | ----- | ----------- |
+| arr       | T\[\] |             |
+
+**Returns:**
+
+arr is [OneOrMore](./types.oneormore.md)<!-- -->&lt;T&gt;
+
+## Remarks
+
+This checks if the array has at least one element.

markdown/types.md

@@ -35,8 +35,10 @@ Runtime type-validation with derived TypeScript types.
 | [autoCast(type)](./types.autocast.md)                             | Returns the same type, but with an auto-casting default parser installed.                                                                         |
 | [autoCastAll(type)](./types.autocastall.md)                       | Create a recursive autocasting version of the given type.                                                                                         |
 | [booleanAutoCaster(input)](./types.booleanautocaster.md)          |                                                                                                                                                   |
+| [checkOneOrMore(arr)](./types.checkoneormore.md)                  | Returns the original array if and only if it has at least one element.                                                                            |
 | [createType(impl, override)](./types.createtype.md)               | Create a Type from the given type-implementation.                                                                                                 |
 | [intersection(args)](./types.intersection.md)                     | Intersect the given types.                                                                                                                        |
+| [isOneOrMore(arr)](./types.isoneormore.md)                        | Type guard for <code>OneOrMore</code>                                                                                                             |
 | [isType(value)](./types.istype.md)                                | Type-guard that asserts that a given value is a Type.                                                                                             |
 | [keyof(args)](./types.keyof.md)                                   |                                                                                                                                                   |
 | [literal(value)](./types.literal.md)                              |                                                                                                                                                   |

markdown/types.oneormore.md

@@ -11,3 +11,7 @@ An Array with at least one element.
 ```typescript
 type OneOrMore<T> = [T, ...T[]];
 ```
+
+## Remarks
+
+Note that this type does not disable the mutable methods of the array, which may still invalidate the non-emptiness of the array.

src/index.ts

@@ -7,4 +7,5 @@ export * from './symbols';
 export * from './type-guard';
 export * from './types';
 export { printKey, printPath, printValue } from './utils/print-utils';
+export { checkOneOrMore, isOneOrMore } from './utils/type-utils';
 export * from './validation-error';

src/interfaces.ts

@@ -362,6 +362,8 @@ export type TypeguardResult<ResultType, Input> =
 
 /**
  * An Array with at least one element.
+ * @remarks
+ * Note that this type does not disable the mutable methods of the array, which may still invalidate the non-emptiness of the array.
  */
 export type OneOrMore<T> = [T, ...T[]];
 

src/utils/type-utils.ts

@@ -1,9 +1,17 @@
 import type { BasicType, Failure, OneOrMore, Result, ValidationResult } from '../interfaces';
 
+/**
+ * Type guard for `OneOrMore`
+ * @remarks
+ * This checks if the array has at least one element.
+ */
 export function isOneOrMore<T>(arr: T[]): arr is OneOrMore<T> {
     return arr.length > 0;
 }
 
+/**
+ * Returns the original array if and only if it has at least one element.
+ */
 export function checkOneOrMore<T>(arr: T[]): OneOrMore<T> {
     // istanbul ignore if
     if (!isOneOrMore(arr)) {