@jk2908/cxx 0.2.4 → 0.3.1

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
@@ -22,37 +24,27 @@ type LogEntry = {
 }
 
 /**
- * Log messages with different severity levels
+ * 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
 	}
 
 	/**
-	 * Convert a value to an Error instance
+	 * Convert a value to an Error instance.
 	 */
 	static toError(err: unknown) {
 		return err instanceof Error ? err : new Error(String(err), { cause: err })
 	}
 
 	/**
-	 * Stringify the error for logging
+	 * Stringify the error for logging.
 	 */
 	static print(err: unknown) {
 		if (err instanceof Error) {
@@ -79,11 +71,11 @@ export class Logger {
 	}
 
 	get level() {
-		return this.#level ?? Logger.#defaultLevel
+		return this.#level
 	}
 
 	/**
-	 * Log a message with a specific level
+	 * Log a message with a specific level.
 	 */
 	log(level: LogLevel, message: string, error?: Error) {
 		if (LEVELS[level] < LEVELS[this.level]) return
@@ -115,35 +107,35 @@ export class Logger {
 	}
 
 	/**
-	 * Log a debug message
+	 * Log a debug message.
 	 */
 	debug(...messages: string[]) {
 		this.log('debug', messages.join(' '))
 	}
 
 	/**
-	 * Log an info message
+	 * Log an info message.
 	 */
 	info(...messages: string[]) {
 		this.log('info', messages.join(' '))
 	}
 
 	/**
-	 * Log a warning message
+	 * Log a warning message.
 	 */
 	warn(...messages: string[]) {
 		this.log('warn', messages.join(' '))
 	}
 
 	/**
-	 * Log an error message
+	 * Log an error message.
 	 */
 	error(message: string, error?: unknown) {
 		this.log('error', message, error === undefined ? undefined : Logger.toError(error))
 	}
 
 	/**
-	 * Log a fatal error message
+	 * Log a fatal error message.
 	 */
 	fatal(message: string, error?: unknown) {
 		this.log('fatal', message, error === undefined ? undefined : Logger.toError(error))

package/src/lru.ts

@@ -14,7 +14,7 @@ export class LruCache<T> {
 
 	/**
 	 * Retrieve a cached value and promote it to most-recently-used so it won't
-	 * be evicted while still actively referenced
+	 * be evicted while still actively referenced.
 	 */
 	get(key: string) {
 		const cached = this.#cache.get(key)
@@ -27,7 +27,7 @@ export class LruCache<T> {
 	 * Promote an existing cache entry to most-recently-used by deleting and
 	 * re-inserting it, which moves it to the end of the Map's iteration
 	 * order. If the cache is at capacity, evict the least recently used
-	 * entry (front) before inserting
+	 * entry (front) before inserting.
 	 */
 	set(key: string, value: T) {
 		// drop any existing entry

package/src/next/cxx-loader.js

@@ -3,11 +3,7 @@ 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)
 

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 '../index.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()
+		},
+	}
 }