fix: make guard a transformation instead of validation

Author: EskiMojo14

library/src/actions/guard/guard.test-d.ts

@@ -13,44 +13,39 @@ describe('guard', () => {
   describe('should return action object', () => {
     test('with no message', () => {
       expectTypeOf(guard(isPixelString)).toEqualTypeOf<
-        GuardAction<string, typeof isPixelString, undefined>
+        GuardAction<string, PixelString, undefined>
       >();
     });
     test('with string message', () => {
       expectTypeOf(
-        guard<string, typeof isPixelString, 'message'>(isPixelString, 'message')
-      ).toEqualTypeOf<GuardAction<string, typeof isPixelString, 'message'>>();
+        guard<string, PixelString, 'message'>(isPixelString, 'message')
+      ).toEqualTypeOf<GuardAction<string, PixelString, 'message'>>();
     });
 
     test('with function message', () => {
       expectTypeOf(
-        guard<string, typeof isPixelString, () => string>(
-          isPixelString,
-          () => 'message'
-        )
-      ).toEqualTypeOf<
-        GuardAction<string, typeof isPixelString, () => string>
-      >();
+        guard<string, PixelString, () => string>(isPixelString, () => 'message')
+      ).toEqualTypeOf<GuardAction<string, PixelString, () => string>>();
     });
   });
 
   describe('should infer correct types', () => {
     test('of input', () => {
       expectTypeOf<
-        InferInput<GuardAction<string, typeof isPixelString, undefined>>
+        InferInput<GuardAction<string, PixelString, undefined>>
       >().toEqualTypeOf<string>();
     });
 
     test('of output', () => {
       expectTypeOf<
-        InferOutput<GuardAction<string, typeof isPixelString, undefined>>
+        InferOutput<GuardAction<string, PixelString, undefined>>
       >().toEqualTypeOf<PixelString>();
     });
 
     test('of issue', () => {
       expectTypeOf<
-        InferIssue<GuardAction<string, typeof isPixelString, undefined>>
-      >().toEqualTypeOf<GuardIssue<string, typeof isPixelString>>();
+        InferIssue<GuardAction<string, PixelString, undefined>>
+      >().toEqualTypeOf<GuardIssue<string, PixelString>>();
     });
   });
 

library/src/actions/guard/guard.test.ts

@@ -9,21 +9,20 @@ describe('guard', () => {
     /^\d+px$/u.test(input);
 
   const baseAction: Omit<
-    GuardAction<string, typeof isPixelString, undefined>,
+    GuardAction<string, PixelString, undefined>,
     'message'
   > = {
-    kind: 'validation',
+    kind: 'transformation',
     type: 'guard',
     reference: guard,
-    expects: null,
     requirement: isPixelString,
     async: false,
     '~run': expect.any(Function),
   };
 
   describe('should return action object', () => {
     test('with undefined message', () => {
-      const action: GuardAction<string, typeof isPixelString, undefined> = {
+      const action: GuardAction<string, PixelString, undefined> = {
         ...baseAction,
         message: undefined,
       };
@@ -32,7 +31,7 @@ describe('guard', () => {
     });
 
     test('with string message', () => {
-      const action: GuardAction<string, typeof isPixelString, 'message'> = {
+      const action: GuardAction<string, PixelString, 'message'> = {
         ...baseAction,
         message: 'message',
       };
@@ -41,11 +40,10 @@ describe('guard', () => {
 
     test('with function message', () => {
       const message = () => 'message';
-      const action: GuardAction<string, typeof isPixelString, typeof message> =
-        {
-          ...baseAction,
-          message,
-        };
+      const action: GuardAction<string, PixelString, typeof message> = {
+        ...baseAction,
+        message,
+      };
       expect(guard(isPixelString, message)).toStrictEqual(action);
     });
   });
@@ -61,10 +59,10 @@ describe('guard', () => {
   test('should return dataset with issues', () => {
     const action = guard(isPixelString, 'message');
     const baseIssue: Omit<
-      GuardIssue<string, typeof isPixelString>,
+      GuardIssue<string, PixelString>,
       'input' | 'received'
     > = {
-      kind: 'validation',
+      kind: 'transformation',
       type: 'guard',
       expected: null,
       message: 'message',
@@ -86,6 +84,6 @@ describe('guard', () => {
           received: '"123"',
         },
       ],
-    } satisfies FailureDataset<GuardIssue<string, typeof isPixelString>>);
+    } satisfies FailureDataset<GuardIssue<string, PixelString>>);
   });
 });

library/src/actions/guard/guard.ts

@@ -1,32 +1,41 @@
 import type {
   BaseIssue,
-  BaseValidation,
+  BaseTransformation,
   ErrorMessage,
 } from '../../types/index.ts';
 import { _addIssue } from '../../utils/index.ts';
 
-export type Guard<TInput> = (input: TInput) => input is TInput;
+export type Guard<TInput, TOutput extends TInput> = (
+  input: TInput
+) => input is TOutput;
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type InferGuarded<TGuard extends Guard<any>> = TGuard extends (
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  input: any
-) => input is infer TGuarded
-  ? TGuarded
-  : never;
+/**
+ * Guard issue interface.
+ */
+export interface GuardIssue<TInput, TOutput extends TInput>
+  extends BaseIssue<TInput> {
+  /**
+   * The issue kind.
+   */
+  readonly kind: 'transformation';
+  /**
+   * The validation type.
+   */
+  readonly type: 'guard';
+  /**
+   * The validation requirement.
+   */
+  readonly requirement: Guard<TInput, TOutput>;
+}
 
 /**
  * Guard action interface.
  */
 export interface GuardAction<
   TInput,
-  TGuard extends Guard<TInput>,
-  TMessage extends ErrorMessage<GuardIssue<TInput, TGuard>> | undefined,
-> extends BaseValidation<
-    TInput,
-    InferGuarded<TGuard>,
-    GuardIssue<TInput, TGuard>
-  > {
+  TOutput extends TInput,
+  TMessage extends ErrorMessage<GuardIssue<TInput, TOutput>> | undefined,
+> extends BaseTransformation<TInput, TOutput, GuardIssue<TInput, TOutput>> {
   /**
    * The action type.
    */
@@ -35,46 +44,25 @@ export interface GuardAction<
    * The action reference.
    */
   readonly reference: typeof guard;
-  /**
-   * The expected property.
-   */
-  readonly expects: null;
   /**
    * The guard function.
    */
-  readonly requirement: TGuard;
+  readonly requirement: Guard<TInput, TOutput>;
   /**
    * The error message.
    */
   readonly message: TMessage;
 }
-
-/**
- * Guard issue interface.
- */
-export interface GuardIssue<TInput, TGuard extends Guard<TInput>>
-  extends BaseIssue<TInput> {
-  /**
-   * The validation type.
-   */
-  type: 'guard';
-  /**
-   * The validation requirement.
-   */
-  requirement: TGuard;
-}
-
 /**
  * Creates a guard validation action.
  *
  * @param requirement The guard function.
  *
  * @returns A guard action.
  */
-// overload for a known input, i.e. within a pipe
-export function guard<TInput, const TGuard extends Guard<TInput>>(
-  requirement: TGuard
-): GuardAction<TInput, TGuard, undefined>;
+export function guard<TInput, TOutput extends TInput>(
+  requirement: Guard<TInput, TOutput>
+): GuardAction<TInput, TOutput, undefined>;
 
 /**
  * Creates a guard validation action.
@@ -84,64 +72,29 @@ export function guard<TInput, const TGuard extends Guard<TInput>>(
  *
  * @returns A guard action.
  */
-// overload for a known input, i.e. within a pipe
 export function guard<
   TInput,
-  const TGuard extends Guard<TInput>,
-  const TMessage extends ErrorMessage<GuardIssue<TInput, TGuard>> | undefined,
+  TOutput extends TInput,
+  const TMessage extends ErrorMessage<GuardIssue<TInput, TOutput>> | undefined,
 >(
-  requirement: TGuard,
+  requirement: Guard<TInput, TOutput>,
   message: TMessage
-): GuardAction<TInput, TGuard, TMessage>;
-
-/**
- * Creates a guard validation action.
- *
- * @param requirement The guard function.
- *
- * @returns A guard action.
- */
-// overload for an unknown input, i.e. standalone
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function guard<const TGuard extends Guard<any>>(
-  requirement: TGuard
-): GuardAction<Parameters<TGuard>[0], TGuard, undefined>;
-
-/**
- * Creates a guard validation action.
- *
- * @param requirement The guard function.
- * @param message The error message.
- *
- * @returns A guard action.
- */
-// overload for an unknown input, i.e. standalone
-export function guard<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const TGuard extends Guard<any>,
-  const TMessage extends
-    | ErrorMessage<GuardIssue<Parameters<TGuard>[0], TGuard>>
-    | undefined,
->(
-  requirement: TGuard,
-  message: TMessage
-): GuardAction<Parameters<TGuard>[0], TGuard, TMessage>;
+): GuardAction<TInput, TOutput, TMessage>;
 
 // @__NO_SIDE_EFFECTS__
 export function guard(
-  requirement: Guard<unknown>,
-  message?: ErrorMessage<GuardIssue<unknown, Guard<unknown>>>
+  requirement: Guard<unknown, unknown>,
+  message?: ErrorMessage<GuardIssue<unknown, unknown>>
 ): GuardAction<
   unknown,
-  Guard<unknown>,
-  ErrorMessage<GuardIssue<unknown, Guard<unknown>>> | undefined
+  unknown,
+  ErrorMessage<GuardIssue<unknown, unknown>> | undefined
 > {
   return {
-    kind: 'validation',
+    kind: 'transformation',
     type: 'guard',
     reference: guard,
     async: false,
-    expects: null,
     requirement,
     message,
     '~run'(dataset, config) {

website/src/routes/api/(actions)/guard/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: guard
-description: Creates a guard validation action.
+description: Creates a guard transformation action.
 source: /actions/guard/guard.ts
 contributors:
   - EskiMojo14
@@ -11,16 +11,16 @@ import { properties } from './properties';
 
 # guard
 
-Creates a guard validation action.
+Creates a guard transformation action.
 
 ```ts
-const Action = v.guard<TInput, TGuard, TMessage>(requirement, message);
+const Action = v.guard<TInput, TOutput, TMessage>(requirement, message);
 ```
 
 ## Generics
 
 - `TInput` <Property {...properties.TInput} />
-- `TGuard` <Property {...properties.TGuard} />
+- `TOutput` <Property {...properties.TOutput} />
 - `TMessage` <Property {...properties.TMessage} />
 
 ## Parameters
@@ -34,6 +34,8 @@ With `guard` you can freely validate the input and return `true` if it is valid
 
 This is especially useful if you have an existing type predicate (for example, from an external library).
 
+> `guard` is useful for narrowing known types. For validating completely unknown values, consider [`custom`](../custom/) instead.
+
 ## Returns
 
 - `Action` <Property {...properties.Action} />
@@ -49,9 +51,7 @@ Schema to validate a pixel string.
 ```ts
 const PixelStringSchema = v.pipe(
   v.string(),
-  v.guard((input): input is `${number}px` =>
-    typeof input === 'string' ? /^\d+px$/.test(input) : false
-  )
+  v.guard((input): input is `${number}px` => /^\d+px$/.test(input))
 );
 ```