spearkit 0.3.0 → 0.3.1

package/docs/getting-started.md

@@ -0,0 +1,147 @@
+# Getting started
+
+spearkit is **discord.js++**: it re-exports the entire discord.js surface and adds a
+fully type-safe layer for events, slash commands and interactive components. This
+page takes you from an empty folder to a running bot that responds to a slash
+command.
+
+## Install
+
+spearkit sits alongside discord.js, so install both:
+
+```bash
+npm install spearkit discord.js
+```
+
+Everything in your code imports from `"spearkit"` — including the plain discord.js
+symbols, which spearkit re-exports unchanged.
+
+## Credentials you need
+
+Create an application in the [Discord Developer Portal](https://discord.com/developers/applications)
+and collect three values:
+
+| Value | Where to find it | Used for |
+| ----- | ---------------- | -------- |
+| Bot token | Application → **Bot** → *Reset Token* | `client.start(token)` |
+| Application id | Application → **General Information** → *Application ID* | command deployment (spearkit reads it from the client once ready) |
+| Test guild id | Right-click your server in Discord (with Developer Mode on) → *Copy Server ID* | guild-scoped deploy |
+
+Keep the token secret. The examples below read these from the environment
+(`DISCORD_TOKEN`, `GUILD_ID`).
+
+## Your first bot
+
+```ts
+import { SpearClient, Intents, command, option, event } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: {
+    who: option.user({ description: "Who to greet", required: true }),
+  },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // ctx.options.who: User
+});
+
+const ready = event("clientReady", (c) => console.log(`Online as ${c.user.tag}`));
+
+client.register(greet, ready);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+What each step does:
+
+1. **`new SpearClient({ intents })`** — a discord.js `Client` with command, event
+   and component routing wired up. `Intents.default` is `[Guilds]`, enough for
+   slash commands and interactions.
+2. **`command({ ... })`** — defines a leaf slash command. Required options resolve
+   to their value type (`who` is a `User`); optional options would resolve to
+   `value | undefined`.
+3. **`client.register(...)`** — routes each item to the matching registry
+   (commands, events, components) by its kind.
+4. **`client.start(token)`** — logs in. With no argument it falls back to the
+   `DISCORD_TOKEN` environment variable.
+5. **`client.deployCommands({ guildId })`** — pushes your command definitions to
+   Discord over the client's own authenticated REST connection. Must run after the
+   client is ready (i.e. after `start`).
+
+### Guild vs global deploy
+
+`deployCommands` takes an optional `guildId`:
+
+- **Guild deploy** (`{ guildId }`) registers commands in a single server. Changes
+  appear **instantly** — ideal while developing.
+- **Global deploy** (omit `guildId`) registers commands across every server the
+  bot is in. Propagation can take up to an hour.
+
+```ts
+await client.deployCommands({ guildId: process.env.GUILD_ID }); // instant, one guild
+await client.deployCommands();                                  // global, slow to propagate
+```
+
+You only need to deploy when your command *definitions* change (names,
+descriptions, options) — not on every restart.
+
+## Suggested project layout
+
+As a bot grows, give each command, event and component its own file:
+
+```
+my-bot/
+  src/
+    index.ts          # construct the client, register/load, start, deploy
+    commands/
+      greet.ts
+      ping.ts
+    events/
+      ready.ts
+    components/
+      vote.ts
+  package.json
+  tsconfig.json
+```
+
+A module exports a command, event or component as a default or named export:
+
+```ts
+// src/commands/ping.ts
+import { command } from "spearkit";
+
+export default command({
+  name: "ping",
+  description: "Check that the bot is alive",
+  run: (ctx) => ctx.reply(`Pong! ${ctx.client.ws.ping}ms`),
+});
+```
+
+You can wire the pieces up explicitly with `register`, or let spearkit discover them
+with `client.load` (see [File-based loading](./loading.md)).
+
+## Running it
+
+**With tsx** (run TypeScript directly, great for development):
+
+```bash
+npx tsx src/index.ts
+```
+
+**Compiled JavaScript** (for production):
+
+```bash
+npx tsc            # emit JS into dist/ per your tsconfig
+node dist/index.js
+```
+
+Note that `client.load` imports **compiled JavaScript**, so if you use file-based
+loading you must build before running the compiled output. Explicit `register`
+calls work the same under `tsx` or `node`.
+
+## See also
+
+- [Client](./client.md) — `SpearClient`, intents, `register`, `start`, deployment.
+- [Commands](./commands.md) — slash commands, subcommands, options, deployment.

package/docs/loading.md

@@ -0,0 +1,142 @@
+# File-based loading
+
+Instead of importing and registering every handler by hand, you can keep one
+command, event or component per file and let spearkit discover them. The loader
+imports a directory, inspects each module's exports, and registers everything that
+is a command, event or component.
+
+## `client.load`
+
+```ts
+load(dir: string, options?: LoadOptions): Promise<number>
+```
+
+`client.load` imports `dir` and registers every spearkit-registrable export it finds,
+resolving to the number of items registered.
+
+```ts
+import { fileURLToPath } from "node:url";
+import { SpearClient, Intents } from "spearkit";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+
+const client = new SpearClient({ intents: Intents.default });
+
+const loaded =
+  (await client.load(`${here}commands`)) +
+  (await client.load(`${here}events`)) +
+  (await client.load(`${here}components`));
+console.log(`Loaded ${loaded} modules.`);
+
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+```
+
+### What gets registered
+
+For every imported file, spearkit walks **all** of its exports — default *and*
+named — and registers each value that is a command (`command`, `commandGroup`),
+an event (`event`), or a component (`button`, `stringSelect`, `modal`, …). Other
+exports (helpers, constants, types) are ignored. So both of these are picked up:
+
+```ts
+// default export
+export default command({ name: "ping", description: "…", run: (ctx) => ctx.reply("pong") });
+```
+
+```ts
+// named export
+export const vote = button({ id: "vote:{choice}", label: "Vote", run: (ctx) => ctx.update(ctx.params.choice) });
+```
+
+### Options
+
+```ts
+interface LoadOptions {
+  extensions?: readonly string[]; // default: [".js", ".mjs", ".cjs"]
+  recursive?: boolean;            // default: true
+}
+```
+
+- **`extensions`** — which file extensions to import. By default the loader reads
+  `.js`, `.mjs` and `.cjs` — i.e. **compiled JavaScript**, not `.ts` source.
+- **`recursive`** — by default the loader descends into subdirectories. Pass
+  `recursive: false` to load only the top level.
+
+```ts
+await client.load(`${here}features`, { recursive: false });
+```
+
+> The loader imports compiled JavaScript. **Build your TypeScript first**, then run
+> (and load) the emitted output — `npx tsc && node dist/index.js`. Loading a
+> directory of `.ts` source files will not match the default extensions.
+
+## Standalone helpers
+
+`client.load` is the method form of `loadInto`. Both helpers are exported if you
+want to collect or register modules separately.
+
+```ts
+collectModules(dir: string, options?: LoadOptions): Promise<Registerable[]>
+loadInto(client: SpearClient, dir: string, options?: LoadOptions): Promise<number>
+```
+
+- **`collectModules`** imports a directory and returns the registrable exports it
+  found, without touching any client. Use it to inspect, filter, or combine
+  modules before registering.
+- **`loadInto`** calls `collectModules` and then `client.register(...)` for you,
+  returning the count.
+
+```ts
+import { collectModules, loadInto } from "spearkit";
+
+// Inspect before registering:
+const items = await collectModules(`${here}commands`);
+console.log(`Found ${items.length} modules`);
+client.register(...items);
+
+// Or do both in one step:
+const count = await loadInto(client, `${here}events`);
+```
+
+## Example layout
+
+The `examples/file-based-loading` project keeps each handler in its own file:
+
+```
+file-based-loading/
+  index.ts            # construct client, load each folder, start, deploy
+  commands/
+    ping.ts           # export default command({ ... })
+    echo.ts           # export default command({ ... })
+  events/
+    ready.ts          # export default event("clientReady", ...)
+  components/
+    vote.ts           # export const vote = button({ ... })
+```
+
+A command file looks like this:
+
+```ts
+// commands/echo.ts
+import { command, option } from "spearkit";
+
+export default command({
+  name: "echo",
+  description: "Repeat a message",
+  options: {
+    text: option.string({ description: "What to say", required: true }),
+    loud: option.boolean({ description: "Shout it" }),
+  },
+  // text: string, loud: boolean | undefined
+  run: (ctx) => ctx.reply(ctx.options.loud ? ctx.options.text.toUpperCase() : ctx.options.text),
+});
+```
+
+Build the project, then run the compiled `index.js`; `client.load` will import the
+emitted `.js` files and register `ping`, `echo`, `ready` and `vote` for you.
+
+## See also
+
+- [Client](./client.md) — `load`, `register`, and the registries the loader writes to.
+- [Events](./events.md) — the `event()` helper that event modules export.

package/docs/logging.md

@@ -0,0 +1,195 @@
+# Logging
+
+spearkit ships a small, dependency-free structured logger. Every client owns one
+at `client.logger`, and spearkit routes its own command, component, event, and
+gateway errors through it. You can use the same logger for your code, or build a
+standalone one.
+
+## A first logger
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger(); // level "info", logs to the console
+log.info("bot starting");
+log.error("connection lost", { error: new Error("ECONNRESET") });
+```
+
+A logger is constructed from `LoggerOptions`:
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger({
+  level: "debug",   // minimum severity to emit; default "info"
+  scope: "worker",  // a prefix attached to every entry
+  // sink: consoleSink (the default)
+});
+```
+
+## Levels
+
+There are four levels, lowest to highest: `debug`, `info`, `warn`, `error`. The
+logger emits an entry only if its level is at or above the configured threshold.
+The default threshold is **`info`**, so `debug` entries are suppressed until you
+lower it. A fifth threshold, `"silent"`, suppresses everything.
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger(); // threshold "info"
+log.debug("only visible at debug"); // suppressed by default
+log.info("visible");
+
+log.setLevel("debug");        // now debug entries are emitted too
+log.enabled("debug");         // true
+log.setLevel("silent");       // suppress everything
+```
+
+| Method | Level | Use for |
+| ------ | ----- | ------- |
+| `log.debug(msg, opts?)` | `debug` | Verbose diagnostics, off by default. |
+| `log.info(msg, opts?)` | `info` | Normal operational messages. |
+| `log.warn(msg, opts?)` | `warn` | Recoverable problems worth attention. |
+| `log.error(msg, opts?)` | `error` | Failures; attach the cause via `{ error }`. |
+
+`log.level` reads the current threshold, `log.setLevel(level)` changes it, and
+`log.enabled(level)` reports whether an entry of that level would be emitted —
+handy to guard expensive message construction.
+
+## Scopes and child loggers
+
+`log.child("scope")` returns a child logger whose entries carry an extra scope
+segment. A child **shares its parent's threshold and sink**, so changing the
+level on any logger in the tree affects them all.
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger({ scope: "app" });
+const db = log.child("db");      // scope "app:db"
+const cache = db.child("cache"); // scope "app:db:cache"
+
+db.info("connected");
+log.setLevel("debug");           // affects log, db, and cache
+cache.debug("warm");             // now emitted
+```
+
+spearkit uses this internally: the client creates `commands`, `components`,
+`events`, `scheduler`, `prefix`, and `usage` children off `client.logger`, so
+every subsystem's output is scoped and a single `setLevel` controls them all.
+
+## Structured `data` and `error`
+
+Both arguments live in the optional second parameter (`LogOptions`):
+
+```ts
+import { Logger } from "spearkit";
+
+const log = new Logger();
+
+log.info("command finished", {
+  data: { command: "ping", ms: 12, cached: true },
+});
+
+try {
+  throw new Error("kaboom");
+} catch (cause) {
+  log.error("handler failed", {
+    error: cause instanceof Error ? cause : new Error(String(cause)),
+    data: { command: "purge", guildId: "123" },
+  });
+}
+```
+
+`data` is a flat record of primitives (`string | number | boolean | bigint |
+null | undefined`). `error` is an `Error`; the default sink renders its stack.
+
+### Coercing unknown throws
+
+A `catch` binding is `unknown`. `toError(value)` turns any thrown value into an
+`Error` so it fits `{ error }`:
+
+```ts
+import { Logger, toError } from "spearkit";
+
+const log = new Logger();
+try {
+  JSON.parse("{");
+} catch (cause) {
+  log.error("parse failed", { error: toError(cause) });
+}
+```
+
+## Custom sinks
+
+A sink is `(entry: LogEntry) => void`. The default is `consoleSink`, which writes
+human-readable lines to the console (stderr for `warn`/`error`). Pass your own to
+route entries anywhere — JSON lines, a file, an aggregator:
+
+```ts
+import { Logger, type LogEntry } from "spearkit";
+
+const log = new Logger({
+  level: "debug",
+  sink: (entry: LogEntry) => {
+    process.stdout.write(
+      JSON.stringify({
+        level: entry.level,
+        message: entry.message,
+        scope: entry.scope,
+        at: entry.timestamp.toISOString(),
+        data: entry.data,
+        error: entry.error?.message,
+      }) + "\n",
+    );
+  },
+});
+
+log.child("commands").info("dispatched", { data: { name: "ping" } });
+```
+
+A `LogEntry` is the fully-resolved record handed to the sink:
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `level` | `LogLevel` | One of `debug`/`info`/`warn`/`error`. |
+| `message` | `string` | The log message. |
+| `scope` | `string \| undefined` | The accumulated scope, if any. |
+| `timestamp` | `Date` | When the entry was created. |
+| `error` | `Error \| undefined` | The attached error, if any. |
+| `data` | `Record<string, LogValue> \| undefined` | The structured metadata, if any. |
+
+## Configuring via the client
+
+Pass `logger` to `SpearClient`. Give it `LoggerOptions` to build one, or a
+`Logger` instance you already have:
+
+```ts
+import { SpearClient, Logger } from "spearkit";
+
+// Build from options:
+const a = new SpearClient({ logger: { level: "debug" } });
+
+// Or reuse an instance (e.g. one shared with non-Discord code):
+const shared = new Logger({ level: "info", scope: "svc" });
+const b = new SpearClient({ logger: shared });
+
+a.logger.info("ready");
+```
+
+The client logs all command, component, and event handler errors plus gateway
+errors through `client.logger`. Set `level: "debug"` to see dispatch traces from
+every subsystem:
+
+```ts
+import { SpearClient } from "spearkit";
+
+const client = new SpearClient({ logger: { level: "debug" } });
+// client.logger.child("commands"), ".child('events')", etc. all log at debug now
+```
+
+## See also
+
+- [Client](./client.md) — the `logger` and other construction options.
+- [Environment & dotenv](./env.md) — load configuration before you start.

package/docs/migration.md

@@ -0,0 +1,160 @@
+# Migrating from discord.js
+
+spearkit re-exports the entire discord.js surface, so adopting it is not a rewrite —
+it is a one-line import change followed by *optional*, incremental cleanup. You can
+move to spearkit today and start using its ergonomic helpers whenever you like.
+
+## The drop-in story
+
+Change `from "discord.js"` to `from "spearkit"`. Nothing else has to change: every
+discord.js export is available under the same name with the same types.
+
+```ts
+// before
+import { Client, EmbedBuilder, GatewayIntentBits } from "discord.js";
+
+// after — identical behaviour
+import { Client, EmbedBuilder, GatewayIntentBits } from "spearkit";
+```
+
+The full classic surface is there — builders, enums, the REST client, route
+helpers, the `Events` map, and so on:
+
+```ts
+import {
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  Client,
+  EmbedBuilder,
+  Events,
+  GatewayIntentBits,
+  REST,
+  Routes,
+  SlashCommandBuilder,
+} from "spearkit";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+const pingCommand = new SlashCommandBuilder()
+  .setName("ping")
+  .setDescription("Replies with an embed and a button");
+
+client.once(Events.ClientReady, (c) => {
+  console.log(`Ready as ${c.user.tag}`);
+});
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (!interaction.isChatInputCommand()) return;
+  if (interaction.commandName !== "ping") return;
+
+  const embed = new EmbedBuilder().setTitle("Pong!").setDescription(`Latency: ${client.ws.ping}ms`);
+  const buttons = new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder().setCustomId("again").setLabel("Again").setStyle(ButtonStyle.Primary),
+  );
+  await interaction.reply({ embeds: [embed], components: [buttons] });
+});
+
+async function deploy(token: string, appId: string): Promise<void> {
+  const rest = new REST().setToken(token);
+  await rest.put(Routes.applicationCommands(appId), { body: [pingCommand.toJSON()] });
+}
+```
+
+This file is 100% classic discord.js — only the import source changed. It keeps
+working exactly as before.
+
+## Incremental adoption
+
+Once your imports point at spearkit, you can convert pieces one at a time. There is no
+big-bang migration; old and new styles coexist.
+
+1. **Swap the client.** Replace `new Client(...)` with `new SpearClient(...)`. It
+   *is* a discord.js `Client` (it extends it), so your existing `client.on`,
+   `client.once`, `client.ws`, `client.rest` code is unchanged — but now it also
+   routes interactions to spearkit's registries.
+
+   ```ts
+   import { SpearClient, Intents } from "spearkit";
+
+   const client = new SpearClient({ intents: Intents.default });
+   ```
+
+2. **Move commands to `command()`.** Replace a hand-written `SlashCommandBuilder`
+   plus its branch of the `interactionCreate` switch with a single co-located
+   definition. Option values become fully typed.
+3. **Move events to `event()`.** Replace `client.on(Events.X, ...)` listeners with
+   `event("x", ...)` definitions and register them.
+4. **Move components to spearkit builders.** Replace manual `ButtonBuilder` +
+   custom-id parsing with `button()`, `stringSelect()`, `modal()`, etc. — spearkit
+   routes them by custom-id namespace and decodes `{param}`s for you.
+
+Convert at whatever pace suits you; un-migrated handlers keep running through your
+existing `interactionCreate` listener.
+
+## Before and after
+
+The classic approach hand-routes every interaction through one big switch and
+parses custom ids by hand:
+
+```ts
+// discord.js: one listener routes everything by hand
+import { Client, Events, GatewayIntentBits } from "discord.js";
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+client.on(Events.InteractionCreate, async (interaction) => {
+  if (interaction.isChatInputCommand()) {
+    if (interaction.commandName === "greet") {
+      const who = interaction.options.getUser("who", true);
+      await interaction.reply(`Hello ${who}!`);
+    }
+  } else if (interaction.isButton()) {
+    const [name, choice] = interaction.customId.split(":"); // manual parsing
+    if (name === "vote") {
+      await interaction.update({ content: `You chose ${choice}` });
+    }
+  }
+});
+```
+
+spearkit co-locates each command and component with its handler, and routes
+interactions for you — no switch, no manual id parsing:
+
+```ts
+// spearkit: each handler owns its definition; routing is automatic
+import { SpearClient, Intents, command, option, button, row } from "spearkit";
+
+const client = new SpearClient({ intents: Intents.default });
+
+const greet = command({
+  name: "greet",
+  description: "Greet someone",
+  options: { who: option.user({ description: "Who to greet", required: true }) },
+  run: (ctx) => ctx.reply(`Hello ${ctx.options.who}!`), // who: User
+});
+
+const vote = button({
+  id: "vote:{choice}",                              // {choice} is a typed param
+  label: "Yes",
+  style: "Success",
+  run: (ctx) => ctx.update(`You chose ${ctx.params.choice}`), // choice: string
+});
+
+client.register(greet, vote);
+await client.start(process.env.DISCORD_TOKEN);
+await client.deployCommands({ guildId: process.env.GUILD_ID });
+
+// build() requires exactly the params the id pattern declares:
+await channel.send({ content: "Vote:", components: [row(vote.build({ choice: "yes" }))] });
+```
+
+The option value (`who`) and the custom-id param (`choice`) are inferred from the
+definitions — no casts, no `getUser`/`split` boilerplate, and no `interactionCreate`
+switch to maintain.
+
+## See also
+
+- [Getting started](./getting-started.md) — install spearkit and build a first bot.
+- [Commands](./commands.md) — define slash commands with typed options.
+- [Components](./components.md) — buttons, selects, modals and custom-id routing.