feat: add guardStringIncludes() and guardStringIncludesSome() fun…

…ctions with tests.

src/guard/lib/guard-string-includes-some.func.ts

@@ -0,0 +1,31 @@
+// Function.
+import { isStringIncludesSome } from '../../is/lib/is-string-includes-some.func';
+import { resultCallback } from '../../lib/result-callback.func';
+// Type.
+import { AnyString } from '../../type/any-string.type';
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be a `string` type or an instance of `String` that includes some of the specified words/sentences.
+ * @param value The value of a generic type variable `Type` constrained by the `AnyString`, by default of the type captured from the
+ * provided `value` to check against the `string` that contains some of the words/sentences from a given `includes`.
+ * @param includes An `Array` of `string` as words/sentences to be case-sensitive searched for within 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 provided `value` is a `string` type or an instance of `String` that
+ * includes all of the specified words/sentences.
+ * @angularpackage
+ */
+export const guardStringIncludesSome = <
+  Type extends AnyString,
+  Payload extends object = object
+>(
+  value: Type,
+  includes: string[],
+  callback: ResultCallback<
+    Type,
+    CallbackPayload<{ includes: typeof includes } & Payload>
+  > = resultCallback,
+  payload?: CallbackPayload<Payload>
+): value is Type =>
+  isStringIncludesSome(value, includes, callback, payload);

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

@@ -0,0 +1,31 @@
+// Function.
+import { isStringIncludes } from '../../is/lib/is-string-includes.func';
+import { resultCallback } from '../../lib/result-callback.func';
+// Type.
+import { AnyString } from '../../type/any-string.type';
+import { CallbackPayload } from '../../type/callback-payload.type';
+import { ResultCallback } from '../../type/result-callback.type';
+/**
+ * Guards the value to be a `string` type or an instance of `String` that includes the specified words/sentences.
+ * @param value The value of a generic type variable `Type` constrained by the `AnyString`, by default of the type captured from the
+ * provided `value` to check against the `string` that contains words/sentences from a given `includes`.
+ * @param includes An `Array` of `string` as words/sentences to be case-sensitive searched for within 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 provided `value` is a `string` type or an instance of `String` that
+ * includes the specified words/sentences.
+ * @angularpackage
+ */
+export const guardStringIncludes = <
+  Type extends AnyString,
+  Payload extends object = object
+>(
+  value: Type,
+  includes: string[],
+  callback: ResultCallback<
+    Type,
+    CallbackPayload<{ includes: typeof includes } & Payload>
+  > = resultCallback,
+  payload?: CallbackPayload<Payload>
+): value is Type =>
+  isStringIncludes(value, includes, callback, payload);

src/guard/test/guard-string-includes-some.spec.ts

@@ -0,0 +1,87 @@
+// Function.
+import { guardStringIncludesSome } from '../lib/guard-string-includes-some.func';
+// Testing.
+import {
+  // Main.
+  Testing,
+
+  // Constant.
+  TESTING_STRING,
+  TESTING_STRING_CONSTRUCTOR,
+} from '@angular-package/testing';
+// Execute tests.
+import { tests } from '../../execute-tests';
+/**
+ * Initialize testing.
+ */
+const testing = new Testing(
+  tests.is.stringIncludesSome.describe,
+  tests.is.stringIncludesSome.it
+);
+/**
+ * Tests.
+ */
+testing.describe(guardStringIncludesSome.name, () => {
+  const TESTING_STRING_LONG = `Lorem Ipsum is simply dummy text of the printing and typesetting industry.
+  Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
+  when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+  It has survived not only five centuries, but also the leap into electronic typesetting,
+  remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset
+  sheets containing Lorem Ipsum passages, and more recently with desktop publishing software
+  like Aldus PageMaker including versions of Lorem Ipsum.`;
+
+  const TESTING_STRING_LONG_INSTANCE = new String(TESTING_STRING_LONG);
+
+  testing
+    // Defined.
+    .it('is DEFINED', () => expect(guardStringIncludesSome).toBeDefined())
+
+    // Checks ...
+    .describe(`checks`, () => {
+      testing
+        .it('callback', () => {
+          guardStringIncludesSome(TESTING_STRING, ['Company'], (result, value, payload) => {
+            expect(result).toBeTrue();
+            if (payload) {
+              expect(value).toEqual(TESTING_STRING);
+            }
+            return result;
+          });
+        })
+        // ... primitives.
+        .describe(`primitive`, () => {
+          testing
+            // string
+            .describe(`string`, () => {
+              testing
+                .it(`TESTING_STRING, TESTING_STRING_LONG`, () => {
+                  expect(guardStringIncludesSome(TESTING_STRING, [TESTING_STRING, '!@#$%^&*()', '3'])).toBeTrue();
+                    // No word exists.
+                  expect(guardStringIncludesSome(TESTING_STRING_LONG, [
+                    'no text',
+                    'no text is here'
+                  ])).toBeFalse();
+
+                  // Every word exists.
+                  expect(guardStringIncludesSome(TESTING_STRING_LONG_INSTANCE, [
+                    'Lorem',
+                    'unchanged',
+                    'versions',
+                    'only',
+                  ])).toBeTrue();
+
+                  // Some word exists.
+                  expect(guardStringIncludesSome(TESTING_STRING_LONG, [
+                    'Lorem',
+                    'unchanged',
+                    'versions',
+                    'only',
+                    'no text is here'
+                  ])).toBeTrue();
+                })
+                .it(`String(${TESTING_STRING})`, () =>
+                  expect(guardStringIncludesSome(TESTING_STRING_CONSTRUCTOR, [TESTING_STRING, '!@#$%^&*()', '3'])).toBeTrue());
+            });
+        });
+    });
+});

src/guard/test/guard-string-includes.spec.ts

@@ -0,0 +1,88 @@
+// Function.
+import { guardStringIncludes } from '../lib/guard-string-includes.func';
+// Testing.
+import {
+  // Main.
+  Testing,
+
+  // Constant.
+  TESTING_STRING,
+  TESTING_STRING_CONSTRUCTOR,
+} from '@angular-package/testing';
+// Execute tests.
+import { tests } from '../../execute-tests';
+/**
+ * Initialize testing.
+ */
+const testing = new Testing(
+  tests.guard.stringIncludes.describe,
+  tests.guard.stringIncludes.it
+);
+/**
+ * Tests.
+ */
+testing.describe(guardStringIncludes.name, () => {
+  const TESTING_STRING_LONG = `Lorem Ipsum is simply dummy text of the printing and typesetting industry.
+  Lorem Ipsum has been the industry's standard dummy text ever since the 1500s,
+  when an unknown printer took a galley of type and scrambled it to make a type specimen book.
+  It has survived not only five centuries, but also the leap into electronic typesetting,
+  remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset
+  sheets containing Lorem Ipsum passages, and more recently with desktop publishing software
+  like Aldus PageMaker including versions of Lorem Ipsum.`;
+
+  const TESTING_STRING_LONG_INSTANCE = new String(TESTING_STRING_LONG);
+
+  testing
+    // Defined.
+    .it('is DEFINED', () => expect(guardStringIncludes).toBeDefined())
+
+    // Checks ...
+    .describe(`checks`, () => {
+      testing
+        .it('callback', () => {
+          guardStringIncludes(TESTING_STRING, ['Company'], (result, value, payload) => {
+            expect(result).toBeTrue();
+            if (payload) {
+              expect(value).toEqual(TESTING_STRING);
+            }
+            return result;
+          });
+        })
+        // ... primitives.
+        .describe(`primitive`, () => {
+          testing
+            // string
+            .describe(`string`, () => {
+              testing
+                .it(`${TESTING_STRING}`, () => {
+                  expect(guardStringIncludes(TESTING_STRING, ['Company'])).toBeTrue();
+                  expect(guardStringIncludes(TESTING_STRING, [TESTING_STRING, '!@#$%^&*()'])).toBeTrue();
+                    // No word exists.
+                  expect(guardStringIncludes(TESTING_STRING_LONG, [
+                    'no text',
+                    'no text is here'
+                  ])).toBeFalse();
+
+                  // Every word exists.
+                  expect(guardStringIncludes(TESTING_STRING_LONG_INSTANCE, [
+                    'Lorem',
+                    'unchanged',
+                    'versions',
+                    'only',
+                  ])).toBeTrue();
+
+                  // Some word exists.
+                  expect(guardStringIncludes(TESTING_STRING_LONG, [
+                    'Lorem',
+                    'unchanged',
+                    'versions',
+                    'only',
+                    'no text is here'
+                  ])).toBeFalse();
+                })
+                .it(`String(${TESTING_STRING})`, () =>
+                  expect(guardStringIncludes(TESTING_STRING_CONSTRUCTOR, [TESTING_STRING, '!@#$%^&*()'])).toBeTrue());
+            });
+        });
+    });
+});