@stealthscale/tool-fixtures 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @stealthscale/tool-fixtures
+
+A **kit**: another repository takes it at development time.
+
+A fixture builds the sample values a specification or a story shows. It answers the same
+value on every run, so a snapshot, a visual diff and a failing assertion each mean what they
+say.
+
+```ts
+import { fixture, many } from '@stealthscale/tool-fixtures'
+
+const person = fixture<Person>((source) => ({
+  email: source.internet.email(),
+  name: source.person.fullName(),
+  role: 'Reviewer',
+}))
+
+person() // the same person, every run
+person({ name: 'Noor Haddad' }) // the case states what it is about; the rest is filled in
+person(undefined, { locale: 'nl-BE' }) // a Flemish name, address and telephone number
+many(person, 3) // three different people, the same three every run
+```
+
+## Determinism
+
+A fixture is seeded by its position in a series, not by the order it was called in. `person()`
+is position 0 and answers the same values whatever else ran first, so two specifications
+cannot disturb each other and a case can be read on its own.
+
+Each position gets its own source rather than one shared source that is re-seeded. A fixture
+that builds another fixture would otherwise re-seed the source its caller is part-way
+through, and the outer value would change according to what it happened to contain.
+
+## Locales
+
+A locale is named as a BCP-47 tag, the same vocabulary the rest of the workspace uses, and
+the nearest locale the sample data ships answers it. `nl-NL` reaches `nl`, `zh-Hans` reaches
+`zh-CN`, and a tag nothing answers falls back to `en` rather than throwing, because a fixture
+that refuses to build fails a specification about something else.
+
+`LOCALES` lists every locale the sample data ships, as canonical tags, so a story that renders
+in each of them reads the list rather than restating it. A layout that survives `Noor Haddad`
+may still break on a German compound or an Arabic right-to-left label, and this is how a story
+shows that before a customer does.
+
+## What belongs here, and what does not
+
+This package holds the machinery. The values themselves belong to whichever repository owns
+the domain, because a fixture is only worth having if it reads as something a person could
+plausibly see in the product. `Lorem ipsum` and `Button` tell a reviewer nothing about
+whether a layout survives a real label.
+
+## Install
+
+```sh
+bun add -d @stealthscale/tool-fixtures
+```

package/dist/index.d.mts

@@ -0,0 +1,102 @@
+import { Faker, LocaleDefinition } from "@faker-js/faker";
+//#region src/fixtures.d.ts
+/**
+ * Seeds every fixture.
+ *
+ * The number is arbitrary and fixed. What matters is that it never changes, because changing
+ * it rewrites every value every fixture in every repository has ever produced.
+ */
+declare const SEED = 20260908;
+/**
+ * Says which value of a series to build, and which locale to draw it from.
+ */
+interface At {
+  /**
+   * The position in the series, counting from zero. Two positions differ, and the same
+   * position answers the same values on every run. Default: 0.
+   */
+  index?: number;
+  /**
+   * The locale to draw from, as a BCP-47 tag. The nearest locale the sample data ships
+   * answers it. Default: `en`.
+   */
+  locale?: string;
+}
+/**
+ * Builds one value of a series.
+ *
+ * @template Value - What the fixture produces.
+ * @param {Faker} source - Sample data, seeded for this position and drawn from the locale
+ *     that was asked for.
+ * @param {number} index - The position in the series, counting from zero.
+ * @returns {Value} The value, before a caller's overrides go on top of it.
+ */
+type Build<Value> = (source: Faker, index: number) => Value;
+/**
+ * Makes one value of a fixture.
+ *
+ * @template Value - What the fixture produces.
+ * @param {Partial<Value>} [overrides] - The fields this caller states itself, which win over
+ *     what the fixture built. Default: none.
+ * @param {At} [at] - Which value of the series to build, and which locale to draw it from.
+ *     Default: the first, in `en`.
+ * @returns {Value} The value.
+ */
+type Maker<Value> = (overrides?: Partial<Value>, at?: At) => Value;
+/**
+ * Declares a fixture from the function that builds one value out of a seeded source and its
+ * position.
+ *
+ * @template Value - What the fixture produces.
+ * @param {Build<Value>} build - Builds one value.
+ * @returns {Maker<Value>} The maker, which takes overrides, a position and a locale.
+ */
+declare function fixture<Value extends object>(build: Build<Value>): Maker<Value>;
+/**
+ * Makes a series of values, each from its own position, so they differ from one another and
+ * every run produces the same series.
+ *
+ * @template Value - What the fixture produces.
+ * @param {Maker<Value>} make - The fixture to draw from.
+ * @param {number} count - How many to make.
+ * @param {Partial<Value>} [overrides] - The fields every value in the series carries.
+ *     Default: none.
+ * @param {string} [locale] - The locale to draw them from, as a BCP-47 tag. Default: `en`.
+ * @returns {Value[]} The values, in order.
+ */
+declare function many<Value extends object>(make: Maker<Value>, count: number, overrides?: Partial<Value>, locale?: string): Value[];
+//#endregion
+//#region src/locales.d.ts
+/**
+ * Names the locale a caller gets without asking for one.
+ */
+declare const DEFAULT_LOCALE = "en";
+/**
+ * Lists every locale the sample data ships, as BCP-47 tags, sorted.
+ *
+ * A story that renders in each of them reads this rather than restating the list.
+ */
+declare const LOCALES: readonly string[];
+/**
+ * Finds the locale the sample data ships that is nearest the one asked for.
+ *
+ * The match is ECMA-402's lookup, so `nl-NL` reaches `nl` and `zh-Hans` reaches `zh-CN`. A
+ * tag nothing answers falls back to {@link DEFAULT_LOCALE} rather than throwing, because a
+ * fixture that refuses to build fails a specification about something else.
+ *
+ * @param {string} tag - The locale asked for, as a BCP-47 tag.
+ * @returns {string} The nearest locale the sample data ships.
+ */
+declare function nearestLocale(tag: string): string;
+/**
+ * Collects the definitions a locale is drawn from, nearest first.
+ *
+ * English and the language-independent base sit under every locale, so a field the locale
+ * does not define is filled in rather than throwing.
+ *
+ * @param {string} tag - The locale asked for, as a BCP-47 tag.
+ * @returns {LocaleDefinition[]} The definitions, the nearest match first.
+ */
+declare function definitionsFor(tag: string): LocaleDefinition[];
+//#endregion
+export { type At, type Build, DEFAULT_LOCALE, LOCALES, type Maker, SEED, definitionsFor, fixture, many, nearestLocale };

package/dist/index.mjs

@@ -0,0 +1,153 @@
+import { Faker, allLocales, base, en } from "@faker-js/faker";
+import { canonical, negotiate } from "@stealthscale/core-locale";
+//#region src/locales.ts
+/**
+* @fileoverview Picks the sample data a locale is drawn from. A caller names a BCP-47 tag,
+* the same vocabulary the rest of the workspace uses, and gets the nearest locale the sample
+* data actually ships.
+*/
+/**
+* Names the locale a caller gets without asking for one.
+*/
+const DEFAULT_LOCALE = "en";
+/**
+* Maps the keys faker spells in its own way to the tag each stands for. Faker writes a script
+* as a trailing word, `sr_RS_latin`, and a Kurdish variety as a subtag of `ku`; the tag is
+* the ISO code with the script where BCP-47 puts it, so a request for the script reaches it.
+* Kurmanji is `ku` here rather than `kmr`, because CLDR aliases the one to the other and
+* Node's ICU applies the alias where Bun's does not.
+*/
+const RESPELLED = {
+	ku_ckb: "ckb",
+	ku_kmr_latin: "ku-Latn",
+	mn_MN_cyrl: "mn-Cyrl-MN",
+	sr_RS_latin: "sr-Latn-RS",
+	uz_UZ_latin: "uz-Latn-UZ"
+};
+/**
+* Lists the keys nothing should ask for: the language-independent base every locale sits on,
+* and faker's two joke locales.
+*/
+const DROPPED = /* @__PURE__ */ new Set([
+	"base",
+	"en_AU_ocker",
+	"en_BORK"
+]);
+/**
+* Reads the tag a faker key stands for.
+*
+* @param {string} key - The key as faker names it: `nl_BE`.
+* @returns {string | undefined} The canonical tag, or `undefined` for a key nothing should
+*     ask for.
+*/
+function tagOf(key) {
+	if (DROPPED.has(key)) return void 0;
+	return canonical(RESPELLED[key] ?? key.replaceAll("_", "-"));
+}
+/**
+* Maps each locale the sample data ships to its definitions, keyed by canonical tag.
+*/
+const SHIPPED = new Map(Object.entries(allLocales).map(([key, definition]) => [tagOf(key), definition]).filter((entry) => entry[0] !== void 0));
+/**
+* Lists every locale the sample data ships, as BCP-47 tags, sorted.
+*
+* A story that renders in each of them reads this rather than restating the list.
+*/
+const LOCALES = [...SHIPPED.keys()].toSorted();
+/**
+* Finds the locale the sample data ships that is nearest the one asked for.
+*
+* The match is ECMA-402's lookup, so `nl-NL` reaches `nl` and `zh-Hans` reaches `zh-CN`. A
+* tag nothing answers falls back to {@link DEFAULT_LOCALE} rather than throwing, because a
+* fixture that refuses to build fails a specification about something else.
+*
+* @param {string} tag - The locale asked for, as a BCP-47 tag.
+* @returns {string} The nearest locale the sample data ships.
+*/
+function nearestLocale(tag) {
+	return negotiate([tag], LOCALES, "en");
+}
+/**
+* Collects the definitions a locale is drawn from, nearest first.
+*
+* English and the language-independent base sit under every locale, so a field the locale
+* does not define is filled in rather than throwing.
+*
+* @param {string} tag - The locale asked for, as a BCP-47 tag.
+* @returns {LocaleDefinition[]} The definitions, the nearest match first.
+*/
+function definitionsFor(tag) {
+	const nearest = SHIPPED.get(nearestLocale(tag));
+	return nearest === void 0 || nearest === en ? [en, base] : [
+		nearest,
+		en,
+		base
+	];
+}
+//#endregion
+//#region src/fixtures.ts
+/**
+* @fileoverview Builds the sample values a specification or a story shows. A fixture answers
+* the same value on every run, so a snapshot, a visual diff and a failing assertion each
+* mean what they say rather than reporting the weather.
+*/
+/**
+* Seeds every fixture.
+*
+* The number is arbitrary and fixed. What matters is that it never changes, because changing
+* it rewrites every value every fixture in every repository has ever produced.
+*/
+const SEED = 20260908;
+/**
+* Seeds a source for one position, drawn from one locale.
+*
+* The instance is fresh rather than shared and re-seeded. A fixture that builds another
+* fixture would otherwise re-seed the source its caller is part-way through, and the outer
+* value would change according to what it happened to contain.
+*
+* @param {number} index - The position in the series.
+* @param {string} locale - The locale to draw from, as a BCP-47 tag.
+* @returns {Faker} The source, seeded.
+*/
+function sourceFor(index, locale) {
+	const source = new Faker({ locale: definitionsFor(locale) });
+	source.seed(SEED + index);
+	return source;
+}
+/**
+* Declares a fixture from the function that builds one value out of a seeded source and its
+* position.
+*
+* @template Value - What the fixture produces.
+* @param {Build<Value>} build - Builds one value.
+* @returns {Maker<Value>} The maker, which takes overrides, a position and a locale.
+*/
+function fixture(build) {
+	return (overrides = {}, at = {}) => {
+		const index = at.index ?? 0;
+		return {
+			...build(sourceFor(index, at.locale ?? "en"), index),
+			...overrides
+		};
+	};
+}
+/**
+* Makes a series of values, each from its own position, so they differ from one another and
+* every run produces the same series.
+*
+* @template Value - What the fixture produces.
+* @param {Maker<Value>} make - The fixture to draw from.
+* @param {number} count - How many to make.
+* @param {Partial<Value>} [overrides] - The fields every value in the series carries.
+*     Default: none.
+* @param {string} [locale] - The locale to draw them from, as a BCP-47 tag. Default: `en`.
+* @returns {Value[]} The values, in order.
+*/
+function many(make, count, overrides = {}, locale = "en") {
+	return Array.from({ length: count }, (_, index) => make(overrides, {
+		index,
+		locale
+	}));
+}
+//#endregion
+export { DEFAULT_LOCALE, LOCALES, SEED, definitionsFor, fixture, many, nearestLocale };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@stealthscale/tool-fixtures",
+  "version": "0.1.0",
+  "description": "Builds the sample values a specification or a story shows, the same on every run, drawn from any locale.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/tooling.git",
+    "directory": "tools/fixtures"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "tooling-source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack src/index.ts"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^10.6.0",
+    "@stealthscale/core-locale": "^0.1.0"
+  },
+  "devDependencies": {
+    "@stealthscale/tool-config": "^0.1.0"
+  }
+}