@lunibee/builders 0.1.7 → 0.1.8

package/README.md

@@ -1,11 +1,58 @@
-# @lunibee/builders
-
-> Part of the lunibee ecosystem.
-
-## Basic use
-
-```ts
-import { ... } from '@lunibee/builders';
-
-// Example basic usage
-```
+# @lunibee/builders
+
+> Fluent, validated builders for embeds, components, modals, commands and attachments.
+
+```bash
+bun add @lunibee/builders
+```
+
+```ts
+import {
+    EmbedBuilder,
+    ActionRowBuilder,
+    ButtonBuilder,
+    ButtonStyle,
+    StringSelectMenuBuilder,
+    SlashCommandBuilder,
+} from "@lunibee/builders";
+
+const embed = new EmbedBuilder()
+    .setTitle("Welcome")
+    .setDescription("Pick a role below.")
+    .setColor(0xf5c542)
+    .addFields([{ name: "Server", value: "Lunibee" }]);
+
+const buttons = new ActionRowBuilder().addComponents(
+    new ButtonBuilder().setCustomId("yes").setLabel("Yes").setStyle(ButtonStyle.Success),
+);
+
+const menu = new ActionRowBuilder().addComponents(
+    new StringSelectMenuBuilder()
+        .setCustomId("role")
+        .addOptions({ label: "Developer", value: "dev" }),
+);
+
+const ping = new SlashCommandBuilder()
+    .setName("ping")
+    .setDescription("Replies with pong")
+    .addStringOption((option) => option.setName("message").setDescription("Echo text"));
+
+console.log(embed.toJSON(), buttons.toJSON(), menu.toJSON(), ping.toJSON());
+```
+
+## Builders
+
+| Area | Builders |
+|---|---|
+| Embeds | `EmbedBuilder` |
+| Buttons & rows | `ButtonBuilder`, `ActionRowBuilder` |
+| Select menus | `StringSelectBuilder` (alias `StringSelectMenuBuilder`), `EntitySelectBuilder`, `UserSelectMenuBuilder`, `RoleSelectMenuBuilder`, `ChannelSelectMenuBuilder`, `MentionableSelectMenuBuilder` |
+| Modals | `ModalBuilder`, `TextInputBuilder` |
+| Slash commands | `SlashCommandBuilder`, `SubcommandBuilder`, `SubcommandGroupBuilder`, option builders |
+| Context menus | `ContextMenuCommandBuilder` (`setType(2 \| 3)`), `UserCommandBuilder`, `MessageCommandBuilder` |
+| Components V2 | `ContainerBuilder`, `SectionBuilder`, `TextDisplayBuilder`, `MediaGalleryBuilder`, `FileComponentBuilder`, `SeparatorBuilder`, `ThumbnailBuilder` |
+| Files | `AttachmentBuilder` |
+
+Every builder validates Discord's limits as you set values and serialises with `toJSON()`.
+
+Docs: https://lunibee.js.org/core-concepts/builders/

package/package.json

@@ -1,10 +1,10 @@
-{
-  "name": "@lunibee/builders",
-  "version": "0.1.7",
-  "type": "module",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts"
-  }
-}
+{
+  "name": "@lunibee/builders",
+  "version": "0.1.8",
+  "type": "module",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/src/attachment.ts

@@ -1,68 +1,70 @@
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
-
-export interface AttachmentData {
-    name: string;
-    description?: string;
-    file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
-}
-
-/** Builder for message attachments and file uploads. */
-export class AttachmentBuilder {
-    public name: string;
-    public description?: string;
-    public file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
-
-    public constructor(
-        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
-        data?: Partial<Omit<AttachmentData, "file">> | string,
-    ) {
-        this.file = file;
-        if (typeof data === "string") {
-            this.name = data;
-        } else {
-            this.name =
-                data?.name ??
-                (typeof file === "string" ? basename(file) : "file.bin");
-            this.description = data?.description;
-        }
-    }
-
-    /** Sets the attachment filename. */
-    public setName(name: string): this {
-        this.name = name;
-        return this;
-    }
-
-    /** Sets the attachment description / alt text. */
-    public setDescription(description: string): this {
-        this.description = description;
-        return this;
-    }
-
-    /** Sets the file contents. */
-    public setFile(
-        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
-    ): this {
-        this.file = file;
-        return this;
-    }
-
-    /** Resolves the attachment payload to a binary Uint8Array. */
-    public async toBuffer(): Promise<Uint8Array> {
-        if (typeof this.file === "string") {
-            const buffer = await readFile(this.file);
-            return new Uint8Array(buffer);
-        }
-        if (this.file instanceof Uint8Array) return this.file;
-        if (this.file instanceof ArrayBuffer) return new Uint8Array(this.file);
-        if (this.file instanceof Blob) {
-            const buf = await this.file.arrayBuffer();
-            return new Uint8Array(buf);
-        }
-        if (typeof Buffer !== "undefined" && Buffer.isBuffer(this.file)) {
-            return new Uint8Array(this.file);
-        }
-        throw new TypeError("Attachment file must be a supported binary value or file path.");
-    }
-}
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+export interface AttachmentData {
+    name: string;
+    description?: string;
+    file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
+}
+
+/** Builder for message attachments and file uploads. */
+export class AttachmentBuilder {
+    public name: string;
+    public description?: string;
+    public file: Uint8Array | ArrayBuffer | Blob | Buffer | string;
+
+    public constructor(
+        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
+        data?: Partial<Omit<AttachmentData, "file">> | string,
+    ) {
+        this.file = file;
+        if (typeof data === "string") {
+            this.name = data;
+        } else {
+            this.name =
+                data?.name ??
+                (typeof file === "string" ? basename(file) : "file.bin");
+            this.description = data?.description;
+        }
+    }
+
+    /** Sets the attachment filename. */
+    public setName(name: string): this {
+        this.name = name;
+        return this;
+    }
+
+    /** Sets the attachment description / alt text. */
+    public setDescription(description: string): this {
+        this.description = description;
+        return this;
+    }
+
+    /** Sets the file contents. */
+    public setFile(
+        file: Uint8Array | ArrayBuffer | Blob | Buffer | string,
+    ): this {
+        this.file = file;
+        return this;
+    }
+
+    /** Resolves the attachment payload to a binary Uint8Array. */
+    public async toBuffer(): Promise<Uint8Array> {
+        if (typeof this.file === "string") {
+            const buffer = await readFile(this.file);
+            return new Uint8Array(buffer);
+        }
+        if (this.file instanceof Uint8Array) return this.file;
+        if (this.file instanceof ArrayBuffer) return new Uint8Array(this.file);
+        if (this.file instanceof Blob) {
+            const buf = await this.file.arrayBuffer();
+            return new Uint8Array(buf);
+        }
+        if (typeof Buffer !== "undefined" && Buffer.isBuffer(this.file)) {
+            return new Uint8Array(this.file);
+        }
+        throw new TypeError(
+            "Attachment file must be a supported binary value or file path.",
+        );
+    }
+}