Merge pull request #3 from arghyadeep-k/dev

Dev

Author: arghyadeep-k

.github/workflows/deno-ci.yml

@@ -8,11 +8,13 @@
 
 name: CI
 
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
+on: [push, pull_request]
+  # push:
+  #   branches:
+  #     - dev
+  #     - main
+  # pull_request:
+  #   branches: [main]
 
 jobs:
   test:

README.md

@@ -18,6 +18,12 @@ Deno🦕 module to test if a password/string fulfills all the preset criterias.
 import { checkPassword } from "https://deno.land/x/password_checker/mod.ts";
 ```
 
+or
+
+```typescript
+import { checkPasswordWithResult } from "https://deno.land/x/password_checker/mod.ts";
+```
+
 ## Parameters
 
 ### Mandatory Parameters:
@@ -42,7 +48,13 @@ import { checkPassword } from "https://deno.land/x/password_checker/mod.ts";
 
 ## Output
 
-Returns true if password passes all checks.
+- If `checkPassword()` is invoked:
+  - Returns `true` if password passes all the checks, else `false`.
+- If `checkPasswordWithResult()` is invoked:
+  - `isValid: boolean` - `true` if the password is valid and passes all the
+    checks, else `false`.
+  - `reason: string` - The reason why the input password was marked as invalid.
+    Returns undefined in case `isValid` is `true`.`
 
 ## Usage
 
@@ -93,6 +105,17 @@ isPasswordValid = checkPassword({
 });
 ```
 
+If you want the reason of failure as well, you can use
+`checkPasswordWithResult()` which returns an object of type
+`VerificationResult`.
+
+```typescript
+interface VerificationResult {
+  isValid: boolean;
+  reason?: string;
+}
+```
+
 ## Reference
 
 - https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt

mod.ts

@@ -1,4 +1,4 @@
-interface IParams {
+export interface IParams {
   password: string;
   minLen?: number;
   maxLen?: number;
@@ -8,6 +8,11 @@ interface IParams {
   checkWithCommonPasswords?: boolean;
 }
 
+export interface VerificationResult {
+  isValid: boolean;
+  reason?: string;
+}
+
 const url =
   "https://raw.githubusercontent.com/danielmiessler/SecLists/master/Passwords/Common-Credentials/10k-most-common.txt";
 const response = await fetch(
@@ -16,46 +21,59 @@ const response = await fetch(
 
 const passwordList = await response.text();
 
-export function checkPassword({
+export function checkPasswordWithResult({
   password,
   minLen = 0,
   maxLen = 0,
   containsNum = true,
   containsSpecialChar = true,
   containsAlphabet = true,
   checkWithCommonPasswords = false,
-}: IParams): boolean {
-  if (minLen != 0) {
-    if (password.length < minLen) {
-      return false;
-    }
+}: IParams): VerificationResult {
+  if (minLen != 0 && password.length < minLen) {
+    return {
+      isValid: false,
+      reason: `The password should contain at least ${minLen} characters`,
+    };
   }
-  if (maxLen != 0) {
-    if (password.length > maxLen) {
-      return false;
-    }
+  if (maxLen != 0 && password.length > maxLen) {
+    return {
+      isValid: false,
+      reason: `The password should contain at most ${maxLen} characters`,
+    };
   }
-  if (containsNum) {
-    if (password.search(/\d/) == -1) {
-      return false;
-    }
+  if (containsNum && password.search(/\d/) == -1) {
+    return {
+      isValid: false,
+      reason: "The password should contain at least one digit",
+    };
   }
-  if (containsSpecialChar) {
-    if (password.search(/[^\w\s]/) == -1) {
-      return false;
-    }
+  if (containsSpecialChar && password.search(/[^\w\s]/) == -1) {
+    return {
+      isValid: false,
+      reason: "The password should contain at least one special character",
+    };
   }
-  if (containsAlphabet) {
-    if (password.search(/[A-Za-z]/) == -1) {
-      return false;
-    }
+  if (containsAlphabet && password.search(/[A-Za-z]/) == -1) {
+    return {
+      isValid: false,
+      reason: "The password should contain at least one letter",
+    };
   }
 
-  if (checkWithCommonPasswords) {
-    if (passwordList != undefined && passwordList.includes(password)) {
-      return false;
-    }
+  if (
+    checkWithCommonPasswords && passwordList != undefined &&
+    passwordList.includes(password)
+  ) {
+    return {
+      isValid: false,
+      reason: "The password should not be too common",
+    };
   }
 
-  return true;
+  return { isValid: true };
+}
+
+export function checkPassword(params: IParams): boolean {
+  return checkPasswordWithResult(params).isValid;
 }

mod_test.ts

@@ -1,97 +1,118 @@
 import { assertEquals } from "./test_deps.ts";
-import { checkPassword } from "./mod.ts";
+import {
+  checkPassword,
+  checkPasswordWithResult,
+  IParams,
+  VerificationResult,
+} from "./mod.ts";
 
 Deno.test("Test with defaults", () => {
-  assertEquals(checkPassword({ password: "random123." }), true);
+  assertResult({ password: "random123." }, {
+    isValid: true,
+  });
 });
 
 Deno.test("Test for minimum length", () => {
-  assertEquals(checkPassword({ password: "random123", minLen: 10 }), false);
+  assertResult({ password: "random123", minLen: 10 }, {
+    isValid: false,
+    reason: "The password should contain at least 10 characters",
+  });
 });
 
 Deno.test("Test for maximum length", () => {
-  assertEquals(
-    checkPassword({ password: "random123", minLen: 2, maxLen: 5 }),
-    false,
-  );
+  assertResult({ password: "radnom123", minLen: 2, maxLen: 5 }, {
+    isValid: false,
+    reason: "The password should contain at most 5 characters",
+  });
 });
 
 Deno.test("Test for numbers", () => {
-  assertEquals(
-    checkPassword({
-      password: "random",
-      minLen: 2,
-      maxLen: 10,
-      containsNum: true,
-    }),
-    false,
-  );
+  assertResult({
+    password: "random",
+    minLen: 2,
+    maxLen: 10,
+    containsNum: true,
+  }, {
+    isValid: false,
+    reason: "The password should contain at least one digit",
+  });
 });
 
 Deno.test("Test for special characters", () => {
-  assertEquals(
-    checkPassword({
-      password: "random123",
-      minLen: 2,
-      maxLen: 10,
-      containsNum: true,
-      containsSpecialChar: true,
-    }),
-    false,
-  );
+  assertResult({
+    password: "random123",
+    minLen: 2,
+    maxLen: 10,
+    containsNum: true,
+    containsSpecialChar: true,
+  }, {
+    isValid: false,
+    reason: "The password should contain at least one special character",
+  });
 });
 
 Deno.test("Test for alphabets", () => {
-  assertEquals(
-    checkPassword({
-      password: "123456.!",
-      minLen: 2,
-      maxLen: 10,
-      containsNum: true,
-      containsSpecialChar: true,
-      containsAlphabet: true,
-    }),
-    false,
-  );
+  assertResult({
+    password: "123456.!",
+    minLen: 2,
+    maxLen: 10,
+    containsNum: true,
+    containsSpecialChar: true,
+    containsAlphabet: true,
+  }, {
+    isValid: false,
+    reason: "The password should contain at least one letter",
+  });
 });
 
 Deno.test("Test for all options", () => {
-  assertEquals(
-    checkPassword({
-      password: "abc123456.!",
-      minLen: 2,
-      maxLen: 12,
-      containsNum: true,
-      containsSpecialChar: true,
-      containsAlphabet: true,
-    }),
-    true,
-  );
+  assertResult({
+    password: "abc123456.!",
+    minLen: 2,
+    maxLen: 12,
+    containsNum: true,
+    containsSpecialChar: true,
+    containsAlphabet: true,
+  }, {
+    isValid: true,
+  });
 });
 
 Deno.test("Test for common password - Positive", () => {
-  assertEquals(
-    checkPassword({
-      password: "batman123.?",
-      minLen: 2,
-      maxLen: 12,
-      checkWithCommonPasswords: true,
-    }),
-    true,
-  );
+  assertResult({
+    password: "batman123.?",
+    minLen: 2,
+    maxLen: 12,
+    checkWithCommonPasswords: true,
+  }, {
+    isValid: true,
+  });
 });
 
 Deno.test("Test for common password - Negative", () => {
-  assertEquals(
-    checkPassword({
-      password: "batman",
-      minLen: 2,
-      maxLen: 12,
-      containsNum: false,
-      containsSpecialChar: false,
-      containsAlphabet: true,
-      checkWithCommonPasswords: true,
-    }),
-    false,
-  );
+  assertResult({
+    password: "batman",
+    minLen: 2,
+    maxLen: 12,
+    containsNum: false,
+    containsSpecialChar: false,
+    containsAlphabet: true,
+    checkWithCommonPasswords: true,
+  }, {
+    isValid: false,
+    reason: "The password should not be too common",
+  });
 });
+
+/**
+ * Test both `checkPassword` and `checkPasswordWithResult` against the provided case with custom assert function
+ * @param params
+ * @param expectedResult
+ */
+function assertResult(params: IParams, expectedResult: VerificationResult) {
+  // Invoking checkPassword()
+  assertEquals(checkPassword(params), expectedResult.isValid);
+
+  // Invoking checkPasswordWithResult()
+  assertEquals(checkPasswordWithResult(params), expectedResult);
+}