chapterjs 0.1.2 → 0.2.0

package/dist/events/declaration.js

@@ -0,0 +1,80 @@
+// What a file declares with `event()`, checked when it loads: the event
+// exists, the options are the ones of that event, `run` is a function. A
+// mistake is explained before the bot even connects.
+import { isEventDeclaration } from './event.js';
+import { EVENT_NAMES, EVENTS, isEventName, } from './registry.js';
+const fail = message => {
+    throw new TypeError(message);
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Checks the options written next to `name` against what the event accepts. */
+function readOptions(name, options) {
+    const allowed = EVENTS[name].options ?? {};
+    const names = Object.keys(allowed);
+    const list = names.length === 0
+        ? `${name} has no options: an event has a name, a run function, and nothing else.`
+        : `Options of ${name} are: ${names.join(', ')}.`;
+    for (const [key, value] of Object.entries(options)) {
+        if (!Object.hasOwn(allowed, key)) {
+            fail(`"${key}" is not an option of ${name}. ${list}`);
+        }
+        const kind = allowed[key];
+        const got = JSON.stringify(value) ?? typeof value;
+        if (kind === 'boolean') {
+            if (typeof value !== 'boolean') {
+                fail(`The option ${key} of ${name} is true or false, got ${got}.`);
+            }
+        }
+        else if (!kind.includes(value)) {
+            fail(`The option ${key} of ${name} is ${kind
+                .map(word => `'${word}'`)
+                .join(', ')
+                .replace(/, ([^,]*)$/, ' or $1')}, got ${got}.`);
+        }
+    }
+    return Object.freeze({ ...options });
+}
+/** " Did you mean "x"?" when a name is close to a real one. */
+function suggest(name) {
+    const wanted = name.toLowerCase().replace(/[^a-z]/g, '');
+    if (wanted === '')
+        return '';
+    const close = EVENT_NAMES.find(event => {
+        const real = event.toLowerCase();
+        return real === wanted || real.includes(wanted) || wanted.includes(real);
+    });
+    return close ? ` Did you mean "${close}"?` : '';
+}
+const EXAMPLE = `event({ name: 'messageCreate', run({ message }) { ... } })`;
+/**
+ * An event, declared anywhere in `src/` with `event()`: its `name` is the
+ * event, the rest its options and what to do. A file may declare several,
+ * of the same event or not.
+ */
+export const eventDeclaration = {
+    one: 'event',
+    many: 'events',
+    is: isEventDeclaration,
+    list: true,
+    read(value) {
+        const { config } = value;
+        if (!isRecord(config)) {
+            return fail(`event() needs an object: ${EXAMPLE}`);
+        }
+        const { name, run, ...options } = config;
+        if (name === undefined) {
+            fail(`This event has no "name": the event to react to, like ${EXAMPLE}. Events are: ${EVENT_NAMES.join(', ')}.`);
+        }
+        if (!isEventName(name)) {
+            fail(`${JSON.stringify(name) ?? typeof name} is not an event.${typeof name === 'string' ? suggest(name) : ''} Events are: ${EVENT_NAMES.join(', ')}.`);
+        }
+        if (typeof run !== 'function') {
+            fail(`This ${name} event has no "run": the function to run when it happens, like ${EXAMPLE}`);
+        }
+        return Object.freeze({
+            name,
+            handler: run,
+            options: readOptions(name, options),
+        });
+    },
+};

package/dist/events/event.d.ts

@@ -0,0 +1,45 @@
+import type { ContextOf, EventName, OptionsOf } from './registry.js';
+/** The options written next to `name` and `run`, as written. */
+type OptionsWritten<Options> = {
+    [Key in keyof Options as Key extends 'name' | 'run' ? never : Key]: Options[Key];
+};
+/**
+ * What a file gives to `event()`: the event, its options when it has
+ * some, and what to do. What `run` receives follows the options: what an
+ * option lets through is only there to handle when the option is on.
+ */
+export type EventConfig<Name extends EventName = EventName, Options extends object = {}> = {
+    /** The event to react to: `'messageCreate'`, `'memberJoin'`... */
+    name: Name;
+    /** What to do when the event happens. */
+    run: (context: ContextOf<Name, OptionsWritten<Options>>) => unknown;
+} & Partial<OptionsOf<Name>> & {
+    [Key in keyof Options]: Key extends 'name' | 'run' ? unknown : Key extends keyof OptionsOf<Name> ? Options[Key] : never;
+};
+/** What `event()` returns: a declaration the framework finds in the exports of a file. */
+export interface EventDeclaration<Name extends EventName = EventName> {
+    /** What the file gave to `event()`, not checked yet. */
+    readonly config: EventConfig<Name, never>;
+}
+/**
+ * Declares what to do when an event happens. Export the result from any
+ * file of `src/`; `name` says which event, and types what `run` receives:
+ *
+ * ```ts
+ * import { event } from 'chapterjs';
+ *
+ * export const welcome = event({
+ *   name: 'memberJoin',
+ *   async run({ member, guild }) {
+ *     await member.send(`Welcome to ${guild.name}!`);
+ *   },
+ * });
+ * ```
+ *
+ * Some events have options, written next to `name` (`bots: true`, `where:
+ * 'dm'`): what `run` receives follows them.
+ */
+export declare function event<Name extends EventName, const Options extends Partial<OptionsOf<Name>> & object = {}>(config: EventConfig<Name, Options>): EventDeclaration<Name>;
+/** Whether a value was made by `event()`. */
+export declare function isEventDeclaration(value: unknown): value is EventDeclaration;
+export {};

package/dist/events/event.js

@@ -0,0 +1,34 @@
+// `event()`, as user files import it from 'chapterjs': what to do when
+// something happens on Discord. The `name` of the event types the rest: what
+// `run` receives, and the options the event has.
+const BRAND = Symbol.for('chapterjs.event');
+/**
+ * Declares what to do when an event happens. Export the result from any
+ * file of `src/`; `name` says which event, and types what `run` receives:
+ *
+ * ```ts
+ * import { event } from 'chapterjs';
+ *
+ * export const welcome = event({
+ *   name: 'memberJoin',
+ *   async run({ member, guild }) {
+ *     await member.send(`Welcome to ${guild.name}!`);
+ *   },
+ * });
+ * ```
+ *
+ * Some events have options, written next to `name` (`bots: true`, `where:
+ * 'dm'`): what `run` receives follows them.
+ */
+export function event(config) {
+    return Object.freeze({
+        [BRAND]: true,
+        config,
+    });
+}
+/** Whether a value was made by `event()`. */
+export function isEventDeclaration(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}