djs-next 1.0.0-dev.2 → 1.0.0-dev.3

package/README.md

@@ -13,17 +13,18 @@
 ## ✨ Features
 
 - 📁 **Next.js File-Based Routing**: Auto-loads commands, events, components, and tasks natively. Supports Regex dynamic routes (e.g., `[id].ts` for components).
-- 🛠️ **Native Developer Tools (`dnxt`)**: A comprehensive, built-in developer suite. Live JS evaluation, module reloading, remote shell execution, and advanced block pagination!
+- 🛠️ **Native Developer Tools (`dnxt`)**: A comprehensive, built-in developer suite. Live JS evaluation, remote shell execution, and instant Hot-Module Reloading!
 - 🔄 **Hot Module Replacement (HMR)**: Live-reload your commands, events, and logic on save without ever dropping your Discord Gateway connection.
-- 🗄️ **Strict Database Interop**: The entire framework `<DB>` generic safely propagates your ORM (Prisma, Mongoose, Supabase) universally without global ambient overrides.
+- 🗄️ **Strict Database Interop**: Connect your ORM (Prisma, Mongoose) securely.
 - 🌍 **Localization (i18n)**: Out-of-the-box native string translations.
 - 🛡️ **Middleware Routing**: Global `beforeExecute` hooks for overarching permission checks and analytics.
-- 🚦 **Built-in Safety**: The interaction core automatically resolves `cooldowns`, `userPermissions`, `developerOnly`, and `guildOnly` rules before execution.
+- 🚦 **Persistent Cooldowns**: Connect custom cache adapters (like Redis) for global persistent cooldown tracking.
+- 📄 **PaginationBuilder**: A built-in class for creating robust interactive pagination menus.
 
 ## 📦 Installation
 
 ```bash
-npm install djs-next discord.js dotenv
+npm install djs-next
 ```
 *(Or use `pnpm`, `yarn`, or `bun`)*
 
@@ -44,9 +45,7 @@ If you prefer to start manually, here's how to bootstrap `djs-next`:
 
 ### 1. The Entry Point (`index.js`)
 ```javascript
-require('dotenv').config();
-const { GatewayIntentBits } = require('discord.js');
-const { DJSNextClient } = require('djs-next');
+const { GatewayIntentBits, DJSNextClient } = require('djs-next');
 const { PrismaClient } = require('@prisma/client'); // Optional Database
 
 const db = new PrismaClient();
@@ -54,12 +53,18 @@ const db = new PrismaClient();
 const client = new DJSNextClient({
   intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
   developers: ['YOUR_DISCORD_ID'], // Required for Developer Tools
-  prefixes: ['!', '?'], // Standard prefixes. Pass [''] for no-prefix commands!
-  enableMentionPrefix: true // Allows "@Bot ping" to work natively
+  
+  // Explicit Framework Toggles
+  enableSlashCommands: true,
+  enableTextCommands: true,
+  enableMentionPrefix: true, 
+  enableNoPrefix: false, 
+  prefixes: ['!', '?'], // Standard prefixes
+  
+  // Connect your database (Mongoose, Prisma, etc.)
+  db: db,
 });
 
-// Attach your database for global framework availability
-client.db = db;
 
 // Enable Hot-Module Reloading (HMR) for dev
 client.enableHMR();
@@ -104,6 +109,25 @@ module.exports = {
     await interaction.reply(`Banning user ${targetId}...`);
   }
 };
+```
+
+  }
+};
+```
+
+### 4. Interactive Pagination
+You no longer need to write complex collectors for simple pagination menus. `djs-next` ships with a `PaginationBuilder`:
+```javascript
+const { PaginationBuilder } = require('djs-next');
+const { EmbedBuilder } = require('discord.js');
+
+// Inside a command execute function:
+const paginator = new PaginationBuilder()
+  .addPage(new EmbedBuilder().setDescription('Page 1'))
+  .addPage(new EmbedBuilder().setDescription('Page 2'))
+  .setTimeout(60000);
+
+await paginator.build(interaction);
 ```
 
 ---
@@ -116,20 +140,18 @@ Because `djs-next` uses a global `<DB>` generic, you can natively bind any popul
 
 ```javascript
 // index.js
-require('dotenv').config();
 const mongoose = require('mongoose');
-const { DJSNextClient } = require('djs-next');
-const { GatewayIntentBits } = require('discord.js');
+const { DJSNextClient, GatewayIntentBits } = require('djs-next');
 
 // Connect to Atlas
 mongoose.connect(process.env.MONGO_URI);
 
 // Initialize DJSNext
 const client = new DJSNextClient({
-  intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages ]
+  intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages ],
+  db: mongoose
 });
 
-client.db = mongoose;
 client.start(process.env.TOKEN);
 ```
 
@@ -152,18 +174,16 @@ module.exports = {
 
 ```javascript
 // index.js
-require('dotenv').config();
 const { createClient } = require('@supabase/supabase-js');
-const { DJSNextClient } = require('djs-next');
-const { GatewayIntentBits } = require('discord.js');
+const { DJSNextClient, GatewayIntentBits } = require('djs-next');
 
 const supabase = createClient('https://xyz.supabase.co', process.env.SUPABASE_KEY);
 
 const client = new DJSNextClient({
-  intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages ]
+  intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages ],
+  db: supabase
 });
 
-client.db = supabase;
 client.start(process.env.TOKEN);
 ```
 
@@ -190,18 +210,15 @@ module.exports = {
 
 | Command | Action |
 | --- | --- |
-| `dnxt js <code>` | Evaluates Javascript live with pagination, async resolution, and timer tracing. |
-| `dnxt sh <cmd>` | Executes raw shell/terminal code on your host machine (e.g., `dnxt sh npm run build`). |
+| `dnxt js <code>` | Evaluates Javascript live with async resolution. |
+| `dnxt sh <cmd>` | Executes raw shell/terminal code on your host machine. |
 | `dnxt git <cmd>` | Executes standard git workflows (e.g., `dnxt git pull`). |
-| `dnxt su <id> <cmd>`| Triggers a mock message command mimicking another user's execution perspective. |
+| `dnxt in <channelId> <text>`| Injects a message seamlessly into a specific channel as the bot. |
 | `dnxt reload <target>` | Hot-swaps the internal cache. (e.g., `dnxt reload commands`, `dnxt reload all`). |
-| `dnxt source <cmd>` | Directly `fs.readFileSync`s the underlying source code of an active command! |
 | `dnxt debug <cmd>` | Executes Javascript while explicitly tracking the Node.js V8 Heap Memory Delta. |
-| `dnxt tasks` | Views all running background `setInterval` tasks in the framework. |
-| `dnxt cancel <task>` | Forcefully kills a background interval process. |
 | `dnxt sync` | Manually forces a global Discord Slash Command synchronization. |
-| `dnxt sql <query>` | Attempts to execute a raw SQL query against your `client.db` connection. |
-| `dnxt vc` | Dumps VoiceChannel state and Voice Debugger information. |
+| `dnxt restart` | Safely spawns a new background process and shuts down the current one. |
+| `dnxt stop` or `dnxt shutdown` | Fully disconnects the client and kills the Node process. |
 | `dnxt` | Displays the Developer Dashboard tracking System RAM, Node Host status, and Process uptime. |
 
 ---
@@ -220,6 +237,11 @@ module.exports = {
     components: 'src/components',
     tasks: 'src/tasks',
     locales: 'src/locales'
+  },
+  // Optional Redis or persistent cache adapter for cooldowns
+  cooldownAdapter: {
+    get: async (cmdId, userId) => { /* return timestamp or null */ },
+    set: async (cmdId, userId, expiration) => { /* save to db */ }
   }
 };
 ```

package/bin/create-djs-next.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const projectDir = process.cwd();
+
+console.log('🚀 Welcome to create-djs-next! Scaffolding your project...\n');
+
+const dirsToCreate = [
+  'src/commands',
+  'src/events',
+  'src/components',
+  'src/tasks',
+  'src/locales'
+];
+
+for (const dir of dirsToCreate) {
+  const dirPath = path.join(projectDir, dir);
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+    console.log(`✅ Created directory: ${dir}`);
+  }
+}
+
+const envContent = `DISCORD_TOKEN=your_token_here\nCLIENT_ID=your_client_id\nGUILD_ID=your_dev_guild_id`;
+const envPath = path.join(projectDir, '.env');
+if (!fs.existsSync(envPath)) {
+  fs.writeFileSync(envPath, envContent);
+  console.log('✅ Created .env file');
+}
+
+const indexContent = `const { GatewayIntentBits, DJSNextClient } = require('djs-next');
+
+const client = new DJSNextClient({
+  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
+  developers: ['YOUR_DISCORD_USER_ID'],
+  clientId: process.env.CLIENT_ID,
+  
+  // Framework Toggles
+  enableSlashCommands: true,
+  enableTextCommands: true,
+  enableMentionPrefix: true, 
+  enableNoPrefix: false, 
+  prefixes: ['!', '?'], 
+  
+  // Custom Middleware
+  middleware: (interactionOrMessage, client) => {
+    return true; // Return false to block execution
+  },
+
+  // Configuration
+  config: {
+    devGuildId: process.env.GUILD_ID,
+    locales: ['en'],
+    defaultLocale: 'en',
+    responses: {
+      developerOnly: '⛔ This command is restricted to bot developers.',
+      guildOnly: '⛔ This command can only be used inside a server.',
+      cooldown: '⏳ You are on cooldown! Please wait {time}.',
+      missingPerms: '⛔ You lack permissions.',
+      errorBoundary: '❌ An unexpected error occurred.',
+    }
+  }
+});
+
+client.enableHMR();
+client.enableDevTools('dnxt'); // Enable 'dnxt' prefix dev commands
+client.start(process.env.DISCORD_TOKEN);
+\`;
+
+const indexPath = path.join(projectDir, 'index.js');
+if (!fs.existsSync(indexPath)) {
+  fs.writeFileSync(indexPath, indexContent);
+  console.log('✅ Created index.js');
+}
+
+console.log('\n🎉 Scaffolding complete! Run \`npm install djs-next\` and start coding!');

package/dist/index.d.mts

@@ -1,9 +1,20 @@
-import * as discord_js from 'discord.js';
 import { ApplicationCommandOptionData, PermissionResolvable, ChatInputCommandInteraction, Client, Message, AutocompleteInteraction, MessageComponentInteraction, ModalSubmitInteraction, ClientOptions, Interaction, ClientEvents, Collection, CommandInteraction, EmbedBuilder } from 'discord.js';
 export * from 'discord.js';
 
+interface CooldownAdapter {
+    get(commandId: string, userId: string): Promise<number | null> | number | null;
+    set(commandId: string, userId: string, expirationTime: number): Promise<void> | void;
+}
 interface DJSNextConfig {
     devGuildId?: string;
+    errorLogChannelId?: string;
+    responses?: {
+        developerOnly?: string | null;
+        guildOnly?: string | null;
+        cooldown?: string | null;
+        missingPerms?: string | null;
+        errorBoundary?: string | null;
+    };
     locales?: string[];
     defaultLocale?: string;
     directories?: {
@@ -13,6 +24,7 @@ interface DJSNextConfig {
         tasks?: string;
         locales?: string;
     };
+    cooldownAdapter?: CooldownAdapter;
 }
 interface DJSNextClientOptions extends ClientOptions {
     commandsDir?: string;
@@ -23,9 +35,13 @@ interface DJSNextClientOptions extends ClientOptions {
     guildId?: string;
     developers?: string[];
     prefixes?: string[] | string;
-    enableMentionPrefix?: boolean;
+    enableSlashCommands?: boolean;
+    enableTextCommands?: boolean;
+    enableMentionPrefix?: boolean | string[];
+    enableNoPrefix?: boolean | string[];
     middleware?: (interaction: Interaction | Message, client: Client) => Promise<boolean> | boolean;
     config?: DJSNextConfig;
+    db?: any;
 }
 interface FileTask<DB = any> {
     filepath?: string;
@@ -46,6 +62,7 @@ interface FileCommand<DB = any> {
     developerOnly?: boolean;
     guildOnly?: boolean;
     aliases?: string[];
+    preconditions?: string[];
     execute?: (interaction: ChatInputCommandInteraction, client: Client & {
         db: DB;
         t: Function;
@@ -65,6 +82,7 @@ interface FileCommand<DB = any> {
 interface FileComponent<DB = any> {
     filepath?: string;
     customId?: string;
+    preconditions?: string[];
     execute: (interaction: MessageComponentInteraction | ModalSubmitInteraction, client: Client & {
         db: DB;
         t: Function;
@@ -103,17 +121,41 @@ declare class DJSNextClient<DB = any> extends Client {
     private _developers;
     private _middleware?;
     private _prefixes;
+    private _enableSlashCommands;
+    private _enableTextCommands;
     private _enableMentionPrefix;
+    private _enableNoPrefix;
     constructor(options: DJSNextClientOptions);
     private attachCoreListeners;
     start(token: string): Promise<void>;
     enableDevTools(prefix?: 'dnxt' | 'nxt'): void;
     enableHMR(): Promise<void>;
+    private handleCommandError;
+    private handlePreconditions;
 }
 
-declare function paginate(interaction: CommandInteraction | MessageComponentInteraction, pages: EmbedBuilder[], time?: number): Promise<discord_js.Message<boolean> | undefined>;
+declare function paginate(context: Message | CommandInteraction | MessageComponentInteraction, pages: EmbedBuilder[], time?: number): Promise<Message<boolean> | undefined>;
+
+/**
+ * Sends a confirmation prompt (Yes/No) to the user.
+ * @param context The message or interaction context.
+ * @param content The text or embed to display in the prompt.
+ * @param time Time to wait for a response in milliseconds.
+ * @returns Boolean indicating true for Yes, false for No, or null if timed out.
+ */
+declare function confirmPrompt(context: Message | CommandInteraction | MessageComponentInteraction, content: string | EmbedBuilder, time?: number): Promise<boolean | null>;
 
 declare function loadConfig(): Promise<DJSNextConfig>;
 declare function defineConfig(config: DJSNextConfig): DJSNextConfig;
 
-export { DJSNextClient, type DJSNextClientOptions, type DJSNextConfig, type Event as DJSNextEvent, type FileCommand, type FileComponent, type FileTask, defineConfig, getLocalesCache, loadConfig, loadLocales, paginate, translate };
+declare class PaginationBuilder {
+    private pages;
+    private timeout;
+    constructor(pages?: EmbedBuilder[]);
+    addPage(embed: EmbedBuilder): this;
+    setPages(pages: EmbedBuilder[]): this;
+    setTimeout(ms: number): this;
+    build(target: CommandInteraction | Message): Promise<Message | null>;
+}
+
+export { type CooldownAdapter, DJSNextClient, type DJSNextClientOptions, type DJSNextConfig, type Event as DJSNextEvent, type FileCommand, type FileComponent, type FileTask, PaginationBuilder, confirmPrompt, defineConfig, getLocalesCache, loadConfig, loadLocales, paginate, translate };

package/dist/index.d.ts

@@ -1,9 +1,20 @@
-import * as discord_js from 'discord.js';
 import { ApplicationCommandOptionData, PermissionResolvable, ChatInputCommandInteraction, Client, Message, AutocompleteInteraction, MessageComponentInteraction, ModalSubmitInteraction, ClientOptions, Interaction, ClientEvents, Collection, CommandInteraction, EmbedBuilder } from 'discord.js';
 export * from 'discord.js';
 
+interface CooldownAdapter {
+    get(commandId: string, userId: string): Promise<number | null> | number | null;
+    set(commandId: string, userId: string, expirationTime: number): Promise<void> | void;
+}
 interface DJSNextConfig {
     devGuildId?: string;
+    errorLogChannelId?: string;
+    responses?: {
+        developerOnly?: string | null;
+        guildOnly?: string | null;
+        cooldown?: string | null;
+        missingPerms?: string | null;
+        errorBoundary?: string | null;
+    };
     locales?: string[];
     defaultLocale?: string;
     directories?: {
@@ -13,6 +24,7 @@ interface DJSNextConfig {
         tasks?: string;
         locales?: string;
     };
+    cooldownAdapter?: CooldownAdapter;
 }
 interface DJSNextClientOptions extends ClientOptions {
     commandsDir?: string;
@@ -23,9 +35,13 @@ interface DJSNextClientOptions extends ClientOptions {
     guildId?: string;
     developers?: string[];
     prefixes?: string[] | string;
-    enableMentionPrefix?: boolean;
+    enableSlashCommands?: boolean;
+    enableTextCommands?: boolean;
+    enableMentionPrefix?: boolean | string[];
+    enableNoPrefix?: boolean | string[];
     middleware?: (interaction: Interaction | Message, client: Client) => Promise<boolean> | boolean;
     config?: DJSNextConfig;
+    db?: any;
 }
 interface FileTask<DB = any> {
     filepath?: string;
@@ -46,6 +62,7 @@ interface FileCommand<DB = any> {
     developerOnly?: boolean;
     guildOnly?: boolean;
     aliases?: string[];
+    preconditions?: string[];
     execute?: (interaction: ChatInputCommandInteraction, client: Client & {
         db: DB;
         t: Function;
@@ -65,6 +82,7 @@ interface FileCommand<DB = any> {
 interface FileComponent<DB = any> {
     filepath?: string;
     customId?: string;
+    preconditions?: string[];
     execute: (interaction: MessageComponentInteraction | ModalSubmitInteraction, client: Client & {
         db: DB;
         t: Function;
@@ -103,17 +121,41 @@ declare class DJSNextClient<DB = any> extends Client {
     private _developers;
     private _middleware?;
     private _prefixes;
+    private _enableSlashCommands;
+    private _enableTextCommands;
     private _enableMentionPrefix;
+    private _enableNoPrefix;
     constructor(options: DJSNextClientOptions);
     private attachCoreListeners;
     start(token: string): Promise<void>;
     enableDevTools(prefix?: 'dnxt' | 'nxt'): void;
     enableHMR(): Promise<void>;
+    private handleCommandError;
+    private handlePreconditions;
 }
 
-declare function paginate(interaction: CommandInteraction | MessageComponentInteraction, pages: EmbedBuilder[], time?: number): Promise<discord_js.Message<boolean> | undefined>;
+declare function paginate(context: Message | CommandInteraction | MessageComponentInteraction, pages: EmbedBuilder[], time?: number): Promise<Message<boolean> | undefined>;
+
+/**
+ * Sends a confirmation prompt (Yes/No) to the user.
+ * @param context The message or interaction context.
+ * @param content The text or embed to display in the prompt.
+ * @param time Time to wait for a response in milliseconds.
+ * @returns Boolean indicating true for Yes, false for No, or null if timed out.
+ */
+declare function confirmPrompt(context: Message | CommandInteraction | MessageComponentInteraction, content: string | EmbedBuilder, time?: number): Promise<boolean | null>;
 
 declare function loadConfig(): Promise<DJSNextConfig>;
 declare function defineConfig(config: DJSNextConfig): DJSNextConfig;
 
-export { DJSNextClient, type DJSNextClientOptions, type DJSNextConfig, type Event as DJSNextEvent, type FileCommand, type FileComponent, type FileTask, defineConfig, getLocalesCache, loadConfig, loadLocales, paginate, translate };
+declare class PaginationBuilder {
+    private pages;
+    private timeout;
+    constructor(pages?: EmbedBuilder[]);
+    addPage(embed: EmbedBuilder): this;
+    setPages(pages: EmbedBuilder[]): this;
+    setTimeout(ms: number): this;
+    build(target: CommandInteraction | Message): Promise<Message | null>;
+}
+
+export { type CooldownAdapter, DJSNextClient, type DJSNextClientOptions, type DJSNextConfig, type Event as DJSNextEvent, type FileCommand, type FileComponent, type FileTask, PaginationBuilder, confirmPrompt, defineConfig, getLocalesCache, loadConfig, loadLocales, paginate, translate };