feat(guard): add guardDate(), guardFalse(), guardNumberBetween(), guardObjectKeyIn(), guardObjectSomeKeys(), guardRegExp(), guardStringLength(), guardTrue()`.

Author: sciborrudnicki

src/guard/index.ts

@@ -5,17 +5,25 @@ export { guardArray } from './lib/guard-array.func';
 export { guardBigInt } from './lib/guard-big-int.func';
 export { guardBoolean } from './lib/guard-boolean.func';
 export { guardClass } from './lib/guard-class.func';
+export { guardDate  } from './lib/guard-date.func';
 export { guardDefined } from './lib/guard-defined.func';
+export { guardFalse  } from './lib/guard-false.func';
 export { guardFunction } from './lib/guard-function.func';
 export { guardInstance } from './lib/guard-instance.func';
 export { guardKey } from './lib/guard-key.func';
-export { guardNumber } from './lib/guard-number.func';
 export { guardNull } from './lib/guard-null.func';
+export { guardNumber } from './lib/guard-number.func';
+export { guardNumberBetween } from './lib/guard-number-between.func';
 export { guardObject } from './lib/guard-object.func';
 export { guardObjectKey } from './lib/guard-object-key.func';
+export { guardObjectKeyIn } from './lib/guard-object-key-in.func';
 export { guardObjectKeys } from './lib/guard-object-keys.func';
+export { guardObjectSomeKeys } from './lib/guard-object-some-keys.func';
 export { guardPrimitive } from './lib/guard-primitive.func';
+export { guardRegExp } from './lib/guard-regexp.func';
 export { guardString } from './lib/guard-string.func';
+export { guardStringLength } from './lib/guard-string-length.func';
 export { guardSymbol } from './lib/guard-symbol.func';
+export { guardTrue } from './lib/guard-true.func';
 export { guardType } from './lib/guard-type.func';
 export { guardUndefined } from './lib/guard-undefined.func';

src/guard/lib/guard-date.func.ts

@@ -0,0 +1,18 @@
+// Function.
+import { isDate } from '../../is/lib/is-date.func';
+// Type.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be a date.
+ * @param value The value of `Date` type to guard.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the value is a date.
+ */
+export const guardDate = <Payload extends object>(
+  value: Date,
+  callback?: ResultCallback<Date, CallbackPayload<Payload>>,
+  payload?: CallbackPayload<Payload>
+): value is Date =>
+  isDate(value, callback, payload);

src/guard/lib/guard-false.func.ts

@@ -0,0 +1,18 @@
+// Function.
+import { isFalse } from '../../is/lib/is-false.func';
+// Type.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the provided value to be `false`.
+ * @param value The value of `false` type to guard.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the `value` is a `boolean` type or an instance of `Boolean` equal to `false`.
+ */
+export const guardFalse = <Payload extends object>(
+  value: false,
+  callback?: ResultCallback<false, CallbackPayload<Payload>>,
+  payload?: CallbackPayload<Payload>
+): value is false =>
+  isFalse(value, callback, payload);

src/guard/lib/guard-number-between.func.ts

@@ -0,0 +1,31 @@
+// Function.
+import { isNumberBetween } from '../../is/lib/is-number-between.func';
+// Interface.
+import { MinMax } from '../../interface/min-max.interface';
+// Type.
+import { AnyNumber } from '../../type/any-number.type';
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { NumberBetween } from '../../type/number-between.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be `number` between the specified range.
+ * @param value The value of a generic type variable `Type` constrained by `AnyNumber`, by default of the type captured from the
+ * provided `value`, to guard.
+ * @param range An `object` of optional minimum and maximum `range` of the provided `value`.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the `value` is a `number` type or an instance of `Number` between the
+ * specified range.
+ */
+export const guardNumberBetween = <
+  Type extends AnyNumber,
+  Min extends number,
+  Max extends number,
+  Payload extends object = object
+>(
+  value: Type,
+  range: MinMax<Min, Max>,
+  callback?: ResultCallback<Type, CallbackPayload<MinMax<Min, Max> & Payload>>,
+  payload?: CallbackPayload<Payload>
+): value is NumberBetween<Min, Max, Type> =>
+  isNumberBetween(value, range, callback, payload);

src/guard/lib/guard-object-key-in.func.ts

@@ -0,0 +1,29 @@
+// Function.
+import { isObjectKeyIn } from '../../is/lib/is-object-key-in.func';
+// Type.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the `value` to be an `object` of a generic type variable `Obj` that contains(or its prototype chain) the given `key`.
+ * @param value An `object` of a generic type variable `Obj`, by default of the type captured from the provided `value` that contains
+ * (or its prototype chain) the given `key`.
+ * @param key A key of `Obj` type as the name of the property that the given `value` contains(or its prototype chain).
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the `value` is an `object` that contains(or its prototype chain) the given
+ * `key`.
+ */
+export const guardObjectKeyIn = <
+  Obj extends object,
+  Key extends keyof Obj,
+  Payload extends object = object
+>(
+  value: Obj,
+  key: Key,
+  callback?: ResultCallback<
+    Obj,
+    CallbackPayload<{ key: typeof key } & Payload>
+  >,
+  payload?: CallbackPayload<Payload>
+): value is Obj =>
+  isObjectKeyIn(value, key, callback, payload as any);

src/guard/lib/guard-object-some-keys.func.ts

@@ -0,0 +1,29 @@
+// Function.
+import { isObjectSomeKeys } from '../../is/lib/is-object-some-keys.func';
+// Type.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be an `object` of a generic type variable `Obj` with its specified `keys`.
+ * @param value An object of a generic type variable `Obj`, by default of the type captured from the `value` that contains some or some of
+ * the groups of the given `keys`, to guard.
+ * @param keys An `Array` of property names or a two-dimensional array of property names to check if the given `value` contains some of them
+ * or some groups of them.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the provided `value` is an `object` with some or some groups of its keys from
+ * a given `keys`.
+ * @angularpackage
+ */
+export const guardObjectSomeKeys = <
+  Obj extends object,
+  Payload extends object = object
+>(
+  value: Obj,
+  keys: (keyof Obj | Array<keyof Obj>)[],
+  callback?: ResultCallback<
+    Obj,
+    CallbackPayload<{ keys: typeof keys } & Payload>
+  >,
+  payload?: CallbackPayload<Payload>
+): value is Obj => isObjectSomeKeys(value, keys, callback, payload as any);

src/guard/lib/guard-regexp.func.ts

@@ -0,0 +1,18 @@
+// Function.
+import { isRegExp } from '../../is/lib/is-regexp.func';
+// Type.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be a `RegExp`.
+ * @param value A `RegExp` type value to guard.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return `value` is a `boolean` indicating whether the `value` is a `RegExp`.
+ */
+export const guardRegExp = <Payload extends object>(
+  value: RegExp,
+  callback?: ResultCallback<RegExp, CallbackPayload<Payload>>,
+  payload?: CallbackPayload<Payload>
+): value is RegExp =>
+  isRegExp(value, callback, payload);

src/guard/lib/guard-string-length.func.ts

@@ -0,0 +1,31 @@
+// Function.
+import { isStringLength } from '../../is';
+// Interface.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { MinMax } from '../../interface/min-max.interface';
+// Type.
+import { AnyString } from '../../type/any-string.type';
+import { ResultCallback } from '../../type/result-callback.type';
+import { StringOfLength } from '../../type/string-of-length.type';
+/**
+ * Guards the value to be a `string` of a length between the specified range.
+ * @param value The value of a generic type variable `Type` constrained by `AnyString`, by default of the type captured from the
+ * provided `value` to guard.
+ * @param length An `object` of optional minimum and a maximum `length` of the given `value`.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the `value` is a `string` type or an instance of `String` of a length between
+ * the specified range.
+ */
+export const guardStringLength = <
+  Type extends AnyString,
+  Min extends number,
+  Max extends number,
+  Payload extends object = object
+>(
+  value: Type,
+  length: MinMax<Min, Max>,
+  callback?: ResultCallback<Type, CallbackPayload<MinMax<Min, Max> & Payload>>,
+  payload?: CallbackPayload<Payload>
+): value is StringOfLength<Min, Max, Type> =>
+  isStringLength(value, length, callback, payload);

src/guard/lib/guard-true.func.ts

@@ -0,0 +1,18 @@
+// Function.
+import { isTrue } from '../../is/lib/is-true.func';
+// Type.
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be `true`.
+ * @param value The value of `true` type to guard.
+ * @param callback An optional `ResultCallback` function to handle the result before returns.
+ * @param payload An optional `object` of `CallbackPayload<Payload>` that is assigned to the `payload` of the provided `callback` function.
+ * @returns The return value is a `boolean` indicating whether the `value` is a `boolean` type or an instance of `Boolean` equal to `true`.
+ */
+export const guardTrue = <Payload extends object>(
+  value: true,
+  callback?: ResultCallback<true, CallbackPayload<Payload>>,
+  payload?: CallbackPayload<Payload>
+): value is true =>
+  isTrue(value, callback, payload);

src/guard/test/guard-array.spec.ts

@@ -1,46 +1,53 @@
 // Function.
 import { guardArray } from '../lib/guard-array.func';
-// Constant.
+// Testing.
 import {
-  ARRAY_BIGINT,
-  ARRAY_BOOLEAN,
-  ARRAY_CLASS,
-  ARRAY_FUNCTION,
-  ARRAY_NULL,
-  ARRAY_NUMBER,
-  ARRAY_OBJECT_ONE,
-  ARRAY_OBJECT_TWO,
-  ARRAY_STRING,
-  ARRAY_SYMBOL_NUMBER,
-  ARRAY_SYMBOL_STRING,
-  ARRAY_UNDEFINED
-} from '../../testing/src/strict/array.const';
-import { Class } from '../../testing/src/strict/class.const';
-// Type.
-import { Func } from '../../type/func.type';
-// Interface.
-import { ObjectOne, ObjectTwo } from '../../testing/interface';
+  // Main.
+  Testing,
 
-describe(guardArray.name, () => {
-  // TRUE
-  it('is DEFINED', () => {
-    expect(guardArray).toBeDefined();
-  });
+  // Constants.
+  TESTING_ARRAY_BIGINT,
+  TESTING_ARRAY_BOOLEAN,
+  TESTING_ARRAY_CLASS,
+  TESTING_ARRAY_FUNCTION,
+  TESTING_ARRAY_NULL,
+  TESTING_ARRAY_NUMBER,
+  TESTING_ARRAY_OBJECT_ONE,
+  TESTING_ARRAY_STRING,
+  TESTING_ARRAY_SYMBOL_NUMBER,
+  TESTING_ARRAY_SYMBOL_STRING,
+  TESTING_ARRAY_UNDEFINED,
 
-  it('Array<bigint>', () => expect(guardArray<bigint>(ARRAY_BIGINT)).toBeTruthy());
-  it('Array<boolean>', () => expect(guardArray<boolean | Boolean>(ARRAY_BOOLEAN)).toBeTruthy());
-  it('Array<Class>', () => expect(guardArray<Class>(ARRAY_CLASS)).toBeTruthy());
-  it('Array<Func>', () => expect(guardArray<Func>(ARRAY_FUNCTION)).toBeTruthy());
-  it('Array<null>', () => expect(guardArray<null>(ARRAY_NULL)).toBeTruthy());
-  it('Array<number>', () => expect(guardArray<number | Number>(ARRAY_NUMBER)).toBeTruthy());
-  it('Array<ObjectOne> Array<ObjectTwo>', () => {
-    expect(guardArray<ObjectOne>(ARRAY_OBJECT_ONE)).toBeTruthy();
-    expect(guardArray<ObjectTwo>(ARRAY_OBJECT_TWO)).toBeTruthy();
-  });
-  it('Array<string>', () => expect(guardArray<string | String>(ARRAY_STRING)).toBeTruthy());
-  it('Array<symbol>', () => {
-    expect(guardArray<symbol>(ARRAY_SYMBOL_STRING)).toBeTruthy();
-    expect(guardArray<symbol>(ARRAY_SYMBOL_NUMBER)).toBeTruthy();
-  });
-  it('Array<undefined>', () => expect(guardArray<undefined | unknown>(ARRAY_UNDEFINED)).toBeTruthy());
+  // Class.
+  TestingClass,
+} from '@angular-package/testing';
+// Execute tests.
+import { tests } from '../../execute-tests';
+/**
+ * Initialize testing.
+ */
+const testing = new Testing(
+  tests.is.array.describe,
+  tests.is.array.it
+);
+/**
+ * Tests.
+ */
+testing.describe(guardArray.name, () => {
+  testing
+    // TRUE
+    .it('is DEFINED', () => expect(guardArray).toBeDefined())
+    .it('Array<bigint>', () => expect(guardArray<bigint>(TESTING_ARRAY_BIGINT)).toBeTruthy())
+    .it('Array<boolean>', () => expect(guardArray<boolean | Boolean>(TESTING_ARRAY_BOOLEAN)).toBeTruthy())
+    .it('Array<TestingClass>', () => expect(guardArray<TestingClass>(TESTING_ARRAY_CLASS)).toBeTruthy())
+    .it('Array<Func>', () => expect(guardArray<Function>(TESTING_ARRAY_FUNCTION)).toBeTruthy())
+    .it('Array<null>', () => expect(guardArray<null>(TESTING_ARRAY_NULL)).toBeTruthy())
+    .it('Array<number>', () => expect(guardArray<number | Number>(TESTING_ARRAY_NUMBER)).toBeTruthy())
+    .it('Array<ObjectOne> Array<ObjectTwo>', () => expect(guardArray(TESTING_ARRAY_OBJECT_ONE)).toBeTruthy())
+    .it('Array<string>', () => expect(guardArray<string | String>(TESTING_ARRAY_STRING)).toBeTruthy())
+    .it('Array<symbol>', () => {
+      expect(guardArray(TESTING_ARRAY_SYMBOL_STRING)).toBeTruthy();
+      expect(guardArray(TESTING_ARRAY_SYMBOL_NUMBER)).toBeTruthy();
+    })
+    .it('Array<undefined>', () => expect(guardArray<undefined | unknown>(TESTING_ARRAY_UNDEFINED)).toBeTruthy());
 });

src/guard/test/guard-bigint.spec.ts

@@ -1,30 +1,50 @@
+// Testing.
+import {
+  // Main.
+  Testing,
+
+  // Constant.
+  TESTING_TRUE,
+  TESTING_BIGINT
+} from '@angular-package/testing';
+// Execute tests.
+import { tests } from '../../execute-tests';
 // Function.
 import { guardBigInt } from '../lib/guard-big-int.func';
-// Constant.
-import { BIGINT, BIGINT_EXPECTATION, BIGINT_INSTANCE } from '../../testing/src/strict/big-int.const';
-import { TRUE } from '../../testing/src/strict/boolean.const';
-
-describe(guardBigInt.name, () => {
-  // Defined.
-  it('is DEFINED', () => expect(guardBigInt).toBeDefined());
-
-  // Checks ...
-  describe(`checks`, () => {
-    it('callback', () => {
-      guardBigInt(BIGINT, (result: boolean, value: bigint) => {
-        expect(result).toBe(TRUE);
-        expect(value).toEqual(BIGINT);
-        return result;
-      });
-    });
-
-    // ... primitives.
-    describe(`primitive`, () => {
-      // bigint
-      describe(`bigint`, () => {
-        it(`${BIGINT}`, () => expect(guardBigInt(BIGINT)).toBe(TRUE));
-        it(`${BIGINT_EXPECTATION}`, () => expect(guardBigInt(BIGINT_INSTANCE)).toBe(TRUE));
+/**
+ * Initialize testing.
+ */
+const testing = new Testing(
+  tests.guard.bigint.describe,
+  tests.guard.bigint.it
+);
+/**
+ * Tests.
+ */
+testing.describe(guardBigInt.name, () => {
+  testing
+    // Defined.
+    .it('is DEFINED', () => expect(guardBigInt).toBeDefined())
+    // Checks ...
+    .describe(`guards`, () => {
+      testing
+      .it('with callback and payload', () => {
+        guardBigInt(TESTING_BIGINT, (result, value, payload) => {
+          expect(result).toBe(TESTING_TRUE);
+          expect(value).toEqual(TESTING_BIGINT);
+          if (payload) {
+            expect(payload.action).toEqual('action');
+            expect(payload.name).toEqual('name');
+            expect(payload.param).toEqual('param');
+          }
+          return result;
+        }, { action: 'action', name: 'name', param: 'param' });
+      })
+      // ... primitives.
+      .describe(`primitive`, () => {
+        testing
+          // bigint
+          .describe(`bigint`, () => it(`${TESTING_BIGINT}`, () => expect(guardBigInt(TESTING_BIGINT)).toBe(TESTING_TRUE)));
       });
     });
-  });
 });