@jk2908/cxx 0.1.10 → 0.2.1

package/src/index.ts

@@ -1,12 +1,221 @@
-declare module 'react' {
-	interface StyleHTMLAttributes<T> extends React.HTMLAttributes<T> {
-		href?: string
-		precedence?: 'low' | 'medium' | 'high'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { transform } from 'lightningcss'
+
+import type { BuildContext, Cxx, PluginConfig, Result, Tags } from './types.js'
+import { AUTOGEN_MSG, GENERATED_DIR, PKG_NAME } from './config.js'
+import { LruCache } from './lru.js'
+import { pascalise } from './utils.js'
+
+/**
+ * LRU cache of `collect` results by file id and last seen source so watcher and transform can
+ * reuse the same parsed template/tags
+ */
+const collectCache = new LruCache<{ source: string; template: string; tags: Tags }>()
+
+/**
+ * LRU cache for file content. Stores the last written content per file path so `maybeWrite`
+ * can skip disk i/o when nothing has changed
+ */
+const fileCache = new LruCache<string>()
+
+/**
+ * Returns whether the error was caused by a missing file or directory
+ */
+export function isENOENT(err: unknown) {
+	return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}
+
+/**
+ * Write a file only if the content has changed since the last build
+ */
+export async function maybeWrite(filePath: string, content: string) {
+	const cached = fileCache.get(filePath)
+
+	if (cached !== content) {
+		// cache says content changed, write without reading
+		await fs.writeFile(filePath, content)
+		fileCache.set(filePath, content)
+
+		return true
+	}
+
+	// cache miss or cache hit with same content — verify on disk
+	try {
+		if ((await fs.readFile(filePath, 'utf-8')) === content) {
+			fileCache.set(filePath, content)
+			return false
+		}
+	} catch (err) {
+		if (!isENOENT(err)) throw err
 	}
+
+	await fs.writeFile(filePath, content)
+	fileCache.set(filePath, content)
+
+	return true
 }
 
-export const cxx = (_: TemplateStringsArray): readonly ['', Record<string, string>, ''] => [
-	'',
-	{},
-	'',
-]
+// 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
+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
+
+/**
+ * Hash transformed CSS into a stable href for style deduplication
+ */
+function hashCss(code: Uint8Array) {
+	return `cxx-${createHash('sha256').update(code).digest('base64url').slice(0, 12)}`
+}
+
+export class TagDuplicateError extends Error {
+	constructor(tag: string) {
+		super(`Tag ${tag} has already been seen. Tags must be unique across your application`)
+	}
+}
+
+/**
+ * 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 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 (tag) {
+				const suffix =
+					typeof config.typeSuffix === 'string'
+						? config.typeSuffix
+						: config.typeSuffix === false
+							? ''
+							: 'Classes'
+				const tagWithSuffix = pascalise(`${tag}${suffix}`)
+
+				if (tags.has(tagWithSuffix)) throw new TagDuplicateError(tagWithSuffix)
+
+				// side effect but neccessary
+				tags.set(tagWithSuffix, Object.keys(styles))
+			}
+
+			return [
+				varOne && `const ${varOne} = \`${code}\``,
+				varTwo && `const ${varTwo} = ${JSON.stringify(styles)}`,
+				varThree && `const ${varThree} = \`${href}\``,
+			]
+				.filter(Boolean)
+				.join('\n')
+		},
+	)
+
+	// cache
+	collectCache.set(id, { source, template, tags })
+
+	return {
+		template,
+		tags,
+	}
+}
+
+/**
+ * Write the generated declaration file for the current set of collected tags
+ */
+export async function writeTypes(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
+		}
+
+		return
+	}
+
+	await fs.mkdir(GENERATED_DIR, { recursive: true })
+
+	await maybeWrite(
+		filePath,
+		`${AUTOGEN_MSG}
+
+			import '${PKG_NAME}'
+
+			declare module '${PKG_NAME}' {
+				${tagsToType(tags)}
+			}
+		`,
+	)
+}
+
+/**
+ * Render collected tags as a module augmentation for the package entrypoint
+ */
+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')
+}
+
+/**
+ * Merge per-file tag maps into one application-wide tag map
+ */
+export function flattenTags(tagsByFile: BuildContext['tagsByFile']) {
+	const tags = new Map<string, string[]>()
+
+	for (const fileTags of tagsByFile.values()) {
+		for (const [name, classes] of fileTags) {
+			if (tags.has(name)) throw new TagDuplicateError(name)
+			tags.set(name, classes)
+		}
+	}
+
+	return tags
+}
+
+/**
+ * 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 css = cxx

package/src/logger.ts

@@ -0,0 +1,151 @@
+const LEVELS = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	fatal: 4,
+} as const
+
+export type LogLevel = keyof typeof LEVELS
+
+type LogEntry = {
+	ts: number
+	level: LogLevel
+	message: string
+	error?:
+		| Error
+		| {
+				message: string
+				stack?: string
+				cause?: unknown
+		  }
+}
+
+/**
+ * Log messages with different severity levels
+ */
+export class Logger {
+	static #defaultLevel: LogLevel = 'info'
+
+	#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
+	}
+
+	/**
+	 * 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
+	 */
+	static print(err: unknown) {
+		if (err instanceof Error) {
+			return err.message + (err.stack ? `\n${err.stack}` : '')
+		}
+
+		// for plain objects, attempt to stringify with indentation
+		// for readability
+		if (typeof err === 'object' && err !== null) {
+			try {
+				return JSON.stringify(err, null, 2)
+			} catch {
+				// if stringify fails (e.g. circular reference), fall back
+				// to basic string conversion
+				return String(err)
+			}
+		}
+
+		return String(err)
+	}
+
+	set level(level: LogLevel) {
+		this.#level = level
+	}
+
+	get level() {
+		return this.#level ?? Logger.#defaultLevel
+	}
+
+	/**
+	 * Log a message with a specific level
+	 */
+	log(level: LogLevel, message: string, error?: Error) {
+		if (LEVELS[level] < LEVELS[this.level]) return
+
+		const entry: LogEntry = {
+			ts: Date.now(),
+			level,
+			message,
+		}
+
+		if (level === 'error' || level === 'fatal') {
+			entry.error = error ? Logger.toError(error) : new Error(message)
+		}
+
+		const line = `${this.name ? `[${this.name}]` : ''} [${entry.ts}] [${level.toUpperCase()}] ${message}`
+		const extra = entry.error ? `\n${Logger.print(entry.error)}` : ''
+
+		if (level === 'warn') {
+			console.warn(line, extra)
+			return
+		}
+
+		if (level === 'error' || level === 'fatal') {
+			console.error(line, extra)
+			return
+		}
+
+		console.log(line, extra)
+	}
+
+	/**
+	 * Log a debug message
+	 */
+	debug(...messages: string[]) {
+		this.log('debug', messages.join(' '))
+	}
+
+	/**
+	 * Log an info message
+	 */
+	info(...messages: string[]) {
+		this.log('info', messages.join(' '))
+	}
+
+	/**
+	 * Log a warning message
+	 */
+	warn(...messages: string[]) {
+		this.log('warn', messages.join(' '))
+	}
+
+	/**
+	 * Log an error message
+	 */
+	error(message: string, error?: unknown) {
+		this.log('error', message, error === undefined ? undefined : Logger.toError(error))
+	}
+
+	/**
+	 * Log a fatal error message
+	 */
+	fatal(message: string, error?: unknown) {
+		this.log('fatal', message, error === undefined ? undefined : Logger.toError(error))
+	}
+}

package/src/lru.ts

@@ -0,0 +1,51 @@
+export const CACHE_MAX_SIZE = 100
+
+export class LruCache<T> {
+	#cache: Map<string, T> = new Map()
+	#maxSize: number
+
+	constructor(maxSize = CACHE_MAX_SIZE) {
+		this.#maxSize = maxSize
+	}
+
+	get size() {
+		return this.#cache.size
+	}
+
+	/**
+	 * Retrieve a cached value and promote it to most-recently-used so it won't
+	 * be evicted while still actively referenced
+	 */
+	get(key: string) {
+		const cached = this.#cache.get(key)
+		if (this.#cache.has(key)) this.set(key, cached as T)
+
+		return cached
+	}
+
+	/**
+	 * 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
+	 */
+	set(key: string, value: T) {
+		// drop any existing entry
+		this.#cache.delete(key)
+
+		if (this.#cache.size >= this.#maxSize) {
+			const lru = this.#cache.keys().next().value
+			if (lru !== undefined) this.#cache.delete(lru)
+		}
+
+		this.#cache.set(key, value)
+	}
+
+	delete(key: string) {
+		return this.#cache.delete(key)
+	}
+
+	clear() {
+		return this.#cache.clear()
+	}
+}

package/src/next/cxx-loader.js

@@ -1,5 +1,17 @@
-import { inject } from '../inject'
+import { Logger } from '../logger.js'
+import { processFile } from './index.js'
 
-export default function loader(source) {
-	return inject(source, this.resourcePath, this.getOptions())
-}
+const loader = function (source) {
+	const { pluginConfig } = this.getOptions()
+	const logger = new Logger(
+		(pluginConfig?.logger?.level ?? process.env.NODE_ENV === 'production')
+			? 'error'
+			: 'debug',
+	)
+
+	const { template } = processFile(source, this.resourcePath, pluginConfig, logger)
+
+	return template
+}
+
+export default loader

package/src/next/index.ts

@@ -1,56 +1,179 @@
+import type { AsyncSubscription, Event } from '@parcel/watcher'
+import type { NextConfig } from 'next'
+
+import fs from 'node:fs/promises'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 
-import type { Configuration } from 'webpack'
-import type { NextConfig } from 'next'
-import type { WebpackConfigContext } from 'next/dist/server/config-shared'
-
-import type { Config } from '../inject'
-
-export function withCxx(nextConfig: NextConfig = {}, config: Config = {}) {
-	const pkg = require('next/package.json')
-
-	const IS_CANARY = pkg.version?.includes('canary') ?? false
-	const IS_TURBO = process.env.TURBOPACK === '1'
-	const TURBO_GLOB = '*.{tsx,jsx,ts,js}'
-
-	const loader = path.resolve(__dirname, `cxx-loader.${IS_TURBO ? 'cjs' : 'js'}`)
-
-	const turboConfig = {
-		...nextConfig.turbo,
-		rules: {
-			...nextConfig.turbo?.rules,
-			[TURBO_GLOB]: {
-				loaders: [
-					...(nextConfig.turbo?.rules?.[TURBO_GLOB]?.loaders ?? []),
-					{
-						loader,
-						options: config,
-					},
-				],
-			},
+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'
+
+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
+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
+
+	const { pluginConfig, logger } = watchedFile
+	const hadTags = tagsByFile.has(filePath)
+
+	if (event === 'delete') {
+		tagsByFile.delete(filePath)
+		if (!hadTags) return
+
+		await writeTypes(flattenTags(tagsByFile))
+		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
+
+		await writeTypes(flattenTags(tagsByFile))
+		logger.info(`updated types from ${filePath}`)
+	} catch (err) {
+		if (!isENOENT(err)) throw err
+		if (!hadTags) return
+
+		tagsByFile.delete(filePath)
+		await writeTypes(flattenTags(tagsByFile))
+
+		logger.info(`updated types from ${filePath}`)
+	}
+}
+
+/**
+ * Transform one module and, in development, register it with the shared watcher state
+ */
+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)
+
+	if (process.env.NODE_ENV !== 'production') {
+		// Parcel watches directories, so remember the exact file inputs we care about
+		watchedFiles.set(resolvedFilePath, { pluginConfig, logger })
+
+		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)
+					}
+				}
+			})
+
+			subscriptionsByDir.set(directoryPath, subscription)
+		}
+	}
+
+	const result = collect(source, filePath, pluginConfig)
+
+	if (result.tags.size > 0) {
+		tagsByFile.set(filePath, result.tags)
+	} else {
+		tagsByFile.delete(filePath)
+	}
+
+	void writeTypes(flattenTags(tagsByFile))
+
+	return result
+}
+
+/**
+ * Close all active Parcel subscriptions before the process exits.
+ */
+async function cleanup() {
+	await Promise.all(
+		[...subscriptionsByDir].map(async ([directoryPath, subPromise]) => {
+			subscriptionsByDir.delete(directoryPath)
+			await (await subPromise).unsubscribe()
+		}),
+	)
+
+	subscriptionsByDir.clear()
+}
+
+process.once('SIGINT', () => {
+	cleanup().finally(() => process.exit(130))
+})
+
+process.once('SIGTERM', () => {
+	cleanup().finally(() => process.exit(143))
+})
+
+export async function withCxx(
+	nextConfig: NextConfig = {},
+	pluginConfig: PluginConfig = {},
+) {
+	const TURBOPACK_GLOB = '*.{tsx,jsx,ts,js}'
+
+	const loaderItem = {
+		loader,
+		options: {
+			pluginConfig,
 		},
 	}
 
+	const currentRule = nextConfig.turbopack?.rules?.[TURBOPACK_GLOB]
+
 	return {
 		...nextConfig,
-		webpack(conf: Configuration, options: WebpackConfigContext) {
-			const resolvedWebpackConfig = (
-				typeof nextConfig?.webpack === 'function' ? nextConfig?.webpack(conf, options) : conf
-			) satisfies Configuration
-
-			resolvedWebpackConfig?.module?.rules?.push({
-				test: /\.(js|jsx|ts|tsx)$/,
-				exclude: /node_modules/,
-				use: {
-					loader,
-					options: config,
-				},
-			})
-
-			return resolvedWebpackConfig
+		turbopack: {
+			...nextConfig.turbopack,
+			rules: {
+				...nextConfig.turbopack?.rules,
+				[TURBOPACK_GLOB]: Array.isArray(currentRule)
+					? [...currentRule, loaderItem]
+					: currentRule
+						? {
+								...currentRule,
+								loaders: [...(currentRule.loaders ?? []), loaderItem],
+							}
+						: { loaders: [loaderItem] },
+			},
 		},
-		...(IS_CANARY
-			? { experimental: { ...nextConfig?.experimental, turbo: turboConfig } }
-			: { turbo: turboConfig }),
 	}
 }

package/src/types.ts

@@ -0,0 +1,28 @@
+import type { LogLevel } from './logger.js'
+
+export type Result<ClassName extends string = string> = readonly [
+	css: string,
+	classes: Readonly<Record<ClassName, string>>,
+	href: string,
+]
+
+export type Tags = Map<string, string[]>
+
+export type PluginConfig = {
+	typeSuffix?: string | false
+	logger?: {
+		level?: LogLevel
+	}
+}
+
+export type BuildContext = {
+	tagsByFile: Map<string, Tags>
+}
+
+export type Tag = <ClassName extends string = string>(
+	name: string,
+) => (_: TemplateStringsArray) => Result<ClassName>
+
+export type Cxx = ((_: TemplateStringsArray) => Result) & {
+	tag: Tag
+}