@saykit/carbon 0.10.0 → 0.11.0

package/README.md

@@ -16,13 +16,12 @@ pnpm add @saykit/carbon saykit @buape/carbon
 
 ```ts
 import { Client, Command, type CommandInteraction } from '@buape/carbon';
-import { SayPlugin, withSay } from '@saykit/carbon';
-import { type Catalogue } from 'saykit';
-import catalogue from './i18n.js';
+import { SayPlugin } from '@saykit/carbon';
+import { catalogue, withSay } from './i18n.js';
 
 class PingCommand extends withSay(Command) {
-  constructor(catalogue: Catalogue) {
-    super(catalogue, (say) => ({
+  constructor() {
+    super((say) => ({
       name: say`ping`,
       description: say`Ping the bot!`,
     }));
@@ -33,7 +32,7 @@ class PingCommand extends withSay(Command) {
   }
 }
 
-const client = new Client({/* options */}, { commands: [new PingCommand(catalogue)] }, [
+const client = new Client({/* options */}, { commands: [new PingCommand()] }, [
   new SayPlugin(catalogue),
 ]);
 ```

package/dist/index.d.mts

@@ -20,22 +20,52 @@ declare function applyGuildExtension(): () => void;
 type Keys = 'name' | 'description' | 'label' | 'title' | 'placeholder' | 'content' | 'options' | 'components' | 'subcommands' | 'subcommandGroups';
 type AbstractConstructor<Args extends any[] = any[], Instance extends object = object> = abstract new (...args: Args) => Instance;
 type SayProps<T> = Pick<T, Extract<keyof T, Keys>>;
+interface WithSay {
+  /**
+   * Enhances a {@link BaseCommand} subclass with support for localisation.
+   *
+   * @param Base Abstract command constructor to extend.
+   * @returns A new constructor that accepts a properties-mapping function and
+   * the original constructor arguments.
+   */
+  <Args extends unknown[], Instance extends BaseCommand>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[properties: (say: View) => SayProps<Instance>, ...args: Args], Instance & Partial<Record<Keys, unknown>>>;
+  /**
+   * Enhances a {@link BaseComponent} or {@link Modal} subclass with
+   * support for localisation.
+   *
+   * @param Base Abstract component or modal constructor to extend.
+   * @returns A new constructor that accepts a set of properties.
+   */
+  <Args extends unknown[], Instance extends BaseComponent | Modal>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[properties: SayProps<Instance>, ...args: Args], Instance & Partial<Record<Keys, unknown>>>;
+}
 /**
- * Enhances a {@link BaseCommand} subclass with support for localisation.
+ * Bind a `withSay` to a {@link Catalogue}, normally once beside the catalogue
+ * itself.
  *
- * @param Base Abstract command constructor to extend.
- * @returns A new constructor that accepts a {@link Catalogue}, a
- * properties-mapping function, and the original constructor arguments.
- */
-declare function withSay<Args extends unknown[], Instance extends BaseCommand>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[catalogue: Catalogue, properties: (say: View) => SayProps<Instance>, ...args: Args], Instance & Partial<Record<Keys, unknown>>>;
-/**
- * Enhances a {@link BaseComponent} or {@link Modal} subclass with
- * support for localisation.
+ * `withSay` wraps a Carbon base class so a command's name, description and
+ * options are built once per locale in the catalogue and registered with
+ * Discord as localisations, without the command having to reach for the
+ * catalogue itself.
+ *
+ * @example
+ * ```ts
+ * // i18n.ts
+ * export const withSay = createWithSay(catalogue);
+ *
+ * // commands/pick.ts
+ * export class PickCommand extends withSay(Command) {
+ *   constructor() {
+ *     super((say) => ({ name: say`pick`, description: say`What we are reading.` }));
+ *   }
+ * }
+ * ```
  *
- * @param Base Abstract component or modal constructor to extend.
- * @returns A new constructor that accepts a set of properties.
+ * @param catalogue The catalogue to take views from
+ * @returns A `withSay` bound to that catalogue
+ * @throws If the base class is neither a {@link BaseCommand} nor a
+ * {@link BaseComponent}
  */
-declare function withSay<Args extends unknown[], Instance extends BaseComponent | Modal>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[properties: SayProps<Instance>, ...args: Args], Instance & Partial<Record<Keys, unknown>>>;
+declare function createWithSay(catalogue: Catalogue): WithSay;
 //#endregion
 //#region src/plugin.d.ts
 /**
@@ -56,4 +86,4 @@ declare class SayPlugin extends Plugin {
   constructor(catalogue: Catalogue);
 }
 //#endregion
-export { SayPlugin, type applyBaseInteractionExtension, type applyGuildExtension, withSay };
+export { SayPlugin, type applyBaseInteractionExtension, type applyGuildExtension, createWithSay };

package/dist/index.mjs

@@ -21,24 +21,26 @@ function combineCommandOptions(mappedOptions, baseLocale) {
 }
 //#endregion
 //#region src/mixers/with-say.ts
-const ClassMap = /* @__PURE__ */ new WeakMap();
-function withSay(Base) {
-	if (ClassMap.has(Base)) return ClassMap.get(Base);
-	if (Base.prototype instanceof BaseCommand) {
-		const Derived = createSayCommand(Base);
-		ClassMap.set(Base, Derived);
-		return Derived;
-	}
-	if (Base.prototype instanceof BaseComponent || Base === Modal) {
-		const Derived = createSayComponent(Base);
-		ClassMap.set(Base, Derived);
-		return Derived;
-	}
-	throw new Error("Invalid base class");
+function createWithSay(catalogue) {
+	const cache = /* @__PURE__ */ new WeakMap();
+	return function withSay(Base) {
+		if (cache.has(Base)) return cache.get(Base);
+		if (Base.prototype instanceof BaseCommand) {
+			const Derived = createSayCommand(catalogue, Base);
+			cache.set(Base, Derived);
+			return Derived;
+		}
+		if (Base.prototype instanceof BaseComponent || Base === Modal) {
+			const Derived = createSayComponent(Base);
+			cache.set(Base, Derived);
+			return Derived;
+		}
+		throw new Error("Invalid base class");
+	};
 }
-function createSayCommand(Base) {
+function createSayCommand(catalogue, Base) {
 	class SayCommand extends Base {
-		constructor(catalogue, properties, ...args) {
+		constructor(properties, ...args) {
 			super(...args);
 			const options = combineCommandOptions(Array.from(catalogue).reduce((acc, [locale, say]) => {
 				acc[locale] = properties(say);
@@ -97,4 +99,4 @@ var SayPlugin = class extends Plugin {
 	}
 };
 //#endregion
-export { SayPlugin, withSay };
+export { SayPlugin, createWithSay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/carbon",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Carbon Discord framework integration for saykit",
   "keywords": [
     "bot",
@@ -37,7 +37,7 @@
   },
   "devDependencies": {
     "@buape/carbon": "0.16.0",
-    "saykit": "^0.10.0"
+    "saykit": "^0.11.0"
   },
   "peerDependencies": {
     "@buape/carbon": "*",