spearkit 0.3.0 → 0.4.0

package/docs/shutdown.md

@@ -0,0 +1,42 @@
+# Graceful shutdown
+
+A `Ctrl-C` or a container stop sends your process a signal. If you don't handle
+it, the process dies mid-flight — the gateway connection, scheduler timers, and
+any open database handles are reaped abruptly. Graceful shutdown runs an optional
+cleanup hook, calls `client.destroy()` (which also stops spearkit's scheduler),
+then exits — with a hard timeout so a wedged shutdown can't hang forever.
+
+## On a SpearClient
+
+```ts
+client.enableGracefulShutdown({
+  onShutdown: () => db.close(), // flush state before we exit
+});
+await client.start();
+```
+
+Progress is logged through `client.logger`. The method returns a disposer that
+removes the signal handlers (useful for tests / hot-reload).
+
+## Standalone
+
+`gracefulShutdown(client, options)` works with any object that has a `destroy()`
+method:
+
+```ts
+import { gracefulShutdown } from "spearkit";
+
+gracefulShutdown(client, { onShutdown: () => db.close() });
+```
+
+## Options
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `signals` | `["SIGINT", "SIGTERM"]` | Signals to listen for. |
+| `timeoutMs` | `10000` | Force-exit if shutdown exceeds this. |
+| `onShutdown` | — | Runs before `destroy()`; receives the signal. |
+| `exit` | `true` | Call `process.exit()` when done (set `false` in tests). |
+| `logger` | — | `{ info?, error? }` progress logger. |
+
+Shutdown runs **once** — repeated signals during teardown are ignored.

package/docs/store.md

@@ -0,0 +1,90 @@
+# Key-value store & settings
+
+Almost every community bot needs to remember *something* per guild — a custom
+prefix, a mod-log channel, a welcome message — and reaches for a database on day
+one. spearkit ships a dependency-free `KeyValueStore` interface with two
+backends, plus a typed per-guild settings helper. Swap in Redis/SQL later by
+implementing the same interface.
+
+## Stores
+
+```ts
+import { JsonStore, MemoryStore } from "spearkit";
+
+const dev = new MemoryStore();             // in-memory, great for tests
+const prod = new JsonStore("data/db.json"); // durable JSON file
+```
+
+Both implement `KeyValueStore`:
+
+```ts
+await store.set("key", { any: "json" });
+await store.get<{ any: string }>("key"); // typed read, or undefined
+await store.has("key");
+await store.delete("key");                // → boolean (existed?)
+await store.keys();                       // → string[]
+await store.clear();
+```
+
+`MemoryStore` deep-clones on read and write, so callers can't mutate stored
+state. `JsonStore` serves reads from an in-memory cache and commits writes
+atomically (temp file + rename) through a queue — a crash mid-write can't corrupt
+the file, and concurrent writes don't interleave.
+
+## Typed per-guild settings
+
+`createSettings` wraps a store with defaults. `get` always returns a complete
+object; `set` persists *only* the overrides, so widening `defaults` later is
+safe.
+
+```ts
+import { JsonStore, createSettings } from "spearkit";
+
+const settings = createSettings({
+  store: new JsonStore("data/guilds.json"),
+  defaults: { prefix: "!", modLogChannelId: null as string | null },
+});
+
+const cfg = await settings.get(guildId);          // { prefix, modLogChannelId }
+await settings.set(guildId, { prefix: "?" });     // shallow-merged + persisted
+await settings.reset(guildId);                    // back to defaults
+```
+
+Pass `namespace` to keep several settings groups in one store:
+
+```ts
+const guilds = createSettings({ store, defaults: { prefix: "!" }, namespace: "guild" });
+const users = createSettings({ store, defaults: { xp: 0 }, namespace: "user" });
+```
+
+## Dynamic per-guild prefix
+
+A stored prefix is only useful if prefix commands respect it. `prefix.dynamic`
+resolves extra prefix(es) per message — combine it with `createSettings` for true
+per-guild prefixes:
+
+```ts
+const client = new SpearClient({
+  prefix: {
+    dynamic: async (message) =>
+      message.guildId ? (await settings.get(message.guildId)).prefix : null,
+  },
+});
+```
+
+The resolver runs on every candidate message, so keep it fast (cache or use the
+in-memory `JsonStore` cache). Returned prefixes are tried *in addition* to any
+static `prefix`. See [Prefix commands](./prefix.md) for the rest of the prefix
+system.
+
+## Namespacing a raw store
+
+`namespaced(store, prefix)` returns a `KeyValueStore` whose keys are
+transparently prefixed — handy for sharing one file across features:
+
+```ts
+import { namespaced } from "spearkit";
+
+const tags = namespaced(store, "tags");
+await tags.set("hello", "world"); // stored under "tags:hello"
+```

package/docs/usage.md

@@ -0,0 +1,188 @@
+# Usage tracking
+
+Usage tracking records **who used what**: every command, component, context-menu
+and prefix-command invocation — successful or errored — becomes a `UsageEvent`
+that spearkit can persist to a
+store and/or mirror into a Discord channel. Turn it on with the client's `usage`
+option.
+
+## Usage tracking vs the logger
+
+These look similar but answer different questions, and they are completely
+independent sinks:
+
+| | Logger | Usage tracking |
+| --- | --- | --- |
+| Question | *What is the bot doing?* (diagnostics) | *Who used which feature?* (audit) |
+| Content | Free-form messages, levels, errors, internals | Structured `UsageEvent`s for every completed use (with its `outcome`) |
+| Sinks | Console / your log pipeline | A database store and/or a Discord channel |
+| Configured by | the `logger` option | the `usage` option |
+
+Both successes and handler errors are recorded as usage events — an error carries
+`outcome: "error"` and an `errorMessage` — so usage is a complete audit trail.
+The [logger](./logging.md) is for debugging; usage tracking is for analytics,
+audit trails, and "top commands" dashboards.
+
+## Enabling it
+
+Set the `usage` option. Provide a `store` (a database), a `channel` (a Discord
+channel id to mirror events into), or both:
+
+```ts
+import { MemoryUsageStore, SpearClient } from "spearkit";
+
+const client = new SpearClient({
+  usage: {
+    store: new MemoryUsageStore(),
+    channel: "123456789012345678", // optional: also post each event here
+  },
+});
+```
+
+Once enabled, spearkit auto-tracks every command, component, context-menu and
+prefix-command invocation — successes and errors alike — with no tracking code in
+your handlers.
+
+## The usage event
+
+Each tracked use is a `UsageEvent`:
+
+```ts
+interface UsageEvent {
+  type: UsageType;         // "command" | "prefix" | "component" | "event"
+  name: string;            // command / component / event name
+  userId?: string;
+  userTag?: string;
+  guildId?: string | null;
+  channelId?: string | null;
+  detail?: string;         // free-form extra detail
+  outcome?: UsageOutcome;  // "success" | "error"
+  durationMs?: number;     // handler wall-clock time
+  options?: Readonly<Record<string, UsageMetaValue>>; // snapshot of typed options
+  errorMessage?: string;   // set when outcome === "error"
+  timestamp: Date;
+}
+type UsageType = "command" | "prefix" | "component" | "event";
+type UsageOutcome = "success" | "error";
+type UsageMetaValue = string | number | boolean | null;
+```
+
+## Stores (the database)
+
+A store is any object implementing `UsageStore`:
+
+```ts
+interface UsageStore {
+  record(event: UsageEvent): void | Promise<void>;
+  all(): UsageEvent[] | Promise<readonly UsageEvent[]>;
+}
+```
+
+spearkit ships two.
+
+### MemoryUsageStore
+
+In-memory and synchronous — ideal for tests, prototypes, and live dashboards.
+Pass an optional cap to keep only the most recent N events:
+
+```ts
+import { MemoryUsageStore } from "spearkit";
+
+const store = new MemoryUsageStore(1_000); // keep the last 1,000 events
+
+store.all();             // readonly UsageEvent[]
+store.size;              // number of events held
+store.byUser("123...");  // UsageEvent[] for one user id
+store.clear();           // forget everything
+```
+
+### JsonFileUsageStore
+
+Durable and dependency-free: appends one event per line as newline-delimited
+JSON (`.jsonl`). `all()` reads the file back and parses it, so it behaves like a
+small file-backed database:
+
+```ts
+import { JsonFileUsageStore } from "spearkit";
+
+const store = new JsonFileUsageStore("./usage.jsonl");
+
+await store.record({ type: "command", name: "ping", timestamp: new Date() });
+const events = await store.all(); // readonly UsageEvent[]
+```
+
+The directory is created on demand. Because `all()` is async here (it reads from
+disk), always `await` it.
+
+## Querying the store
+
+`client.usage.store` is the store you configured — query it directly. Note that
+`all()` may be synchronous (`MemoryUsageStore`) or asynchronous
+(`JsonFileUsageStore`); awaiting works for both:
+
+```ts
+const store = client.usage.store;
+if (store !== undefined) {
+  const events = await store.all();
+  const topCommand = events.filter((e) => e.type === "command").length;
+  console.log(`${topCommand} command uses recorded`);
+}
+```
+
+## The Discord channel reporter
+
+Besides (or instead of) a store, you can mirror each event into a Discord
+channel. Pass `channel` (a channel id) in the `usage` option; spearkit posts one
+line per event using `formatUsage`:
+
+```ts
+import { SpearClient } from "spearkit";
+
+new SpearClient({ usage: { channel: "123456789012345678" } });
+```
+
+`formatUsage(event)` is the default renderer (e.g. `` `command` **ping** by
+user#0001 in <#…> ``). Override it with `format` to control the line:
+
+```ts
+import { SpearClient, type UsageEvent } from "spearkit";
+
+new SpearClient({
+  usage: {
+    channel: "123456789012345678",
+    format: (event: UsageEvent) => `${event.userTag ?? "someone"} used ${event.name}`,
+  },
+});
+```
+
+## The usage tracker
+
+`client.usage` is a `UsageTracker`. The client configures it from the `usage`
+option, but you can drive it directly:
+
+| Member | Description |
+| ------ | ----------- |
+| `setStore(store)` | Set (or swap) the persistence store. |
+| `reportTo(channelId, format?)` | Mirror events into a channel, optionally with a custom formatter. |
+| `track(event)` | Record a use. Returns immediately; storing/reporting run in the background. |
+| `store` | The configured store, for querying. |
+| `enabled` | `true` if a store or channel is configured. |
+
+```ts
+import { JsonFileUsageStore } from "spearkit";
+
+client.usage.setStore(new JsonFileUsageStore("./usage.jsonl"));
+client.usage.reportTo("123456789012345678");
+
+// Record a custom event yourself (e.g. a non-command action).
+client.usage.track({ type: "event", name: "signup", timestamp: new Date() });
+```
+
+Tracking is fire-and-forget: a slow store or channel never blocks command
+handling, and any failure is logged rather than thrown.
+
+## See also
+
+- [Logging](./logging.md) — diagnostics, the other sink.
+- [Commands](./commands.md) / [Prefix commands](./prefix.md) / [Components](./components.md) — what gets tracked.
+- [Client](./client.md) — the `usage` option.