saykit 0.10.0 → 0.11.1

package/README.md

@@ -6,7 +6,7 @@
 
 The core runtime for [SayKit](https://saykit.js.org). Exports `createCatalogue`, which holds your locales and where each one's messages come from, `createView`, which binds one locale and formats messages using ICU MessageFormat, and `createStore`, which holds the current view and swaps it when you switch locale.
 
-You author messages with the `` say`...` `` tagged template (and `say.plural`, `say.ordinal`, `say.select`); a SayKit build-tool plugin rewrites them at build time into small runtime calls.
+You author messages with the `` say`...` `` tagged template (and `say.plural`, `say.ordinal`, `say.select`), and format numbers, dates and times for the locale with `say.number`, `say.date` and `say.time`; a SayKit build-tool plugin rewrites them at build time into small runtime calls.
 
 ## Install
 
@@ -29,6 +29,8 @@ const say = catalogue.locale('en');
 
 say`Hello, ${name}!`;
 say.plural(count, { one: '1 item', other: `${count} items` });
+say`Total: ${say.number(total, { style: '::currency/EUR' })}`;
+say.date(new Date(), { style: 'long' });
 ```
 
 In a browser, where the locale can change, hold a store instead of a view:

package/dist/index.d.mts

@@ -58,6 +58,32 @@ declare namespace View {
   type Messages = {
     [key: string]: string;
   };
+  /**
+   * What the transform compiles a message down to: the id it was extracted
+   * under, or the ICU message itself when there was nothing to extract, with
+   * its values behind one underscore each.
+   */
+  type Descriptor = ({
+    id: string;
+  } | {
+    message: string;
+  }) & {
+    [match: string | number]: unknown;
+  };
+  interface Options {
+    /**
+     * Whether a substituted value is wrapped in Unicode bidi isolation marks,
+     * U+2068 and U+2069, so right-to-left text cannot reorder the sentence
+     * around it.
+     *
+     * `'none'` leaves values byte-for-byte as given, for output that is parsed
+     * after it is formatted: a Discord mention such as `<#123>` stops being
+     * one once the id inside it is isolated.
+     *
+     * @default 'default'
+     */
+    bidiIsolation?: 'default' | 'none';
+  }
 }
 /**
  * One locale, bound to the messages it formats against.
@@ -104,16 +130,22 @@ interface View<Locale extends string = string> {
   /** The messages this view formats against. */
   readonly messages: Readonly<View.Messages>;
   /**
-   * Format the message a descriptor names.
+   * How this view formats its messages. Plain data, so it can cross a
+   * server/client boundary alongside {@link locale} and {@link messages}.
+   */
+  readonly options: Readonly<View.Options>;
+  /**
+   * Format the message a descriptor names, or the message it carries.
+   *
+   * A message with nothing to translate, a lone `say.date(x)` with no text
+   * around it, is never extracted: the transform writes the ICU into the call
+   * instead of an id.
    *
    * @param descriptor Descriptor to format
    * @returns The formatted message
    * @throws If the id has no message
    */
-  call(descriptor: {
-    id: string;
-    [match: string | number]: unknown;
-  }): string;
+  call(descriptor: View.Descriptor): string;
   /**
    * Define a pluralised message.
    *
@@ -239,9 +271,10 @@ interface View<Locale extends string = string> {
  *
  * @param locale The locale to bind to
  * @param messages The messages this view formats against
+ * @param options How this view formats its messages
  * @returns The view
  */
-declare function createView<Locale extends string>(locale: Locale, messages: View.Messages): View<Locale>;
+declare function createView<Locale extends string>(locale: Locale, messages: View.Messages, options?: View.Options): View<Locale>;
 //#endregion
 //#region src/catalogue.d.ts
 declare namespace Catalogue {
@@ -268,13 +301,8 @@ declare namespace Catalogue {
   type Produced = View.Messages | {
     default: View.Messages;
   };
-  /**
-   * Where each locale's messages come from, keyed by locale.
-   *
-   * The keys are the catalogue's locales, in the order they are written, and
-   * the first of them is the default locale.
-   */
-  type Options<Locale extends string> = Record<Locale, Source>;
+  /** How every view the catalogue hands back formats its messages. */
+  type Options = View.Options;
 }
 /**
  * Everything an application knows how to say: its locales and where their
@@ -356,10 +384,14 @@ interface Catalogue<Locale extends string = string> {
  * const say = catalogue.locale('en');
  * ```
  *
- * @param messages Where each locale's messages come from, keyed by locale
+ * @param messages Where each locale's messages come from, keyed by locale. The
+ *   keys are the catalogue's locales, in the order they are written, and the
+ *   first of them is the default locale
+ * @param options How every view the catalogue hands back formats its
+ *   messages, such as `{ bidiIsolation: 'none' }`
  * @returns The catalogue
  */
-declare function createCatalogue<const Locale extends string = string>(messages: Catalogue.Options<Locale>): Catalogue<Locale>;
+declare function createCatalogue<const Locale extends string = string>(messages: Record<Locale, Catalogue.Source>, options?: Catalogue.Options): Catalogue<Locale>;
 //#endregion
 //#region src/store.d.ts
 declare namespace Store {

package/dist/index.mjs

@@ -420,28 +420,33 @@ const functions = {
 };
 //#endregion
 //#region src/messageformat/index.ts
-function compile(locale, source) {
-	return new MessageFormat(locale, toMessage(parse(source)), { functions });
+function compile(locale, source, options) {
+	return new MessageFormat(locale, toMessage(parse(source)), {
+		...options,
+		functions
+	});
 }
 //#endregion
 //#region src/view.ts
 function resolveDescriptorValues(descriptor) {
-	return Object.fromEntries(Object.entries(descriptor).filter(([key]) => key !== "id").map(([key, value]) => [key.startsWith("_") ? key.slice(1) : key, value]));
+	return Object.fromEntries(Object.entries(descriptor).filter(([key]) => key !== "id" && key !== "message").map(([key, value]) => [key.startsWith("_") ? key.slice(1) : key, value]));
 }
 function macro(name) {
 	throw new Error(`'say.${name}' is a macro and must be used with the relevant saykit plugin`);
 }
-function createView(locale, messages) {
+function createView(locale, messages, options = {}) {
+	const { bidiIsolation } = options;
+	const ownOptions = Object.freeze(bidiIsolation ? { bidiIsolation } : {});
 	const own = Object.freeze({ ...messages });
 	const formats = /* @__PURE__ */ new Map();
 	const say = (() => {
 		throw new Error("'say' is a macro and must be used with the relevant saykit plugin");
 	});
 	function call(descriptor) {
-		const message = own[descriptor.id];
-		if (typeof message !== "string") throw new Error(`Message for ${descriptor.id} is not a string`);
-		let format = formats.get(descriptor.id);
-		if (!format) formats.set(descriptor.id, format = compile(locale, message));
+		const { id, message = own[id] } = descriptor;
+		if (typeof message !== "string") throw new Error(`Message for ${id} is not a string`);
+		let format = formats.get(message);
+		if (!format) formats.set(message, format = compile(locale, message, { bidiIsolation }));
 		return String(format.format(resolveDescriptorValues(descriptor)));
 	}
 	return Object.freeze(Object.defineProperties(say, {
@@ -453,6 +458,10 @@ function createView(locale, messages) {
 			value: own,
 			enumerable: true
 		},
+		options: {
+			value: ownOptions,
+			enumerable: true
+		},
 		call: { value: call },
 		plural: { value: () => macro("plural") },
 		ordinal: { value: () => macro("ordinal") },
@@ -465,7 +474,8 @@ function createView(locale, messages) {
 }
 //#endregion
 //#region src/catalogue.ts
-function createCatalogue(messages) {
+function createCatalogue(messages, options = {}) {
+	const { bidiIsolation } = options;
 	const sources = Object.assign(Object.create(null), messages);
 	const keys = Object.freeze(Object.keys(sources));
 	if (keys.length === 0) throw new Error("A catalogue needs at least one locale, none were given");
@@ -484,7 +494,7 @@ function createCatalogue(messages) {
 			const messages = store.get(locale);
 			if (!messages) throw new Error(typeof sources[locale] === "function" ? `Messages for locale '${locale}' have not been loaded yet` : `No messages for locale '${locale}'`);
 			let view = views.get(locale);
-			if (!view) views.set(locale, view = createView(locale, messages));
+			if (!view) views.set(locale, view = createView(locale, messages, { bidiIsolation }));
 			return view;
 		},
 		loaded(locale) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saykit",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Type-safe i18n library with compile-time macro transforms",
   "keywords": [
     "i18n",