chapterjs 0.1.1 → 0.1.4

package/dist/events/convention.js

@@ -0,0 +1,97 @@
+import { isEventFile } from './event.js';
+import { EVENT_NAMES, EVENTS, isEventName, } from './registry.js';
+/** Checks the second argument of `event()` against what the event accepts. */
+function readOptions(name, options) {
+    if (options === undefined)
+        return Object.freeze({});
+    const allowed = EVENTS[name].options ?? {};
+    const names = Object.keys(allowed);
+    const first = names[0];
+    const kind = first === undefined ? undefined : allowed[first];
+    const example = first === undefined
+        ? 'option: true'
+        : `${first}: ${kind === 'boolean' || !kind ? 'true' : `'${kind.at(-1)}'`}`;
+    const list = names.length === 0
+        ? `${name} has no options: remove the second argument of event().`
+        : `Options of ${name} are: ${names.join(', ')}.`;
+    if (typeof options !== 'object' ||
+        options === null ||
+        Array.isArray(options)) {
+        throw new TypeError(`The second argument of event() is its options, like { ${example} }. ${list}`);
+    }
+    for (const [key, value] of Object.entries(options)) {
+        if (!Object.hasOwn(allowed, key)) {
+            throw new TypeError(`"${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') {
+                throw new TypeError(`The option ${key} of ${name} is true or false, got ${got}.`);
+            }
+        }
+        else if (!kind.includes(value)) {
+            throw new TypeError(`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}"?` : '';
+}
+/**
+ * `src/events/`: one folder per event, named after it, and in it one file
+ * per reaction. The name of a file is free; it exports by default what
+ * `event()` returns:
+ *
+ * ```ts
+ * // src/events/memberJoin/welcome.ts
+ * import { event } from 'chapterjs';
+ *
+ * export default event(async ({ member, guild }) => {
+ *   await member.send(`Welcome to ${guild.name}!`);
+ * });
+ * ```
+ */
+export const eventsConvention = {
+    folder: 'events',
+    one: 'event',
+    many: 'events',
+    /** The event of a file, from its path: known without running the file. */
+    check(path) {
+        const parts = path.split('/');
+        if (parts.length < 2) {
+            throw new TypeError(`This file is directly in src/events/. Put it in a folder named after the event it reacts to, like src/events/messageCreate/${path}. Events are: ${EVENT_NAMES.join(', ')}.`);
+        }
+        const name = parts[0];
+        if (!isEventName(name)) {
+            throw new TypeError(`The folder src/events/${name} is not named after an event.${suggest(name)} Events are: ${EVENT_NAMES.join(', ')}.`);
+        }
+    },
+    read(exports, path) {
+        const name = path.split('/')[0];
+        const file = exports.default;
+        if (!isEventFile(file)) {
+            const example = `import { event } from 'chapterjs'; export default event(({ ... }) => { ... })`;
+            throw new TypeError('default' in exports
+                ? `The default export of this file must be what event() returns: ${example}`
+                : `This file has no default export. It should look like: ${example}`);
+        }
+        return Object.freeze({
+            name,
+            handler: file.handler,
+            options: readOptions(name, file.options),
+        });
+    },
+};

package/dist/events/event.d.ts

@@ -0,0 +1,8 @@
+import type { EventFile } from './registry.js';
+/**
+ * Says what to do when an event happens. Export the result as the default
+ * export of a file of `src/events/<event>/`: the folder says which event.
+ */
+export declare function event(handler: (context: never) => unknown, options?: unknown): EventFile;
+/** Whether a value was made by `event()`. */
+export declare function isEventFile(value: unknown): value is EventFile;

package/dist/events/event.js

@@ -0,0 +1,20 @@
+// `event()`, as user files import it from 'chapterjs'. Its type here is the
+// loose one; in each event folder of a project, the generated types give it
+// the one of that event (see `types.ts`).
+const BRAND = Symbol.for('chapterjs.event');
+/**
+ * Says what to do when an event happens. Export the result as the default
+ * export of a file of `src/events/<event>/`: the folder says which event.
+ */
+export function event(handler, options) {
+    if (typeof handler !== 'function') {
+        throw new TypeError('event() needs the function to run when the event happens: export default event(({ ... }) => { ... })');
+    }
+    return Object.freeze({ [BRAND]: true, handler, options });
+}
+/** Whether a value was made by `event()`. */
+export function isEventFile(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}