saykit 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# saykit
+
+> Type-safe i18n library with compile-time macro transforms.
+
+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.
+
+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.
+
+## Install
+
+```sh
+pnpm add saykit
+```
+
+You will normally also want [`@saykit/config`](https://github.com/k0d13/saykit/tree/main/packages/config) and a build-tool plugin ([`unplugin-saykit`](https://github.com/k0d13/saykit/tree/main/packages/plugin-unplugin) or [`babel-plugin-saykit`](https://github.com/k0d13/saykit/tree/main/packages/plugin-babel)).
+
+## Usage
+
+```ts
+import { Say } from 'saykit';
+import en from './locales/en.po';
+import fr from './locales/fr.po';
+
+const say = new Say({
+  locales: ['en', 'fr'],
+  messages: { en, fr },
+});
+
+say.activate('en');
+
+say`Hello, ${name}!`;
+say.plural(count, { one: '1 item', other: '# items' });
+```
+
+## Documentation
+
+Full guide at [saykit.js.org](https://saykit.js.org).

package/dist/runtime.d.mts

@@ -0,0 +1,207 @@
+//#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>;
+interface NumeralOptions extends Omit<Partial<Record<Intl.LDMLPluralRule, string>>, 'other'> {
+  other: string;
+  [digit: number]: string;
+}
+interface SelectOptions {
+  other: string;
+  [match: string | number]: string;
+}
+//#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.
+   *
+   * @example
+   * ```ts
+   * say`Hello, ${name}!`
+   * ```
+   *
+   * @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 # items',
+   * })
+   * ```
+   *
+   * The `#` symbol inside options is replaced with the numeric value.
+   * @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, options: Disallow<NumeralOptions, 'id' | 'context'>): string;
+  /**
+   * Define an ordinal message (e.g. "1st", "2nd", "3rd").
+   * The `#` symbol inside options is replaced with the numeric value.
+   *
+   * @example
+   * ```ts
+   * say.ordinal(position, {
+   *   1: '#st',
+   *   2: '#nd',
+   *   3: '#rd',
+   *   other: '#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, 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, options: Disallow<SelectOptions, 'id' | 'context'>): string;
+}
+//#endregion
+export { Awaitable, Disallow, NumeralOptions, ReadonlySay, Say, SelectOptions, Tuple };

package/dist/runtime.mjs

@@ -0,0 +1,254 @@
+import { mf1ToMessage } from "@messageformat/icu-messageformat-1";
+//#region \0@oxc-project+runtime@0.127.0/helpers/checkPrivateRedeclaration.js
+function _checkPrivateRedeclaration(e, t) {
+	if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/classPrivateMethodInitSpec.js
+function _classPrivateMethodInitSpec(e, a) {
+	_checkPrivateRedeclaration(e, a), a.add(e);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/classPrivateFieldInitSpec.js
+function _classPrivateFieldInitSpec(e, t, a) {
+	_checkPrivateRedeclaration(e, t), t.set(e, a);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/assertClassBrand.js
+function _assertClassBrand(e, t, n) {
+	if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
+	throw new TypeError("Private element is not present on this object");
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/classPrivateFieldSet2.js
+function _classPrivateFieldSet2(s, a, r) {
+	return s.set(_assertClassBrand(s, a), r), r;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/classPrivateFieldGet2.js
+function _classPrivateFieldGet2(s, a) {
+	return s.get(_assertClassBrand(s, a));
+}
+//#endregion
+//#region src/runtime.ts
+let _Symbol$iterator, _Symbol$for;
+var _locales = /* @__PURE__ */ new WeakMap();
+var _loader = /* @__PURE__ */ new WeakMap();
+var _messages = /* @__PURE__ */ new WeakMap();
+var _formats = /* @__PURE__ */ new WeakMap();
+var _active = /* @__PURE__ */ new WeakMap();
+var _Say_brand = /* @__PURE__ */ new WeakSet();
+_Symbol$iterator = Symbol.iterator;
+_Symbol$for = Symbol.for("nodejs.util.inspect.custom");
+var Say = class Say {
+	constructor(options) {
+		_classPrivateMethodInitSpec(this, _Say_brand);
+		_classPrivateFieldInitSpec(this, _locales, void 0);
+		_classPrivateFieldInitSpec(this, _loader, void 0);
+		_classPrivateFieldInitSpec(this, _messages, void 0);
+		_classPrivateFieldInitSpec(this, _formats, void 0);
+		_classPrivateFieldInitSpec(this, _active, void 0);
+		_classPrivateFieldSet2(_locales, this, options.locales);
+		_classPrivateFieldSet2(_loader, this, options.loader);
+		_classPrivateFieldSet2(_messages, this, /* @__PURE__ */ new Map());
+		_classPrivateFieldSet2(_formats, this, /* @__PURE__ */ new Map());
+		if (options.messages) this.assign(options.messages);
+	}
+	/**
+	* The currently active locale.
+	*
+	* @throws If no locale is active
+	*/
+	get locale() {
+		if (!_classPrivateFieldGet2(_active, this)) throw new Error("No active locale");
+		return _classPrivateFieldGet2(_active, this);
+	}
+	/**
+	* All available messages mapped by locale.
+	*
+	* @throws If no locale is active
+	* @throws If no messages are available for the active locale
+	*/
+	get messages() {
+		if (!_classPrivateFieldGet2(_messages, this).has(this.locale)) throw new Error("No messages loaded for locale");
+		return _classPrivateFieldGet2(_messages, this).get(this.locale);
+	}
+	/**
+	* All available locales.
+	*/
+	get locales() {
+		return _classPrivateFieldGet2(_locales, this);
+	}
+	/**
+	* 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) {
+		if (Object.isFrozen(this)) throw new Error("Cannot load messages on a frozen Say");
+		if (locales.length === 0) locales = _classPrivateFieldGet2(_locales, this);
+		const tasks = [];
+		for (const locale of locales) {
+			if (_classPrivateFieldGet2(_messages, this).has(locale)) continue;
+			if (!_classPrivateFieldGet2(_loader, this)) throw new Error("No loader provided, cannot load messages");
+			const result = _classPrivateFieldGet2(_loader, this).call(this, 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") _classPrivateFieldGet2(_messages, this).set(localeOrMessages, maybeMessages);
+		else for (const locale in localeOrMessages) _classPrivateFieldGet2(_messages, this).set(locale, localeOrMessages[locale]);
+		return this;
+	}
+	/**
+	* Set the active locale.
+	*
+	* @param locale Locale to set
+	* @returns This
+	* @throws If locale is not available
+	*/
+	activate(locale) {
+		if (Object.isFrozen(this)) throw new Error("Cannot activate locale on a frozen Say");
+		if (!_classPrivateFieldGet2(_messages, this).has(locale)) throw new Error("No messages loaded for locale");
+		_classPrivateFieldSet2(_active, this, locale);
+		return this;
+	}
+	/**
+	* Creates a clone of the Say instance, with the same locales and messages.
+	*
+	* @returns A clone of the Say instance
+	*/
+	clone() {
+		const copy = new Say({
+			locales: _classPrivateFieldGet2(_locales, this),
+			messages: Object.fromEntries(_classPrivateFieldGet2(_messages, this)),
+			loader: _classPrivateFieldGet2(_loader, this)
+		});
+		_classPrivateFieldSet2(_active, copy, _classPrivateFieldGet2(_active, this));
+		return copy;
+	}
+	/**
+	* Make this `Say` instance immutable.
+	*/
+	freeze() {
+		return Object.freeze(this);
+	}
+	*[_Symbol$iterator]() {
+		for (const l of _classPrivateFieldGet2(_locales, this)) yield [this.clone().activate(l).freeze(), l];
+	}
+	/**
+	* 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) {
+		const flat = guesses.flat();
+		if (flat.length === 0) return _classPrivateFieldGet2(_locales, this)[0];
+		for (const guess of flat) {
+			if (_classPrivateFieldGet2(_locales, this).includes(guess)) return guess;
+			const prefix = guess.split("-")[0];
+			if (!prefix) continue;
+			const match = _classPrivateFieldGet2(_locales, this).find((l) => l.startsWith(prefix));
+			if (match) return match;
+		}
+		return _classPrivateFieldGet2(_locales, this)[0];
+	}
+	/**
+	* 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) {
+		return _assertClassBrand(_Say_brand, this, _call).call(this, this.locale, this.messages, descriptor);
+	}
+	[_Symbol$for](_depth, context, inspect) {
+		if (_classPrivateFieldGet2(_active, this)) return `${this.constructor.name}<${inspect(_classPrivateFieldGet2(_active, this), context)}> {}`;
+		else return `${this.constructor.name} {}`;
+	}
+	/**
+	* Define a pluralised message.
+	*
+	* @example
+	* ```ts
+	* say.plural(count, {
+	*   one: 'You have 1 item',
+	*   other: 'You have # items',
+	* })
+	* ```
+	*
+	* The `#` symbol inside options is replaced with the numeric value.
+	* @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(_, options) {
+		throw new Error("'Say#plural' is a macro and must be used with the relevant saykit plugin");
+	}
+	/**
+	* Define an ordinal message (e.g. "1st", "2nd", "3rd").
+	* The `#` symbol inside options is replaced with the numeric value.
+	*
+	* @example
+	* ```ts
+	* say.ordinal(position, {
+	*   1: '#st',
+	*   2: '#nd',
+	*   3: '#rd',
+	*   other: '#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(_, options) {
+		throw new Error("'Say#ordinal' is a macro and must be used with the relevant saykit plugin");
+	}
+	/**
+	* 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(_, options) {
+		throw new Error("'Say#select' is a macro and must be used with the relevant saykit plugin");
+	}
+};
+function _call(locale, messages, descriptor) {
+	const message = messages[descriptor.id];
+	if (typeof message !== "string") throw new Error(`Message for ${descriptor.id} is not a string`);
+	const key = `${locale}:${descriptor.id}`;
+	const format = _classPrivateFieldGet2(_formats, this).get(key) ?? _classPrivateFieldGet2(_formats, this).set(key, mf1ToMessage(locale, message)).get(key);
+	return String(format.format(descriptor));
+}
+//#endregion
+export { Say };

package/package.json

@@ -1,4 +1,45 @@
 {
   "name": "saykit",
-  "version": "0.0.0"
+  "version": "0.1.0",
+  "description": "Type-safe i18n library with compile-time macro transforms",
+  "keywords": [
+    "i18n",
+    "icu",
+    "internationalization",
+    "localization",
+    "macros",
+    "typescript"
+  ],
+  "homepage": "https://github.com/k0d13/saykit#readme",
+  "bugs": {
+    "url": "https://github.com/k0d13/saykit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k0d13/saykit.git",
+    "directory": "packages/integration"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/runtime.d.mts",
+      "default": "./dist/runtime.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@messageformat/icu-messageformat-1": "^0.12.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsdown"
+  }
 }