@jk2908/cxx 0.2.6 → 0.3.1

package/src/next/index.ts

@@ -5,159 +5,183 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import watcher from '@parcel/watcher'
-
 import type { Logger } from '../logger.js'
-import type { PluginConfig, Tags } from '../types.js'
-import { collect, flattenTags, isENOENT, writeTypes } from '../build.js'
+import type { PluginConfig } from '../types.js'
+import { collect, isENOENT, writeTypesForFile } from '../build.js'
+import { GENERATED_DIR } from '../config.js'
 
 const nextDir = path.dirname(fileURLToPath(import.meta.url))
 const loader = path.join(nextDir, 'cxx-loader.cjs')
 
-// keep the latest extracted tags per file so one edit can rebuild the full type surface
-const tagsByFile: Map<string, Tags> = new Map()
-
-// directory watches are shared, but rebuilds still need the file's config and logger
+// keep the exact file inputs and their config so a single recursive watcher can filter events
 const watchedFiles = new Map<string, { pluginConfig: PluginConfig; logger: Logger }>()
-const subscriptionsByDir = new Map<string, Promise<AsyncSubscription>>()
 
-/**
- * Rebuild the generated type surface for one watched file after a Parcel event
- */
-async function rebuildFile(filePath: string, event: Event['type']) {
-	const watchedFile = watchedFiles.get(filePath)
-	if (!watchedFile) return
+let subscription: AsyncSubscription | null = null
+let subscriptionPromise: Promise<void> | null = null
+let cleanupRegistered = false
+let watcherLogger: Logger | null = null
 
-	const { pluginConfig, logger } = watchedFile
-	const hadTags = tagsByFile.has(filePath)
+// a single recursive watch avoids overlapping per-directory watchers; ignore the parts of the
+// tree that never contain source we transform
+const DEFAULT_IGNORE = [
+	'**/node_modules/**',
+	'**/.next/**',
+	`**/${GENERATED_DIR}/**`,
+	'**/.git/**',
+]
 
-	if (event === 'delete') {
-		tagsByFile.delete(filePath)
-		if (!hadTags) return
+async function onEvent(event: Event['type'], filePath: string) {
+	const watched = watchedFiles.get(filePath)
+	if (!watched) return
+
+	const { pluginConfig, logger } = watched
 
-		await writeTypes(flattenTags(tagsByFile))
+	if (event === 'delete') {
+		await writeTypesForFile(filePath, new Map())
 		logger.info(`updated types from ${filePath}`)
 
 		return
 	}
 
-	try {
-		const source = await fs.readFile(filePath, 'utf-8')
-		const { tags } = collect(source, filePath, pluginConfig)
-		const hasTags = tags.size > 0
-
-		if (hasTags) {
-			tagsByFile.set(filePath, tags)
-		} else {
-			tagsByFile.delete(filePath)
-		}
-
-		if (!hadTags && !hasTags) return
+	let source: string
 
-		await writeTypes(flattenTags(tagsByFile))
-		logger.info(`updated types from ${filePath}`)
+	try {
+		source = await fs.readFile(filePath, 'utf-8')
 	} catch (err) {
 		if (!isENOENT(err)) throw err
-		if (!hadTags) return
-
-		tagsByFile.delete(filePath)
-		await writeTypes(flattenTags(tagsByFile))
 
+		await writeTypesForFile(filePath, new Map())
 		logger.info(`updated types from ${filePath}`)
+
+		return
 	}
+
+	const { tags } = collect(source, filePath, pluginConfig)
+
+	await writeTypesForFile(filePath, tags)
+	logger.info(`updated types from ${filePath}`)
 }
 
 /**
- * Transform one module and, in development, register it with the shared watcher state
+ * Start the watcher lazily, on the first file we actually process, so merely importing this module
+ * has no side effects.
  */
-export function processFile(
-	source: string,
-	filePath: string,
-	pluginConfig: PluginConfig,
-	logger: Logger,
-) {
-	const resolvedFilePath = path.resolve(filePath)
-	const directoryPath = path.dirname(resolvedFilePath)
-	let subscription = subscriptionsByDir.get(directoryPath)
+function ensureWatcher(pluginConfig: PluginConfig, logger: Logger) {
+	watcherLogger = logger
 
-	if (process.env.NODE_ENV !== 'production') {
-		// Parcel watches directories, so remember the exact file inputs we care about
-		watchedFiles.set(resolvedFilePath, { pluginConfig, logger })
+	if (subscriptionPromise) return
+
+	const root = pluginConfig.watch?.root ?? process.cwd()
+	const ignore = [...DEFAULT_IGNORE, ...(pluginConfig.watch?.ignore ?? [])]
+
+	subscriptionPromise = (async () => {
+		// lazily imported so the native module is only loaded when watching is needed
+		const { subscribe } = await import('@parcel/watcher')
+
+		subscription = await subscribe(
+			root,
+			(watchErr, events) => {
+				if (watchErr) {
+					watcherLogger?.error(`failed to watch ${root}`, watchErr)
 
-		if (!subscription) {
-			// one subscription per directory is enough; the callback filters back down to watched files
-			subscription = watcher.subscribe(directoryPath, async (err, events) => {
-				if (err) {
-					logger.error(`failed to update types from ${directoryPath}`, err)
 					return
 				}
 
-				// Parcel can report unrelated files from the same directory, so ignore anything unregistered
 				for (const event of events) {
-					const eventFilePath = path.resolve(event.path)
-					if (!watchedFiles.has(eventFilePath)) continue
-
-					try {
-						await rebuildFile(eventFilePath, event.type)
-					} catch (watchErr) {
-						logger.error(`failed to update types from ${eventFilePath}`, watchErr)
-					}
+					const filePath = path.resolve(event.path)
+					if (!watchedFiles.has(filePath)) continue
+
+					void onEvent(event.type, filePath).catch(err => {
+						watcherLogger?.error(`failed to update types from ${filePath}`, err)
+					})
 				}
-			})
+			},
+			{ ignore },
+		)
+
+		registerCleanup()
+	})().catch(err => {
+		watcherLogger?.error('failed to start cxx watcher', err)
+		subscriptionPromise = null
+	})
+}
 
-			subscriptionsByDir.set(directoryPath, subscription)
-		}
-	}
+/**
+ * Close all active Parcel subscriptions.
+ */
+async function cleanup() {
+	const active = subscription
 
-	const result = collect(source, filePath, pluginConfig)
+	subscription = null
+	subscriptionPromise = null
+	watchedFiles.clear()
 
-	if (result.tags.size > 0) {
-		tagsByFile.set(filePath, result.tags)
-	} else {
-		tagsByFile.delete(filePath)
+	if (active) await active.unsubscribe()
+}
+
+/**
+ * Restore the host process's default signal behaviour instead of forcing an exit from a library.
+ */
+async function shutdown(signal: NodeJS.Signals) {
+	try {
+		await cleanup()
+	} finally {
+		// our `once` handlers have already been removed, so re-raising lets Node terminate as usual
+		process.kill(process.pid, signal)
 	}
+}
 
-	void writeTypes(flattenTags(tagsByFile))
+function registerCleanup() {
+	if (cleanupRegistered) return
 
-	return result
+	cleanupRegistered = true
+	process.once('SIGINT', () => void shutdown('SIGINT'))
+	process.once('SIGTERM', () => void shutdown('SIGTERM'))
 }
 
 /**
- * Close all active Parcel subscriptions before the process exits
+ * Transform one module and, in development, register it with the shared watcher state.
  */
-async function cleanup() {
-	await Promise.all(
-		[...subscriptionsByDir].map(async ([directoryPath, subPromise]) => {
-			subscriptionsByDir.delete(directoryPath)
-			await (await subPromise).unsubscribe()
-		}),
-	)
-
-	subscriptionsByDir.clear()
-}
+export function processFile(
+	source: string,
+	filePath: string,
+	pluginConfig: PluginConfig,
+	logger: Logger,
+) {
+	const resolvedFilePath = path.resolve(filePath)
 
-process.once('SIGINT', () => {
-	cleanup().finally(() => process.exit(130))
-})
+	if (process.env['NODE_ENV'] !== 'production') {
+		watchedFiles.set(resolvedFilePath, { pluginConfig, logger })
+		ensureWatcher(pluginConfig, logger)
+	}
 
-process.once('SIGTERM', () => {
-	cleanup().finally(() => process.exit(143))
-})
+	const result = collect(source, resolvedFilePath, pluginConfig)
 
-export async function withCxx(
-	nextConfig: NextConfig = {},
-	pluginConfig: PluginConfig = {},
-) {
-	const TURBOPACK_GLOB = '*.{tsx,jsx,ts,js}'
+	void writeTypesForFile(resolvedFilePath, result.tags).catch(err => {
+		logger.error(`failed to write types for ${resolvedFilePath}`, err)
+	})
+
+	return result
+}
+
+const TURBOPACK_GLOB = '*.{tsx,jsx,ts,js}'
+
+export function withCxx(nextConfig: NextConfig = {}, pluginConfig: PluginConfig = {}) {
+	const watchRoot =
+		pluginConfig.watch?.root ?? nextConfig.turbopack?.root ?? process.cwd()
 
 	const loaderItem = {
 		loader,
 		options: {
-			pluginConfig,
+			pluginConfig: {
+				...pluginConfig,
+				watch: { ...pluginConfig.watch, root: watchRoot },
+			},
 		},
 	}
 
 	const currentRule = nextConfig.turbopack?.rules?.[TURBOPACK_GLOB]
+	const userWebpack = nextConfig.webpack
 
 	return {
 		...nextConfig,
@@ -175,5 +199,24 @@ export async function withCxx(
 						: { loaders: [loaderItem] },
 			},
 		},
+		// webpack builds (Next without `--turbopack`) would otherwise silently skip the transform
+		webpack(config: unknown, context: unknown) {
+			const next = (
+				userWebpack ? userWebpack(config as never, context as never) : config
+			) as {
+				module?: { rules?: unknown[] }
+			}
+
+			next.module ??= {}
+			next.module.rules ??= []
+			next.module.rules.push({
+				test: /\.[jt]sx?$/,
+				exclude: /node_modules/,
+				enforce: 'pre',
+				use: [loaderItem],
+			})
+
+			return next
+		},
 	}
 }

package/src/types.ts

@@ -1,5 +1,3 @@
-import type { LogLevel } from './logger.js'
-
 export type Result<ClassName extends string = string> = readonly [
 	css: string,
 	classes: Readonly<Record<ClassName, string>>,
@@ -10,8 +8,11 @@ export type Tags = Map<string, string[]>
 
 export type PluginConfig = {
 	typeSuffix?: string | false
-	logger?: {
-		level?: LogLevel
+	watch?: {
+		// root used for type-regeneration watching; defaults to the Vite root / Next turbopack root
+		root?: string
+		// extra globs to ignore on top of the defaults
+		ignore?: string[]
 	}
 }
 

package/src/utils.ts

@@ -9,16 +9,81 @@ export function pascalise(str: string) {
 		.join('')
 }
 
-export function debounce<T extends unknown[]>(fn: (...args: T) => void, wait: number) {
-	let timeoutId: ReturnType<typeof setTimeout> | null = null
+export type Batcher<K, V> = {
+	/**
+	 * Queue a value for a key. Queueing the same key again replaces the previous value.
+	 */
+	add: (key: K, value: V) => void
+	/**
+	 * Run any waiting work now and resolve once it has finished.
+	 */
+	flush: () => Promise<void>
+}
+
+/**
+ * Group bursts of work and run them together. Every key queued within `wait` is
+ * included once, and a key queued while a batch is running is handled in the next
+ * batch instead of replacing the one in progress.
+ */
+export function createBatcher<K, V>(
+	wait: number,
+	flush: (batch: Map<K, V>) => void | Promise<void>,
+): Batcher<K, V> {
+	// work waiting to run, keyed so each key is only queued once
+	const pending = new Map<K, V>()
+	// waits for a burst of changes to settle before running
+	let timer: ReturnType<typeof setTimeout> | null = null
+	// true while a batch is running, so we never start a second one
+	let running = false
+
+	async function drain() {
+		// a run is already going, so let it pick up the new work
+		if (running) return
+		running = true
 
-	return (...args: T) => {
-		if (timeoutId) {
-			clearTimeout(timeoutId)
+		try {
+			// keep looping while there is work, including work added during a flush
+			while (pending.size > 0) {
+				// snapshot the queued work
+				const batch = new Map(pending)
+				// empty the queue right away, so anything added during flush waits for the next loop
+				pending.clear()
+
+				await flush(batch)
+			}
+		} finally {
+			// always allow the next run, even if flush threw
+			running = false
 		}
+	}
 
-		timeoutId = setTimeout(() => {
-			fn.apply(null, args)
+	function schedule() {
+		// cancel the previous wait, so the timer restarts from now
+		if (timer) clearTimeout(timer)
+
+		// run once the calls stop coming for `wait` ms
+		timer = setTimeout(() => {
+			// the timer has fired, so drop the stale handle
+			timer = null
+			// start the run without waiting for it (this is a timer callback)
+			void drain()
 		}, wait)
 	}
+
+	return {
+		add(key, value) {
+			// the newest value for this key wins
+			pending.set(key, value)
+			schedule()
+		},
+		flush() {
+			// run now instead of waiting out the timer
+			if (timer) {
+				clearTimeout(timer)
+				timer = null
+			}
+
+			return drain()
+		},
+	}
 }

package/src/vite/index.ts

@@ -2,16 +2,18 @@ import { realpathSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
-import { type Plugin, type ViteDevServer } from 'vite'
+import { type Plugin, type ResolvedConfig, type ViteDevServer } from 'vite'
 
 import type { BuildContext, PluginConfig } from '../types.js'
 import { collect, flattenTags, isENOENT, writeTypes } from '../build.js'
 import { GENERATED_DIR } from '../config.js'
 import { Logger } from '../logger.js'
-import { debounce } from '../utils.js'
+import { createBatcher } from '../utils.js'
 
 const ACCEPTED_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx'])
 
+type WatchEvent = 'add' | 'change' | 'unlink'
+
 function normaliseWatchPath(p: string) {
 	return p.replace(/\\/g, '/')
 }
@@ -21,23 +23,11 @@ export default function cxx(pluginConfig: PluginConfig = {}) {
 		tagsByFile: new Map(),
 	} satisfies BuildContext
 
-	const logger = new Logger(
-		(pluginConfig?.logger?.level ?? process.env.NODE_ENV === 'production')
-			? 'error'
-			: 'debug',
-	)
-
-	// write generated files into a hidden folder at the project root
-	// keep the generated surface out of src
-	const watchRoot = normaliseWatchPath(realpathSync.native(process.cwd()))
-	const watchedRoots = [`${watchRoot}/`]
+	const logger = new Logger()
 
-	let rebuildRunning = false
-	let rebuildQueued = false
+	// resolved from Vite's root in `configResolved`, not from `process.cwd()`
+	let watchRoot = normaliseWatchPath(process.cwd())
 
-	// watcher events can arrive through symlinked paths like /var while cwd has
-	// already resolved to /private/var, so canonicalise the parent dir once and
-	// reattach the file name for stable prefix checks
 	function resolveWatchFile(filePath: string) {
 		const absolutePath = path.resolve(watchRoot, filePath)
 		const parentPath = path.dirname(absolutePath)
@@ -53,101 +43,142 @@ export default function cxx(pluginConfig: PluginConfig = {}) {
 		}
 	}
 
-	function watchedFile(filePath: string) {
+	// returns the canonical, watchable path or null when the file is irrelevant
+	function watchedFile(filePath: string): string | null {
 		const resolvedPath = resolveWatchFile(filePath)
 
-		return (
-			watchedRoots.some(root => resolvedPath.startsWith(root)) &&
+		if (
+			resolvedPath.startsWith(`${watchRoot}/`) &&
 			!resolvedPath.includes(`/${GENERATED_DIR}/`) &&
 			ACCEPTED_EXTENSIONS.has(path.extname(resolvedPath))
-		)
-	}
+		) {
+			return resolvedPath
+		}
 
-	const rebuild = debounce((event: 'add' | 'change' | 'unlink', filePath: string) => {
-		function queue() {
-			void (async () => {
-				// collapse bursts of file events into one active rebuild plus a single
-				// queued rerun when changes land mid-build
-				if (rebuildRunning) {
-					rebuildQueued = true
-					return
-				}
+		return null
+	}
 
-				rebuildRunning = true
+	async function onEvent(event: WatchEvent, file: string) {
+		const hadTags = buildContext.tagsByFile.has(file)
 
-				do {
-					rebuildQueued = false
+		if (event === 'unlink') {
+			if (!hadTags) return
 
-					try {
-						const hadTags = buildContext.tagsByFile.has(file)
-						let hasTags = false
+			buildContext.tagsByFile.delete(file)
+			await writeTypes(flattenTags(buildContext.tagsByFile))
+			logger.info(`updated types from ${file}`)
 
-						if (event === 'unlink') {
-							buildContext.tagsByFile.delete(file)
-						} else {
-							const source = await fs.readFile(file, 'utf-8')
-							const { tags } = collect(source, file, pluginConfig)
+			return
+		}
 
-							hasTags = tags.size > 0
+		let source: string
 
-							if (hasTags) {
-								buildContext.tagsByFile.set(file, tags)
-							} else {
-								buildContext.tagsByFile.delete(file)
-							}
-						}
+		try {
+			source = await fs.readFile(file, 'utf-8')
+		} catch (err) {
+			if (!isENOENT(err)) throw err
+			if (!hadTags) return
 
-						if (!hadTags && !hasTags) continue
+			buildContext.tagsByFile.delete(file)
+			await writeTypes(flattenTags(buildContext.tagsByFile))
+			logger.info(`updated types from ${file}`)
 
-						await writeTypes(flattenTags(buildContext.tagsByFile))
-						logger.info(`updated types from ${file}`)
-					} catch (err) {
-						if (isENOENT(err)) {
-							if (!buildContext.tagsByFile.has(file)) continue
+			return
+		}
 
-							buildContext.tagsByFile.delete(file)
-							await writeTypes(flattenTags(buildContext.tagsByFile))
+		const { tags } = collect(source, file, pluginConfig)
+		const hasTags = tags.size > 0
 
-							logger.info(`updated types from ${file}`)
+		if (hasTags) {
+			buildContext.tagsByFile.set(file, tags)
+		} else {
+			buildContext.tagsByFile.delete(file)
+		}
 
-							continue
-						}
+		if (!hadTags && !hasTags) return
 
-						logger.error(`failed to update types from ${file}`, err)
-					}
-				} while (rebuildQueued)
+		await writeTypes(flattenTags(buildContext.tagsByFile))
+		logger.info(`updated types from ${file}`)
+	}
 
-				rebuildRunning = false
-			})()
+	// collect change events that arrive close together and handle each file once.
+	// The file path is the key, so changes to different files are all kept, and a
+	// change that arrives during a rebuild runs after that rebuild finishes.
+	const queue = createBatcher<string, WatchEvent>(75, async batch => {
+		for (const [file, event] of batch) {
+			try {
+				await onEvent(event, file)
+			} catch (err) {
+				logger.error(`failed to update types from ${file}`, err)
+			}
 		}
-
-		// ignore anything outside the watched content dirs
-		if (!watchedFile(filePath)) return
-
-		const file = resolveWatchFile(filePath)
-		queue()
-	}, 75)
+	})
 
 	return {
 		name: 'cxx',
 		enforce: 'pre',
+		config() {
+			const ignore = pluginConfig.watch?.ignore
+			if (!ignore?.length) return null
+
+			// Vite concatenates `server.watch.ignored`, so only return the additions
+			return {
+				server: {
+					watch: {
+						ignored: ignore,
+					},
+				},
+			}
+		},
+		configResolved(config: ResolvedConfig) {
+			const root = pluginConfig.watch?.root ?? config.root
+
+			try {
+				watchRoot = normaliseWatchPath(realpathSync.native(root))
+			} catch {
+				watchRoot = normaliseWatchPath(root)
+			}
+		},
 		transform(code, id) {
-			const { template, tags } = collect(code, id, pluginConfig)
+			if (id.startsWith('\0') || id.includes('/node_modules/')) return null
+			// cheap bail-out before running the regex/lightningcss on every module
+			if (!code.includes('cxx')) return null
+
+			const cleanId = id.split('?')[0]
+			if (!ACCEPTED_EXTENSIONS.has(path.extname(cleanId))) return null
 
-			if (tags.size) buildContext.tagsByFile.set(id, tags)
+			const { template, tags, map } = collect(code, cleanId, pluginConfig)
+			if (template === code) return null
+
+			const resolved = resolveWatchFile(cleanId)
+
+			if (tags.size) {
+				buildContext.tagsByFile.set(resolved, tags)
+			} else {
+				buildContext.tagsByFile.delete(resolved)
+			}
 
 			return {
 				code: template,
-				map: null,
+				map,
 			}
 		},
 		configureServer(server: ViteDevServer) {
 			logger.info('Watching for changes...')
 
 			server.watcher
-				.on('add', (p: string) => rebuild('add', p))
-				.on('change', (p: string) => rebuild('change', p))
-				.on('unlink', (p: string) => rebuild('unlink', p))
+				.on('add', (p: string) => {
+					const file = watchedFile(p)
+					if (file) queue.add(file, 'add')
+				})
+				.on('change', (p: string) => {
+					const file = watchedFile(p)
+					if (file) queue.add(file, 'change')
+				})
+				.on('unlink', (p: string) => {
+					const file = watchedFile(p)
+					if (file) queue.add(file, 'unlink')
+				})
 		},
 		async writeBundle() {
 			await writeTypes(flattenTags(buildContext.tagsByFile))