feat: add translations for custom matchers

README.md

@@ -1,6 +1,7 @@
 # @zxcvbn-custom-matchers
 
 The package is adding custom matchers to the zxcvbn-ts package. The matchers enforce specific character requirements in passwords and provide feedback and scoring.
+> Please note! this package works only with zxcvbn-ts v.4 and above.
 
 ## Installation
 ```sh
@@ -9,25 +10,33 @@ npm install zxcvbn-custom-matchers
 
 ### Usage
 ```ts
-import { zxcvbnOptions } from '@zxcvbn-ts/core';
+import { ZxcvbnFactory } from '@zxcvbn-ts/core';
 import {
-    lowercaseMatcher,
     numberMatcher,
     specialMatcher,
+    lowercaseMatcher,
     uppercaseMatcher,
-    minLengthMatcher
+    minLengthMatcher,
+    customMatchersTranslations
 } from 'zxcvbn-custom-matchers';
-
-// Add the matchers
-zxcvbnOptions.addMatcher('lowercase', lowercaseMatcher);
-zxcvbnOptions.addMatcher('number', numberMatcher);
-zxcvbnOptions.addMatcher('special', specialMatcher);
-zxcvbnOptions.addMatcher('uppercase', uppercaseMatcher);
-zxcvbnOptions.addMatcher('minLength', minLengthMatcher(10));
+import { merge } from 'lodash';
+
+// Add the custom matchers and their translations
+const options = {
+    translations: merge({}, zxcvbnEnPackage.translations, customMatchersTranslations)
+};
+const customMatchers = {
+    minLength: minLengthMatcher(commons.MIN_PASSWORD_LENGTH),
+    specialRequired: specialMatcher,
+    numberRequired: numberMatcher,
+    lowercaseRequired: lowercaseMatcher,
+    uppercaseRequired: uppercaseMatcher
+};
+const zxcvbn = new ZxcvbnFactory(options, customMatchers);
 
 // Use zxcvbn as usual
 import { zxcvbn } from '@zxcvbn-ts/core';
-const result = zxcvbn('password123');
+const result = zxcvbn.check('password123');
 console.log(result);
 ```
 

package.json

@@ -28,7 +28,7 @@
     "@types/mocha": "^10.0.10",
     "@typescript-eslint/eslint-plugin": "^6.7.5",
     "@typescript-eslint/parser": "^6.7.5",
-    "@zxcvbn-ts/core": "^3.0.4",
+    "@zxcvbn-ts/core": "^4.0.0-beta.2",
     "chai": "^4.5.0",
     "depcheck": "^1.4.3",
     "eslint": "^8.18.0",
@@ -40,5 +40,8 @@
     "nyc": "^17.1.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@zxcvbn-ts/core": "^4.0.0-beta.2"
   }
 }

src/index.ts

@@ -1,5 +1,6 @@
-export { uppercaseMatcher } from './matchers/uppercaseMatcher';
 export { minLengthMatcher } from './matchers/minLengthMatcher';
+export { uppercaseMatcher } from './matchers/uppercaseMatcher';
 export { lowercaseMatcher } from './matchers/lowercaseMatcher';
 export { numberMatcher } from './matchers/numberMatcher';
 export { specialMatcher } from './matchers/specialMatcher';
+export { customMatchersTranslations } from './translations';

src/matchers/lowercaseMatcher.ts

@@ -9,12 +9,15 @@ export const lowercaseMatcher: Matcher = {
           return matches;
         }
       }
-      matches.push({ pattern: 'lowercase', token: password, i: 0, j: password.length - 1 });
+      matches.push({ pattern: 'lowercaseRequired', token: password, i: 0, j: password.length - 1 });
       return matches;
     }
   },
-  feedback(_match) {
-    return { warning: 'Include at least one lowercase letter.', suggestions: [] };
+  feedback: options => {
+    return {
+      warning: options.translations.warnings.lowercaseRequired || 'lowercaseRequired',
+      suggestions: [options.translations.suggestions.lowercaseRequired || 'lowercaseRequired'],
+    };
   },
   scoring(_match) {
     return -100;

src/matchers/minLengthMatcher.ts

@@ -10,8 +10,11 @@ export const minLengthMatcher = (minLength: number): Matcher => ({
       return matches;
     }
   },
-  feedback(_match) {
-    return { warning: `Password may not be shorter than ${minLength} characters.`, suggestions: [] };
+  feedback: options => {
+    return {
+      warning: options.translations.warnings.minLength?.replace('%s', minLength) || 'minLength',
+      suggestions: [options.translations.suggestions.minLength?.replace('%s', minLength) || 'minLength'],
+    };
   },
   scoring(_match) {
     return -100;

src/matchers/numberMatcher.ts

@@ -9,12 +9,15 @@ export const numberMatcher: Matcher = {
           return matches;
         }
       }
-      matches.push({ pattern: 'number', token: password, i: 0, j: password.length - 1 });
+      matches.push({ pattern: 'numberRequired', token: password, i: 0, j: password.length - 1 });
       return matches;
     }
   },
-  feedback(_match) {
-    return { warning: 'Include at least one number.', suggestions: [] };
+  feedback: options => {
+    return {
+      warning: options.translations.warnings.numberRequired || 'numberRequired',
+      suggestions: [options.translations.suggestions.numberRequired || 'numberRequired'],
+    };
   },
   scoring(_match) {
     return -100;

src/matchers/specialMatcher.ts

@@ -10,12 +10,15 @@ export const specialMatcher: Matcher = {
           return matches;
         }
       }
-      matches.push({ pattern: 'special', token: password, i: 0, j: password.length - 1 });
+      matches.push({ pattern: 'specialRequired', token: password, i: 0, j: password.length - 1 });
       return matches;
     }
   },
-  feedback(_match) {
-    return { warning: 'Include at least one special character.', suggestions: [] };
+  feedback: options => {
+    return {
+      warning: options.translations.warnings.specialRequired || 'specialRequired',
+      suggestions: [options.translations.suggestions.specialRequired || 'specialRequired'],
+    };
   },
   scoring(_match) {
     return -100;

src/matchers/uppercaseMatcher.ts

@@ -9,12 +9,15 @@ export const uppercaseMatcher: Matcher = {
           return matches;
         }
       }
-      matches.push({ pattern: 'uppercase', token: password, i: 0, j: password.length - 1 });
+      matches.push({ pattern: 'uppercaseRequired', token: password, i: 0, j: password.length - 1 });
       return matches;
     }
   },
-  feedback(_match) {
-    return { warning: 'Include at least one uppercase letter.', suggestions: [] };
+  feedback: options => {
+    return {
+      warning: options.translations.warnings.uppercaseRequired || 'uppercaseRequired',
+      suggestions: [options.translations.suggestions.uppercaseRequired || 'uppercaseRequired'],
+    };
   },
   scoring(_match) {
     return -100;

src/translations.ts

@@ -0,0 +1,17 @@
+export const customMatchersTranslations = {
+  warnings: {
+    lowercaseRequired: 'At least one lowercase letter is required.',
+    minLength: 'Password must be at least %s characters long.',
+    numberRequired: 'At least one number is required.',
+    specialRequired: 'At least one special character is required.',
+    uppercaseRequired: 'At least one uppercase letter is required.',
+  },
+  suggestions: {
+    lowercaseRequired: 'Include at least one lowercase letter.',
+    minLength: 'Password may not be shorter than %s characters.',
+    numberRequired: 'Include at least one number.',
+    specialRequired: 'Include at least one special character.',
+    uppercaseRequired: 'Include at least one uppercase letter.',
+  },
+  timeEstimation: {},
+};

tests/unit/matchers.test.ts

@@ -1,21 +1,20 @@
 import 'mocha';
 import { expect } from 'chai';
 import { uppercaseMatcher, lowercaseMatcher, numberMatcher, specialMatcher, minLengthMatcher } from '../../src';
+import { customMatchersTranslations } from '../../src/translations';
 
 describe('uppercaseMatcher', () => {
   it('should return a match for missing uppercase letters', () => {
     const result = uppercaseMatcher.Matching.prototype.match({ password: 'password123!' });
-    expect(result).to.deep.include({ pattern: 'uppercase', token: 'password123!', i: 0, j: 11 });
-  });
-
-  it('should provide correct feedback for missing uppercase letters', () => {
-    const match = { pattern: 'uppercase', token: 'password123!', i: 0, j: 11, guesses: 1, guessesLog10: 0 };
-    const feedback = uppercaseMatcher.feedback(match);
-    expect(feedback.warning).to.equal('Include at least one uppercase letter.');
+    expect(result).to.deep.include({ pattern: 'uppercaseRequired', token: 'password123!', i: 0, j: 11 });
+    expect(customMatchersTranslations.warnings.uppercaseRequired).to.equal(
+      'At least one uppercase letter is required.',
+    );
+    expect(customMatchersTranslations.suggestions.uppercaseRequired).to.equal('Include at least one uppercase letter.');
   });
 
   it('should return a score of -100 for missing uppercase letters', () => {
-    const match = { pattern: 'uppercase', token: 'password123!', i: 0, j: 11 };
+    const match = { pattern: 'uppercaseRequired', token: 'password123!', i: 0, j: 11 };
     const score = uppercaseMatcher.scoring(match);
     expect(score).to.equal(-100);
   });
@@ -24,18 +23,16 @@
 describe('lowercaseMatcher', () => {
   it('should return a match for missing lowercase letters', () => {
     const result = lowercaseMatcher.Matching.prototype.match({ password: 'PASSWORD123!' });
-    expect(result).to.deep.include({ pattern: 'lowercase', token: 'PASSWORD123!', i: 0, j: 11 });
-  });
-
-  it('should provide correct feedback for missing lowercase letters', () => {
-    const match = { pattern: 'lowercase', token: 'PASSWORD123!', i: 0, j: 11, guesses: 1, guessesLog10: 0 };
-    const feedback = lowercaseMatcher.feedback(match);
-    expect(feedback.warning).to.equal('Include at least one lowercase letter.');
+    expect(result).to.deep.include({ pattern: 'lowercaseRequired', token: 'PASSWORD123!', i: 0, j: 11 });
+    expect(customMatchersTranslations.warnings.lowercaseRequired).to.equal(
+      'At least one lowercase letter is required.',
+    );
+    expect(customMatchersTranslations.suggestions.lowercaseRequired).to.equal('Include at least one lowercase letter.');
   });
 
   it('should return a score of -100 for missing lowercase letters', () => {
-    const match = { pattern: 'lowercase', token: 'PASSWORD123!', i: 0, j: 11 };
+    const match = { pattern: 'lowercaseRequired', token: 'PASSWORD123!', i: 0, j: 11 };
     const score = lowercaseMatcher.scoring(match);
     expect(score).to.equal(-100);
   });
 });
@@ -43,18 +40,14 @@
 describe('numberMatcher', () => {
   it('should return a match for missing numbers', () => {
     const result = numberMatcher.Matching.prototype.match({ password: 'Password!' });
-    expect(result).to.deep.include({ pattern: 'number', token: 'Password!', i: 0, j: 8 });
-  });
-
-  it('should provide correct feedback for missing numbers', () => {
-    const match = { pattern: 'number', token: 'Password!', i: 0, j: 8, guesses: 1, guessesLog10: 0 };
-    const feedback = numberMatcher.feedback(match);
-    expect(feedback.warning).to.equal('Include at least one number.');
+    expect(result).to.deep.include({ pattern: 'numberRequired', token: 'Password!', i: 0, j: 8 });
+    expect(customMatchersTranslations.warnings.numberRequired).to.equal('At least one number is required.');
+    expect(customMatchersTranslations.suggestions.numberRequired).to.equal('Include at least one number.');
   });
 
   it('should return a score of -100 for missing numbers', () => {
-    const match = { pattern: 'number', token: 'Password!', i: 0, j: 8 };
+    const match = { pattern: 'numberRequired', token: 'Password!', i: 0, j: 8 };
     const score = numberMatcher.scoring(match);
     expect(score).to.equal(-100);
   });
 });
@@ -62,45 +55,39 @@
 describe('specialMatcher', () => {
   it('should return a match for missing special characters', () => {
     const result = specialMatcher.Matching.prototype.match({ password: 'Password123' });
-    expect(result).to.deep.include({ pattern: 'special', token: 'Password123', i: 0, j: 10 });
-  });
-
-  it('should provide correct feedback for missing special characters', () => {
-    const match = { pattern: 'special', token: 'Password123', i: 0, j: 10, guesses: 1, guessesLog10: 0 };
-    const feedback = specialMatcher.feedback(match);
-    expect(feedback.warning).to.equal('Include at least one special character.');
+    expect(result).to.deep.include({ pattern: 'specialRequired', token: 'Password123', i: 0, j: 10 });
+    expect(customMatchersTranslations.warnings.specialRequired).to.equal('At least one special character is required.');
+    expect(customMatchersTranslations.suggestions.specialRequired).to.equal('Include at least one special character.');
   });
 
   it('should return a score of -100 for missing special characters', () => {
-    const match = { pattern: 'special', token: 'Password123', i: 0, j: 10 };
+    const match = { pattern: 'specialRequired', token: 'Password123', i: 0, j: 10 };
     const score = specialMatcher.scoring(match);
     expect(score).to.equal(-100);
   });
 });
 
 describe('minLengthMatcher', () => {
-  const minLength = 10;
+  const minLength = 12;
   const matcher = minLengthMatcher(minLength);
 
   it('should return a match for passwords shorter than the minimum length', () => {
     const result = matcher.Matching.prototype.match({ password: 'short' });
     expect(result).to.deep.include({ pattern: 'minLength', token: 'short', i: 0, j: 4 });
+    expect(customMatchersTranslations.warnings.minLength).to.equal('Password must be at least 12 characters long.');
+    expect(customMatchersTranslations.suggestions.minLength).to.equal(
+      'Password may not be shorter than 12 characters.',
+    );
   });
 
   it('should return no matches for passwords meeting the minimum length', () => {
     const result = matcher.Matching.prototype.match({ password: 'longenoughpassword' });
     expect(result).to.be.empty;
   });
 
-  it('should provide correct feedback for passwords shorter than the minimum length', () => {
-    const match = { pattern: 'minLength', token: 'short', i: 0, j: 4, guesses: 1, guessesLog10: 0 };
-    const feedback = matcher.feedback(match);
-    expect(feedback.warning).to.equal(`Password may not be shorter than ${minLength} characters.`);
-  });
-
   it('should return a score of -100 for passwords shorter than the minimum length', () => {
     const match = { pattern: 'minLength', token: 'short', i: 0, j: 4 };
     const score = matcher.scoring(match);
     expect(score).to.equal(-100);
   });
 });