@saykit/carbon 0.9.1 → 0.11.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![Coverage](https://codecov.io/gh/k0d13/saykit/graph/badge.svg?flag=integration-carbon)](https://codecov.io/gh/k0d13/saykit?flags%5B0%5D=integration-carbon)
 
-Registers a shared `Say` with your Carbon client, helps command and component classes expose translated metadata, and adds locale-aware `interaction.say` and `guild.say` properties.
+Registers a shared catalogue with your Carbon client, helps command and component classes expose translated metadata, and adds locale-aware `interaction.say` and `guild.say` properties.
 
 ## Install
 
@@ -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 Say } from 'saykit';
-import say from './i18n.js';
+import { SayPlugin } from '@saykit/carbon';
+import { catalogue, withSay } from './i18n.js';
 
 class PingCommand extends withSay(Command) {
-  constructor(say: Say) {
-    super(say, (say) => ({
+  constructor() {
+    super((say) => ({
       name: say`ping`,
       description: say`Ping the bot!`,
     }));
@@ -33,8 +32,8 @@ class PingCommand extends withSay(Command) {
   }
 }
 
-const client = new Client({/* options */}, { commands: [new PingCommand(say)] }, [
-  new SayPlugin(say),
+const client = new Client({/* options */}, { commands: [new PingCommand()] }, [
+  new SayPlugin(catalogue),
 ]);
 ```
 

package/dist/index.d.mts

@@ -1,13 +1,9 @@
 import { APIInteraction, BaseCommand, BaseComponent, Modal, Plugin } from "@buape/carbon";
-import { Say } from "saykit";
-//#region src/constants.d.ts
-declare const kSay: unique symbol;
-//#endregion
+import { Catalogue, View } from "saykit";
 //#region src/extensions/base-interaction.d.ts
 declare module '@buape/carbon' {
   interface BaseInteraction<T extends APIInteraction> {
-    get say(): Say;
-    [kSay]: Say;
+    get say(): View;
   }
 }
 declare function applyBaseInteractionExtension(): () => void;
@@ -15,8 +11,7 @@ declare function applyBaseInteractionExtension(): () => void;
 //#region src/extensions/guild.d.ts
 declare module '@buape/carbon' {
   interface Guild {
-    get say(): Say;
-    [kSay]: Say;
+    get say(): View;
   }
 }
 declare function applyGuildExtension(): () => void;
@@ -25,40 +20,70 @@ 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 Say} instance, a
- * properties-mapping function, and the original constructor arguments.
- */
-declare function withSay<Args extends unknown[], Instance extends BaseCommand>(Base: AbstractConstructor<Args, Instance>): AbstractConstructor<[say: Say, properties: (say: Say) => 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
 /**
- * A Carbon plugin that provides a singleton {@link Say} instance.
+ * A Carbon plugin that provides a singleton {@link Catalogue}.
  *
- * `SayPlugin` registers a {@link Say} instance globally and
- * applies interaction and guild-level extensions so that commands and
- * other handlers can access localisation utilities directly.
+ * `SayPlugin` registers a {@link Catalogue} globally and applies interaction and
+ * guild-level extensions, so that commands and other handlers can reach a view
+ * for their own locale directly.
  *
  * @example
  * ```ts
- * const say = new Say({ ... });
- * const client = new Client({ ... }, { ... }, [new SayPlugin(say)]);
+ * const catalogue = createCatalogue({ ... });
+ * const client = new Client({ ... }, { ... }, [new SayPlugin(catalogue)]);
  * ```
  */
 declare class SayPlugin extends Plugin {
   id: string;
-  constructor(say: Say);
+  constructor(catalogue: Catalogue);
 }
 //#endregion
-export { SayPlugin, type applyBaseInteractionExtension, type applyGuildExtension, withSay };
+export { SayPlugin, type applyBaseInteractionExtension, type applyGuildExtension, createWithSay };

package/dist/index.mjs

@@ -21,29 +21,31 @@ 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(say, properties, ...args) {
+		constructor(properties, ...args) {
 			super(...args);
-			const options = combineCommandOptions(Array.from(say).reduce((acc, [s, l]) => {
-				acc[l] = properties(s);
+			const options = combineCommandOptions(Array.from(catalogue).reduce((acc, [locale, say]) => {
+				acc[locale] = properties(say);
 				return acc;
-			}, {}), say.locale);
+			}, {}), catalogue.locales[0]);
 			Object.assign(this, options);
 		}
 	}
@@ -65,12 +67,9 @@ const kSay = Symbol.for("saykit.say");
 //#region src/extensions/base-interaction.ts
 function applyBaseInteractionExtension() {
 	Object.defineProperty(BaseInteraction.prototype, "say", { get() {
-		const say = Reflect.get(globalThis, kSay);
-		if (!say) throw new Error("No `say` instance available");
-		this[kSay] ??= say.clone();
-		const locale = this[kSay].match([this.rawData.locale]);
-		this[kSay].activate(locale);
-		return this[kSay];
+		const catalogue = Reflect.get(globalThis, kSay);
+		if (!catalogue) throw new Error("No catalogue registered, add SayPlugin to your Carbon client");
+		return catalogue.locale(catalogue.match([this.rawData.locale]));
 	} });
 	return () => {
 		Object.defineProperty(BaseInteraction.prototype, "say", { value: void 0 });
@@ -80,12 +79,9 @@ function applyBaseInteractionExtension() {
 //#region src/extensions/guild.ts
 function applyGuildExtension() {
 	Object.defineProperty(Guild.prototype, "say", { get() {
-		const say = Reflect.get(globalThis, kSay);
-		if (!say) throw new Error("No `say` instance available");
-		this[kSay] ??= say.clone();
-		const locale = this[kSay].match([this.rawData.preferred_locale]);
-		this[kSay].activate(locale);
-		return this[kSay];
+		const catalogue = Reflect.get(globalThis, kSay);
+		if (!catalogue) throw new Error("No catalogue registered, add SayPlugin to your Carbon client");
+		return catalogue.locale(catalogue.match([this.rawData.preferred_locale]));
 	} });
 	return () => {
 		Object.defineProperty(Guild.prototype, "say", { value: void 0 });
@@ -95,12 +91,12 @@ function applyGuildExtension() {
 //#region src/plugin.ts
 var SayPlugin = class extends Plugin {
 	id = "saykit";
-	constructor(say) {
+	constructor(catalogue) {
 		super();
-		Reflect.set(globalThis, kSay, say);
+		Reflect.set(globalThis, kSay, catalogue);
 		applyBaseInteractionExtension();
 		applyGuildExtension();
 	}
 };
 //#endregion
-export { SayPlugin, withSay };
+export { SayPlugin, createWithSay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/carbon",
-  "version": "0.9.1",
+  "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.9.1"
+    "saykit": "^0.11.0"
   },
   "peerDependencies": {
     "@buape/carbon": "*",