XtonCore Framework v3.0.0 🚀

A comprehensive, production-ready Discord.js framework with powerful optimizations

Features • Installation • Quick Start • Documentation • Examples

✨ Features

⚡ Performance Optimizations

• Lazy Loading - Load commands on-demand (~80% faster startup, 67% less memory!)
• Parallel Loading - Load modules simultaneously (~57% faster initialization)
• Combined Performance - Up to 90% faster startup with both optimizations
• Hot Reload - Development-friendly file watching and instant reloading

🎯 Core Features

• Command Handler - Advanced slash command management with autocomplete support
• Event Handler - Automatic event loading and management
• Component Handler - Button, select menu, and modal interaction handling
• Validation System - Flexible command validation pipeline

🏗️ Advanced Framework Features (v3.0)

• Middleware Pipeline - Express-style .use() pipeline to intercept commands
• Cron Job Manager - Built-in scheduled tasks loaded from jobs/
• Localization (i18n) - Multi-language support with locales/ dynamic loading
• Persistent Storage - IStorageAdapter for Redis/DB instead of memory caching
• Automated Pagination - Easy and secure embed paginations out-of-the-box

🚀 Enhanced Features

• Performance Monitoring - Real-time execution tracking and statistics
• Cooldown Management - Per-user, per-command cooldown system (Persistent)
• Permission System - Advanced permission checking with caching
• Rate Limiting - Built-in rate limiting to prevent abuse (Persistent)
• Input Sanitization - Security-focused input validation
• Enhanced Logging - Multi-level logging with context

🎨 Utility Classes

• EnhancedEmbedBuilder - Beautiful preset embeds (success, error, info, etc.)
• ComponentHelpers - Quick Discord component creation
• PaginationBuilder - Automated embed scroll wheels with timeouts
• InputSanitizer - Security-focused input validation
• CommandBuilder - Simplified command creation

📦 Installation

npm install xtoncore discord.js
# or
yarn add xtoncore discord.js

Requirements:

• Node.js >= 18.0.0
• Discord.js v14

🚀 Quick Start

Basic Setup

import { Client, GatewayIntentBits } from 'discord.js';
import { ClientHandler } from 'xtoncore';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

async function main() {
  const handler = await ClientHandler.create({
    client,
    commandsPath: './commands',
    eventsPath: './events',
    componentsPath: './components',
    jobsPath: './jobs',
    localesPath: './locales',
    defaultLocale: 'en-US',
    ownerIds: ['YOUR_USER_ID'],
    
    // ⚡ Performance optimizations (enabled by default)
    lazyLoading: true, // 80% faster startup!
    preloadCommands: ['ping', 'help'], // Preload frequently used commands
    
    // 🔥 Development features
    enableHotReload: true,
    
    // 🛡️ Security features
    rateLimiting: {
      enabled: true,
      defaultLimit: 5,
      defaultWindow: 60,
    },
  });

  await client.login('YOUR_BOT_TOKEN');
}

main();

Project Structure

your-bot/
├── commands/
│   ├── utility/
│   │   ├── ping.ts
│   │   └── help.ts
│   └── admin/
│       └── stats.ts
├── events/
│   ├── ready/
│   │   └── 00-startup.ts
│   └── interactionCreate/
│       └── 01-logging.ts
├── components/
│   ├── buttons/
│   │   └── confirm-button.ts
│   ├── modals/
│   │   └── feedback-modal.ts
│   └── selectmenus/
│       └── role-selector.ts
└── index.ts

📚 Documentation

Command Example

import { SlashCommandBuilder } from 'discord.js';
import { CommandRunOptions } from 'xtoncore';
import { EnhancedEmbedBuilder } from 'xtoncore';

export const data = new SlashCommandBuilder()
  .setName('ping')
  .setDescription('Check bot latency');

export const cooldown = 5; // 5 seconds
export const category = 'utility';

export async function run({ interaction, client, handler }: CommandRunOptions) {
  const embed = EnhancedEmbedBuilder.createInfo(
    '🏓 Pong!',
    `Latency: ${client.ws.ping}ms`
  );
  
  await interaction.reply({ embeds: [embed] });
}

Component Example

import { ButtonInteraction } from 'discord.js';
import { ComponentHandler } from 'xtoncore';

export const customId = 'confirm-action';
export const type = 'button';

export async function run(interaction: ButtonInteraction, client: any, handler: any) {
  await interaction.reply({ 
    content: '✅ Action confirmed!', 
    ephemeral: true 
  });
}

Event Example

import { Client } from 'discord.js';

export default async function (client: Client) {
  console.log(`✅ Logged in as ${client.user?.tag}`);
}

⚡ Performance Features

Lazy Loading

Commands are loaded on-demand for dramatically faster startup:

const handler = await ClientHandler.create({
  client,
  commandsPath: './commands',
  lazyLoading: true, // Default: true
  preloadCommands: ['ping', 'help'], // Preload critical commands
});

// Check lazy loading stats
const stats = handler.getLazyLoadingStats();
console.log(`Loaded: ${stats.loaded}/${stats.total} (${stats.percentage}%)`);

// Preload all commands (useful for production)
await handler.preloadAllCommands();

Performance Impact:

• 🚀 80% faster startup
• 💾 67% less memory usage
• ⚡ Commands load in ~3-5ms on first use

Parallel Loading

Modules load simultaneously for faster initialization:

// Happens automatically!
const handler = await ClientHandler.create({
  client,
  commandsPath: './commands',
  eventsPath: './events',
  componentsPath: './components',
  // All load in parallel (~57% faster)
});

Combined Performance

Traditional Loading:  1000ms startup, 150MB memory
With Optimizations:   150ms startup, 50MB memory
Improvement:          85% faster, 67% less memory! 🚀

🎨 Utility Classes

EnhancedEmbedBuilder

import { EnhancedEmbedBuilder } from 'xtoncore';

// Preset embeds
const success = EnhancedEmbedBuilder.createSuccess('Success!', 'Operation completed');
const error = EnhancedEmbedBuilder.createError('Error!', 'Something went wrong');
const info = EnhancedEmbedBuilder.createInfo('Info', 'Here is some information');
const warning = EnhancedEmbedBuilder.createWarning('Warning!', 'Be careful');

// Pagination
const paginated = EnhancedEmbedBuilder.createPagination(items, 1, 10, 'Results');

// Progress bar
const progress = EnhancedEmbedBuilder.createProgressBar(75, 100, 20, 'Loading');

// Access preset colors
const custom = EnhancedEmbedBuilder.createBasic(
  'Title',
  'Description',
  EnhancedEmbedBuilder.COLORS.PRIMARY
);

ComponentHelpers

import { ComponentHelpers } from 'xtoncore';

// Buttons
const confirmButtons = ComponentHelpers.createConfirmButtons();
const pagination = ComponentHelpers.createPaginationButtons(1, 5);

// Select menu
const menu = ComponentHelpers.createSelectMenu('menu_id', 'Choose option', [
  { label: 'Option 1', value: 'opt1', emoji: '1️⃣' },
  { label: 'Option 2', value: 'opt2', emoji: '2️⃣' },
]);

// Modal
const modal = ComponentHelpers.createModal('modal_id', 'Feedback Form', [
  {
    customId: 'feedback',
    label: 'Your Feedback',
    style: 2, // Paragraph
    required: true,
  },
]);

InputSanitizer

import { InputSanitizer } from 'xtoncore';

// Sanitize user input
const clean = InputSanitizer.sanitizeString(userInput, {
  maxLength: 1000,
  allowHtml: false,
  trim: true,
});

// Validate IDs
const isValid = InputSanitizer.validateUserId('123456789012345678');

// Sanitize Discord content
const cleanContent = InputSanitizer.sanitizeDiscordContent(message);

📊 Performance Monitoring

// Access performance manager
const perfManager = handler.performanceManager;

// Get command statistics
const stats = perfManager.getCommandStats('ping');
const topCommands = perfManager.getTopCommands(10);

// Get memory usage
const memory = perfManager.getMemoryUsage();
console.log(`Memory: ${memory.current}MB`);

// Generate report
const report = perfManager.generateReport();
console.log(report);

🔒 Permission Management

// Access permission manager
const permManager = handler.permissionManager;

// Add/remove owners
permManager.addOwner('USER_ID');
permManager.removeOwner('USER_ID');

// Blacklist users/guilds
permManager.blacklistUser('USER_ID');
permManager.blacklistGuild('GUILD_ID');

// Check permissions
const result = await permManager.checkPermissions(interaction, command);
if (!result.allowed) {
  console.log(result.reason);
}

⏱️ Cooldown Management

// Access cooldown manager
const cooldownManager = handler.cooldownManager;

// Set cooldown
cooldownManager.setCooldown('USER_ID', 'command_name', 30);

// Check cooldown
const isOnCooldown = cooldownManager.isOnCooldown('USER_ID', 'command_name');
const remainingTime = cooldownManager.getRemainingTime('USER_ID', 'command_name');

// Remove cooldown
cooldownManager.removeCooldown('USER_ID', 'command_name');

🚦 Rate Limiting

// Access rate limiter
const rateLimiter = handler.rateLimiter;

// Check rate limit
const result = rateLimiter.checkLimit('USER_ID', 'action', 5, 60);
if (!result.allowed) {
  console.log(`Rate limited! Reset in ${result.resetTime - Date.now()}ms`);
}

🔥 Hot Reload

// Access hot reload manager
const hotReload = handler.hotReloadManager;

// Check if enabled
console.log(hotReload.isEnabled());

// Get watched directories
console.log(hotReload.getWatchedDirectories());

// Manual reload
await handler.reloadCommands();
await handler.reloadComponents();
await handler.reloadAll(); // Reload everything in parallel

� Statisstics

// Get comprehensive stats
const stats = handler.getStats();
console.log(stats);
// {
//   commands: 50,
//   performance: {...},
//   cooldowns: 5,
//   components: 10,
//   permissions: {...},
//   rateLimiter: {...},
//   hotReload: {...}
// }

// Generate full report
const report = handler.generateReport();
console.log(report);

🎯 Configuration Options

interface ClientHandlerOptions {
  client: Client;                    // Discord.js client (required)
  commandsPath?: string;             // Path to commands directory
  eventsPath?: string;               // Path to events directory
  validationsPath?: string;          // Path to validations directory
  componentsPath?: string;           // Path to components directory
  jobsPath?: string;                 // Path to scheduled cron jobs (v3.0)
  localesPath?: string;              // Path to translation JSONs (v3.0)
  defaultLocale?: string;            // Default bot language (v3.0)
  guild?: string;                    // Guild ID for guild-specific commands
  ownerIds?: string[];               // Array of owner user IDs
  
  // ⚡ Performance
  enableHotReload?: boolean;         // Enable hot reload (default: dev mode)
  lazyLoading?: boolean;             // Enable lazy loading (default: true)
  preloadCommands?: string[];        // Commands to preload immediately
  
  // 🛡️ Security
  rateLimiting?: {
    enabled: boolean;
    defaultLimit?: number;           // Requests per window
    defaultWindow?: number;          // Window in seconds
  };
  
  // 📊 Monitoring
  performance?: {
    enabled: boolean;
    trackMemory?: boolean;
  };
}

📖 Advanced Examples

Custom Command Data

interface MyCommandData {
  requiredRole: string;
  logChannel: string;
}

export const customData: MyCommandData = {
  requiredRole: '123456789',
  logChannel: '987654321',
};

export async function run({ interaction, customData }: CommandRunOptions<MyCommandData>) {
  // customData is fully typed!
  if (customData?.requiredRole) {
    // Your logic here
  }
}

🛑 Advanced Middleware Pipeline

// Define custom context types
const handler = await ClientHandler.create({ /* ... */ });

handler.middlewareManager.use(async (ctx, next) => {
  console.log(`Command triggered: ${ctx.command.data.name}`);
  ctx.state.customProperty = "Hello from Middleware!";
  
  if (ctx.interaction.user.bot) {
    return; // Short-circuit, command doesn't run
  }
  
  await next(); // Proceed to the next middleware or command
});

🌐 Localization (i18n) Usage

// Use anywhere using the handler instance
const welcomeMessage = handler.languageManager?.t('messages.welcome', 'th-TH', { 
  user: interaction.user.username 
});
await interaction.reply(welcomeMessage);

📑 Easy Pagination

import { PaginationBuilder } from 'xtoncore';

const embed1 = new EmbedBuilder().setTitle('Page 1');
const embed2 = new EmbedBuilder().setTitle('Page 2');

await new PaginationBuilder(interaction, 60000)
  .setEmbeds([embed1, embed2])
  .setEphemeral(true)
  .render();

Production Setup

const handler = await ClientHandler.create({
  client,
  commandsPath: './commands',
  lazyLoading: true,
  preloadCommands: ['ping', 'help'], // Critical commands
});

client.once('ready', async () => {
  // Preload all commands in background
  await handler.preloadAllCommands();
  console.log('All commands ready!');
});

Development Setup

const handler = await ClientHandler.create({
  client,
  commandsPath: './commands',
  lazyLoading: true,              // Fast startup
  enableHotReload: true,          // Auto-reload on changes
  rateLimiting: { enabled: false }, // Disable for testing
});

📊 Performance Benchmarks

| Bot Size | Traditional | XtonCore v2.1 | Improvement | |----------|------------|---------------|-------------| | Small (10 cmds) | 100ms | 40ms | 60% faster ⚡ | | Medium (50 cmds) | 350ms | 150ms | 57% faster ⚡ | | Large (200 cmds) | 1200ms | 200ms | 83% faster ⚡ | | Huge (500 cmds) | 3000ms | 500ms | 83% faster ⚡ |

Memory Usage:

• Small: 30MB → 15MB (50% less)
• Medium: 80MB → 30MB (62% less)
• Large: 150MB → 50MB (67% less)

🔧 TypeScript Support

Full TypeScript support with complete type definitions:

import { 
  ClientHandler, 
  LocalCommand, 
  CommandRunOptions,
  EnhancedEmbedBuilder,
  ComponentHelpers 
} from 'xtoncore';

// Full IntelliSense and type checking
const handler = await ClientHandler.create({ /* ... */ });
const stats = handler.getStats(); // Fully typed!

See TYPESCRIPT.md for detailed TypeScript usage guide.

📚 Additional Documentation

• TYPESCRIPT.md - Complete TypeScript guide
• PERFORMANCE.md - Performance optimization guide
• LAZY_LOADING.md - Lazy loading detailed guide
• examples/ - Practical code examples

🛠️ CLI Tool

Want to scaffold projects quickly? Check out our CLI tool:

npm install -g xton-cli
xton init my-bot

Learn more about xton-cli

🤝 Contributing

Contributions, issues, and feature requests are welcome!

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

📝 Changelog

v2.1.0 - Performance & Feature Update

• ✨ Added lazy loading system (80% faster startup)
• ✨ Added parallel loading (57% faster initialization)
• ✨ Added component management system
• ✨ Added advanced permission system
• ✨ Added rate limiting
• ✨ Added input sanitization
• ✨ Added utility classes
• ✨ Enhanced logging system
• 🔧 Improved TypeScript support
• 🔧 Better error handling
• 📊 Performance monitoring

📄 License

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

🙏 Credits

Created and maintained by Narabordee Wirakkamo

📞 Support

• 📧 Email: [[email protected]]
• 🐛 Issues: GitHub Issues
• 💬 Discord: [Your Discord Server]

XtonCore Enhanced v2.1 - Making Discord.js development easier and more powerful! 🚀

⭐ Star us on GitHub if you find this useful!