saykit 0.9.0 → 0.10.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![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 the `Say` class, which stores your locales, loads message catalogues, and formats messages using ICU MessageFormat.
+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.
 
@@ -19,21 +19,32 @@ You will normally also want [`@saykit/config`](https://github.com/k0d13/saykit/t
 ## Usage
 
 ```ts
-import { Say } from 'saykit';
+import { createCatalogue } from 'saykit';
 import en from './locales/en.po';
 import fr from './locales/fr.po';
 
-const say = new Say({
-  locales: ['en', 'fr'],
-  messages: { en, fr },
-});
+const catalogue = createCatalogue({ en, fr });
 
-say.activate('en');
+const say = catalogue.locale('en');
 
 say`Hello, ${name}!`;
 say.plural(count, { one: '1 item', other: `${count} items` });
 ```
 
+In a browser, where the locale can change, hold a store instead of a view:
+
+```ts
+import { createStore } from 'saykit';
+
+const store = createStore(catalogue, 'en');
+
+store.subscribe((say) => render(say));
+
+await store.set('fr');
+
+store.say`Hello, ${name}!`;
+```
+
 ## Documentation
 
 Full guide at [saykit.js.org](https://saykit.js.org).

package/dist/index.d.mts

@@ -0,0 +1,558 @@
+//#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>;
+/**
+ * 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> = {
+  [name: string]: T;
+};
+/**
+ * Branches of a choice, keyed by CLDR category or by exact number.
+ *
+ * `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'> {
+  other: Branch;
+  [digit: number]: Branch;
+  /**
+   * Subtracted from the value before `#` is formatted, so "You and 2 others"
+   * can select on a total of three. Reserved, it never names a branch.
+   */
+  offset?: number;
+}
+interface SelectOptions<Branch = string> {
+  other: Branch;
+  [match: string | number]: Branch;
+}
+/**
+ * An ICU skeleton: a `::`-prefixed description of the parts a value is written
+ * with, rather than a name for a whole format. `::currency/EUR` and
+ * `::yyyyMMdd` say what to show and leave the arrangement to the locale.
+ *
+ * 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}`;
+/**
+ * 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 {
+  style?: 'integer' | 'percent' | Skeleton | (string & {});
+}
+/** Formatting for a `{arg, date}` or `{arg, time}` placeholder. */
+interface DateTimeOptions {
+  style?: 'short' | 'medium' | 'long' | 'full' | Skeleton;
+}
+//#endregion
+//#region src/view.d.ts
+declare namespace View {
+  type Messages = {
+    [key: string]: string;
+  };
+}
+/**
+ * One locale, bound to the messages it formats against.
+ *
+ * Callable, immutable and memoised: `catalogue.locale('en')` hands back the
+ * same value every time. A view has no reference back to its catalogue and so
+ * cannot switch locale; switching belongs to whoever owns the catalogue.
+ */
+interface View<Locale extends string = string> {
+  /**
+   * Define a message.
+   *
+   * An interpolated variable is named after itself. Anything else is numbered,
+   * unless written as a single-key object, which names it.
+   *
+   * @example
+   * ```ts
+   * say`Hello, ${name}!`
+   * say`Your total is ${{ cartTotal: getCartTotal() }}`
+   * ```
+   *
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  (strings: TemplateStringsArray, ...placeholders: unknown[]): string;
+  /**
+   * Give the message a custom id, or a context to disambiguate identical
+   * strings that mean different things.
+   *
+   * @example
+   * ```ts
+   * say({ context: 'direction' })`Right`
+   * say({ context: 'correctness' })`Right`
+   * ```
+   *
+   * @param descriptor Object containing optional `id` and `context` properties
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  (descriptor: {
+    id?: string;
+    context?: string;
+  }): View<Locale>;
+  /** The locale this view is bound to. */
+  readonly locale: Locale;
+  /** The messages this view formats against. */
+  readonly messages: Readonly<View.Messages>;
+  /**
+   * Format the message a descriptor names.
+   *
+   * @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;
+  /**
+   * Define a pluralised message.
+   *
+   * Interpolating the selector into a branch extracts as ICU's `#`. A `#` you
+   * write yourself is text.
+   *
+   * @example
+   * ```ts
+   * say.plural(count, {
+   *   one: 'You have 1 item',
+   *   other: `You have ${count} items`,
+   * })
+   * ```
+   *
+   * @param _ Number to determine the plural form of
+   * @param options Pluralisation rules keyed by CLDR categories or specific numbers
+   * @returns The plural form of the number
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  plural(_: number | Named<number>, options: Disallow<NumeralOptions, 'id' | 'context'>): string;
+  /**
+   * Define an ordinal message ("1st", "2nd", "3rd").
+   *
+   * Interpolating the selector into a branch extracts as ICU's `#`. A `#` you
+   * write yourself is text.
+   *
+   * @example
+   * ```ts
+   * say.ordinal(position, {
+   *   1: `${position}st`,
+   *   2: `${position}nd`,
+   *   3: `${position}rd`,
+   *   other: `${position}th`,
+   * })
+   * ```
+   *
+   * @param _ Number to determine the ordinal form of
+   * @param options Ordinal rules keyed by CLDR categories or specific numbers
+   * @returns The ordinal form of the number
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  ordinal(_: number | Named<number>, options: Disallow<NumeralOptions, 'id' | 'context'>): string;
+  /**
+   * Define a select message, for gender, status, or other categories.
+   *
+   * @example
+   * ```ts
+   * say.select(gender, {
+   *   male: 'He',
+   *   female: 'She',
+   *   other: 'They',
+   * })
+   * ```
+   *
+   * @param _ Selector value to determine which option is chosen
+   * @param options A mapping of possible selector values to message strings
+   * @returns The select form of the value
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  select(_: string | number | Named<string | number>, options: Disallow<SelectOptions, 'id' | 'context'>): string;
+  /**
+   * Format a number the way this view's locale writes one, with its own
+   * grouping separators and decimal mark.
+   *
+   * Unlike `plural`, `ordinal` and `select`, this is a fragment rather than a
+   * whole message, and is normally written inside one.
+   *
+   * @example
+   * ```ts
+   * say`You have ${say.number(items.length)} items`
+   * say`Battery at ${say.number(level, { style: 'percent' })}`
+   * say`Total: ${say.number({ cartTotal: getTotal() }, { style: '#,##0.00' })}`
+   * say`Total: ${say.number(total, { style: '::currency/EUR' })}`
+   * ```
+   *
+   * @param _ Number to format
+   * @param options Formatting style: a named style, an ICU skeleton such as
+   *   `::currency/EUR`, or a pattern such as `#,##0.00`
+   * @returns The formatted number
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  number(_: number | Named<number>, options?: Disallow<NumberOptions, 'id' | 'context'>): string;
+  /**
+   * Format the date portion of a value the way this view's locale writes one.
+   *
+   * @example
+   * ```ts
+   * say`Published ${say.date(post.publishedAt)}`
+   * say`Published ${say.date(post.publishedAt, { style: 'full' })}`
+   * say`Published ${say.date(post.publishedAt, { style: '::yMMMM' })}`
+   * ```
+   *
+   * @param _ Date to format
+   * @param options A named style or an ICU skeleton such as `::yyyyMMdd`
+   * @returns The formatted date
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  date(_: Date | number | Named<Date | number>, options?: Disallow<DateTimeOptions, 'id' | 'context'>): string;
+  /**
+   * Format the time portion of a value the way this view's locale writes one.
+   *
+   * @example
+   * ```ts
+   * say`Doors open at ${say.time(opensAt)}`
+   * say`Doors open at ${say.time(opensAt, { style: 'short' })}`
+   * say`Doors open at ${say.time(opensAt, { style: '::Hm' })}`
+   * ```
+   *
+   * @param _ Date to format
+   * @param options A named style or an ICU skeleton such as `::Hm`
+   * @returns The formatted time
+   * @remark This is a macro and must be used with the relevant saykit plugin
+   */
+  time(_: Date | number | Named<Date | number>, options?: Disallow<DateTimeOptions, 'id' | 'context'>): 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.
+ *
+ * @param locale The locale to bind to
+ * @param messages The messages this view formats against
+ * @returns The view
+ */
+declare function createView<Locale extends string>(locale: Locale, messages: View.Messages): View<Locale>;
+//#endregion
+//#region src/catalogue.d.ts
+declare namespace Catalogue {
+  /**
+   * One guess at a locale, or several. Guesses are read from cookies, headers
+   * and URL segments, none of which is guaranteed to be there, so an absent
+   * one is allowed and skipped.
+   */
+  type Guess = string | null | undefined | readonly (string | null | undefined)[];
+  /**
+   * Where one locale's messages come from: the messages themselves, or a
+   * function that produces them the first time the locale is asked for.
+   *
+   * A thunk is normally a dynamic import, which is what splits a locale into
+   * its own chunk: `fr: () => import('./locales/fr.po')`. Written per locale
+   * rather than as one function keyed by locale, so a bundler can see each
+   * import statically.
+   */
+  type Source = View.Messages | (() => Catalogue.Produced | Promise<Catalogue.Produced>);
+  /**
+   * What a thunk produces: a locale's messages, or the module a dynamic import
+   * resolves to, which holds them as its default export.
+   */
+  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>;
+}
+/**
+ * Everything an application knows how to say: its locales and where their
+ * messages come from.
+ *
+ * A catalogue never formats anything and has no active locale. Formatting is
+ * what a {@link View} does, and a view is what `locale` hands back.
+ */
+interface Catalogue<Locale extends string = string> {
+  /**
+   * All available locales, in the order they were written.
+   *
+   * Never empty, and the first of them is the fallback: the locale
+   * {@link match} resolves to when nothing else does.
+   */
+  readonly locales: readonly [Locale, ...Locale[]];
+  /**
+   * A view bound to one locale: callable, immutable, and memoised, so asking
+   * twice returns the same view.
+   *
+   * @param locale Locale to bind to
+   * @returns The view for the locale
+   * @throws If the locale's messages are not here yet, as for a thunk nobody
+   *   has {@link load}ed
+   */
+  locale(locale: Locale): View<Locale>;
+  /**
+   * Whether a locale's messages are here, and so whether
+   * {@link Catalogue.locale} hands back a view for it. Inline messages are
+   * here from the start; a thunk's once it has been {@link load}ed.
+   *
+   * @param locale Locale to check
+   */
+  loaded(locale: Locale): boolean;
+  /**
+   * Calls a locale's thunk, if it has one and nothing has called it yet, and
+   * hands back the locale's view.
+   *
+   * If the thunk returns a promise, so does this. A locale whose messages are
+   * already here does not go near its thunk and comes back synchronously,
+   * which keeps a switch between loaded locales in one tick.
+   *
+   * A thunk is called once and a locale is filled once, so nothing can replace
+   * the messages a view was built over.
+   *
+   * @param locale Locale to load
+   * @returns The view for the locale
+   */
+  load(locale: Locale): View<Locale> | Promise<View<Locale>>;
+  /**
+   * Matches the best locale from a list of guesses.
+   *
+   * An absent or empty guess is skipped rather than throwing, which lets a
+   * caller write `match(fromCookie, fromHeader)` without narrowing each first.
+   *
+   * @param guesses List of locale guesses
+   * @returns The best matching locale, or the first of {@link locales} if no
+   *   matches are found
+   */
+  match(...guesses: Catalogue.Guess[]): Locale;
+  /**
+   * Every locale, paired with its view.
+   *
+   * @throws If any locale's messages have not been produced yet
+   */
+  [Symbol.iterator](): IterableIterator<[Locale, View<Locale>]>;
+}
+/**
+ * Create a {@link Catalogue}.
+ *
+ * @example
+ * ```ts
+ * const catalogue = createCatalogue({
+ *   en,
+ *   fr: () => import('./locales/fr.po'),
+ *   pl: () => import('./locales/pl.po'),
+ * });
+ *
+ * const say = catalogue.locale('en');
+ * ```
+ *
+ * @param messages Where each locale's messages come from, keyed by locale
+ * @returns The catalogue
+ */
+declare function createCatalogue<const Locale extends string = string>(messages: Catalogue.Options<Locale>): Catalogue<Locale>;
+//#endregion
+//#region src/store.d.ts
+declare namespace Store {
+  /** Called after a successful switch, with the view that is now current. */
+  type Listener<Locale extends string> = (view: View<Locale>) => void;
+}
+/**
+ * Which view is current, and when that changed.
+ *
+ * A catalogue owns the messages and a view formats one locale's; neither of
+ * them mutates. A store is the role that does: it holds one view at a time,
+ * swaps it for another, and tells whoever is listening.
+ *
+ * That mutation is the point, so a store is a browser value: one locale, one
+ * user, module scope. A server handles several locales at once and should
+ * reach a view through the request instead.
+ */
+interface Store<Locale extends string = string> {
+  /**
+   * The current view: callable, immutable, and safe to hold onto until the
+   * next switch.
+   *
+   * It is named for the tag a message is written against, so a store can be
+   * formatted through directly, and it is read at the moment of access rather
+   * than bound once. Read it per call: a `const say = store.say` held across a
+   * switch is the old view.
+   *
+   * Its identity changes when the locale does, which is what lets a subscriber
+   * compare snapshots. Because a catalogue memoises views, switching away and
+   * back hands the same view back.
+   *
+   * @example
+   * ```ts
+   * store.say`Hello, ${name}!`;
+   * store.say.locale; // 'en'
+   * ```
+   */
+  readonly say: View<Locale>;
+  /**
+   * Switch to another locale, loading its messages first if the catalogue does
+   * not have them yet.
+   *
+   * Like {@link Catalogue.load}, this returns a promise only when the thunk
+   * does: a locale that is already loaded switches synchronously, so a
+   * subscriber sees the new view in the same tick.
+   *
+   * Switching to the current locale does nothing, though asking again for a
+   * locale still being switched to hands back the switch already in flight. A
+   * load that throws leaves the current view where it was.
+   *
+   * @param locale Locale to switch to
+   * @returns Nothing, or a promise that resolves once the switch is done
+   */
+  set(locale: Locale): void | Promise<void>;
+  /**
+   * Listen for switches. The listener is called after {@link Store.say} has
+   * changed, and not on subscribe: the current view is already readable.
+   *
+   * @param listener Called with the view that is now current
+   * @returns A function that removes the listener
+   */
+  subscribe(listener: Store.Listener<Locale>): () => void;
+}
+/**
+ * Create a {@link Store} over a catalogue.
+ *
+ * @example
+ * ```ts
+ * const store = createStore(catalogue, 'en');
+ *
+ * store.subscribe(render);
+ * await store.set('fr');
+ * store.say`Hello, ${name}!`;
+ * store.say.locale; // 'fr'
+ * ```
+ *
+ * @param catalogue The catalogue to take views from
+ * @param locale The locale to start on, defaults to the first of
+ *   {@link Catalogue.locales}
+ * @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
+declare namespace Scope {
+  /**
+   * Where a scope holds the view a piece of work is running under.
+   *
+   * This is `AsyncLocalStorage`'s own shape, so node's is passed directly and
+   * any polyfill fits without an adapter. saykit imports none of them: which
+   * storage to use, if any, is the application's choice.
+   *
+   * @example
+   * ```ts
+   * import { AsyncLocalStorage } from 'node:async_hooks';
+   *
+   * const scope = createScope(new AsyncLocalStorage());
+   * ```
+   */
+  interface Storage {
+    /** The view established by the innermost enclosing {@link Scope.run}. */
+    getStore(): View | undefined;
+    /** Run a callback with a view in place. */
+    run<Args extends unknown[], Return>(view: View, callback: (...args: Args) => Return, ...args: Args): Return;
+  }
+  /**
+   * Where a scope reads its view outside {@link Scope.run}: the view itself,
+   * or a store to read {@link Store.say} from on every access, so a scope
+   * follows that store's switches without subscribing to it.
+   */
+  type Source<Locale extends string = string> = View<Locale> | Store<Locale>;
+}
+/**
+ * Which view the work running right now is saying things in.
+ *
+ * A scope is how code reaches a view without being handed it:
+ * {@link Scope.say} is imported once at the top of a module and resolves, on
+ * every use, to the view established around the call.
+ *
+ * On a server a {@link Scope.Storage} makes that one view per request, kept
+ * across every await and invisible to the requests beside it. A browser has
+ * one locale at a time, so a scope built without a storage holds one view,
+ * and {@link Scope.use} is how a store establishes it.
+ */
+interface Scope {
+  /**
+   * The current view, read through the scope on every use.
+   *
+   * Callable and carrying the macros like any `View`, but not bound to a
+   * locale: each read resolves the view established around the call, which is
+   * what lets a module import it once and still say the right thing for the
+   * request it ends up serving.
+   *
+   * @throws On use, if no view is in scope
+   */
+  readonly say: View;
+  /**
+   * Run a callback with a view in scope. Everything it calls, at any depth,
+   * reads that view from {@link say}.
+   *
+   * With a {@link Scope.Storage}, each call is isolated and keeps its view
+   * across every await. Without one, the previous view is put back when the
+   * callback returns, so an async callback keeps its view only until its
+   * first await.
+   *
+   * @param view View to establish for the duration
+   * @param callback Callback to run
+   * @param args Arguments to call it with
+   * @returns Whatever the callback returns
+   */
+  run<Args extends unknown[], Return>(view: View, callback: (...args: Args) => Return, ...args: Args): Return;
+  /**
+   * Establish the view to read outside any {@link run}.
+   *
+   * A browser has no request to hang a scope on, so this is how it establishes
+   * one, usually from a store, which is read on every access and so follows
+   * its switches.
+   *
+   * A server should prefer a scope per request. This is still useful there for
+   * a process that only ever serves one locale, such as a CLI or a worker.
+   *
+   * @param source The view to read, or a store to read it from, or `undefined`
+   *   to leave none
+   * @returns A function that puts back whatever was there before
+   */
+  use(source: Scope.Source | undefined): () => void;
+}
+/**
+ * Create a {@link Scope}.
+ *
+ * @example
+ * ```ts
+ * // A server: one view per request, and `say` anywhere inside it
+ * export const scope = createScope(new AsyncLocalStorage());
+ * export const { say } = scope;
+ *
+ * scope.run(catalogue.locale(locale), handler);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // A browser: one locale at a time, read from a store
+ * export const { say, use } = createScope();
+ *
+ * use(store);
+ * ```
+ *
+ * @param storage Where to hold the view, normally an `AsyncLocalStorage`. Left
+ *   out, the scope holds one view for the whole program, which is what a
+ *   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 };

package/dist/{runtime.mjs → index.mjs}

@@ -424,121 +424,237 @@ function compile(locale, source) {
 	return new MessageFormat(locale, toMessage(parse(source)), { functions });
 }
 //#endregion
-//#region src/runtime.ts
+//#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]));
 }
-var Say = class Say {
-	#locales;
-	#loader;
-	#messages;
-	#formats;
-	#active;
-	constructor(options) {
-		this.#locales = options.locales;
-		this.#loader = options.loader;
-		this.#messages = /* @__PURE__ */ new Map();
-		this.#formats = /* @__PURE__ */ new Map();
-		if (options.messages) this.assign(options.messages);
-	}
-	get locale() {
-		if (!this.#active) throw new Error("No active locale");
-		return this.#active;
-	}
-	get messages() {
-		/* v8 ignore next */
-		if (!this.#messages.has(this.locale)) throw new Error("No messages loaded for locale");
-		return this.#messages.get(this.locale);
-	}
-	get locales() {
-		return this.#locales;
-	}
-	load(...locales) {
-		if (Object.isFrozen(this)) throw new Error("Cannot load messages on a frozen Say");
-		if (locales.length === 0) locales = this.#locales;
-		const tasks = [];
-		for (const locale of locales) {
-			if (this.#messages.has(locale)) continue;
-			if (!this.#loader) throw new Error("No loader provided, cannot load messages");
-			const result = this.#loader(locale);
-			if (result instanceof Promise) {
-				const task = result.then((m) => this.assign(locale, m));
-				tasks.push(task);
-			} else this.assign(locale, result);
-		}
-		return tasks.length > 0 ? Promise.all(tasks).then(() => this) : this;
-	}
-	assign(localeOrMessages, maybeMessages) {
-		if (Object.isFrozen(this)) throw new Error("Cannot assign messages on a frozen Say");
-		if (typeof localeOrMessages === "string") this.#messages.set(localeOrMessages, maybeMessages);
-		else for (const locale in localeOrMessages) this.#messages.set(locale, localeOrMessages[locale]);
-		return this;
-	}
-	activate(locale) {
-		if (Object.isFrozen(this)) throw new Error("Cannot activate locale on a frozen Say");
-		if (!this.#messages.has(locale)) throw new Error("No messages loaded for locale");
-		this.#active = locale;
-		return this;
-	}
-	clone() {
-		const copy = new Say({
-			locales: this.#locales,
-			messages: Object.fromEntries(this.#messages),
-			loader: this.#loader
-		});
-		copy.#active = this.#active;
-		return copy;
-	}
-	freeze() {
-		return Object.freeze(this);
-	}
-	*[Symbol.iterator]() {
-		for (const l of this.#locales) yield [this.clone().activate(l).freeze(), l];
-	}
-	match(...guesses) {
-		const flat = guesses.flat();
-		if (flat.length === 0) return this.#locales[0];
-		for (const guess of flat) {
-			if (this.#locales.includes(guess)) return guess;
-			const prefix = guess.split("-")[0];
-			if (!prefix) continue;
-			const match = this.#locales.find((l) => l.startsWith(prefix));
-			if (match) return match;
-		}
-		return this.#locales[0];
-	}
-	call(descriptor) {
-		return this.#call(this.locale, this.messages, descriptor);
-	}
-	#call(locale, messages, descriptor) {
-		const message = messages[descriptor.id];
+function macro(name) {
+	throw new Error(`'say.${name}' is a macro and must be used with the relevant saykit plugin`);
+}
+function createView(locale, messages) {
+	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`);
-		const key = `${locale}:${descriptor.id}`;
-		const format = this.#formats.get(key) ?? this.#formats.set(key, compile(locale, message)).get(key);
+		let format = formats.get(descriptor.id);
+		if (!format) formats.set(descriptor.id, format = compile(locale, message));
 		return String(format.format(resolveDescriptorValues(descriptor)));
 	}
-	[Symbol.for("nodejs.util.inspect.custom")](_depth, context, inspect) {
-		if (this.#active) return `${this.constructor.name}<${inspect(this.#active, context)}> {}`;
-		else return `${this.constructor.name} {}`;
+	return Object.freeze(Object.defineProperties(say, {
+		locale: {
+			value: locale,
+			enumerable: true
+		},
+		messages: {
+			value: own,
+			enumerable: true
+		},
+		call: { value: call },
+		plural: { value: () => macro("plural") },
+		ordinal: { value: () => macro("ordinal") },
+		select: { value: () => macro("select") },
+		number: { value: () => macro("number") },
+		date: { value: () => macro("date") },
+		time: { value: () => macro("time") },
+		[Symbol.for("nodejs.util.inspect.custom")]: { value: (_depth, context, inspect) => `View<${inspect(locale, context)}> {}` }
+	}));
+}
+//#endregion
+//#region src/catalogue.ts
+function createCatalogue(messages) {
+	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");
+	const locales = keys;
+	const store = /* @__PURE__ */ new Map();
+	const views = /* @__PURE__ */ new Map();
+	const loading = /* @__PURE__ */ new Map();
+	function fill(locale, produced) {
+		const messages = typeof produced.default === "object" ? produced.default : produced;
+		if (!store.has(locale)) store.set(locale, messages);
+		return catalogue.locale(locale);
 	}
-	plural(_, options) {
-		throw new Error("'Say#plural' is a macro and must be used with the relevant saykit plugin");
+	const catalogue = {
+		locales,
+		locale(locale) {
+			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));
+			return view;
+		},
+		loaded(locale) {
+			return store.has(locale);
+		},
+		load(locale) {
+			if (store.has(locale)) return catalogue.locale(locale);
+			const pending = loading.get(locale);
+			if (pending) return pending;
+			const source = sources[locale];
+			if (typeof source !== "function") throw new Error(`No messages for locale '${locale}'`);
+			const produced = source();
+			if (!(produced instanceof Promise)) return fill(locale, produced);
+			const task = produced.then((messages) => {
+				loading.delete(locale);
+				return fill(locale, messages);
+			}, (error) => {
+				loading.delete(locale);
+				throw error;
+			});
+			loading.set(locale, task);
+			return task;
+		},
+		match(...guesses) {
+			const flat = guesses.flat().filter((guess) => typeof guess === "string" && guess !== "");
+			if (flat.length === 0) return locales[0];
+			for (const guess of flat) {
+				if (locales.includes(guess)) return guess;
+				const prefix = guess.split("-")[0];
+				if (!prefix) continue;
+				const match = locales.find((l) => l.startsWith(prefix));
+				if (match) return match;
+			}
+			return locales[0];
+		},
+		*[Symbol.iterator]() {
+			for (const locale of locales) yield [locale, catalogue.locale(locale)];
+		}
+	};
+	for (const locale of locales) {
+		const source = sources[locale];
+		if (typeof source !== "function") fill(locale, source);
 	}
-	ordinal(_, options) {
-		throw new Error("'Say#ordinal' is a macro and must be used with the relevant saykit plugin");
+	return Object.freeze(catalogue);
+}
+//#endregion
+//#region src/scope.ts
+const NO_VIEW = "No view is in scope for 'say'. Run the work inside 'scope.run(view, callback)', or establish one with 'scope.use(store)'.";
+function createVariableStorage() {
+	let running;
+	return {
+		getStore: () => running,
+		run(view, callback, ...args) {
+			const previous = running;
+			running = view;
+			try {
+				return callback(...args);
+			} finally {
+				running = previous;
+			}
+		}
+	};
+}
+function createScope(storage = createVariableStorage()) {
+	let source;
+	let calls = 0;
+	let call = 0;
+	function peek() {
+		const running = storage.getStore();
+		if (running) return running;
+		if (!source) return void 0;
+		return typeof source === "function" ? source : source.say;
 	}
-	select(_, options) {
-		throw new Error("'Say#select' is a macro and must be used with the relevant saykit plugin");
+	function resolve() {
+		const view = peek();
+		if (!view) throw new Error(NO_VIEW);
+		return view;
 	}
-	number(_, options) {
-		throw new Error("'Say#number' is a macro and must be used with the relevant saykit plugin");
+	const target = (() => {});
+	const scope = {
+		say: new Proxy(target, {
+			apply: (_target, _this, args) => resolve()(...args),
+			get: (_target, property) => Reflect.get(resolve(), property),
+			has: (_target, property) => Reflect.has(resolve(), property),
+			ownKeys: () => Reflect.ownKeys(resolve()),
+			getOwnPropertyDescriptor: (_target, property) => {
+				const descriptor = Reflect.getOwnPropertyDescriptor(resolve(), property);
+				return descriptor && {
+					...descriptor,
+					configurable: true
+				};
+			},
+			set: () => false,
+			defineProperty: () => false,
+			deleteProperty: () => false
+		}),
+		run(view, callback, ...args) {
+			return storage.run(view, callback, ...args);
+		},
+		use(next) {
+			const previous = source;
+			const previousCall = call;
+			const mine = ++calls;
+			source = next;
+			call = mine;
+			return () => {
+				if (call !== mine) return;
+				source = previous;
+				call = previousCall;
+			};
+		}
+	};
+	return Object.freeze(Object.defineProperties(scope, { [Symbol.for("nodejs.util.inspect.custom")]: { value: (_depth, context, inspect) => {
+		const view = peek();
+		return `Scope<${view ? inspect(view.locale, context) : "unset"}> {}`;
+	} } }));
+}
+//#endregion
+//#region src/store.ts
+function createStore(catalogue, locale = catalogue.locales[0]) {
+	let current = catalogue.locale(locale);
+	const listeners = /* @__PURE__ */ new Set();
+	let generation = 0;
+	let intended = current.locale;
+	let pending;
+	function settle(at) {
+		if (at === generation) pending = void 0;
 	}
-	date(_, options) {
-		throw new Error("'Say#date' is a macro and must be used with the relevant saykit plugin");
+	function swap(view, at) {
+		if (at !== generation) return;
+		if (view === current) return;
+		current = view;
+		for (const listener of listeners) listener(current);
 	}
-	time(_, options) {
-		throw new Error("'Say#time' is a macro and must be used with the relevant saykit plugin");
+	function undo(at) {
+		if (at === generation) intended = current.locale;
 	}
-};
+	return Object.freeze(Object.defineProperties({
+		get say() {
+			return current;
+		},
+		set(target) {
+			if (target === intended) return pending;
+			const at = ++generation;
+			intended = target;
+			try {
+				const loading = catalogue.load(target);
+				if (loading instanceof Promise) return pending = loading.then((view) => {
+					settle(at);
+					swap(view, at);
+				}, (error) => {
+					settle(at);
+					undo(at);
+					throw error;
+				});
+				pending = void 0;
+				swap(loading, at);
+			} catch (error) {
+				pending = void 0;
+				undo(at);
+				throw error;
+			}
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	}, { [Symbol.for("nodejs.util.inspect.custom")]: { value: (_depth, context, inspect) => `Store<${inspect(current.locale, context)}> {}` } }));
+}
 //#endregion
-export { Say };
+export { createCatalogue, createScope, createStore, createView };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saykit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Type-safe i18n library with compile-time macro transforms",
   "keywords": [
     "i18n",
@@ -28,8 +28,8 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/runtime.d.mts",
-      "default": "./dist/runtime.mjs"
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
     }
   },
   "publishConfig": {

package/dist/runtime.d.mts

@@ -1,316 +0,0 @@
-//#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>;
-/**
- * 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> = {
-  [name: string]: T;
-};
-/**
- * Branches of a choice, keyed by CLDR category or by exact number.
- *
- * `Branch` is what a case may be written as. It is text everywhere the message
- * is text, and widens in JSX, where a case that shows the number has to be a
- * fragment — a string attribute has nowhere to put a value.
- */
-interface NumeralOptions<Branch = string> extends Omit<Partial<Record<Intl.LDMLPluralRule, Branch>>, 'other'> {
-  other: Branch;
-  [digit: number]: Branch;
-  /**
-   * Subtracted from the value before `#` is formatted, so "You and 2 others"
-   * can select on a total of three. Reserved — it never names a branch.
-   */
-  offset?: number;
-}
-interface SelectOptions<Branch = string> {
-  other: Branch;
-  [match: string | number]: Branch;
-}
-/**
- * An ICU skeleton: a `::`-prefixed description of the parts a value is written
- * with, rather than a name for a whole format. `::currency/EUR` and
- * `::yyyyMMdd` say what to show and leave the arrangement to the locale.
- *
- * A skeleton is where the formats the named styles have no word for live —
- * currency, compact notation, a year and month with no day — so every argument
- * type accepts one alongside its named styles.
- */
-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 {
-  style?: 'integer' | 'percent' | Skeleton | (string & {});
-}
-/**
- * Formatting for a `{arg, date}` or `{arg, time}` placeholder.
- */
-interface DateTimeOptions {
-  style?: 'short' | 'medium' | 'long' | 'full' | Skeleton;
-}
-//#endregion
-//#region src/runtime.d.ts
-declare namespace Say {
-  type Messages = {
-    [key: string]: string;
-  };
-  type Loader<Locale extends string> = (locale: Locale) => Messages | Promise<Messages>;
-  type Options<Locale extends string, Loader extends Say.Loader<Locale> | undefined> = {
-    locales: Locale[];
-  } & ({
-    messages: Record<Locale, Messages>;
-    loader?: Loader;
-  } | {
-    messages?: Partial<Record<Locale, Messages>>;
-    loader: Loader;
-  });
-}
-interface Say {
-  /**
-   * Define a message.
-   *
-   * An interpolated variable is named after itself. Anything else is numbered,
-   * unless it is written as a single-key object, which names it.
-   *
-   * @example
-   * ```ts
-   * say`Hello, ${name}!`
-   * say`Your total is ${{ cartTotal: getCartTotal() }}`
-   * ```
-   *
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  (strings: TemplateStringsArray, ...placeholders: unknown[]): string;
-  /**
-   * Provide a custom id or context for the message, the latter used to disambiguate
-   * identical strings that have different meanings depending on usage.
-   *
-   * @example
-   * ```ts
-   * say({ context: 'direction' })`Right`
-   * say({ context: 'correctness' })`Right`
-   * ```
-   *
-   * @param descriptor Object containing optional `id` and `context` properties
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  (descriptor: {
-    id?: string;
-    context?: string;
-  }): Say;
-}
-type ReadonlySay<Locale extends string = string, Loader extends Say.Loader<Locale> | undefined = Say.Loader<Locale> | undefined> = Say<Locale, Loader> & {
-  activate: never;
-  load: never;
-  assign: never;
-};
-declare class Say<Locale extends string = string, Loader extends Say.Loader<Locale> | undefined = Say.Loader<Locale> | undefined> {
-  #private;
-  constructor(options: Say.Options<Locale, Loader>);
-  /**
-   * The currently active locale.
-   *
-   * @throws If no locale is active
-   */
-  get locale(): Locale;
-  /**
-   * All available messages mapped by locale.
-   *
-   * @throws If no locale is active
-   * @throws If no messages are available for the active locale
-   */
-  get messages(): Say.Messages;
-  /**
-   * All available locales.
-   */
-  get locales(): Locale[];
-  /**
-   * Loads messages for the given locales.
-   * If no locales are provided, all available locales are loaded.
-   * Requires a {@link Say.Loader} to be provided.
-   * If `loader` returns a promise, so will this method.
-   *
-   * @param locales Locales to load messages for, defaults to {@link Say.locales}
-   * @returns This
-   */
-  load(...locales: Locale[]): this | Promise<this>;
-  /**
-   * Manually bulk assign messages.
-   *
-   * @param messages Messages map to assign
-   */
-  assign(messages: Partial<Record<Locale, Say.Messages>>): this;
-  /**
-   * Manually assign messages to a locale.
-   *
-   * @param locale Locale to assign messages to
-   * @param messages Messages to assign
-   * @returns This
-   */
-  assign(locale: Locale, messages: Say.Messages): this;
-  /**
-   * Set the active locale.
-   *
-   * @param locale Locale to set
-   * @returns This
-   * @throws If locale is not available
-   */
-  activate(locale: Locale): this;
-  /**
-   * Creates a clone of the Say instance, with the same locales and messages.
-   *
-   * @returns A clone of the Say instance
-   */
-  clone(): this;
-  /**
-   * Make this `Say` instance immutable.
-   */
-  freeze(): ReadonlySay<Locale, Loader>;
-  [Symbol.iterator](): Generator<[ReadonlySay<Locale, Loader>, Locale], void, unknown>;
-  /**
-   * Matches the best locale from a list of guesses.
-   *
-   * @param guesses List of locale guesses
-   *
-   * @returns The best matching locale, or the first locale if no matches are found
-   */
-  match(...guesses: (string | string[])[]): Locale;
-  /**
-   * Get the translation for a descriptor.
-   *
-   * @param descriptor Descriptor to get the translation for
-   * @returns The translation string for the descriptor
-   * @throws If no locale is active
-   * @throws If no messages are available for the active locale
-   * @throws If descriptor id is not found
-   */
-  call(descriptor: {
-    id: string;
-    [match: string | number]: unknown;
-  }): string;
-  /**
-   * Define a pluralised message.
-   *
-   * @example
-   * ```ts
-   * say.plural(count, {
-   *   one: 'You have 1 item',
-   *   other: `You have ${count} items`,
-   * })
-   * ```
-   *
-   * Interpolating the selector into a branch extracts as ICU's `#`, the number
-   * the message branched on. A `#` you write yourself is text.
-   * @param _ Number to determine the plural form of
-   * @param options Pluralisation rules keyed by CLDR categories or specific numbers
-   * @returns The plural form of the number
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  plural(_: number | Named<number>, options: Disallow<NumeralOptions, 'id' | 'context'>): string;
-  /**
-   * Define an ordinal message (e.g. "1st", "2nd", "3rd").
-   *
-   * Interpolating the selector into a branch extracts as ICU's `#`, the number
-   * the message branched on. A `#` you write yourself is text.
-   *
-   * @example
-   * ```ts
-   * say.ordinal(position, {
-   *   1: `${position}st`,
-   *   2: `${position}nd`,
-   *   3: `${position}rd`,
-   *   other: `${position}th`,
-   * })
-   * ```
-   *
-   * @param _ Number to determine the ordinal form of
-   * @param options Ordinal rules keyed by CLDR categories or specific numbers
-   * @returns The ordinal form of the number
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  ordinal(_: number | Named<number>, options: Disallow<NumeralOptions, 'id' | 'context'>): string;
-  /**
-   * Define a select message, useful for handling gender, status, or other categories.
-   *
-   * @example
-   * ```ts
-   * say.select(gender, {
-   *   male: 'He',
-   *   female: 'She',
-   *   other: 'They',
-   * })
-   * ```
-   *
-   * @param _ Selector value to determine which option is chosen
-   * @param options A mapping of possible selector values to message strings
-   * @returns The select form of the value
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  select(_: string | number | Named<string | number>, options: Disallow<SelectOptions, 'id' | 'context'>): string;
-  /**
-   * Format a number the way the active locale writes one, with its own grouping
-   * separators and decimal mark.
-   *
-   * Unlike `plural`, `ordinal`, and `select`, this is a fragment rather than a
-   * whole message, and is normally written inside one.
-   *
-   * @example
-   * ```ts
-   * say`You have ${say.number(items.length)} items`
-   * say`Battery at ${say.number(level, { style: 'percent' })}`
-   * say`Total: ${say.number({ cartTotal: getTotal() }, { style: '#,##0.00' })}`
-   * say`Total: ${say.number(total, { style: '::currency/EUR' })}`
-   * ```
-   *
-   * @param _ Number to format
-   * @param options Formatting style: a named style, an ICU skeleton such as
-   *   `::currency/EUR`, or a literal number pattern such as `#,##0.00`
-   * @returns The formatted number
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  number(_: number | Named<number>, options?: Disallow<NumberOptions, 'id' | 'context'>): string;
-  /**
-   * Format the date portion of a value the way the active locale writes one.
-   *
-   * @example
-   * ```ts
-   * say`Published ${say.date(post.publishedAt)}`
-   * say`Published ${say.date(post.publishedAt, { style: 'full' })}`
-   * say`Published ${say.date(post.publishedAt, { style: '::yMMMM' })}`
-   * ```
-   *
-   * @param _ Date to format
-   * @param options Formatting style, either a named style or an ICU skeleton
-   *   such as `::yyyyMMdd`
-   * @returns The formatted date
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  date(_: Date | number | Named<Date | number>, options?: Disallow<DateTimeOptions, 'id' | 'context'>): string;
-  /**
-   * Format the time portion of a value the way the active locale writes one.
-   *
-   * @example
-   * ```ts
-   * say`Doors open at ${say.time(opensAt)}`
-   * say`Doors open at ${say.time(opensAt, { style: 'short' })}`
-   * say`Doors open at ${say.time(opensAt, { style: '::Hm' })}`
-   * ```
-   *
-   * @param _ Date to format
-   * @param options Formatting style, either a named style or an ICU skeleton
-   *   such as `::Hm`
-   * @returns The formatted time
-   * @remark This is a macro and must be used with the relevant saykit plugin
-   */
-  time(_: Date | number | Named<Date | number>, options?: Disallow<DateTimeOptions, 'id' | 'context'>): string;
-}
-//#endregion
-export { Awaitable, DateTimeOptions, Disallow, Named, NumberOptions, NumeralOptions, ReadonlySay, Say, SelectOptions, Skeleton, Tuple };