@jk2908/cxx 0.2.6 → 0.3.3

package/src/next/index.ts

@@ -5,159 +5,192 @@ 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, takeRebuildError, 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
 
-		await writeTypes(flattenTags(tagsByFile))
+	const { pluginConfig, logger } = watched
+
+	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)
-		}
+	let source: string
 
-		if (!hadTags && !hasTags) return
-
-		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 = source.includes('cxx')
+		? collect(source, filePath, pluginConfig).tags
+		: new Map()
+
+	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))
-})
+	// skip files that cannot contain a template, including node_modules
+	if (!source.includes('cxx') || /[\\/]node_modules[\\/]/.test(resolvedFilePath)) {
+		return { template: source, tags: new Map(), map: null }
+	}
 
-process.once('SIGTERM', () => {
-	cleanup().finally(() => process.exit(143))
-})
+	// surface a duplicate-tag error from a previous background rebuild
+	const priorError = takeRebuildError()
+	if (priorError) throw priorError
 
-export async function withCxx(
-	nextConfig: NextConfig = {},
-	pluginConfig: PluginConfig = {},
-) {
-	const TURBOPACK_GLOB = '*.{tsx,jsx,ts,js}'
+	if (process.env['NODE_ENV'] !== 'production') {
+		watchedFiles.set(resolvedFilePath, { pluginConfig, logger })
+		ensureWatcher(pluginConfig, logger)
+	}
+
+	const result = collect(source, resolvedFilePath, pluginConfig)
+
+	void writeTypesForFile(resolvedFilePath, result.tags)
+
+	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 +208,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,15 +8,14 @@ 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 or Next Turbopack root. */
+		root?: string
+		/** Extra globs to ignore on top of the defaults. */
+		ignore?: string[]
 	}
 }
 
-export type BuildContext = {
-	tagsByFile: Map<string, Tags>
-}
-
 export type Tag = <ClassName extends string = string>(
 	name: string,
 ) => (_: TemplateStringsArray) => Result<ClassName>

package/src/utils.ts

@@ -9,16 +9,89 @@ 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
+	// the run in progress, so `flush` can wait for it and we never start a second
+	let current: Promise<void> | null = null
+
+	function drain() {
+		// a run is already going, so let it pick up the new work
+		if (current) return current
 
-	return (...args: T) => {
-		if (timeoutId) {
-			clearTimeout(timeoutId)
-		}
+		const run = (async () => {
+			// 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()
 
-		timeoutId = setTimeout(() => {
-			fn.apply(null, args)
+				await flush(batch)
+			}
+		})()
+
+		current = run
+		run.then(
+			() => {
+				if (current === run) current = null
+			},
+			() => {
+				if (current === run) current = null
+			},
+		)
+
+		return run
+	}
+
+	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
+			// the flush callback handles its own errors, so just start the run
+			void drain().catch(() => {})
 		}, 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()
+		},
+	}
 }