konami-code-detector

> A lightweight, zero-dependency JavaScript library for detecting the Konami Code sequence on your website. Add easter eggs and hidden features with style! 🎮


Features

- 🚀 Zero dependencies - Pure JavaScript, no bloat
- 📦 Tiny footprint - Less than 4KB minified
- 🎯 Multiple sequences - Classic Konami, custom patterns, and presets
- ⚡ Modern JavaScript - ES6+ with async/await support
- 🔧 Framework agnostic - Works with React, Vue, Angular, or vanilla JS
- 📱 Cross-platform - Browser, Node.js, and Chrome extensions
- ✅ Fully tested - 100% test coverage with Jest
- 📝 Well documented - Comprehensive API documentation

Installation

$3

``bash
npm install konami-code-detector
`

$3

`bash
yarn add konami-code-detector
`

$3

`html

`

Quick Start

`javascript
const KonamiCode = require('konami-code-detector');
// or
import KonamiCode from 'konami-code-detector';

// Initialize with default settings - it just works!
const konami = new KonamiCode();
konami.enable();

// That's it! Press ↑↑↓↓←→←→BA to see the magic ✨
`

Usage Examples

$3

When no callback is provided, the library logs a fun default message:

`javascript
const konami = new KonamiCode();
konami.enable();
// When activated: "🎮 Konami Code Activated! ↑↑↓↓←→←→BA"
`

$3

`javascript
const konami = new KonamiCode(() => {
document.body.style.background = 'linear-gradient(45deg, #ff006e, #8338ec)';
alert('🎉 You found the secret!');
});
konami.enable();
`

$3

`javascript
const konami = new KonamiCode(async () => {
const response = await fetch('/api/unlock-feature');
const data = await response.json();
console.log('Feature unlocked:', data);
});
konami.enable();
`

$3

`javascript
const konami = new KonamiCode();

konami
.on('progress', ({ percentage }) => {
document.querySelector('.progress-bar').style.width = ${percentage}%;
})
.on('activated', () => {
confetti(); // Trigger confetti animation
})
.on('failed', () => {
document.body.style.animation = 'shake 0.5s';
});

konami.enable();
`

$3

`javascript
const { SEQUENCES } = require('konami-code-detector');

// Use built-in sequences
const debugMode = new KonamiCode(unlockDebugPanel, {
sequence: SEQUENCES.debug // 'd', 'e', 'b', 'u', 'g'
});

// Or create your own
const customCode = new KonamiCode(activateFeature, {
sequence: ['g', 'o', 'd', 'm', 'o', 'd', 'e']
});
`

API Reference

$3

`javascript
new KonamiCode(callback?, options?)
`

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| callback | Function | defaultCallback | Function to execute when code is activated |
| options | Object | {} | Configuration options |

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| sequence | string[] | SEQUENCES.classic | Key sequence to detect |
| timeout | number | 1000 | Time in ms before sequence resets |
| target | EventTarget | document | Element to listen for keypresses |
| once | boolean | false | Only allow activation once |
| debug | boolean | false | Enable debug logging |
| maxAttempts | number | Infinity | Maximum number of activations |
| cooldown | number | 0 | Cooldown period between activations (ms) |
| autoEnable | boolean | false | Automatically enable on instantiation |
| preventDefault | boolean | true | Prevent default key behavior on activation |

$3

#### Core Methods

| Method | Returns | Description |
|--------|---------|-------------|
| enable() | Promise | Start listening for keypresses |
| disable() | Promise | Stop listening for keypresses |
| destroy() | Promise | Clean up and remove all listeners |
| reset() | void | Reset the current sequence progress |

#### Configuration Methods

| Method | Returns | Description |
|--------|---------|-------------|
| setCallback(fn) | KonamiCode | Update the activation callback |
| setSequence(keys) | KonamiCode | Change the key sequence |

#### State Methods

| Method | Returns | Description |
|--------|---------|-------------|
| isEnabled() | boolean | Check if listener is active |
| isActivated() | boolean | Check if code has been activated |
| getProgress() | Object | Get current sequence progress |
| getStats() | Object | Get activation statistics |
| resetStats() | KonamiCode | Reset all statistics |

#### Event Methods

| Method | Returns | Description |
|--------|---------|-------------|
| on(event, handler) | KonamiCode | Add event listener |
| off(event, handler) | KonamiCode | Remove event listener |
| waitForActivation() | Promise | Wait for next activation |

#### Testing Methods

| Method | Returns | Description |
|--------|---------|-------------|
| triggerKey(key) | Promise | Manually trigger a key press |
| triggerSequence() | Promise | Manually trigger the full sequence |

$3

| Event | Payload | Description |
|-------|---------|-------------|
| enabled | { timestamp } | Fired when listener is enabled |
| disabled | { timestamp } | Fired when listener is disabled |
| progress | { current, total, percentage } | Fired on sequence progress |
| activated | { timestamp, activations } | Fired on successful activation |
| failed | { key, expected } | Fired when wrong key is pressed |
| error | { error, timestamp } | Fired when an error occurs |

$3

`javascript
const { SEQUENCES } = require('konami-code-detector');

SEQUENCES.classic // ↑ ↑ ↓ ↓ ← → ← → B A
SEQUENCES.simple // ↑ ↓ ← →
SEQUENCES.debug // D E B U G
SEQUENCES.admin // A D M I N
`

Framework Integration

$3

`javascript
import { useEffect, useRef } from 'react';
import KonamiCode from 'konami-code-detector';

function App() {
const konamiRef = useRef(null);

useEffect(() => {
konamiRef.current = new KonamiCode(() => {
console.log('Easter egg activated in React!');
});

konamiRef.current.enable();

return () => {
konamiRef.current?.destroy();
};
}, []);

return

;
}
`

$3

`javascript

`

$3

`typescript
import { Component, OnInit, OnDestroy } from '@angular/core';
import KonamiCode from 'konami-code-detector';

@Component({
selector: 'app-root',
template: ''
})
export class AppComponent implements OnInit, OnDestroy {
private konami: any;

ngOnInit() {
this.konami = new KonamiCode(() => {
console.log('Easter egg activated in Angular!');
});
this.konami.enable();
}

ngOnDestroy() {
this.konami?.destroy();
}
}
`

$3

`javascript
// content.js
const KonamiCode = require('konami-code-detector');

const konami = new KonamiCode(async () => {
// Send message to background script
const response = await chrome.runtime.sendMessage({
type: 'KONAMI_ACTIVATED'
});
console.log('Easter egg unlocked!', response);
});

konami.enable();
`

`javascript
// background.js
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
if (request.type === 'KONAMI_ACTIVATED') {
console.log('Konami code activated on:', sender.tab.url);
sendResponse({ success: true });
}
});
`

Real-World Examples

$3

`javascript
const konami = new KonamiCode(() => {
document.body.classList.add('retro-mode');
new Audio('/sounds/powerup.mp3').play();
showSecretCharacter();
});
`

$3

`javascript
const konami = new KonamiCode(() => {
localStorage.setItem('debug_mode', 'true');
console.log('Debug mode enabled!');
window.location.reload();
}, {
sequence: SEQUENCES.debug,
once: true
});
`

$3

`javascript
const konami = new KonamiCode(() => {
const img = document.createElement('img');
img.src = 'https://media.giphy.com/media/3o7aCPVr3uUiCdmYQE/giphy.gif';
img.style.cssText =
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%);
z-index: 9999;
;
document.body.appendChild(img);

setTimeout(() => img.remove(), 3000);
});
`

$3

`javascript
const konami = new KonamiCode();
let level = 0;

konami.on('activated', () => {
level++;
switch(level) {
case 1:
console.log('Level 1: You found the first secret!');
break;
case 2:
console.log('Level 2: You are persistent!');
document.body.style.filter = 'hue-rotate(90deg)';
break;
case 3:
console.log('Level 3: Ultimate Easter Egg Master!');
activatePartyMode();
break;
}
});

konami.enable();
`

Browser Support

Works in all modern browsers that support ES6+:

- Chrome 51+
- Firefox 54+
- Safari 10+
- Edge 15+
- Opera 38+

For older browsers, use a transpiler like Babel.

Testing

The package includes comprehensive Jest tests:

`bash


Run tests

npm test

Watch mode

npm run test:watch

Coverage report

npm run test:coverage
`

Advanced Configuration

$3

`javascript
// Different codes for different features
const debugMode = new KonamiCode(enableDebug, {
sequence: SEQUENCES.debug
});

const godMode = new KonamiCode(enableGodMode, {
sequence: ['g', 'o', 'd'],
cooldown: 5000
});

const resetApp = new KonamiCode(resetApplication, {
sequence: ['r', 'e', 's', 'e', 't'],
once: true
});

debugMode.enable();
godMode.enable();
resetApp.enable();
`

$3

`javascript
const konami = new KonamiCode(async () => {
const userRole = await getUserRole();

if (userRole === 'admin') {
showAdminPanel();
} else if (userRole === 'developer') {
showDebugTools();
} else {
showEasterEgg();
}
});
`

$3

`javascript
// Redux example
const konami = new KonamiCode(() => {
store.dispatch({ type: 'KONAMI_ACTIVATED' });
});

// Vuex example
const konami = new KonamiCode(() => {
store.commit('activateEasterEgg');
});

// Zustand example
const konami = new KonamiCode(() => {
useStore.setState({ easterEggActive: true });
});
`

Performance Considerations

- Event listeners are automatically cleaned up to prevent memory leaks
- Uses AbortController for efficient listener management
- Minimal CPU usage - only processes relevant keypress events
- No polling or continuous checks
- Lazy initialization of features

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

$3

`bash


Clone the repo

git clone https://github.com/yourusername/konami-code-detector.git
cd konami-code-detector

Install dependencies

npm install

Run tests in watch mode

npm run test:watch

Build for production

npm run build
`

Troubleshooting

$3

- Ensure the target element has focus
- Check that no other element is preventing event propagation
- Verify the sequence is correct (case-insensitive)

$3

- Use the once: true option
- Set a cooldown period between activations
- Implement maxAttempts limit

$3

- Always call destroy() when removing the component
- Use AbortController` is automatically handled

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

- Inspired by the classic Konami Code from the 1986 NES port of Gradius
- Thanks to all contributors and users of this library
- Special thanks to the JavaScript community

Support

If you like this project, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting new features
- 📖 Improving documentation

Changelog

$3

- Initial release
- Core functionality
- Event system
- Built-in sequences
- Full test coverage

---

Made with ❤️ and JavaScript