@kubb/fabric-core 0.0.0-canary-20251126084918 → 0.0.0-canary-20251215181926

package/src/Fabric.ts

@@ -37,39 +37,129 @@ export type FabricMode = 'sequential' | 'parallel'
 
 /**
  * Event definitions emitted during the Fabric lifecycle.
+ *
+ * These events allow plugins and external code to hook into different stages
+ * of the file generation process. All events are asynchronous and can be
+ * listened to using `fabric.context.on()` or `fabric.context.onOnce()`.
+ *
+ * @example
+ * ```ts
+ * fabric.context.on('lifecycle:start', async () => {
+ *   console.log('Fabric started!')
+ * })
+ * ```
  */
 export interface FabricEvents {
-  /** Called at the beginning of the app lifecycle. */
-  start: []
+  /**
+   * Emitted when the Fabric application lifecycle begins.
+   * This is typically the first event fired when starting a Fabric run.
+   * Use this to perform initial setup or logging.
+   */
+  'lifecycle:start': []
 
-  /** Called at the end of the app lifecycle. */
-  end: []
+  /**
+   * Emitted when the Fabric application lifecycle completes.
+   * This is typically the last event fired after all processing is done.
+   * Use this for cleanup tasks or final reporting.
+   */
+  'lifecycle:end': []
 
-  /** Called when Fabric is rendering. */
-  render: [{ fabric: Fabric }]
+  /**
+   * Emitted when Fabric starts rendering (used with reactPlugin).
+   * Provides access to the Fabric instance for render-time operations.
+   *
+   * @property fabric - The current Fabric instance being rendered
+   */
+  'lifecycle:render': [{ fabric: Fabric }]
 
-  /** Called once before any files are processed. */
-  'process:start': [{ files: KubbFile.ResolvedFile[] }]
   /**
-   * Called when FileManager is adding files to its cache
+   * Emitted once before file processing begins.
+   * Provides the complete list of files that will be processed.
+   * Use this to prepare for batch operations or display initial file counts.
+   *
+   * @property files - Array of all files queued for processing
+   */
+  'files:processing:start': [{ files: KubbFile.ResolvedFile[] }]
+
+  /**
+   * Emitted when files are successfully added to the FileManager's internal cache.
+   * This happens after files pass through path and name resolution.
+   * Use this to track which files have been registered.
+   *
+   * @property files - Array of files that were just added to the cache
+   */
+  'files:added': [{ files: KubbFile.ResolvedFile[] }]
+
+  /**
+   * Emitted during file path resolution, before a file is cached.
+   * Listeners can modify the file's path property to customize output location.
+   * This is called for each file being added via `addFile()` or `upsertFile()`.
+   *
+   * @property file - The file whose path is being resolved (mutable)
    */
-  'file:add': [{ files: KubbFile.ResolvedFile[] }]
   'file:resolve:path': [{ file: KubbFile.File }]
+
+  /**
+   * Emitted during file name resolution, before a file is cached.
+   * Listeners can modify the file's name-related properties to customize naming.
+   * This is called for each file being added via `addFile()` or `upsertFile()`.
+   *
+   * @property file - The file whose name is being resolved (mutable)
+   */
   'file:resolve:name': [{ file: KubbFile.File }]
-  'write:start': [{ files: KubbFile.ResolvedFile[] }]
-  'write:end': [{ files: KubbFile.ResolvedFile[] }]
 
-  /** Called for each file when processing begins. */
-  'file:start': [{ file: KubbFile.ResolvedFile; index: number; total: number }]
+  /**
+   * Emitted just before files are written to disk.
+   * Provides all files that will be written in this batch.
+   * Use this to perform pre-write operations like creating directories.
+   *
+   * @property files - Array of files about to be written to disk
+   */
+  'files:writing:start': [{ files: KubbFile.ResolvedFile[] }]
 
-  /** Called for each file when processing completes. */
-  'file:end': [{ file: KubbFile.ResolvedFile; index: number; total: number }]
+  /**
+   * Emitted after all files have been successfully written to disk.
+   * Provides all files that were written in this batch.
+   * Use this for post-write operations like running formatters or reporting.
+   *
+   * @property files - Array of files that were written to disk
+   */
+  'files:writing:end': [{ files: KubbFile.ResolvedFile[] }]
 
   /**
-   * Called periodically (or per file) to indicate progress.
-   * Useful for progress bars or logging.
+   * Emitted when an individual file starts being processed.
+   * This happens for each file in the queue, before parsing.
+   * Use this for per-file setup or detailed logging.
+   *
+   * @property file - The file starting processing
+   * @property index - Zero-based position of this file in the queue
+   * @property total - Total number of files to process
    */
-  'process:progress': [
+  'file:processing:start': [{ file: KubbFile.ResolvedFile; index: number; total: number }]
+
+  /**
+   * Emitted when an individual file completes processing.
+   * This happens after the file has been parsed and handled.
+   * Use this for per-file cleanup or progress tracking.
+   *
+   * @property file - The file that finished processing
+   * @property index - Zero-based position of this file in the queue
+   * @property total - Total number of files to process
+   */
+  'file:processing:end': [{ file: KubbFile.ResolvedFile; index: number; total: number }]
+
+  /**
+   * Emitted after each file is processed, providing progress metrics.
+   * This is the primary event for implementing progress bars or tracking.
+   * Plugins like fsPlugin use this to write files to disk.
+   *
+   * @property processed - Number of files processed so far
+   * @property total - Total number of files to process
+   * @property percentage - Completion percentage (0-100)
+   * @property source - Optional parsed source code of the file
+   * @property file - The file that was just processed
+   */
+  'file:processing:update': [
     {
       processed: number
       total: number
@@ -79,8 +169,14 @@ export interface FabricEvents {
     },
   ]
 
-  /** Called once all files have been processed successfully. */
-  'process:end': [{ files: KubbFile.ResolvedFile[] }]
+  /**
+   * Emitted once all files have been successfully processed.
+   * This marks the completion of the processing phase.
+   * Use this to perform batch operations on all processed files.
+   *
+   * @property files - Array of all files that were processed
+   */
+  'files:processing:end': [{ files: KubbFile.ResolvedFile[] }]
 }
 
 /**

package/src/FileManager.ts

@@ -71,7 +71,7 @@ export class FileManager {
       resolvedFiles.push(resolvedFile)
     }
 
-    await this.events.emit('file:add', { files: resolvedFiles })
+    await this.events.emit('files:added', { files: resolvedFiles })
 
     return resolvedFiles
   }
@@ -105,7 +105,7 @@ export class FileManager {
       resolvedFiles.push(resolvedFile)
     }
 
-    await this.events.emit('file:add', { files: resolvedFiles })
+    await this.events.emit('files:added', { files: resolvedFiles })
 
     return resolvedFiles
   }
@@ -155,13 +155,13 @@ export class FileManager {
 
   //TODO add test and check if write of FileManager contains the newly added file
   async write(options: ProcessFilesProps): Promise<KubbFile.ResolvedFile[]> {
-    await this.events.emit('write:start', { files: this.files })
+    await this.events.emit('files:writing:start', { files: this.files })
 
     const resolvedFiles = await this.processor.run(this.files, options)
 
     this.clear()
 
-    await this.events.emit('write:end', { files: resolvedFiles })
+    await this.events.emit('files:writing:end', { files: resolvedFiles })
 
     return resolvedFiles
   }

package/src/FileProcessor.ts

@@ -60,20 +60,20 @@ export class FileProcessor {
     files: Array<KubbFile.ResolvedFile>,
     { parsers, mode = 'sequential', dryRun, extension }: ProcessFilesProps = {},
   ): Promise<KubbFile.ResolvedFile[]> {
-    await this.events.emit('process:start', { files })
+    await this.events.emit('files:processing:start', { files })
 
     const total = files.length
     let processed = 0
 
     const processOne = async (resolvedFile: KubbFile.ResolvedFile, index: number) => {
-      await this.events.emit('file:start', { file: resolvedFile, index, total })
+      await this.events.emit('file:processing:start', { file: resolvedFile, index, total })
 
       const source = dryRun ? undefined : await this.parse(resolvedFile, { extension, parsers })
 
       const currentProcessed = ++processed
       const percentage = (currentProcessed / total) * 100
 
-      await this.events.emit('process:progress', {
+      await this.events.emit('file:processing:update', {
         file: resolvedFile,
         source,
         processed: currentProcessed,
@@ -81,7 +81,7 @@ export class FileProcessor {
         total,
       })
 
-      await this.events.emit('file:end', { file: resolvedFile, index, total })
+      await this.events.emit('file:processing:end', { file: resolvedFile, index, total })
     }
 
     if (mode === 'sequential') {
@@ -101,7 +101,7 @@ export class FileProcessor {
       await Promise.all(promises)
     }
 
-    await this.events.emit('process:end', { files })
+    await this.events.emit('files:processing:end', { files })
 
     return files
   }

package/src/createFabric.ts

@@ -1,3 +1,97 @@
-import { defineFabric } from './defineFabric.ts'
+import { isFunction } from 'remeda'
+import type { Fabric, FabricConfig, FabricContext, FabricEvents, FabricOptions } from './Fabric.ts'
+import { FileManager } from './FileManager.ts'
+import type * as KubbFile from './KubbFile.ts'
+import type { Parser } from './parsers/types.ts'
+import type { Plugin } from './plugins/types.ts'
+import { AsyncEventEmitter } from './utils/AsyncEventEmitter.ts'
 
-export const createFabric = defineFabric()
+/**
+ * Creates a new Fabric instance
+ *
+ * @example
+ * const fabric = createFabric()
+ * fabric.use(myPlugin())
+ */
+export function createFabric<T extends FabricOptions>(config: FabricConfig<T> = { mode: 'sequential' } as FabricConfig<T>): Fabric<T> {
+  const events = new AsyncEventEmitter<FabricEvents>()
+  const installedPlugins = new Set<Plugin<any>>()
+  const installedParsers = new Map<KubbFile.Extname, Parser<any>>()
+  const installedParserNames = new Set<string>()
+  const fileManager = new FileManager({ events })
+
+  const context: FabricContext<T> = {
+    get files() {
+      return fileManager.files
+    },
+    async addFile(...files) {
+      await fileManager.add(...files)
+    },
+    config,
+    fileManager,
+    installedPlugins,
+    installedParsers,
+    on: events.on.bind(events),
+    off: events.off.bind(events),
+    onOnce: events.onOnce.bind(events),
+    removeAll: events.removeAll.bind(events),
+    emit: events.emit.bind(events),
+  } as FabricContext<T>
+
+  const fabric: Fabric<T> = {
+    context,
+    get files() {
+      return fileManager.files
+    },
+    async addFile(...files) {
+      await fileManager.add(...files)
+    },
+    async upsertFile(...files) {
+      await fileManager.upsert(...files)
+    },
+    async use(pluginOrParser, ...options) {
+      if (pluginOrParser.type === 'plugin') {
+        if (installedPlugins.has(pluginOrParser)) {
+          console.warn(`Plugin "${pluginOrParser.name}" already applied.`)
+        } else {
+          installedPlugins.add(pluginOrParser)
+        }
+
+        if (isFunction(pluginOrParser.inject)) {
+          const injecter = pluginOrParser.inject
+
+          const injected = (injecter as any)(context, ...options)
+          Object.assign(fabric, injected)
+        }
+      }
+
+      if (pluginOrParser.type === 'parser') {
+        if (installedParserNames.has(pluginOrParser.name)) {
+          console.warn(`Parser "${pluginOrParser.name}" already applied.`)
+        } else {
+          installedParserNames.add(pluginOrParser.name)
+        }
+
+        if (pluginOrParser.extNames) {
+          for (const extName of pluginOrParser.extNames) {
+            const existing = installedParsers.get(extName)
+            if (existing && existing.name !== pluginOrParser.name) {
+              console.warn(`Parser "${pluginOrParser.name}" is overriding parser "${existing.name}" for extension "${extName}".`)
+            }
+            installedParsers.set(extName, pluginOrParser)
+          }
+        }
+      }
+
+      if (isFunction(pluginOrParser.install)) {
+        const installer = pluginOrParser.install
+
+        await (installer as any)(context, ...options)
+      }
+
+      return fabric
+    },
+  } as Fabric<T>
+
+  return fabric
+}

package/src/index.ts

@@ -1,6 +1,5 @@
 export { createFabric } from './createFabric.ts'
 export { createFile } from './createFile.ts'
-export { defineFabric } from './defineFabric.ts'
 // we need this to override the globals of `fabric.use`
 export type { Fabric } from './Fabric.ts'
 export { FileManager } from './FileManager.ts'

package/src/parsers/defaultParser.ts

@@ -1,6 +1,6 @@
-import { createParser } from './createParser.ts'
+import { defineParser } from './defineParser.ts'
 
-export const defaultParser = createParser({
+export const defaultParser = defineParser({
   name: 'default',
   extNames: ['.json'],
   install() {},

package/src/parsers/{createParser.ts → defineParser.ts}

@@ -1,6 +1,6 @@
 import type { Parser, UserParser } from './types.ts'
 
-export function createParser<TOptions = unknown, TMeta extends object = any>(parser: UserParser<TOptions, TMeta>): Parser<TOptions, TMeta> {
+export function defineParser<TOptions = unknown, TMeta extends object = any>(parser: UserParser<TOptions, TMeta>): Parser<TOptions, TMeta> {
   return {
     type: 'parser',
     ...parser,

package/src/parsers/index.ts

@@ -1,5 +1,4 @@
-export { createParser } from './createParser.ts'
-
 export { defaultParser } from './defaultParser.ts'
+export { defineParser } from './defineParser.ts'
 export { tsxParser } from './tsxParser.ts'
 export { typescriptParser } from './typescriptParser.ts'

package/src/parsers/tsxParser.ts

@@ -1,7 +1,7 @@
-import { createParser } from './createParser.ts'
+import { defineParser } from './defineParser.ts'
 import { typescriptParser } from './typescriptParser.ts'
 
-export const tsxParser = createParser({
+export const tsxParser = defineParser({
   name: 'tsx',
   extNames: ['.tsx', '.jsx'],
   install() {},

package/src/parsers/typescriptParser.ts

@@ -2,7 +2,7 @@ import path from 'node:path'
 import ts from 'typescript'
 import { getRelativePath } from '../utils/getRelativePath.ts'
 import { trimExtName } from '../utils/trimExtName.ts'
-import { createParser } from './createParser.ts'
+import { defineParser } from './defineParser.ts'
 
 const { factory } = ts
 
@@ -122,7 +122,7 @@ export function createExport({
   )
 }
 
-export const typescriptParser = createParser({
+export const typescriptParser = defineParser({
   name: 'typescript',
   extNames: ['.ts', '.js'],
   install() {},

package/src/plugins/barrelPlugin.ts

@@ -5,7 +5,7 @@ import { createFile } from '../createFile.ts'
 import type * as KubbFile from '../KubbFile.ts'
 import { getRelativePath } from '../utils/getRelativePath.ts'
 import { TreeNode } from '../utils/TreeNode.ts'
-import { createPlugin } from './createPlugin.ts'
+import { definePlugin } from './definePlugin.ts'
 
 type Mode = 'all' | 'named' | 'propagate' | false
 
@@ -144,7 +144,7 @@ export function getBarrelFiles({ files, root, mode }: GetBarrelFilesOptions): Ar
   return result
 }
 
-export const barrelPlugin = createPlugin<Options, ExtendOptions>({
+export const barrelPlugin = definePlugin<Options, ExtendOptions>({
   name: 'barrel',
   install(ctx, options) {
     if (!options) {
@@ -155,7 +155,7 @@ export const barrelPlugin = createPlugin<Options, ExtendOptions>({
       return undefined
     }
 
-    ctx.on('write:start', async ({ files }) => {
+    ctx.on('files:writing:start', async ({ files }) => {
       const root = options.root
       const barrelFiles = getBarrelFiles({ files, root, mode: options.mode })
 

package/src/plugins/{createPlugin.ts → definePlugin.ts}

@@ -1,6 +1,6 @@
 import type { Plugin, UserPlugin } from './types.ts'
 
-export function createPlugin<Options = unknown, TAppExtension extends Record<string, any> = {}>(
+export function definePlugin<Options = unknown, TAppExtension extends Record<string, any> = {}>(
   plugin: UserPlugin<Options, TAppExtension>,
 ): Plugin<Options, TAppExtension> {
   return {

package/src/plugins/fsPlugin.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path'
 import fs from 'fs-extra'
 import type * as KubbFile from '../KubbFile.ts'
-import { createPlugin } from './createPlugin.ts'
+import { definePlugin } from './definePlugin.ts'
 
 type WriteOptions = {
   extension?: Record<KubbFile.Extname, KubbFile.Extname | ''>
@@ -85,14 +85,14 @@ declare global {
   }
 }
 
-export const fsPlugin = createPlugin<Options, ExtendOptions>({
+export const fsPlugin = definePlugin<Options, ExtendOptions>({
   name: 'fs',
   install(ctx, options = {}) {
     if (options.clean) {
       fs.removeSync(options.clean.path)
     }
 
-    ctx.on('process:progress', async ({ file, source }) => {
+    ctx.on('file:processing:update', async ({ file, source }) => {
       if (options.onBeforeWrite) {
         await options.onBeforeWrite(file.path, source)
       }

package/src/plugins/graphPlugin.ts

@@ -6,7 +6,7 @@ import { createFile } from '../createFile.ts'
 import type * as KubbFile from '../KubbFile.ts'
 import { open } from '../utils/open.ts'
 import { type Graph, TreeNode } from '../utils/TreeNode.ts'
-import { createPlugin } from './createPlugin.ts'
+import { definePlugin } from './definePlugin.ts'
 
 type Options = {
   root: string
@@ -84,14 +84,14 @@ async function serve(root: string) {
   })
 }
 
-export const graphPlugin = createPlugin<Options>({
+export const graphPlugin = definePlugin<Options>({
   name: 'graph',
   install(ctx, options) {
     if (!options) {
       throw new Error('Graph plugin requires options.root and options.mode')
     }
 
-    ctx.on('write:start', async ({ files }) => {
+    ctx.on('files:writing:start', async ({ files }) => {
       const root = options.root
 
       const graph = getGraph({ files, root })

package/src/plugins/index.ts

@@ -1,5 +1,5 @@
 export { barrelPlugin } from './barrelPlugin.ts'
-export { createPlugin } from './createPlugin.ts'
+export { definePlugin } from './definePlugin.ts'
 export { fsPlugin } from './fsPlugin.ts'
 export { graphPlugin } from './graphPlugin.ts'
 export { loggerPlugin } from './loggerPlugin.ts'

package/src/plugins/loggerPlugin.ts

@@ -6,10 +6,9 @@ import { createConsola, type LogLevel } from 'consola'
 import { WebSocket, WebSocketServer } from 'ws'
 import type { FabricEvents } from '../Fabric.ts'
 import type * as KubbFile from '../KubbFile.ts'
-import { createPlugin } from './createPlugin.ts'
+import { definePlugin } from './definePlugin.ts'
 
 type Broadcast = <T = unknown>(event: keyof FabricEvents | string, payload: T) => void
-
 type WebSocketOptions = {
   /**
    * Hostname to bind the websocket server to.
@@ -43,7 +42,10 @@ type Options = {
   websocket?: boolean | WebSocketOptions
 }
 
-function normalizeAddress(address: AddressInfo): { host: string; port: number } {
+function normalizeAddress(address: AddressInfo): {
+  host: string
+  port: number
+} {
   const host = address.address === '::' ? '127.0.0.1' : address.address
 
   return { host, port: address.port }
@@ -76,7 +78,7 @@ const createProgressBar = () =>
     Presets.shades_grey,
   )
 
-export const loggerPlugin = createPlugin<Options>({
+export const loggerPlugin = definePlugin<Options>({
   name: 'logger',
   install(ctx, options = {}) {
     const { level, websocket = true, progress = true } = options
@@ -140,23 +142,23 @@ export const loggerPlugin = createPlugin<Options>({
 
     const formatPath = (path: string) => relative(process.cwd(), path)
 
-    ctx.on('start', async () => {
+    ctx.on('lifecycle:start', async () => {
       logger.start('Starting Fabric run')
-      broadcast('start', { timestamp: Date.now() })
+      broadcast('lifecycle:start', { timestamp: Date.now() })
     })
 
-    ctx.on('render', async () => {
+    ctx.on('lifecycle:render', async () => {
       logger.info('Rendering application graph')
-      broadcast('render', { timestamp: Date.now() })
+      broadcast('lifecycle:render', { timestamp: Date.now() })
     })
 
-    ctx.on('file:add', async ({ files }) => {
+    ctx.on('files:added', async ({ files }) => {
       if (!files.length) {
         return
       }
 
       logger.info(`Queued ${pluralize('file', files.length)}`)
-      broadcast('file:add', {
+      broadcast('files:added', {
         files: files.map(serializeFile),
       })
     })
@@ -171,9 +173,12 @@ export const loggerPlugin = createPlugin<Options>({
       broadcast('file:resolve:name', { file: serializeFile(file) })
     })
 
-    ctx.on('process:start', async ({ files }) => {
+    ctx.on('files:processing:start', async ({ files }) => {
       logger.start(`Processing ${pluralize('file', files.length)}`)
-      broadcast('process:start', { total: files.length, timestamp: Date.now() })
+      broadcast('files:processing:start', {
+        total: files.length,
+        timestamp: Date.now(),
+      })
 
       if (progressBar) {
         logger.pauseLogs()
@@ -181,20 +186,20 @@ export const loggerPlugin = createPlugin<Options>({
       }
     })
 
-    ctx.on('file:start', async ({ file, index, total }) => {
+    ctx.on('file:processing:start', async ({ file, index, total }) => {
       logger.info(`Processing [${index + 1}/${total}] ${formatPath(file.path)}`)
-      broadcast('file:start', {
+      broadcast('file:processing:start', {
         index,
         total,
         file: serializeFile(file),
       })
     })
 
-    ctx.on('process:progress', async ({ processed, total, percentage, file }) => {
+    ctx.on('file:processing:update', async ({ processed, total, percentage, file }) => {
       const formattedPercentage = Number.isFinite(percentage) ? percentage.toFixed(1) : '0.0'
 
       logger.info(`Progress ${formattedPercentage}% (${processed}/${total}) → ${formatPath(file.path)}`)
-      broadcast('process:progress', {
+      broadcast('file:processing:update', {
         processed,
         total,
         percentage,
@@ -202,36 +207,41 @@ export const loggerPlugin = createPlugin<Options>({
       })
 
       if (progressBar) {
-        progressBar.increment(1, { message: `Writing ${formatPath(file.path)}` })
+        progressBar.increment(1, {
+          message: `Writing ${formatPath(file.path)}`,
+        })
       }
     })
 
-    ctx.on('file:end', async ({ file, index, total }) => {
+    ctx.on('file:processing:end', async ({ file, index, total }) => {
       logger.success(`Finished [${index + 1}/${total}] ${formatPath(file.path)}`)
-      broadcast('file:end', {
+      broadcast('file:processing:end', {
         index,
         total,
         file: serializeFile(file),
       })
     })
 
-    ctx.on('write:start', async ({ files }) => {
+    ctx.on('files:writing:start', async ({ files }) => {
       logger.start(`Writing ${pluralize('file', files.length)} to disk`)
-      broadcast('write:start', {
+      broadcast('files:writing:start', {
         files: files.map(serializeFile),
       })
     })
 
-    ctx.on('write:end', async ({ files }) => {
+    ctx.on('files:writing:end', async ({ files }) => {
       logger.success(`Written ${pluralize('file', files.length)} to disk`)
-      broadcast('write:end', {
+      broadcast('files:writing:end', {
         files: files.map(serializeFile),
       })
     })
 
-    ctx.on('process:end', async ({ files }) => {
+    ctx.on('files:processing:end', async ({ files }) => {
       logger.success(`Processed ${pluralize('file', files.length)}`)
-      broadcast('process:end', { total: files.length, timestamp: Date.now() })
+      broadcast('files:processing:end', {
+        total: files.length,
+        timestamp: Date.now(),
+      })
 
       if (progressBar) {
         progressBar.update(files.length, { message: 'Done ✅' })
@@ -241,9 +251,9 @@ export const loggerPlugin = createPlugin<Options>({
       }
     })
 
-    ctx.on('end', async () => {
+    ctx.on('lifecycle:end', async () => {
       logger.success('Fabric run completed')
-      broadcast('end', { timestamp: Date.now() })
+      broadcast('lifecycle:end', { timestamp: Date.now() })
 
       if (progressBar) {
         progressBar.stop()