@jk2908/cxx 0.2.6 → 0.3.3

package/src/build.ts

@@ -3,23 +3,35 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 
 import { transform } from 'lightningcss'
+import MagicString, { type SourceMap } from 'magic-string'
 
-import type { BuildContext, PluginConfig, Tags } from './types.js'
+import type { PluginConfig, Tags } from './types.js'
 import { AUTOGEN_MSG, GENERATED_DIR, PKG_NAME } from './config.js'
 import { LruCache } from './lru.js'
 import { pascalise } from './utils.js'
 
+// decode bytes to a string, then stringify into a safe literal. `${bytes}` only
+// works by accident for Buffer; a plain Uint8Array stringifies as `97,123,125`
+const decoder = new TextDecoder()
+const encoder = new TextEncoder()
+
 /**
- * LRU cache of `collect` results by file id and last seen source so watcher and transform can
- * reuse the same parsed template/tags.
+ * LRU cache of `collect` results by file id + last seen source + config so watcher and transform
+ * can reuse the same parsed template/tags.
  */
-const collectCache = new LruCache<{ source: string; template: string; tags: Tags }>()
+const collectCache = new LruCache<{
+	source: string
+	config: string
+	template: string
+	tags: Tags
+	map: SourceMap | null
+}>()
 
 /**
- * LRU cache for file content. Stores the last written content per file path so `maybeWrite`
- * can skip disk i/o when nothing has changed.
+ * Serialises type file writes inside a single process so overlapping writes can't interleave or
+ * land out of order.
  */
-const fileCache = new LruCache<string>()
+let writeChain: Promise<void> = Promise.resolve()
 
 /**
  * Returns whether the error was caused by a missing file or directory.
@@ -29,40 +41,63 @@ export function isENOENT(err: unknown) {
 }
 
 /**
- * Write a file only if the content has changed since the last build.
+ * Write a file by writing to a unique temporary file and renaming it into place, so concurrent
+ * writers never observe a partial file. The temp file is cleaned up if the rename fails.
  */
-export async function maybeWrite(filePath: string, content: string) {
-	const cached = fileCache.get(filePath)
+async function writeFileAtomic(filePath: string, content: string) {
+	const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
 
-	if (cached !== content) {
-		// cache says content changed, write without reading
-		await fs.writeFile(filePath, content)
-		fileCache.set(filePath, content)
+	await fs.writeFile(tmp, content)
 
-		return true
+	try {
+		await fs.rename(tmp, filePath)
+	} catch (err) {
+		await fs.rm(tmp, { force: true })
+		throw err
 	}
+}
 
-	// cache miss or cache hit with same content — verify on disk
+/**
+ * Run a write task after all previously queued writes have settled. A rejection doesn't break the
+ * chain for later tasks.
+ */
+function enqueueWrite<T>(task: () => Promise<T>) {
+	// wait for the previous write to finish, then run this one, even if the previous one failed
+	const run = writeChain.then(task, task)
+
+	// move the queue on to this write, but turn either outcome into success so it never rejects
+	writeChain = run.then(
+		() => undefined,
+		() => undefined,
+	)
+
+	// return the real promise, so the caller still sees this write's value or error
+	return run
+}
+
+/**
+ * Write a file only if the content differs from what is already on disk, so watchers are not woken
+ * by a needless mtime change.
+ */
+export async function maybeWrite(filePath: string, content: string) {
 	try {
-		if ((await fs.readFile(filePath, 'utf-8')) === content) {
-			fileCache.set(filePath, content)
-			return false
-		}
+		if ((await fs.readFile(filePath, 'utf-8')) === content) return false
 	} catch (err) {
 		if (!isENOENT(err)) throw err
 	}
 
-	await fs.writeFile(filePath, content)
-	fileCache.set(filePath, content)
+	await writeFileAtomic(filePath, content)
 
 	return true
 }
 
 // matches `[css, classes, href] = cxx\`...\`` and `cxx.tag<T>('name')\`...\``
-// capture groups: 1-3 assigned variable names, 4 plain css body, 5 quote
-// kind, 6 tag name, 7 tagged css body
+// capture groups: 1 optional `export `, 2-4 assigned variable names, 5 plain
+// css body, 6 quote kind, 7 tag name, 8 tagged css body
 const regex =
-	/(?:const|var|let)\s*\[(\w+|)\s*,?\s*(\w+|)\s*,?\s*(\w+|)\s*\]\s*=\s*cxx(?:\s*`([\s\S]*?)`|\s*\.\s*tag(?:\s*<[^>]+>)?\s*\(\s*(['"])(.*?)\5\s*\)\s*`([\s\S]*?)`)/gm
+	/((?:export\s+)?)(?:const|var|let)\s*\[(\w*)\s*,?\s*(\w*)\s*,?\s*(\w*)\s*\]\s*=\s*cxx(?:\s*`([\s\S]*?)`|\s*\.\s*tag(?:\s*<[^>]+>)?\s*\(\s*(['"])(.*?)\6\s*\)\s*`([\s\S]*?)`)/gm
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
 /**
  * Hash transformed CSS into a stable href for style deduplication.
@@ -79,126 +114,208 @@ export class DuplicateTagError extends Error {
 	}
 }
 
+export class InvalidTagError extends Error {
+	name = 'InvalidTagError'
+
+	constructor(tag: string) {
+		super(
+			`Tag "${tag}" does not map to a valid TypeScript identifier. ` +
+				`Use letters, numbers, spaces, "_" or "-"`,
+		)
+	}
+}
+
 /**
  * Transform `cxx` templates in one source file and collect any exported tag types.
  */
 export function collect(source: string, id: string, config: PluginConfig) {
-	const tags: Tags = new Map()
+	const configKey = JSON.stringify(config)
 
+	// reuse the last result when the source and config are unchanged
 	const cached = collectCache.get(id)
-	if (cached?.source === source) return cached
-
-	const template = source.replace(
-		regex,
-		(_match, varOne, varTwo, varThree, plainCss, _quote, tag, taggedCss) => {
-			const css = plainCss ?? taggedCss
-
-			const { code, exports = {} } = transform({
-				minify: true,
-				cssModules: true,
-				filename: id,
-				code: new TextEncoder().encode(css),
-			})
-
-			const href = hashCss(code)
-			const styles = Object.fromEntries(
-				Object.entries(exports).map(([k, v]) => [k, v.name]),
-			)
+	if (cached?.source === source && cached.config === configKey) return cached
+
+	const tags: Tags = new Map()
+	const magic = new MagicString(source)
+	let matched = false
+
+	// the regex is global, so reset its cursor before scanning
+	regex.lastIndex = 0
+
+	let match: RegExpExecArray | null
+
+	// walk every cxx template and replace it in place
+	while ((match = regex.exec(source))) {
+		matched = true
+
+		// capture groups: export, three bindings, plain css, (quote), tag, tagged css
+		const [, exp, varOne, varTwo, varThree, plainCss, , tag, taggedCss] = match
+		const css = plainCss ?? taggedCss
+		const matchIndex = match.index
+
+		// compile the CSS to minified CSS Modules, reporting the source line on failure
+		const { code, exports: classExports = {} } = (() => {
+			try {
+				return transform({
+					minify: true,
+					cssModules: true,
+					filename: id,
+					code: encoder.encode(css),
+				})
+			} catch (err) {
+				const line = source.slice(0, matchIndex).split('\n').length
+				throw new Error(`Failed to compile cxx CSS at ${id}:${line}`, { cause: err })
+			}
+		})()
 
-			if (tag) {
-				const suffix =
-					typeof config.typeSuffix === 'string'
-						? config.typeSuffix
-						: config.typeSuffix === false
-							? ''
-							: 'Classes'
-				const tagWithSuffix = pascalise(`${tag}${suffix}`)
+		const href = hashCss(code)
+		// map each class name to its generated (scoped) name
+		const styles = Object.fromEntries(
+			Object.entries(classExports).map(([k, v]) => [k, v.name]),
+		)
 
-				if (tags.has(tagWithSuffix)) throw new DuplicateTagError(tagWithSuffix)
+		if (tag) {
+			const suffix =
+				typeof config.typeSuffix === 'string'
+					? config.typeSuffix
+					: config.typeSuffix === false
+						? ''
+						: 'Classes'
+			const tagWithSuffix = pascalise(`${tag}${suffix}`)
 
-				// side effect but neccessary
-				tags.set(tagWithSuffix, Object.keys(styles))
-			}
+			if (!IDENTIFIER.test(tagWithSuffix)) throw new InvalidTagError(tag)
+			if (tags.has(tagWithSuffix)) throw new DuplicateTagError(tagWithSuffix)
 
-			return [
-				varOne && `const ${varOne} = \`${code}\``,
-				varTwo && `const ${varTwo} = ${JSON.stringify(styles)}`,
-				varThree && `const ${varThree} = \`${href}\``,
-			]
-				.filter(Boolean)
-				.join('\n')
-		},
-	)
+			// side effect but necessary
+			tags.set(tagWithSuffix, Object.keys(styles))
+		}
+
+		const statements: string[] = []
 
-	// cache
-	collectCache.set(id, { source, template, tags })
+		if (varOne) {
+			statements.push(`${exp}const ${varOne} = ${JSON.stringify(decoder.decode(code))}`)
+		}
 
-	return {
-		template,
-		tags,
+		if (varTwo) {
+			statements.push(`${exp}const ${varTwo} = ${JSON.stringify(styles)}`)
+		}
+
+		if (varThree) {
+			statements.push(`${exp}const ${varThree} = ${JSON.stringify(href)}`)
+		}
+
+		// swap the template for the generated declarations, keeping the export keyword
+		magic.overwrite(matchIndex, matchIndex + match[0].length, statements.join('\n'))
 	}
+
+	const template = magic.toString()
+	// only build a map when something was actually rewritten
+	const map = matched
+		? magic.generateMap({ source: id, includeContent: true, hires: true })
+		: null
+	const result = { source, config: configKey, template, tags, map }
+
+	collectCache.set(id, result)
+
+	return result
 }
 
 /**
- * Write the generated declaration file for the current set of collected tags.
+ * Render the generated declaration file contents for a set of collected tags.
  */
-export async function writeTypes(tags: Tags) {
+function renderTypes(tags: Tags) {
+	return [
+		AUTOGEN_MSG,
+		'',
+		`import '${PKG_NAME}'`,
+		'',
+		`declare module '${PKG_NAME}' {`,
+		tagsToType(tags),
+		'}',
+		'',
+	].join('\n')
+}
+
+/**
+ * Write (or remove) the generated `index.d.ts` for a full tag surface.
+ */
+async function writeRenderedTypes(tags: Tags) {
 	const filePath = path.join(GENERATED_DIR, 'index.d.ts')
 
 	if (!tags.size) {
-		try {
-			await fs.rm(filePath, { force: true })
-			fileCache.delete(filePath)
-		} catch (err) {
-			if (!isENOENT(err)) throw err
-		}
-
+		await fs.rm(filePath, { force: true })
 		return
 	}
 
 	await fs.mkdir(GENERATED_DIR, { recursive: true })
+	await maybeWrite(filePath, renderTypes(tags))
+}
 
-	await maybeWrite(
-		filePath,
-		`${AUTOGEN_MSG}
+const PARTIAL_DIR = path.join(GENERATED_DIR, 'tags')
 
-			import '${PKG_NAME}'
+// wait this long after the last file before rebuilding, so a burst of files
+// only re-reads the partials once
+const REBUILD_WAIT = 100
 
-			declare module '${PKG_NAME}' {
-				${tagsToType(tags)}
-			}
-		`,
+let rebuildTimer: ReturnType<typeof setTimeout> | null = null
+let rebuildError: unknown = null
+
+function partialPath(filePath: string) {
+	return path.join(
+		PARTIAL_DIR,
+		`${createHash('sha1').update(filePath).digest('hex')}.json`,
 	)
 }
 
 /**
- * Render collected tags as a module augmentation for the package entrypoint.
+ * The partial directory changes whenever any process adds, removes or overwrites a partial, so
+ * its mtime tells us whether another writer moved while we were rebuilding.
  */
-export function tagsToType(tags: Tags) {
-	return [...tags]
-		.map(
-			([tag, classes]) => `
-		export type ${tag} = ${
-			classes.length > 0
-				? classes
-						.toSorted((a, b) => a.length - b.length)
-						.map(c => `'${c}'`)
-						.join(' | ')
-				: 'never'
-		}
-	`,
-		)
-		.join('\n')
+async function partialDirMtime() {
+	try {
+		return (await fs.stat(PARTIAL_DIR)).mtimeMs
+	} catch (err) {
+		if (isENOENT(err)) return 0
+		throw err
+	}
 }
 
 /**
- * Merge per-file tag maps into one application-wide tag map.
+ * Read every per-file partial and merge them into one tag map. Partials whose source file no
+ * longer exists are pruned so deleted files drop out of the types.
  */
-export function flattenTags(tagsByFile: BuildContext['tagsByFile']) {
-	const tags = new Map<string, string[]>()
+async function readPartials() {
+	let entries: string[]
+
+	try {
+		entries = await fs.readdir(PARTIAL_DIR)
+	} catch (err) {
+		if (isENOENT(err)) return new Map()
+		throw err
+	}
+
+	const tags: Tags = new Map()
 
-	for (const fileTags of tagsByFile.values()) {
-		for (const [name, classes] of fileTags) {
+	for (const entry of entries) {
+		if (!entry.endsWith('.json')) continue
+
+		const partial = path.join(PARTIAL_DIR, entry)
+		let parsed: { file: string; tags: Record<string, string[]> }
+
+		try {
+			parsed = JSON.parse(await fs.readFile(partial, 'utf-8'))
+		} catch {
+			continue
+		}
+
+		try {
+			await fs.access(parsed.file)
+		} catch {
+			await fs.rm(partial, { force: true })
+			continue
+		}
+
+		for (const [name, classes] of Object.entries(parsed.tags)) {
 			if (tags.has(name)) throw new DuplicateTagError(name)
 			tags.set(name, classes)
 		}
@@ -206,3 +323,90 @@ export function flattenTags(tagsByFile: BuildContext['tagsByFile']) {
 
 	return tags
 }
+
+/**
+ * Persist one file's tags to its own partial, then rebuild the shared types soon. Rebuilding is
+ * debounced and serialised, so a large build does not re-read every partial per file.
+ */
+export function writeTypesForFile(filePath: string, tags: Tags) {
+	return enqueueWrite(async () => {
+		await fs.mkdir(PARTIAL_DIR, { recursive: true })
+
+		const partial = partialPath(filePath)
+
+		if (!tags.size) {
+			await fs.rm(partial, { force: true })
+		} else {
+			await writeFileAtomic(
+				partial,
+				JSON.stringify({ file: filePath, tags: Object.fromEntries(tags) }),
+			)
+		}
+	}).then(() => {
+		scheduleRebuild()
+	})
+}
+
+function scheduleRebuild() {
+	if (rebuildTimer) clearTimeout(rebuildTimer)
+
+	rebuildTimer = setTimeout(() => {
+		rebuildTimer = null
+		flushTypes().catch(err => {
+			rebuildError = err
+		})
+	}, REBUILD_WAIT)
+}
+
+/**
+ * Rebuild `index.d.ts` from every partial now. If another writer touches a partial mid-rebuild,
+ * rebuild once more so the final write reflects every partial. Bounded to avoid spinning.
+ */
+export function flushTypes() {
+	if (rebuildTimer) {
+		clearTimeout(rebuildTimer)
+		rebuildTimer = null
+	}
+
+	return enqueueWrite(async () => {
+		let before = await partialDirMtime()
+
+		for (let attempt = 0; attempt < 3; attempt++) {
+			await writeRenderedTypes(await readPartials())
+
+			const after = await partialDirMtime()
+			if (after === before) return
+
+			before = after
+		}
+	})
+}
+
+/**
+ * Return and clear any error from a background rebuild, so a caller can fail loudly.
+ */
+export function takeRebuildError() {
+	const err = rebuildError
+	rebuildError = null
+	return err
+}
+
+/**
+ * Render collected tags as a module augmentation for the package entrypoint.
+ */
+export function tagsToType(tags: Tags) {
+	return [...tags]
+		.toSorted(([a], [b]) => a.localeCompare(b))
+		.map(([tag, classes]) => {
+			const union =
+				classes.length > 0
+					? classes
+							.toSorted((a, b) => a.length - b.length)
+							.map(c => `'${c}'`)
+							.join(' | ')
+					: 'never'
+
+			return `\texport type ${tag} = ${union}`
+		})
+		.join('\n')
+}

package/src/index.ts

@@ -2,15 +2,32 @@ import type { Cxx, Result } from './types.js'
 
 export type { Cxx, Result, Tag } from './types.js'
 
+/**
+ * Hit when a `cxx` template reaches runtime, which means the build transform did
+ * not run. Throws so the problem is obvious instead of rendering empty styles.
+ *
+ * @example
+ * ```ts
+ * // no cxx plugin configured
+ * const [css, styles, href] = cxx`.a { color: red; }`
+ * // Error: cxx template was not transformed ...
+ * ```
+ */
+function untransformed(): never {
+	throw new Error(
+		'cxx template was not transformed. Make sure the cxx Vite plugin or Next integration is configured and applies to this file.',
+	)
+}
+
 /**
  * Build-time template tag placeholder used by the transform to emit CSS, classes and href values.
  */
-export const cxx: Cxx = Object.assign((_: TemplateStringsArray): Result => ['', {}, ''], {
-	tag:
-		<ClassName extends string = string>(_: string) =>
-		(_strings: TemplateStringsArray): Result<ClassName> => [
-			'',
-			{} as Readonly<Record<ClassName, string>>,
-			'',
-		],
-})
+export const cxx: Cxx = Object.assign(
+	(_: TemplateStringsArray): Result => untransformed(),
+	{
+		tag:
+			<ClassName extends string = string>(_: string) =>
+			(_strings: TemplateStringsArray): Result<ClassName> =>
+				untransformed(),
+	},
+)

package/src/logger.ts

@@ -8,6 +8,8 @@ const LEVELS = {
 
 export type LogLevel = keyof typeof LEVELS
 
+const defaultLevel: LogLevel = process.env['NODE_ENV'] === 'production' ? 'error' : 'info'
+
 type LogEntry = {
 	ts: number
 	level: LogLevel
@@ -25,23 +27,13 @@ type LogEntry = {
  * Log messages with different severity levels.
  */
 export class Logger {
-	static #defaultLevel: LogLevel = 'info'
-
-	#level?: LogLevel
+	#level: LogLevel
 
 	constructor(
 		level?: LogLevel,
 		public name?: string,
 	) {
-		this.#level = level
-	}
-
-	static set defaultLevel(level: LogLevel) {
-		Logger.#defaultLevel = level
-	}
-
-	static get defaultLevel() {
-		return Logger.#defaultLevel
+		this.#level = level ?? defaultLevel
 	}
 
 	/**
@@ -79,7 +71,7 @@ export class Logger {
 	}
 
 	get level() {
-		return this.#level ?? Logger.#defaultLevel
+		return this.#level
 	}
 
 	/**

package/src/next/cxx-loader.js

@@ -3,13 +3,16 @@ import { processFile } from './index.js'
 
 const loader = function (source) {
 	const { pluginConfig } = this.getOptions()
-	const logger = new Logger(
-		(pluginConfig?.logger?.level ?? process.env.NODE_ENV === 'production')
-			? 'error'
-			: 'debug',
-	)
+	const logger = new Logger()
 
-	const { template } = processFile(source, this.resourcePath, pluginConfig, logger)
+	const { template, map } = processFile(source, this.resourcePath, pluginConfig, logger)
+
+	// hand the transform's source map back to webpack/turbopack when they support it
+	if (map && typeof this.callback === 'function') {
+		this.callback(null, template, map)
+
+		return
+	}
 
 	return template
 }