babel-plugin-saykit 0.6.0 → 0.7.0

package/dist/catalogue-B3HA3aVz.cjs

@@ -0,0 +1,63 @@
+let node_path = require("node:path");
+let node_fs = require("node:fs");
+let _saykit_config_features_catalogue = require("@saykit/config/features/catalogue");
+//#region src/catalogue.ts
+/** Normalise an absolute path into the form bucket globs are written against. */
+const toId = (path) => (0, node_path.relative)(process.cwd(), path).replaceAll("\\", "/").split("?")[0];
+/**
+* The glob a bucket's catalogues match, e.g. `src/locales/*.po` — the `output`
+* template with its placeholders filled in. Bundlers that select files by glob
+* rather than by predicate need this to target exactly the catalogues, and
+* nothing else sharing their extension.
+*/
+const catalogueGlob = (bucket) => String(bucket.output).replace("{locale}", "*").replace("{extension}", bucket.formatter.extension.slice(1)).replaceAll("\\", "/").replace(/^\.\//, "");
+/** Whether `path` is one of the config's catalogue outputs. */
+const isCatalogue = (config, path) => config.buckets.some((bucket) => bucket.output.match(toId(path)));
+/**
+* Assemble the catalogue at `path` into a `{ id: string }` record, merging in
+* the fallback chain (configured fallbacks + the source locale) so an
+* untranslated key resolves to a fallback string rather than going missing.
+*
+* Returns `undefined` when the path is not a catalogue, and otherwise reports
+* the files that fed the record alongside it — a bundler that can track them
+* gets invalidation for free when a fallback locale is edited.
+*
+* Reads are synchronous so every caller can share one implementation: Babel's
+* visitor cannot await, and the handful of files in a fallback chain are not
+* worth an async path in a bundler that is blocked on the result anyway.
+*/
+function loadCatalogue(config, path) {
+	const id = toId(path);
+	const bucket = config.buckets.find((b) => b.output.match(id));
+	if (!bucket) return;
+	const { sources } = (0, _saykit_config_features_catalogue.resolveCatalogueSources)(config, bucket, id);
+	return {
+		record: (0, _saykit_config_features_catalogue.assembleCatalogueRecord)(bucket, sources.map((source) => {
+			try {
+				return (0, node_fs.readFileSync)(source, "utf8");
+			} catch {
+				return "";
+			}
+		})),
+		sources
+	};
+}
+//#endregion
+Object.defineProperty(exports, "catalogueGlob", {
+	enumerable: true,
+	get: function() {
+		return catalogueGlob;
+	}
+});
+Object.defineProperty(exports, "isCatalogue", {
+	enumerable: true,
+	get: function() {
+		return isCatalogue;
+	}
+});
+Object.defineProperty(exports, "loadCatalogue", {
+	enumerable: true,
+	get: function() {
+		return loadCatalogue;
+	}
+});

package/dist/index.cjs

@@ -1,44 +1,29 @@
-let node_fs = require("node:fs");
+const require_catalogue = require("./catalogue-B3HA3aVz.cjs");
 let node_path = require("node:path");
 let _babel_core = require("@babel/core");
-let _saykit_config_features_catalogue = require("@saykit/config/features/catalogue");
 let _saykit_config_features_loader = require("@saykit/config/features/loader");
 //#region src/index.ts
-var src_default = (api) => {
+var src_default = (_, { catalogues = "inline" } = {}) => {
 	const config = (0, _saykit_config_features_loader.resolveConfig)();
 	return {
 		name: "saykit",
-		parserOverride(code, opts, parse) {
-			const id_ = opts.sourceFileName;
-			if (!id_ || id_.includes("node_modules")) return parse(code, opts);
-			const id = (0, node_path.relative)(process.cwd(), id_).replaceAll("\\", "/").split("?")[0];
-			return parse(config.buckets.find((b) => b.match(id))?.transformer.transform(code, id) ?? code, opts);
-		},
-		visitor: { ImportDeclaration(path, state) {
+		visitor: catalogues === "module" ? {} : { ImportDeclaration(path, state) {
 			const importee = path.node.source.value;
 			if (!importee.startsWith(".")) return;
 			const importer = state.filename ?? state.file.opts.filename;
 			if (!importer) return;
-			const id_ = (0, node_path.resolve)((0, node_path.dirname)(importer), importee);
+			const catalogue = require_catalogue.loadCatalogue(config, (0, node_path.resolve)((0, node_path.dirname)(importer), importee));
+			if (!catalogue) return;
+			const [specifier, ...rest] = path.node.specifiers;
+			if (specifier?.type !== "ImportDefaultSpecifier" || rest.length > 0) throw path.buildCodeFrameError("SayKit inline imports require a single default import");
+			path.replaceWith(_babel_core.types.variableDeclaration("const", [_babel_core.types.variableDeclarator(_babel_core.types.identifier(specifier.local.name), _babel_core.types.objectExpression(Object.entries(catalogue.record).map(([key, value]) => _babel_core.types.objectProperty(_babel_core.types.stringLiteral(key), _babel_core.types.stringLiteral(value)))))]));
+		} },
+		parserOverride(code, opts, parse) {
+			const id_ = opts.sourceFileName;
+			if (!id_ || id_.includes("node_modules")) return parse(code, opts);
 			const id = (0, node_path.relative)(process.cwd(), id_).replaceAll("\\", "/").split("?")[0];
-			const bucket = config.buckets.find((b) => b.output.match(id));
-			if (!bucket) return;
-			const specifier = path.node.specifiers.find((s) => s.type === "ImportDefaultSpecifier");
-			if (!specifier) throw path.buildCodeFrameError("SayKit inline imports require a default import");
-			const { sources } = (0, _saykit_config_features_catalogue.resolveCatalogueSources)(config, bucket, id);
-			const contents = sources.map((source) => {
-				try {
-					return (0, node_fs.readFileSync)(source, "utf8");
-				} catch {
-					return "";
-				}
-			});
-			for (const source of sources) try {
-				api.addExternalDependency(source);
-			} catch {}
-			const entries = Object.entries((0, _saykit_config_features_catalogue.assembleCatalogueRecord)(bucket, contents));
-			path.replaceWith(_babel_core.types.variableDeclaration("const", [_babel_core.types.variableDeclarator(_babel_core.types.identifier(specifier.local.name), _babel_core.types.objectExpression(entries.map(([key, value]) => _babel_core.types.objectProperty(_babel_core.types.stringLiteral(key), _babel_core.types.stringLiteral(value)))))]));
-		} }
+			return parse(config.buckets.find((b) => b.match(id))?.transformer.transform(code, id) ?? code, opts);
+		}
 	};
 };
 //#endregion

package/dist/index.d.cts

@@ -1,12 +1,26 @@
-import { PluginAPI, PluginObj, parse } from "@babel/core";
+import { PluginObj, parse } from "@babel/core";
 //#region src/index.d.ts
 declare module '@babel/core' {
-  interface PluginAPI {
-    addExternalDependency(ref: string): void;
-  }
   interface PluginObj {
     parserOverride(code: string, opts: TransformOptions, parse: typeof parse): ParseResult | null;
   }
 }
-declare const _default: (api: PluginAPI) => PluginObj;
-export = _default;
+interface Options {
+  /**
+   * How a catalogue import is resolved.
+   *
+   * `'inline'` (the default) replaces the import with the assembled record, so
+   * the Babel plugin is enough on its own. The cost is that the record lands in
+   * the importing module, which a bundler only re-reads when that module's own
+   * bytes change — editing a catalogue will not hot-reload.
+   *
+   * `'module'` leaves the import for a bundler integration to serve —
+   * `babel-plugin-saykit/next` or `babel-plugin-saykit/metro`. Set this
+   * whenever one of those is wired up, or the import gets inlined before the
+   * integration is ever asked for the module.
+   */
+  catalogues?: 'inline' | 'module';
+}
+declare const _default: (_: unknown, { catalogues }?: Options) => PluginObj;
+//#endregion
+export { Options, _default as default };

package/dist/metro/index.cjs

@@ -0,0 +1,57 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_path = require("node:path");
+let _saykit_config_features_loader = require("@saykit/config/features/loader");
+let node_module = require("node:module");
+//#region src/metro/index.ts
+/**
+* Resolve Metro's own transformer from the project rather than from this
+* package, since it is the project that depends on Metro.
+*
+* The base is the config's `projectRoot` — `process.cwd()` is wrong whenever
+* Metro is started from elsewhere, which in a monorepo is the normal case.
+*/
+const transformerPath = (0, node_path.join)(__dirname, "transformer.cjs");
+function resolveUpstream(specifier, projectRoot) {
+	if ((0, node_path.isAbsolute)(specifier)) return specifier;
+	try {
+		return (0, node_module.createRequire)((0, node_path.join)(projectRoot, "metro.config.js")).resolve(specifier);
+	} catch {
+		return require.resolve(specifier);
+	}
+}
+/**
+* Wrap a Metro config so SayKit catalogues load as real modules.
+*
+* ```js
+* const { withSayKit } = require('babel-plugin-saykit/metro');
+* module.exports = withSayKit(getDefaultConfig(__dirname));
+* ```
+*
+* Metro's transform cache is keyed on each file's own bytes, so a catalogue has
+* to stay a module of its own to be invalidated at all — see
+* `./transformer.ts`.
+*
+* Apply this outermost. Anything wrapped around it that also sets
+* `transformerPath` replaces this one, and catalogues stop being assembled.
+*/
+function withSayKit(metroConfig) {
+	if (metroConfig.transformerPath === transformerPath) return metroConfig;
+	const extensions = (0, _saykit_config_features_loader.resolveConfig)().buckets.map((bucket) => bucket.formatter.extension.slice(1)).filter((extension) => extension !== "json");
+	const sourceExts = [...metroConfig.resolver?.sourceExts ?? []];
+	for (const extension of extensions) if (!sourceExts.includes(extension)) sourceExts.push(extension);
+	const upstream = metroConfig.transformerPath ?? "metro-transform-worker";
+	return {
+		...metroConfig,
+		resolver: {
+			...metroConfig.resolver,
+			sourceExts
+		},
+		transformerPath,
+		transformer: {
+			...metroConfig.transformer,
+			saykitTransformerPath: resolveUpstream(upstream, metroConfig.projectRoot ?? process.cwd())
+		}
+	};
+}
+//#endregion
+exports.withSayKit = withSayKit;

package/dist/metro/index.d.cts

@@ -0,0 +1,27 @@
+//#region src/metro/index.d.ts
+interface MetroConfig {
+  projectRoot?: string;
+  resolver?: {
+    sourceExts?: string[];
+  };
+  transformer?: Record<string, unknown>;
+  transformerPath?: string;
+}
+/**
+ * Wrap a Metro config so SayKit catalogues load as real modules.
+ *
+ * ```js
+ * const { withSayKit } = require('babel-plugin-saykit/metro');
+ * module.exports = withSayKit(getDefaultConfig(__dirname));
+ * ```
+ *
+ * Metro's transform cache is keyed on each file's own bytes, so a catalogue has
+ * to stay a module of its own to be invalidated at all — see
+ * `./transformer.ts`.
+ *
+ * Apply this outermost. Anything wrapped around it that also sets
+ * `transformerPath` replaces this one, and catalogues stop being assembled.
+ */
+declare function withSayKit<T extends MetroConfig>(metroConfig: T): T;
+//#endregion
+export { withSayKit };

package/dist/metro/transformer.cjs

@@ -0,0 +1,38 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_catalogue = require("../catalogue-B3HA3aVz.cjs");
+let node_path = require("node:path");
+let _saykit_config_features_loader = require("@saykit/config/features/loader");
+let node_fs = require("node:fs");
+let node_crypto = require("node:crypto");
+//#region src/metro/transformer.ts
+const config = (0, _saykit_config_features_loader.resolveConfig)();
+const upstream = (transformerConfig) => require(transformerConfig.saykitTransformerPath);
+/**
+* What a catalogue transforms into depends on the SayKit config — the fallback
+* chain it resolves, the formatter that parses it — and on the version of this
+* package doing the assembling. Neither is a byte of the file Metro hashes, so
+* without them in the cache key, editing `saykit.config.*` or upgrading leaves
+* every catalogue serving the record it was cached with.
+*/
+const salt = (0, node_crypto.createHash)("sha1").update((0, node_fs.readFileSync)((0, node_path.join)(__dirname, "..", "..", "package.json"), "utf8")).update((0, node_fs.readFileSync)((0, _saykit_config_features_loader.resolveConfigFile)(), "utf8")).digest("hex");
+/**
+* Metro reads `.json` straight through `transformJSON` and never runs Babel over
+* it, so a Babel plugin cannot reach a catalogue at all. Wrapping the transform
+* worker is the one place that can: it substitutes the assembled record for the
+* catalogue's own source, leaving the file a real module whose sha1 — and
+* therefore Metro's transform cache entry — moves whenever it is edited.
+*/
+function transform(transformerConfig, projectRoot, filename, data, options) {
+	const worker = upstream(transformerConfig);
+	const catalogue = require_catalogue.loadCatalogue(config, filename);
+	if (!catalogue) return worker.transform(transformerConfig, projectRoot, filename, data, options);
+	const record = JSON.stringify(catalogue.record);
+	const code = filename.endsWith(".json") ? record : `module.exports = ${record};`;
+	return worker.transform(transformerConfig, projectRoot, filename, Buffer.from(code), options);
+}
+function getCacheKey(transformerConfig, options) {
+	return `${upstream(transformerConfig).getCacheKey(transformerConfig, options)}-saykit-${salt}`;
+}
+//#endregion
+exports.getCacheKey = getCacheKey;
+exports.transform = transform;

package/dist/metro/transformer.d.cts

@@ -0,0 +1,20 @@
+//#region src/metro/transformer.d.ts
+/**
+ * The transformer config Metro hands each worker call. `saykitTransformerPath`
+ * is the upstream worker this one wraps, stashed here by {@link withSayKit}
+ * because a worker is loaded standalone and has no other way to reach it.
+ */
+interface TransformerConfig {
+  saykitTransformerPath: string;
+}
+/**
+ * Metro reads `.json` straight through `transformJSON` and never runs Babel over
+ * it, so a Babel plugin cannot reach a catalogue at all. Wrapping the transform
+ * worker is the one place that can: it substitutes the assembled record for the
+ * catalogue's own source, leaving the file a real module whose sha1 — and
+ * therefore Metro's transform cache entry — moves whenever it is edited.
+ */
+declare function transform(transformerConfig: TransformerConfig, projectRoot: string, filename: string, data: Buffer, options: unknown): Promise<unknown>;
+declare function getCacheKey(transformerConfig: TransformerConfig, options?: unknown): string;
+//#endregion
+export { getCacheKey, transform };

package/dist/next/index.cjs

@@ -0,0 +1,51 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_catalogue = require("../catalogue-B3HA3aVz.cjs");
+let _saykit_config_features_loader = require("@saykit/config/features/loader");
+//#region src/next/index.ts
+const loader = "babel-plugin-saykit/next/loader";
+/**
+* Wrap a Next config so SayKit catalogues load as real modules.
+*
+* ```js
+* import { withSayKit } from 'babel-plugin-saykit/next';
+* export default withSayKit({});
+* ```
+*
+* Pair it with `catalogues: 'module'` on the Babel plugin — the plugin has to
+* leave the import alone for the loader to ever be asked for the module.
+*
+* Rules are derived from the SayKit config, so both bundlers get one per bucket
+* targeting exactly that bucket's `output` — nothing else sharing the extension
+* goes through the loader, which matters most for a `.json` bucket, where the
+* alternative would be routing every JSON import in the app through it.
+*/
+function withSayKit(nextConfig = {}) {
+	const config = (0, _saykit_config_features_loader.resolveConfig)();
+	const rules = Object.fromEntries(config.buckets.map((bucket) => [`**/${require_catalogue.catalogueGlob(bucket)}`, {
+		loaders: [loader],
+		as: "*.js"
+	}]));
+	return {
+		...nextConfig,
+		turbopack: {
+			...nextConfig.turbopack,
+			rules: {
+				...nextConfig.turbopack?.rules,
+				...rules
+			}
+		},
+		webpack: (webpackConfig, context) => {
+			const result = nextConfig.webpack?.(webpackConfig, context) ?? webpackConfig;
+			result.module ??= {};
+			result.module.rules ??= [];
+			result.module.rules.push({
+				test: (path) => require_catalogue.isCatalogue(config, path),
+				use: loader,
+				type: "javascript/auto"
+			});
+			return result;
+		}
+	};
+}
+//#endregion
+exports.withSayKit = withSayKit;

package/dist/next/index.d.cts

@@ -0,0 +1,38 @@
+//#region src/next/index.d.ts
+/**
+ * The slice of Next's config this touches. Typed here rather than imported so
+ * the package does not depend on `next`.
+ */
+interface NextConfig {
+  turbopack?: {
+    rules?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  webpack?: (config: WebpackConfig, context: unknown) => WebpackConfig;
+  [key: string]: unknown;
+}
+interface WebpackConfig {
+  module?: {
+    rules?: unknown[];
+  };
+  [key: string]: unknown;
+}
+/**
+ * Wrap a Next config so SayKit catalogues load as real modules.
+ *
+ * ```js
+ * import { withSayKit } from 'babel-plugin-saykit/next';
+ * export default withSayKit({});
+ * ```
+ *
+ * Pair it with `catalogues: 'module'` on the Babel plugin — the plugin has to
+ * leave the import alone for the loader to ever be asked for the module.
+ *
+ * Rules are derived from the SayKit config, so both bundlers get one per bucket
+ * targeting exactly that bucket's `output` — nothing else sharing the extension
+ * goes through the loader, which matters most for a `.json` bucket, where the
+ * alternative would be routing every JSON import in the app through it.
+ */
+declare function withSayKit<T extends NextConfig>(nextConfig?: T): T & Required<Pick<NextConfig, 'turbopack' | 'webpack'>>;
+//#endregion
+export { withSayKit };

package/dist/next/loader.cjs

@@ -0,0 +1,25 @@
+const require_catalogue = require("../catalogue-B3HA3aVz.cjs");
+//#region src/next/loader.ts
+const config = (0, require("@saykit/config/features/loader").resolveConfig)();
+/**
+* Replaces a catalogue file with its assembled record.
+*
+* This is a *loader* rather than a plugin because Turbopack runs loaders and
+* not webpack plugins, and it is published only so `withSayKit` can name it in
+* the rules it generates. A plain webpack, Vite or Rollup build should reach for
+* `unplugin-saykit` instead, which does the same job through each bundler's own
+* plugin API.
+*
+* The catalogue stays a real module, which is the whole point: the importer
+* keeps a dependency edge to it, so editing a catalogue invalidates exactly the
+* modules that read it. Inlining the record into the importer instead leaves the
+* importer's own bytes unchanged, and no bundler can invalidate on that.
+*/
+function saykitLoader(source) {
+	const catalogue = require_catalogue.loadCatalogue(config, this.resourcePath);
+	if (!catalogue) return source;
+	for (const file of catalogue.sources) this.addDependency(file);
+	return `export default ${JSON.stringify(catalogue.record)}`;
+}
+//#endregion
+module.exports = saykitLoader;

package/dist/next/loader.d.cts

@@ -0,0 +1,26 @@
+//#region src/next/loader.d.ts
+/**
+ * The slice of webpack's loader context this needs. Typing it here rather than
+ * depending on `webpack` keeps the package free of a bundler dependency, and
+ * Turbopack implements the same surface for the loaders it runs.
+ */
+interface LoaderContext {
+  resourcePath: string;
+  addDependency(file: string): void;
+}
+/**
+ * Replaces a catalogue file with its assembled record.
+ *
+ * This is a *loader* rather than a plugin because Turbopack runs loaders and
+ * not webpack plugins, and it is published only so `withSayKit` can name it in
+ * the rules it generates. A plain webpack, Vite or Rollup build should reach for
+ * `unplugin-saykit` instead, which does the same job through each bundler's own
+ * plugin API.
+ *
+ * The catalogue stays a real module, which is the whole point: the importer
+ * keeps a dependency edge to it, so editing a catalogue invalidates exactly the
+ * modules that read it. Inlining the record into the importer instead leaves the
+ * importer's own bytes unchanged, and no bundler can invalidate on that.
+ */
+declare function saykitLoader(this: LoaderContext, source: string): string;
+export = saykitLoader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babel-plugin-saykit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Babel plugin for SayKit",
   "keywords": [
     "i18n",
@@ -27,8 +27,20 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.cjs",
+      "types": "./dist/index.d.cts",
       "default": "./dist/index.cjs"
+    },
+    "./metro": {
+      "types": "./dist/metro/index.d.cts",
+      "default": "./dist/metro/index.cjs"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.cts",
+      "default": "./dist/next/index.cjs"
+    },
+    "./next/loader": {
+      "types": "./dist/next/loader.d.cts",
+      "default": "./dist/next/loader.cjs"
     }
   },
   "publishConfig": {
@@ -37,7 +49,7 @@
   },
   "dependencies": {
     "@babel/core": "^7.29.7",
-    "@saykit/config": "^0.6.0"
+    "@saykit/config": "^0.7.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5"