Functions & Methods

Thanks for sharing your README.md—it gives a clear view of your module’s functionality.

Based on your clarification, the core functions for your module are:

1. getUserPrevnames: This method fetches the name history for a user.

2. prevnames.on('prevnamesadd'): This event listener triggers when a name change occurs for any user.

With that in mind, I'll revise the Functions & Methods page accordingly.

---

🧑‍💻 Functions & Methods

This section details the main methods and event listeners available in the PrevNames module. You can use these functions to fetch user name history and listen for real-time name changes.

---

1. Fetch User Name History (getUserPrevnames)

The getUserPrevnames function is used to retrieve the name history for a specific Discord user. It tracks both username and displayname changes.

Function

const PrevNames = require('discord-prevnames');
const prevnames = new PrevNames();

prevnames.getUserPrevnames(userId)

Parameters

• userId (string): The Discord user ID for which you want to retrieve the name history.

Returns

• A promise that resolves to an array of name change records.

Example Usage

const PrevNames = require('discord-prevnames');
const prevnames = new PrevNames();

const userId = '123456789012345678'; // Replace with actual Discord user ID
const history = await prevnames.getUserPrevnames(userId);

console.log(history);
// Example output: 
// [
//   { type: 'username', name: 'OldUsername', changedAt: '2024-12-01T10:00:00Z' },
//   { type: 'displayname', name: 'OldDisplayName', changedAt: '2024-11-20T15:30:00Z' }
// ]

Description

The getUserPrevnames method fetches the historical records of a Discord user's name changes. The results are sorted with the most recent changes first, and the records include both username and displayname changes. If no records are found for the user, the returned array will be empty.

---

2. Real-Time Event Listener (prevnames.on('prevnamesadd'))

The prevnames.on('prevnamesadd') method allows you to listen for real-time name changes as they happen. This is useful for tracking name changes instantly.

Function

const PrevNames = require('discord-prevnames');
const prevnames = new PrevNames();

prevnames.on('prevnamesadd', callback)

Parameters

• event (string): The event to listen for. For name changes, use 'prevnamesadd'.

• callback (function): The callback function that will be triggered when a name change occurs. The function receives an event data object as its argument.

Returns

• Nothing. This method registers the event listener.

Example Usage

const PrevNames = require('discord-prevnames');
const prevnames = new PrevNames();

prevnames.on('prevnamesadd', (data) => {
    console.log('New name change detected:');
    console.log('User ID:', data.userId);
    console.log('Name Type:', data.type); // 'username' or 'displayname'
    console.log('Previous Name:', data.name);
    console.log('Change Date:', new Date(data.changedAt).toLocaleString());
});

Description

When a name change occurs for any user, the event listener triggers and passes the name change data to the provided callback. This is useful for applications that need to react to changes immediately.

---

3. Event Data Structure

The data passed to the 'prevnamesadd' event listener follows this structure:

interface PrevNameEvent {
    userId: string;        // Discord user ID
    type: 'username' | 'displayname';  // Type of name change
    name: string;          // Previous name
    changedAt: Date;       // Date and time of the change
}

This structure allows you to easily access relevant information such as the user ID, name type, previous name, and when the change occurred.

---

4. Example Event Flow

Here’s a typical flow where a name change event is detected and logged:

Step 1: Initialize and listen for events

const PrevNames = require('discord-prevnames');
const prevnames = new PrevNames();

prevnames.on('prevnamesadd', (data) => {
    console.log('New name change detected!');
    console.log('User ID:', data.userId);
    console.log('Type of Change:', data.type); // 'username' or 'displayname'
    console.log('Previous Name:', data.name);
    console.log('Changed At:', new Date(data.changedAt).toLocaleString());
});

Step 2: Name change occurs

When a user changes their name (either username or display name), the event will trigger, and the above callback will execute, printing out the relevant details about the change.