@stambha/args

Typed argument parsing — prefix command lexer and slash option resolver. Sapphire @sapphire/plugin-subcommands Args parity without coupling to discord.js.

Part of the @stambha monorepo · GitHub

Install

npm install @stambha/args @stambha/core

Requires Node.js 20+.

Quick start

Prefix commands

import { Args, replyIfArgError, stringArg, unwrapArg } from "@stambha/args";
import { Command, ok, type CommandContext, type Registry } from "@stambha/core";

export class EchoCommand extends Command {
  constructor(registry: Registry<Command>) {
    super(registry, { name: "echo", kinds: ["prefix"] });
  }

  async execute(ctx: CommandContext) {
    const args = Args.fromContext(ctx);
    const picked = args.pick(stringArg);
    if (await replyIfArgError(ctx, picked)) return ok(undefined);

    const text = unwrapArg(picked);
    await ctx.reply(text ?? "Usage: `!echo <message>`");
    return ok(undefined);
  }
}

Slash commands

import { SlashArgs } from "@stambha/args";

const args = SlashArgs.fromContext(ctx);
const target = args.getString("target");
const count = args.getInteger("count");

Reply on parse errors

import { replyIfArgError } from "@stambha/args";

if (await replyIfArgError(ctx, picked)) return ok(undefined);

Built-in resolvers

| Resolver | Parses | |----------|--------| | stringArg | Raw token | | integerArg, numberArg, booleanArg | Numeric / boolean literals | | snowflakeArg | Discord snowflake id | | userMentionArg | <@id> mention or raw id | | channelMentionArg | <#id> mention or raw id | | roleMentionArg | <@&id> mention or raw id | | rest (via registry) | Remaining tokens as one string |

REST-backed resolvers (fetch user/member/channel objects) are not built in — use @stambha/rest fetchUser / fetchGuildMember with defineArgResolver. Full Sapphire-style entity resolvers are planned for 1.x B2.

Low-level lexer: tokenize, joinFrom.

Key exports

| Export | Purpose | |--------|---------| | Args | Prefix argument parsers | | SlashArgs, slashArgsFromContext | Slash option parsers | | tokenize, joinFrom | Prefix lexer | | replyArgError, replyIfArgError | User-facing arg errors |

Related packages

| Package | Role | |---------|------| | @stambha/core | CommandContext, ctx.args | | @stambha/gates | Run checks before parsing |

Development

pnpm --filter @stambha/args build
pnpm --filter @stambha/args test