chapterjs 0.0.0 → 0.1.2

package/dist/structures/User.js

@@ -0,0 +1,79 @@
+import { Channel } from './Channel.js';
+import { cdnUrl, snowflakeDate, } from './utils.js';
+/**
+ * A Discord user. `raw` holds every field sent by Discord.
+ * https://docs.discord.com/developers/resources/user#user-object
+ */
+export class User {
+    client;
+    raw;
+    id;
+    username;
+    /** Display name set by the user, if any. */
+    globalName;
+    discriminator;
+    avatar;
+    banner;
+    bot;
+    system;
+    constructor(client, raw) {
+        this.client = client;
+        this.raw = raw;
+        this.id = raw.id;
+        this.username = raw.username;
+        this.globalName = raw.global_name ?? null;
+        this.discriminator = raw.discriminator;
+        this.avatar = raw.avatar ?? null;
+        this.banner = raw.banner ?? null;
+        this.bot = raw.bot ?? false;
+        this.system = raw.system ?? false;
+    }
+    /** Name shown in Discord: the display name, or the username. */
+    get displayName() {
+        return this.globalName ?? this.username;
+    }
+    get createdAt() {
+        return snowflakeDate(this.id);
+    }
+    /** Mention, e.g. `${user}` in a message. */
+    toString() {
+        return `<@${this.id}>`;
+    }
+    /** Uploaded avatar, or null when the user has none. */
+    avatarURL(options) {
+        return this.avatar
+            ? cdnUrl(`avatars/${this.id}`, this.avatar, options)
+            : null;
+    }
+    // https://docs.discord.com/developers/reference#image-formatting-cdn-endpoints
+    /** Default avatar Discord shows when the user has none. */
+    get defaultAvatarURL() {
+        const index = this.discriminator === '0' || !this.discriminator
+            ? Number((BigInt(this.id) >> 22n) % 6n)
+            : Number(this.discriminator) % 5;
+        return `https://cdn.discordapp.com/embed/avatars/${index}.png`;
+    }
+    /** Avatar shown in Discord: the uploaded one, or the default one. */
+    displayAvatarURL(options) {
+        return this.avatarURL(options) ?? this.defaultAvatarURL;
+    }
+    bannerURL(options) {
+        return this.banner
+            ? cdnUrl(`banners/${this.id}`, this.banner, options)
+            : null;
+    }
+    /**
+     * Sends a direct message, opening the DM channel (or reusing it).
+     * https://docs.discord.com/developers/resources/user#create-dm
+     */
+    async send(options) {
+        const channel = await this.client.rest.post('/users/@me/channels', {
+            body: { recipient_id: this.id },
+        });
+        return new Channel(this.client, channel).send(options);
+    }
+    /** Latest data from Discord. */
+    async fetch() {
+        return new User(this.client, await this.client.rest.get(`/users/${this.id}`));
+    }
+}

package/dist/structures/utils.d.ts

@@ -0,0 +1,72 @@
+import { type ComponentInput } from '../components.js';
+import type { FileUpload } from '../discord/rest.js';
+import type { Snowflake } from '../discord/types.js';
+/** Creation date encoded in a snowflake. */
+export declare function snowflakeDate(id: Snowflake): Date;
+export declare const toDate: (timestamp: string | null | undefined) => Date | null;
+export interface ImageOptions {
+    /** Power of 2 between 16 and 4096. */
+    size?: 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096;
+    extension?: 'png' | 'jpg' | 'webp' | 'gif';
+}
+/**
+ * CDN URL of an image. Animated hashes (`a_`) are served as animated WebP,
+ * which works whatever the uploaded format.
+ * https://docs.discord.com/developers/reference#image-formatting
+ */
+export declare function cdnUrl(path: string, hash: string, options?: ImageOptions): string;
+export interface AllowedMentions {
+    parse?: ('roles' | 'users' | 'everyone')[];
+    roles?: Snowflake[];
+    users?: Snowflake[];
+    /** For replies, whether to mention the author of the replied message. */
+    repliedUser?: boolean;
+}
+/** Message content, or every field Discord accepts when sending a message. */
+export type MessageOptions = string | {
+    /** Up to 2000 characters. */
+    content?: string;
+    /** Up to 10 embeds, https://docs.discord.com/developers/resources/message#embed-object */
+    embeds?: object[];
+    /**
+     * Components made with `defineButton`, or raw objects
+     * (https://docs.discord.com/developers/components/reference). Buttons
+     * are put in rows of 5 automatically; an array is one row.
+     */
+    components?: ComponentInput[];
+    allowedMentions?: AllowedMentions;
+    files?: FileUpload[];
+    tts?: boolean;
+    /** https://docs.discord.com/developers/resources/message#message-object-message-flags */
+    flags?: number;
+    stickerIds?: Snowflake[];
+    /** https://docs.discord.com/developers/resources/poll#poll-create-request-object */
+    poll?: object;
+};
+/** Options of `message.reply`. */
+export type ReplyOptions = MessageOptions & {
+    /** Whether to ping the author of the replied message (`allowed_mentions.replied_user`). */
+    mention?: boolean;
+    /** Fail when the replied message no longer exists, instead of sending a normal message. Defaults to true. */
+    failIfNotExists?: boolean;
+};
+/** Converts message options to the JSON body Discord expects, and the files to upload. */
+export declare function toMessageBody(options: MessageOptions | ReplyOptions): {
+    body: Record<string, unknown>;
+    files?: FileUpload[];
+};
+export declare function toAllowedMentions({ repliedUser, ...rest }: AllowedMentions): {
+    parse?: ('roles' | 'users' | 'everyone')[];
+    roles?: Snowflake[];
+    users?: Snowflake[];
+    replied_user?: boolean | undefined;
+};
+/**
+ * Emoji as expected in reaction routes: the unicode character, or `name:id`
+ * for a custom emoji (`<:name:id>` is accepted too), URL encoded.
+ * https://docs.discord.com/developers/resources/message#create-reaction
+ */
+export declare function encodeEmoji(emoji: string | {
+    id: Snowflake | null;
+    name: string | null;
+}): string;

package/dist/structures/utils.js

@@ -0,0 +1,59 @@
+import { serializeComponents } from '../components.js';
+/** https://docs.discord.com/developers/reference#snowflakes */
+const DISCORD_EPOCH = 1420070400000n;
+/** Creation date encoded in a snowflake. */
+export function snowflakeDate(id) {
+    return new Date(Number((BigInt(id) >> 22n) + DISCORD_EPOCH));
+}
+export const toDate = (timestamp) => timestamp ? new Date(timestamp) : null;
+/**
+ * CDN URL of an image. Animated hashes (`a_`) are served as animated WebP,
+ * which works whatever the uploaded format.
+ * https://docs.discord.com/developers/reference#image-formatting
+ */
+export function cdnUrl(path, hash, options = {}) {
+    const animated = hash.startsWith('a_');
+    const url = new URL(`https://cdn.discordapp.com/${path}/${hash}.${options.extension ?? (animated ? 'webp' : 'png')}`);
+    if (options.size)
+        url.searchParams.set('size', String(options.size));
+    if (animated && !options.extension)
+        url.searchParams.set('animated', 'true');
+    return url.href;
+}
+/** Converts message options to the JSON body Discord expects, and the files to upload. */
+export function toMessageBody(options) {
+    if (typeof options === 'string')
+        return { body: { content: options } };
+    const { allowedMentions, files, stickerIds, components, ...rest } = options;
+    delete rest.mention;
+    delete rest.failIfNotExists;
+    return {
+        body: {
+            ...rest,
+            ...(stickerIds && { sticker_ids: stickerIds }),
+            ...(components && { components: serializeComponents(components) }),
+            ...(allowedMentions && {
+                allowed_mentions: toAllowedMentions(allowedMentions),
+            }),
+        },
+        files,
+    };
+}
+export function toAllowedMentions({ repliedUser, ...rest }) {
+    return {
+        ...rest,
+        ...(repliedUser !== undefined && { replied_user: repliedUser }),
+    };
+}
+/**
+ * Emoji as expected in reaction routes: the unicode character, or `name:id`
+ * for a custom emoji (`<:name:id>` is accepted too), URL encoded.
+ * https://docs.discord.com/developers/resources/message#create-reaction
+ */
+export function encodeEmoji(emoji) {
+    if (typeof emoji !== 'string') {
+        emoji = emoji.id ? `${emoji.name}:${emoji.id}` : (emoji.name ?? '');
+    }
+    const custom = /^<a?:(\w+):(\d+)>$/.exec(emoji);
+    return encodeURIComponent(custom ? `${custom[1]}:${custom[2]}` : emoji);
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Formats an error thrown by user code: keeps the stack frames of the user's
+ * files only, relative to the project, without the hot reload query string.
+ */
+export declare function formatUserError(error: unknown, cwd?: string): string;

package/dist/utils/errors.js

@@ -0,0 +1,28 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+/** Root of the framework (`dist/`), whose frames are noise in user errors. */
+const FRAMEWORK_DIR = fileURLToPath(new URL('..', import.meta.url));
+const FRAMEWORK_URL = pathToFileURL(FRAMEWORK_DIR).href;
+/**
+ * Formats an error thrown by user code: keeps the stack frames of the user's
+ * files only, relative to the project, without the hot reload query string.
+ */
+export function formatUserError(error, cwd = process.cwd()) {
+    if (!(error instanceof Error))
+        return String(error);
+    if (!error.stack)
+        return error.message;
+    const projectUrl = `${pathToFileURL(cwd).href}/`;
+    const projectPath = `${cwd}/`;
+    const lines = error.stack.split('\n');
+    const firstFrame = lines.findIndex((line) => /^\s+at /.test(line));
+    if (firstFrame === -1)
+        return error.stack;
+    const frames = lines
+        .slice(firstFrame)
+        .filter((line) => !line.includes(FRAMEWORK_URL) &&
+        !line.includes(FRAMEWORK_DIR) &&
+        !line.includes('node:internal') &&
+        !line.includes('node_modules/chapterjs/'))
+        .map((line) => line.replaceAll(projectUrl, '').replaceAll(projectPath, '').replace(/\?t=\d+/g, ''));
+    return [...lines.slice(0, firstFrame), ...frames].join('\n');
+}

package/dist/utils/modules.d.ts

@@ -0,0 +1,39 @@
+import { type Dirent, type FSWatcher } from 'node:fs';
+/** Returns the path of the first existing file among `names` in `dir`. */
+export declare function findFile(dir: string, names: string[]): string | null;
+/** Imports a user module, bypassing the ESM cache so edits are picked up. */
+export declare function importFresh(path: string): Promise<any>;
+/**
+ * Describes an error thrown while loading the user file `path`, as
+ * `src/events/ping.ts:4: message`, with the code snippet Node gives for syntax
+ * errors and a hint for common mistakes.
+ */
+export declare function describeLoadError(error: unknown, path: string, cwd?: string): string;
+/**
+ * Describes an error thrown by user code while the bot runs: its message, then
+ * only the stack lines from the project's `src/` (not Node's or the
+ * framework's), as relative paths.
+ */
+export declare function describeRuntimeError(error: unknown, cwd?: string): string;
+/**
+ * Calls `onChange` whenever one of `names` is created, edited or deleted in `dir`.
+ * Watches the directory since editors often save by replacing the file.
+ */
+export declare function watchFiles(dir: string, names: string[], onChange: () => void): FSWatcher | null;
+/**
+ * Calls `onChange` whenever a file or folder under `dir` whose path (relative
+ * to `dir`) matches `filter` is created, edited, renamed or deleted.
+ */
+export declare function watchTree(dir: string, filter: (relativePath: string) => boolean, onChange: () => void): FSWatcher | null;
+/**
+ * File of the function that called the caller of `callerFile`, from the V8
+ * call sites. Lets `defineButton` know which file it is defined in.
+ */
+export declare function callerFile(depth?: number): string | null;
+/**
+ * Script files under `dir`, recursively and sorted. Entries starting with `_`
+ * or `.`, declarations and tests are ignored.
+ */
+export declare function scriptFiles(dir: string): string[];
+export declare function readEntries(dir: string): Dirent[];
+export declare function isScript(entry: Dirent): boolean;

package/dist/utils/modules.js

@@ -0,0 +1,156 @@
+import { existsSync, readdirSync, watch, } from 'node:fs';
+import { dirname, extname, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+/** Returns the path of the first existing file among `names` in `dir`. */
+export function findFile(dir, names) {
+    const name = names.find(name => existsSync(resolve(dir, name)));
+    return name ? resolve(dir, name) : null;
+}
+/** Imports a user module, bypassing the ESM cache so edits are picked up. */
+export async function importFresh(path) {
+    const url = pathToFileURL(path);
+    url.searchParams.set('t', String(Date.now()));
+    return import(url.href);
+}
+/**
+ * Describes an error thrown while loading the user file `path`, as
+ * `src/events/ping.ts:4: message`, with the code snippet Node gives for syntax
+ * errors and a hint for common mistakes.
+ */
+export function describeLoadError(error, path, cwd = process.cwd()) {
+    const file = relative(cwd, path);
+    if (!(error instanceof Error))
+        return `${file}: ${String(error)}`;
+    const code = error.code;
+    const stack = error.stack ?? '';
+    // Syntax errors start with `<path>:<line>`, then the code with a ^ marker
+    const syntax = stack.match(/^(.+):(\d+)\n([\s\S]*?)\n\n/);
+    if (error instanceof SyntaxError && syntax) {
+        const snippet = syntax[3].replace(/^/gm, '    ');
+        const hint = code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'
+            ? '\n  Node runs your .ts files by removing the types, so TypeScript syntax that generates code' +
+                ' (enum, namespace, constructor parameter properties) is not supported: use a plain object or class instead.'
+            : '';
+        // A file URL with importFresh's query string, or a path for files it imports
+        const location = syntax[1].startsWith('file:')
+            ? fileURLToPath(syntax[1].split('?')[0])
+            : syntax[1];
+        return `${relative(cwd, location)}:${syntax[2]}: ${error.message}\n${snippet}${hint}`;
+    }
+    if (code === 'ERR_MODULE_NOT_FOUND') {
+        const missing = error.message.match(/^Cannot find (module|package) '(.+)' imported from (.+)$/);
+        if (missing) {
+            const [, kind, target, importer] = missing;
+            const from = relative(cwd, importer);
+            if (kind === 'package') {
+                return `${from}: the package "${target}" is not installed. Install it with your package manager, e.g. npm install ${target}`;
+            }
+            const extension = ['.ts', '.js'].find(ext => existsSync(target + ext));
+            if (extension) {
+                const specifier = relative(dirname(importer), target)
+                    .split(sep)
+                    .join('/');
+                return `${from}: imports of your own files need the file extension: "${specifier.startsWith('.') ? specifier : `./${specifier}`}${extension}".`;
+            }
+            return `${from}: the file ${relative(cwd, target)} imported here doesn't exist.`;
+        }
+    }
+    // Other errors: the first call site in the file, ignoring importFresh's query string
+    const url = pathToFileURL(path).href.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const line = stack.match(new RegExp(`${url}(?:\\?[^:]*)?:(\\d+):\\d+`))?.[1];
+    return `${file}${line ? `:${line}` : ''}: ${error.message}`;
+}
+/**
+ * Describes an error thrown by user code while the bot runs: its message, then
+ * only the stack lines from the project's `src/` (not Node's or the
+ * framework's), as relative paths.
+ */
+export function describeRuntimeError(error, cwd = process.cwd()) {
+    if (!(error instanceof Error))
+        return String(error);
+    const header = error.name === 'Error' ? error.message : `${error.name}: ${error.message}`;
+    const src = pathToFileURL(resolve(cwd, 'src')).href + '/';
+    const frames = (error.stack ?? '')
+        .split('\n')
+        .filter(line => /^\s+at /.test(line) && line.includes(src))
+        .map(line => line
+        .trim()
+        // importFresh's query string sits between the path and the position
+        .replace(/(file:\/\/[^\s?)]+)(\?[^:\s)]*)?/, (_, url) => relative(cwd, fileURLToPath(url))));
+    return [header, ...frames.map(frame => `    ${frame}`)].join('\n');
+}
+/**
+ * Calls `onChange` whenever one of `names` is created, edited or deleted in `dir`.
+ * Watches the directory since editors often save by replacing the file.
+ */
+export function watchFiles(dir, names, onChange) {
+    if (!existsSync(dir))
+        return null;
+    let timeout;
+    return watch(dir, (_event, filename) => {
+        if (!filename || !names.includes(filename))
+            return;
+        // Editors emit several events per save
+        clearTimeout(timeout);
+        timeout = setTimeout(onChange, 100);
+    });
+}
+/**
+ * Calls `onChange` whenever a file or folder under `dir` whose path (relative
+ * to `dir`) matches `filter` is created, edited, renamed or deleted.
+ */
+export function watchTree(dir, filter, onChange) {
+    if (!existsSync(dir))
+        return null;
+    let timeout;
+    return watch(dir, { recursive: true }, (_event, filename) => {
+        if (!filename || !filter(filename))
+            return;
+        // Editors emit several events per save, and moving a folder one per file
+        clearTimeout(timeout);
+        timeout = setTimeout(onChange, 100);
+    });
+}
+/**
+ * File of the function that called the caller of `callerFile`, from the V8
+ * call sites. Lets `defineButton` know which file it is defined in.
+ */
+export function callerFile(depth = 2) {
+    const original = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_, callSites) => callSites;
+        const callSites = new Error().stack;
+        const file = callSites[depth]?.getFileName();
+        if (!file)
+            return null;
+        // ES modules are reported as URLs, with importFresh's query string
+        return file.startsWith('file:') ? fileURLToPath(file.split('?')[0]) : file;
+    }
+    finally {
+        Error.prepareStackTrace = original;
+    }
+}
+const EXTENSIONS = new Set(['.ts', '.mts', '.js', '.mjs']);
+/**
+ * Script files under `dir`, recursively and sorted. Entries starting with `_`
+ * or `.`, declarations and tests are ignored.
+ */
+export function scriptFiles(dir) {
+    return readEntries(dir).flatMap(entry => {
+        const path = resolve(dir, entry.name);
+        if (entry.isDirectory())
+            return scriptFiles(path);
+        return isScript(entry) ? [path] : [];
+    });
+}
+export function readEntries(dir) {
+    return readdirSync(dir, { withFileTypes: true })
+        .filter(entry => !entry.name.startsWith('_') && !entry.name.startsWith('.'))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+export function isScript(entry) {
+    return (entry.isFile() &&
+        EXTENSIONS.has(extname(entry.name)) &&
+        !/\.d\.[mc]?ts$/.test(entry.name) &&
+        !/\.(test|spec)\.[mc]?[jt]s$/.test(entry.name));
+}

package/package.json

@@ -1,6 +1,31 @@
 {
-	"name": "chapterjs",
-	"version": "0.0.0",
-	"license": "MIT",
-	"repository": "github:chapterjs/chapterjs"
-}
+  "name": "chapterjs",
+  "version": "0.1.2",
+  "description": "The Discord framework",
+  "type": "module",
+  "license": "MIT",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "chapterjs": "./dist/cli/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli/cli.js",
+    "dev": "tsc --watch"
+  }
+}