saykit 0.11.1 → 0.13.0

package/README.md

@@ -4,9 +4,9 @@
 
 [![Coverage](https://codecov.io/gh/k0d13/saykit/graph/badge.svg?flag=integration)](https://codecov.io/gh/k0d13/saykit?flags%5B0%5D=integration)
 
-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.
+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 its compiled messages, 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`), 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.
+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, and `saykit compile` turns each catalogue into a `.js` module of data that you import.
 
 ## Install
 
@@ -20,8 +20,8 @@ You will normally also want [`@saykit/config`](https://github.com/k0d13/saykit/t
 
 ```ts
 import { createCatalogue } from 'saykit';
-import en from './locales/en.po';
-import fr from './locales/fr.po';
+import en from './locales/en.js';
+import fr from './locales/fr.js';
 
 const catalogue = createCatalogue({ en, fr });
 

package/dist/index.d.mts

@@ -1,14 +1,63 @@
-//#region src/types.d.ts
-type Tuple = [any, ...any[]];
-type Disallow<T, K extends PropertyKey> = T & Partial<Record<K, never>>;
-type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * What each node in a compiled message is, by the number it starts with.
+ *
+ * The numbers are the format, so a kind is only ever appended, never renumbered or reused.
+ */
+export declare const Kind: {
+  readonly Value: 0;
+  readonly Number: 1;
+  readonly DateTime: 2;
+  readonly Plural: 3;
+  readonly Ordinal: 4;
+  readonly Select: 5;
+  readonly Hash: 6;
+};
+export type Kind = (typeof Kind)[keyof typeof Kind];
+/**
+ * A compiled message.
+ *
+ * The CLI compiles a catalogue to this: strings and arrays, with styles already resolved to
+ * `Intl` options. It is plain JSON, so it can cross a server/client boundary.
+ *
+ * A node is an array starting with its {@link Kind}; an array starting with anything else is a
+ * concatenation. Operands are descriptor keys, never nodes. A message with no placeholders is its
+ * own string.
+ */
+type Message = string | Message[] | [typeof Kind.Value, string] | [typeof Kind.Number, string, Intl.NumberFormatOptions?, number?] | [typeof Kind.DateTime, string, Intl.DateTimeFormatOptions?] | [typeof Kind.Plural, string, Message.Cases, number?] | [typeof Kind.Ordinal, string, Message.Cases, number?] | [typeof Kind.Select, string, Message.Cases] | [typeof Kind.Hash];
+declare namespace Message {
+  /**
+   * A plural's or a select's branches, by key. A plural's keys are CLDR
+   * categories or an exact `=n`, and `other` is the fallback for both.
+   */
+  type Cases = {
+    [key: string]: Message;
+  };
+  /** What a compiled message is called with: the descriptor the transform built. */
+  type Values = Record<string, unknown>;
+}
+/**
+ * Compile one message into the function that formats it.
+ *
+ * Called once per message per locale; a view memoises the result.
+ *
+ * @param message The compiled message, as the CLI emitted it
+ * @param locale The locale to format in
+ * @param options Whether written values are wrapped in bidi isolation marks
+ * @returns A function from a descriptor to the formatted string
+ */
+export declare function compileMessage(message: Message, locale: string, options?: {
+  bidiIsolation?: 'default' | 'none';
+}): (values: Message.Values) => string;
+export type Tuple = [any, ...any[]];
+export type Disallow<T, K extends PropertyKey> = T & Partial<Record<K, never>>;
+export type Awaitable<T> = T | PromiseLike<T>;
 /**
  * A value wrapped in the name its ICU placeholder should take, written inline
  * as a single-key object: `` say`Total: ${{ cartTotal: getTotal() }}` ``. The
  * transform reads the key at build time and compiles only the value, so this
  * is never a real object at runtime.
  */
-type Named<T> = {
+export type Named<T> = {
   [name: string]: T;
 };
 /**
@@ -17,7 +66,7 @@ type Named<T> = {
  * `Branch` is what a case may be written as: text everywhere the message is
  * text, widening in JSX, where a case showing the number has to be a fragment.
  */
-interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLPluralRule, Branch>>, 'other'> {
+export interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLPluralRule, Branch>>, 'other'> {
   other: Branch;
   [digit: number]: Branch;
   /**
@@ -26,7 +75,7 @@ interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLP
    */
   offset?: number;
 }
-interface SelectOptions<Branch = string> {
+export interface SelectOptions<Branch = string> {
   other: Branch;
   [match: string | number]: Branch;
 }
@@ -38,35 +87,38 @@ interface SelectOptions<Branch = string> {
  * A skeleton is where the formats the named styles have no word for live:
  * currency, compact notation, a year and month with no day.
  */
-type Skeleton = `::${string}`;
+export type Skeleton = `::${string}`;
 /**
  * Formatting for a `{arg, number}` placeholder.
  *
  * A literal `NumberFormat` pattern such as `#,##0.00` is also accepted, for the
  * cases neither the named styles nor a skeleton spell more clearly.
  */
-interface NumberOptions {
+export interface NumberOptions {
   style?: 'integer' | 'percent' | Skeleton | (string & {});
 }
 /** Formatting for a `{arg, date}` or `{arg, time}` placeholder. */
-interface DateTimeOptions {
+export interface DateTimeOptions {
   style?: 'short' | 'medium' | 'long' | 'full' | Skeleton;
 }
-//#endregion
-//#region src/view.d.ts
 declare namespace View {
+  /**
+   * One locale's messages, compiled.
+   *
+   * Each is a {@link Message} the CLI compiled from the catalogue. They are plain data, so a
+   * server can hand them to a client tree.
+   */
   type Messages = {
-    [key: string]: string;
+    [key: string]: Message;
   };
   /**
-   * 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.
+   * What the transform compiles a message down to: its extracted id, or the compiled message
+   * itself when there was nothing to extract. Values sit behind one underscore each.
    */
   type Descriptor = ({
     id: string;
   } | {
-    message: string;
+    message: Message;
   }) & {
     [match: string | number]: unknown;
   };
@@ -137,9 +189,8 @@ interface View<Locale extends string = string> {
   /**
    * 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.
+   * A message with nothing to translate, such as a lone `say.date(x)`, is never extracted:
+   * the transform writes the compiled message into the call instead of an id.
    *
    * @param descriptor Descriptor to format
    * @returns The formatted message
@@ -265,18 +316,14 @@ interface View<Locale extends string = string> {
  * Create a view over one locale and the messages it formats against.
  *
  * A catalogue memoises one per locale, which is how application code usually
- * reaches one; a single-locale app can build one directly. The format cache
- * belongs to the view, so a view built over one set of messages can never be
- * served a format compiled from another.
+ * reaches one; a single-locale app can build one directly.
  *
  * @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, options?: View.Options): View<Locale>;
-//#endregion
-//#region src/catalogue.d.ts
+export declare function createView<Locale extends string>(locale: Locale, messages: View.Messages, options?: View.Options): View<Locale>;
 declare namespace Catalogue {
   /**
    * One guess at a locale, or several. Guesses are read from cookies, headers
@@ -355,8 +402,23 @@ interface Catalogue<Locale extends string = string> {
   /**
    * Matches the best locale from a list of guesses.
    *
+   * Guesses are tried in order, and an earlier guess that matches at all wins
+   * over a later one that would match more closely. Each guess is
+   * canonicalised first, so case does not matter (`en-us` is `en-US`), and
+   * then compared in steps, most specific first:
+   *
+   * 1. The same tag
+   * 2. The same language and script, filling in the script a tag implies, so
+   *    `zh-HK` (Traditional) finds `zh-TW` rather than `zh-CN`
+   * 3. The same language subtag, whole, so `fi` never matches `fil`
+   *
+   * Within a step, the locale written first wins, so with `pt-BR` before
+   * `pt-PT`, `pt` matches `pt-BR`.
+   *
    * An absent or empty guess is skipped rather than throwing, which lets a
    * caller write `match(fromCookie, fromHeader)` without narrowing each first.
+   * So is one that is not a well-formed locale tag, unless it is written
+   * exactly as one of {@link locales}.
    *
    * @param guesses List of locale guesses
    * @returns The best matching locale, or the first of {@link locales} if no
@@ -391,9 +453,7 @@ interface Catalogue<Locale extends string = string> {
  *   messages, such as `{ bidiIsolation: 'none' }`
  * @returns The catalogue
  */
-declare function createCatalogue<const Locale extends string = string>(messages: Record<Locale, Catalogue.Source>, options?: Catalogue.Options): Catalogue<Locale>;
-//#endregion
-//#region src/store.d.ts
+export declare function createCatalogue<const Locale extends string = string>(messages: Record<Locale, Catalogue.Source>, options?: Catalogue.Options): Catalogue<Locale>;
 declare namespace Store {
   /** Called after a successful switch, with the view that is now current. */
   type Listener<Locale extends string> = (view: View<Locale>) => void;
@@ -474,9 +534,7 @@ interface Store<Locale extends string = string> {
  * @returns The store
  * @throws If the starting locale has no messages loaded
  */
-declare function createStore<Locale extends string>(catalogue: Catalogue<Locale>, locale?: Locale): Store<Locale>;
-//#endregion
-//#region src/scope.d.ts
+export declare function createStore<Locale extends string>(catalogue: Catalogue<Locale>, locale?: Locale): Store<Locale>;
 declare namespace Scope {
   /**
    * Where a scope holds the view a piece of work is running under.
@@ -585,6 +643,5 @@ interface Scope {
  *   browser wants
  * @returns The scope
  */
-declare function createScope(storage?: Scope.Storage): Scope;
-//#endregion
-export { Awaitable, type Catalogue, DateTimeOptions, Disallow, Named, NumberOptions, NumeralOptions, type Scope, SelectOptions, Skeleton, type Store, Tuple, type View, createCatalogue, createScope, createStore, createView };
+export declare function createScope(storage?: Scope.Storage): Scope;
+export type { Catalogue, Message, Scope, Store, View };