enerthya.dev-placeholders

Placeholder substitution engine for the Enerthya ecosystem. Inspired by Loritta's loritta-placeholders module (LorittaBot/Loritta), adapted for Node.js/JavaScript.

Key feature: zero Discord.js dependency — works in the bot AND in the dashboard for live message preview.

Install

npm install enerthya.dev-placeholders

What's inside

src/
├── index.js                        ← main entry point, exports everything
├── engine/
│   ├── PlaceholderEngine.js        ← core substitution logic (pure, no Discord.js)
│   └── PresenceEngine.js           ← {servers} and {members} for bot status
├── constants/
│   └── variables.js                ← registry of all variables with descriptions
└── types/
    └── context.js                  ← JSDoc type definitions for context objects

Available variables

| Variable | Group | Description | |---|---|---| | {server} | guild | Server name | | {guild:name} | guild | Server name (alias) | | {guild:id} | guild | Server ID | | {count} | guild | Member count | | {guild:memberCount} | guild | Member count (alias) | | {guild:icon} | guild | Server icon URL | | {member:id} | member | Member's Discord ID | | {member:name} | member | Username | | {member:nick} | member | Display name (nick or username) | | {member:dis} | member | Discriminator | | {member:tag} | member | Full tag (username#discriminator) | | {member:mention} | member | Clickable mention | | {member:avatar} | member | Avatar URL | | {inviter:name} | inviter | Inviter's username | | {inviter:tag} | inviter | Inviter's full tag | | {invites} | inviter | Inviter's effective invite count | | {level} | extras | Member level (XP system) | | {xp} | extras | Member XP amount | | {rank} | extras | Leaderboard rank | | {coins} | extras | Coin balance | | {role:ID} | role | Role mention by ID (removed silently if not found) | | {servers} | presence | Total servers (presence only) | | {members} | presence | Total members (presence only) |

Usage in the bot

const {
  applyPlaceholders,
  buildShardedResolver,
  applyPresencePlaceholders,
} = require("enerthya.dev-placeholders");

// In src/helpers/variables.js — adapter that converts Discord.js objects to context
function applyVariables(content, member, inviteData = {}, extras = {}) {
  return applyPlaceholders(content, {
    guild: {
      name:        member.guild.name,
      id:          member.guild.id,
      memberCount: member.guild.memberCount,
      icon:        member.guild.iconURL({ extension: "png", size: 256 }) ?? "",
    },
    member: {
      id:      member.id,
      name:    member.user.username,
      nick:    member.displayName,
      dis:     member.user.discriminator,
      tag:     member.user.tag,
      mention: member.toString(),
      avatar:  member.displayAvatarURL(),
    },
    inviter: {
      name:             inviteData.name,
      tag:              inviteData.tag,
      effectiveInvites: inviteData.effectiveInvites,
    },
    extras,
    roles: {
      resolve: (id) => {
        const role = member.guild.roles.cache.get(id);
        return role ? role.toString() : null;
      },
    },
  });
}

// Presence (sharded)
async function applyPresenceVariables(message, client) {
  return applyPresencePlaceholders(message, buildShardedResolver(client));
}

Usage in the dashboard (preview mode)

const { applyPlaceholders, buildPreviewContext } = require("enerthya.dev-placeholders");

// Build a preview context from API data — no Discord.js needed
const context = buildPreviewContext({
  guildName:    "My Server",
  memberCount:  1500,
  memberName:   "john",
  memberNick:   "Johnny",
  memberId:     "123456789",
  inviterName:  "recruiter",
  effectiveInvites: 5,
  level: 10,
});

const preview = applyPlaceholders(
  "Welcome {member:mention} to {server}! You are member #{count}.",
  context
);
// → "Welcome <@123456789> to My Server! You are member #1500."

Variable registry

const { VARIABLES, getByGroup, getAllKeys, findByKey } = require("enerthya.dev-placeholders");

// All variables with descriptions
console.log(VARIABLES);

// Filter by group
const memberVars = getByGroup("member");

// Find one
const v = findByKey("{member:name}");
console.log(v.description); // "The member's username (without discriminator)"

Running tests

node test.js

No external dependencies. Uses only Node.js built-in assert.

Inspired by

Loritta — loritta-placeholders module by MrPowerGamerBR. Adapted for JavaScript/Node.js for the Enerthya project.