From 256b8d71423453152ada1f4e3bc63e1483b1a0d5 Mon Sep 17 00:00:00 2001 From: Paco van der Linden Date: Mon, 24 Mar 2025 13:03:54 +0100 Subject: [PATCH 1/2] feat: Export the `checkOneOrMore` and `isOneOrMore` utility functions. --- src/index.ts | 1 + src/interfaces.ts | 2 ++ src/utils/type-utils.ts | 8 ++++++++ 3 files changed, 11 insertions(+) diff --git a/src/index.ts b/src/index.ts index 6b752c1..2974d5e 100644 --- a/src/index.ts +++ b/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'; diff --git a/src/interfaces.ts b/src/interfaces.ts index e30fb8e..c43c95d 100644 --- a/src/interfaces.ts +++ b/src/interfaces.ts @@ -362,6 +362,8 @@ export type TypeguardResult = /** * 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[]]; diff --git a/src/utils/type-utils.ts b/src/utils/type-utils.ts index 14b2768..3a5b88e 100644 --- a/src/utils/type-utils.ts +++ b/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(arr: T[]): arr is OneOrMore { return arr.length > 0; } +/** + * Returns the original array if and only if it has at least one element. + */ export function checkOneOrMore(arr: T[]): OneOrMore { // istanbul ignore if if (!isOneOrMore(arr)) { From 20d1dd8c630825598925dd754123850c09587661 Mon Sep 17 00:00:00 2001 From: Paco van der Linden Date: Mon, 24 Mar 2025 13:03:54 +0100 Subject: [PATCH 2/2] chore: update docs --- etc/types.api.md | 6 ++++++ markdown/types.checkoneormore.md | 23 +++++++++++++++++++++++ markdown/types.isoneormore.md | 27 +++++++++++++++++++++++++++ markdown/types.md | 2 ++ markdown/types.oneormore.md | 4 ++++ 5 files changed, 62 insertions(+) create mode 100644 markdown/types.checkoneormore.md create mode 100644 markdown/types.isoneormore.md diff --git a/etc/types.api.md b/etc/types.api.md index fd22500..d0ef588 100644 --- a/etc/types.api.md +++ b/etc/types.api.md @@ -110,6 +110,9 @@ export type Branded = T extends WithBrands(arr: T[]): OneOrMore; + // @public export function createType>(impl: Impl, override?: Partial | 'typeValidator' | 'typeParser' | 'customValidators', PropertyDescriptor>>): TypeImpl; @@ -233,6 +236,9 @@ export class IntersectionType>; } +// @public +export function isOneOrMore(arr: T[]): arr is OneOrMore; + // @public export function isType(value: unknown): value is Type; diff --git a/markdown/types.checkoneormore.md b/markdown/types.checkoneormore.md new file mode 100644 index 0000000..083dbfa --- /dev/null +++ b/markdown/types.checkoneormore.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [@skunkteam/types](./types.md) > [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(arr: T[]): OneOrMore; +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | ----- | ----------- | +| arr | T\[\] | | + +**Returns:** + +[OneOrMore](./types.oneormore.md)<T> diff --git a/markdown/types.isoneormore.md b/markdown/types.isoneormore.md new file mode 100644 index 0000000..fb16eb8 --- /dev/null +++ b/markdown/types.isoneormore.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [@skunkteam/types](./types.md) > [isOneOrMore](./types.isoneormore.md) + +## isOneOrMore() function + +Type guard for `OneOrMore` + +**Signature:** + +```typescript +declare function isOneOrMore(arr: T[]): arr is OneOrMore; +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | ----- | ----------- | +| arr | T\[\] | | + +**Returns:** + +arr is [OneOrMore](./types.oneormore.md)<T> + +## Remarks + +This checks if the array has at least one element. diff --git a/markdown/types.md b/markdown/types.md index 9afbdb8..e5f9258 100644 --- a/markdown/types.md +++ b/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 OneOrMore | | [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) | | diff --git a/markdown/types.oneormore.md b/markdown/types.oneormore.md index 5b9fb7f..36e6b41 100644 --- a/markdown/types.oneormore.md +++ b/markdown/types.oneormore.md @@ -11,3 +11,7 @@ An Array with at least one element. ```typescript type OneOrMore = [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.