Lightweight JavaScript/TypeScript library for Caesar cipher encryption, decryption and bruteforce attacks
npm install caesar-cipher-js

Lightweight JavaScript/TypeScript library for Caesar cipher encryption, decryption, and bruteforce attacks. Zero dependencies, works in Node.js and browsers.
🌐 Used in production: This library powers caesar-cipher.com - an interactive online tool for Caesar cipher encryption and decryption with multi-language support.
- ✅ Encrypt and decrypt text using Caesar cipher
- ✅ Bruteforce decryption when shift key is unknown
- ✅ Multi-language support - English, Polish, German, Spanish, French
- ✅ Custom alphabets support (Polish, German, Spanish, French, alphanumeric, or your own)
- ✅ Diacritics mapping - automatic handling of accented characters (é, è, ê, etc.)
- ✅ Language-specific scoring - intelligent decryption for 5 languages
- ✅ Advanced case handling - maintain, uppercase, or lowercase strategies
- ✅ TypeScript support with full type definitions
- ✅ Dual API - functional and object-oriented
- ✅ Zero dependencies - lightweight and fast
- ✅ Multiple formats - ESM, CommonJS, UMD
- ✅ 100% test coverage - thoroughly tested
``bash`
npm install caesar-cipher-js
Or with yarn:
`bash`
yarn add caesar-cipher-js
`typescript
import { encrypt, decrypt, bruteforce } from 'caesar-cipher-js';
// Encrypt text
const encrypted = encrypt('Hello World', 3);
console.log(encrypted); // 'Khoor Zruog'
// Decrypt text
const decrypted = decrypt('Khoor Zruog', 3);
console.log(decrypted); // 'Hello World'
// Bruteforce when shift is unknown
const results = bruteforce('Khoor Zruog');
console.log(results[3]); // { shift: 3, text: 'Hello World' }
`
#### encrypt(text, shift, options?)
Encrypts text using the Caesar cipher algorithm.
Parameters:
- text (string) - The plaintext to encryptshift
- (number) - The number of positions to shift (can be negative)options
- (object, optional)alphabet
- (string) - Custom alphabet (default: 'a-z'). Automatically normalized to lowercase.caseStrategy
- ('maintain' | 'upper' | 'lower') - Case handling strategy (default: 'maintain')preserveSpaces
- (boolean) - Keep spaces (default: true)preserveSpecialChars
- (boolean) - Keep special characters (default: true)diacriticsLanguage
- (string) - Language for diacritics mapping (e.g., 'french')preserveCase
- (boolean) - _Deprecated: use caseStrategy_preserveNonAlpha
- (boolean) - _Deprecated: use preserveSpaces and preserveSpecialChars_
Returns: Encrypted string
Example:
`typescript
import { encrypt } from 'caesar-cipher-js';
// Basic encryption
encrypt('abc', 1); // 'bcd'
// With options
encrypt('Hello World!', 5, {
preserveCase: true,
preserveNonAlpha: true
}); // 'Mjqqt Btwqi!'
// Custom alphabet
encrypt('test123', 3, {
alphabet: 'abcdefghijklmnopqrstuvwxyz0123456789'
}); // 'whvw456'
`
#### decrypt(text, shift, options?)
Decrypts text encrypted with Caesar cipher.
Parameters:
- text (string) - The ciphertext to decryptshift
- (number) - The shift value used during encryptionoptions
- (object, optional) - Same as encrypt
Returns: Decrypted string
Example:
`typescript
import { decrypt } from 'caesar-cipher-js';
decrypt('Khoor', 3); // 'Hello'
decrypt('MJQQT', 5); // 'HELLO'
`
#### bruteforce(text, options?)
Attempts to decrypt text by trying all possible shift values.
Parameters:
- text (string) - The ciphertext to decryptoptions
- (object, optional)alphabet
- (string) - Custom alphabetmaxResults
- (number) - Limit number of resultsscoreFunction
- (function) - Custom scoring function for ranking results
Returns: Array of { shift, text, score? } objects
Example:
`typescript
import { bruteforce, scoreEnglishText } from 'caesar-cipher-js';
// Basic bruteforce
const results = bruteforce('Khoor');
// Returns all 26 possible decryptions
// With scoring to find most likely result
const scored = bruteforce('Khoor Zruog', {
scoreFunction: scoreEnglishText,
maxResults: 5
});
// Returns top 5 results sorted by likelihood
`
#### CaesarCipher class
Provides a stateful alternative to the functional API.
Constructor:
`typescript
import { CaesarCipher } from 'caesar-cipher-js';
const cipher = new CaesarCipher({
alphabet: 'abcdefghijklmnopqrstuvwxyz',
preserveCase: true,
preserveNonAlpha: true
});
`
Methods:
- encrypt(text, shift) - Encrypt textdecrypt(text, shift)
- - Decrypt textbruteforce(text, maxResults?)
- - Bruteforce decryptsetAlphabet(alphabet)
- - Change alphabetgetAlphabet()
- - Get current alphabetsetPreserveCase(preserve)
- - Set case preservationgetPreserveCase()
- - Get case preservation settingsetPreserveNonAlpha(preserve)
- - Set non-alpha preservationgetPreserveNonAlpha()
- - Get non-alpha preservation settingreset()
- - Reset to default settings
Example:
`typescript
import { CaesarCipher } from 'caesar-cipher-js';
const cipher = new CaesarCipher();
const encrypted = cipher.encrypt('Hello', 3);
// 'Khoor'
const decrypted = cipher.decrypt(encrypted, 3);
// 'Hello'
// Change alphabet
cipher.setAlphabet('abcdefghijklmnopqrstuvwxyz0123456789');
cipher.encrypt('test123', 5);
// 'yjxy678'
`
The library supports custom alphabets, including:
`typescript
import {
encrypt,
ALPHABET_POLISH_LOWER,
ALPHABET_ALPHANUMERIC_LOWER
} from 'caesar-cipher-js';
// Polish alphabet
const polishText = 'zażółć gęślą jaźń';
const encrypted = encrypt(polishText, 5, {
alphabet: ALPHABET_POLISH_LOWER
});
// Alphanumeric
const mixed = 'abc123';
encrypt(mixed, 3, {
alphabet: ALPHABET_ALPHANUMERIC_LOWER
}); // 'def456'
// Custom alphabet
encrypt('hello', 2, {
alphabet: 'abcdefghijklmnopqrstuvwxyz!@#$%'
});
`
Available predefined alphabets:
- ALPHABET_ENGLISH_LOWER - a-zALPHABET_ENGLISH_UPPER
- - A-ZALPHABET_POLISH_LOWER
- - Polish lowercase (aąbcćdeęfghijklłmnńoópqrsśtuvwxyzźż)ALPHABET_POLISH_UPPER
- - Polish uppercase (AĄBCĆDEĘFGHIJKLŁMNŃOÓPQRSŚTUVWXYZŹŻ)ALPHABET_GERMAN_LOWER
- - German lowercase (aäbcdefghijklmnoöpqrstuüvwxyzß)ALPHABET_GERMAN_UPPER
- - German uppercase (AÄBCDEFGHIJKLMNOÖPQRSTUÜVWXYZß)ALPHABET_SPANISH_LOWER
- - Spanish lowercase (abcdefghijklmnñopqrstuvwxyz)ALPHABET_SPANISH_UPPER
- - Spanish uppercase (ABCDEFGHIJKLMNÑOPQRSTUVWXYZ)ALPHABET_FRENCH_LOWER
- - French lowercase (a-z, use with diacritics mapping)ALPHABET_FRENCH_UPPER
- - French uppercase (A-Z, use with diacritics mapping)ALPHABET_ALPHANUMERIC_LOWER
- - a-z + 0-9ALPHABET_ALPHANUMERIC_UPPER
- - A-Z + 0-9
Note: All alphabets are automatically normalized to lowercase internally for consistent processing. You can use uppercase alphabets (e.g., ALPHABET_ENGLISH_UPPER) and they will work correctly - case handling is controlled by the caseStrategy option.
Create a custom scoring function to improve bruteforce accuracy:
`typescript
import { bruteforce } from 'caesar-cipher-js';
const customScore = (text) => {
const commonWords = ['the', 'and', 'is', 'to', 'a'];
let score = 0;
const lower = text.toLowerCase();
for (const word of commonWords) {
if (lower.includes(word)) {
score += 10;
}
}
return score;
};
const results = bruteforce('encrypted text', {
scoreFunction: customScore,
maxResults: 3
});
// Results sorted by score (highest first)
console.log(results[0].text); // Most likely decryption
`
The library includes built-in support for 5 languages with language-specific frequency data and scoring functions:
`typescript
import {
bruteforce,
scoreEnglishText,
scorePolishText,
scoreGermanText,
scoreSpanishText,
scoreFrenchText,
getScoreFunction
} from 'caesar-cipher-js';
// English text
const englishCipher = 'Khoor Zruog';
const englishResults = bruteforce(englishCipher, {
scoreFunction: scoreEnglishText,
maxResults: 1
});
console.log(englishResults[0].text); // 'Hello World'
// Polish text
const polishCipher = 'Fćnuć';
const polishResults = bruteforce(polishCipher, {
scoreFunction: scorePolishText,
alphabet: 'AĄBCĆDEĘFGHIJKLŁMNŃOÓPQRSŚTUVWXYZŹŻ'
});
// Or use getScoreFunction for dynamic language selection
const language = 'french';
const scoreFunc = getScoreFunction(language);
const results = bruteforce(ciphertext, { scoreFunction: scoreFunc });
`
Available scoring functions:
- scoreEnglishText(text) - English language scoringscorePolishText(text)
- - Polish language scoringscoreGermanText(text)
- - German language scoringscoreSpanishText(text)
- - Spanish language scoringscoreFrenchText(text)
- - French language scoringgetScoreFunction(language)
- - Get scoring function by language name
French text with accented characters can be automatically mapped to base letters:
`typescript
import { encrypt, ALPHABET_FRENCH_UPPER } from 'caesar-cipher-js';
// French text with diacritics
const frenchText = 'Café, thé et crème brûlée';
const encrypted = encrypt(frenchText, 5, {
alphabet: ALPHABET_FRENCH_UPPER,
diacriticsLanguage: 'french'
});
// Diacritics (é, è, ê, etc.) are mapped to base letters (e) before encryption
console.log(encrypted); // 'Hfkj, ymd jy hwjrj gwzqjj'
`
Supported diacritics mapping:
- French: é→e, è→e, ê→e, à→a, ç→c, etc.
Control how letter case is handled during encryption/decryption:
`typescript
import { encrypt } from 'caesar-cipher-js';
const text = 'Hello World';
// Maintain original case (default)
encrypt(text, 3, { caseStrategy: 'maintain' });
// 'Khoor Zruog'
// Convert all to uppercase
encrypt(text, 3, { caseStrategy: 'upper' });
// 'KHOOR ZRUOG'
// Convert all to lowercase
encrypt(text, 3, { caseStrategy: 'lower' });
// 'khoor zruog'
`
Separately control spaces and special characters:
`typescript
import { encrypt } from 'caesar-cipher-js';
const text = 'Hello, World! 123';
// Keep spaces, remove special characters
encrypt(text, 3, {
preserveSpaces: true,
preserveSpecialChars: false
});
// 'Khoor Zruog 123'
// Remove spaces, keep special characters
encrypt(text, 3, {
preserveSpaces: false,
preserveSpecialChars: true
});
// 'Khoor,Zruog!123'
`
ROT13 is a special case of Caesar cipher with shift 13:
`typescript
import { encrypt } from 'caesar-cipher-js';
const rot13 = (text) => encrypt(text, 13);
const encoded = rot13('Hello World');
// 'Uryyb Jbeyq'
// ROT13 is its own inverse
const decoded = rot13(encoded);
// 'Hello World'
`
Full TypeScript support with type definitions:
`typescript
import type {
EncryptOptions,
DecryptOptions,
BruteforceOptions,
BruteforceResult,
CipherOptions,
ScoreFunction,
CaseStrategy,
SupportedLanguage,
LanguageFrequencyData
} from 'caesar-cipher-js';
const options: EncryptOptions = {
alphabet: 'abc',
caseStrategy: 'maintain',
preserveSpaces: true,
preserveSpecialChars: false,
diacriticsLanguage: 'french'
};
const scoreFunc: ScoreFunction = (text: string): number => {
return text.length;
};
const language: SupportedLanguage = 'polish';
`
The library works in browsers via CDN:
`html`
Or with ES modules:
`html`
The library is optimized for performance:
- Zero dependencies for minimal bundle size
- Bundle size:
- Raw: ~13.5 KB
- Minified: ~8 KB
- Minified + gzipped: ~3 KB ⚡
`typescript
import { encrypt, decrypt } from 'caesar-cipher-js';
const secret = 'Attack at dawn';
const key = 17;
const encrypted = encrypt(secret, key);
// Send encrypted message...
// Receiver decrypts:
const message = decrypt(encrypted, key);
console.log(message); // 'Attack at dawn'
`
`typescript
import { bruteforce, scoreEnglishText } from 'caesar-cipher-js';
const intercepted = 'Wkh txlfn eurzq ira';
const results = bruteforce(intercepted, {
scoreFunction: scoreEnglishText,
maxResults: 1
});
console.log(results[0].text);
// 'The quick brown fox'
console.log(results[0].shift);
// 3
`
`typescript
import { CaesarCipher, ALPHABET_POLISH_LOWER } from 'caesar-cipher-js';
const cipher = new CaesarCipher({
alphabet: ALPHABET_POLISH_LOWER
});
const encrypted = cipher.encrypt('Łódź', 7);
const decrypted = cipher.decrypt(encrypted, 7);
console.log(decrypted); // 'Łódź'
`
For complete API documentation, see the TypeScript definitions or visit our documentation site.
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature'
3. Commit your changes ()git push origin feature/amazing-feature
4. Push to the branch ()
5. Open a Pull Request
`bashRun tests
npm test
MIT © Tomasz Warezak
Important: Caesar cipher is not secure for real-world encryption. It's trivially broken with frequency analysis or bruteforce attacks. This library is for:
- Educational purposes
- Simple obfuscation
- Historical cryptography study
- Fun projects
For real security, use modern encryption like AES-256, RSA, or libsodium.
- 🌐 Live Demo - caesar-cipher.com - Interactive online tool powered by this library
- GitHub Repository
- NPM Package
- Issue Tracker
- Changelog
---