@kubb/fabric-core 0.2.15 → 0.2.16

package/src/Fabric.ts

@@ -10,51 +10,61 @@ declare global {
   }
 }
 
+/**
+ * Component placeholder type.
+ * May later be extended to support specific runtime renderers.
+ */
 export type Component = any
 
-export type FabricOptions = {
+/**
+ * Defines core runtime options for Fabric.
+ */
+export interface FabricOptions {
   /**
+   * Determines how Fabric processes files.
+   * - `sequential`: files are processed one by one
+   * - `parallel`: files are processed concurrently
+   *
    * @default 'sequential'
    */
   mode?: FabricMode
 }
 
-export type FabricEvents = {
-  /**
-   * Called in the beginning of the app lifecycle.
-   */
+/**
+ * Available modes for file processing.
+ */
+export type FabricMode = 'sequential' | 'parallel'
+
+/**
+ * Event definitions emitted during the Fabric lifecycle.
+ */
+export interface FabricEvents {
+  /** Called at the beginning of the app lifecycle. */
   start: []
-  /**
-   * Called in the end of the app lifecycle.
-   */
+
+  /** Called at the end of the app lifecycle. */
   end: []
-  /**
-   * Called when being rendered
-   */
+
+  /** Called when Fabric is rendering. */
   render: [{ fabric: Fabric }]
-  /**
-   * Called once before processing any files.
-   */
+
+  /** Called once before any files are processed. */
   'process:start': [{ files: KubbFile.ResolvedFile[] }]
-  /**
-   * Called when FileManager is adding files to its cache
-   */
 
+  /** Called when files are added to the FileManager cache. */
   'file:add': [{ files: KubbFile.ResolvedFile[] }]
+
   'write:start': [{ files: KubbFile.ResolvedFile[] }]
   'write:end': [{ files: KubbFile.ResolvedFile[] }]
-  /**
-   * Called for each file when processing begins.
-   */
+
+  /** Called for each file when processing begins. */
   'file:start': [{ file: KubbFile.ResolvedFile; index: number; total: number }]
 
-  /**
-   * Called for each file when processing finishes.
-   */
+  /** Called for each file when processing completes. */
   'file:end': [{ file: KubbFile.ResolvedFile; index: number; total: number }]
 
   /**
-   * Called periodically (or after each file) to indicate progress.
+   * Called periodically (or per file) to indicate progress.
    * Useful for progress bars or logging.
    */
   'process:progress': [
@@ -67,51 +77,90 @@ export type FabricEvents = {
     },
   ]
 
-  /**
-   * Called once all files have been processed successfully.
-   */
+  /** Called once all files have been processed successfully. */
   'process:end': [{ files: KubbFile.ResolvedFile[] }]
 }
 
-export type FabricContext<TOptions extends FabricOptions = FabricOptions> = {
-  config?: FabricConfig<TOptions>
+/**
+ * Shared context passed to all plugins, parsers, and Fabric internals.
+ */
+export interface FabricContext<T extends FabricOptions = FabricOptions> extends AsyncEventEmitter<FabricEvents> {
+  /** The active Fabric configuration. */
+  config?: FabricConfig<T>
+
+  /** The internal file manager handling file creation, merging, and writing. */
   fileManager: FileManager
-  files: Array<KubbFile.ResolvedFile>
-  addFile(...files: Array<KubbFile.File>): Promise<void>
+
+  /** List of files currently in memory. */
+  files: KubbFile.ResolvedFile[]
+
+  /** Add new files to the file manager. */
+  addFile(...files: KubbFile.File[]): Promise<void>
+
+  /** Track installed plugins and parsers to prevent duplicates. */
   installedPlugins: Set<Plugin>
   installedParsers: Set<Parser>
-} & AsyncEventEmitter<FabricEvents>
+}
 
-export type FabricMode = 'sequential' | 'parallel'
+/**
+ * Base configuration object for Fabric.
+ */
+export interface FabricConfig<T extends FabricOptions = FabricOptions> {
+  /** The runtime options used to configure Fabric. */
+  options: T
+}
 
+/**
+ * Utility type that checks whether all properties of `T` are optional.
+ */
 type AllOptional<T> = {} extends T ? true : false
 
-export type FabricConfig<TOptions extends FabricOptions> = {
-  options: TOptions
-}
-
+/**
+ * Defines the signature of a plugin or parser's `install` function.
+ */
 export type Install<TOptions = unknown> = TOptions extends any[]
   ? (context: FabricContext, ...options: TOptions) => void | Promise<void>
   : AllOptional<TOptions> extends true
-    ? (context: FabricContext, options: TOptions | undefined) => void | Promise<void>
+    ? (context: FabricContext, options?: TOptions) => void | Promise<void>
     : (context: FabricContext, options: TOptions) => void | Promise<void>
 
-export type Inject<TOptions = unknown, TAppExtension extends Record<string, any> = {}> = TOptions extends any[]
-  ? (context: FabricContext, ...options: TOptions) => Partial<TAppExtension>
+/**
+ * Defines the signature of a plugin or parser's `inject` function.
+ * Returns an object that extends the Fabric instance.
+ */
+export type Inject<TOptions = unknown, TExtension extends Record<string, any> = {}> = TOptions extends any[]
+  ? (context: FabricContext, ...options: TOptions) => Partial<TExtension>
   : AllOptional<TOptions> extends true
-    ? (context: FabricContext, options: TOptions | undefined) => Partial<TAppExtension>
-    : (context: FabricContext, options: TOptions) => Partial<TAppExtension>
-
-export interface Fabric<TOptions extends FabricOptions = FabricOptions> extends Kubb.Fabric {
-  context: FabricContext<TOptions>
-  files: Array<KubbFile.ResolvedFile>
-  use<TPluginOptions = unknown, TMeta extends object = object, TAppExtension extends Record<string, any> = {}>(
-    pluginOrParser: Plugin<TPluginOptions, TAppExtension> | Parser<TPluginOptions, TMeta>,
+    ? (context: FabricContext, options?: TOptions) => Partial<TExtension>
+    : (context: FabricContext, options: TOptions) => Partial<TExtension>
+
+/**
+ * The main Fabric runtime interface.
+ * Provides access to the current context, registered plugins, files, and utility methods.
+ */
+export interface Fabric<T extends FabricOptions = FabricOptions> extends Kubb.Fabric {
+  /** The shared context for this Fabric instance. */
+  context: FabricContext<T>
+
+  /** The files managed by this Fabric instance. */
+  files: KubbFile.ResolvedFile[]
+
+  /**
+   * Install a plugin or parser into Fabric.
+   *
+   * @param target - The plugin or parser to install.
+   * @param options - Optional configuration or arguments for the target.
+   * @returns A Fabric instance extended by the plugin (if applicable).
+   */
+  use<TPluginOptions = unknown, TMeta extends object = object, TExtension extends Record<string, any> = {}>(
+    target: Plugin<TPluginOptions, TExtension> | Parser<TPluginOptions, TMeta>,
     ...options: TPluginOptions extends any[]
       ? NoInfer<TPluginOptions>
       : AllOptional<TPluginOptions> extends true
         ? [NoInfer<TPluginOptions>?] // Optional when all props are optional
         : [NoInfer<TPluginOptions>] // Required otherwise
-  ): (this & TAppExtension) | Promise<this & TAppExtension>
-  addFile(...files: Array<KubbFile.File>): Promise<void>
+  ): (this & TExtension) | Promise<this & TExtension>
+
+  /** Add one or more files to the Fabric file manager. */
+  addFile(...files: KubbFile.File[]): Promise<void>
 }

package/src/FileManager.ts

@@ -22,6 +22,7 @@ type Options = {
 
 export class FileManager {
   #cache = new Cache<KubbFile.ResolvedFile>()
+  #filesCache: Array<KubbFile.ResolvedFile> | null = null
   events: AsyncEventEmitter<FabricEvents>
   processor: FileProcessor
 
@@ -64,6 +65,7 @@ export class FileManager {
   }
 
   flush() {
+    this.#filesCache = null
     this.#cache.flush()
   }
 
@@ -73,21 +75,36 @@ export class FileManager {
 
   deleteByPath(path: KubbFile.Path): void {
     this.#cache.delete(path)
+    this.#filesCache = null
   }
 
   clear(): void {
     this.#cache.clear()
+    this.#filesCache = null
   }
 
   get files(): Array<KubbFile.ResolvedFile> {
+    if (this.#filesCache) {
+      return [...this.#filesCache]
+    }
+
     const cachedKeys = this.#cache.keys()
 
     // order by path length and if file is a barrel file
     const keys = orderBy(cachedKeys, [(v) => v.length, (v) => trimExtName(v).endsWith('index')])
 
-    const files = keys.map((key) => this.#cache.get(key))
+    const files: Array<KubbFile.ResolvedFile> = []
+
+    for (const key of keys) {
+      const file = this.#cache.get(key)
+      if (file) {
+        files.push(file)
+      }
+    }
+
+    this.#filesCache = files
 
-    return files.filter(Boolean)
+    return [...files]
   }
 
   //TODO add test and check if write of FileManager contains the newly added file

package/src/KubbFile.ts

@@ -88,8 +88,6 @@ export type Path = string
 
 export type AdvancedPath<T extends BaseName = BaseName> = `${BasePath}${T}`
 
-export type OptionalPath = Path | undefined | null
-
 export type File<TMeta extends object = object> = {
   /**
    * Name to be used to create the path

package/src/createFile.ts

@@ -5,11 +5,6 @@ import { isDeepEqual, uniqueBy } from 'remeda'
 import type * as KubbFile from './KubbFile.ts'
 import { trimExtName } from './utils/trimExtName.ts'
 
-function hashObject(obj: Record<string, unknown>): string {
-  const str = JSON.stringify(obj, Object.keys(obj).sort())
-  return createHash('sha256').update(str).digest('hex')
-}
-
 export function combineSources(sources: Array<KubbFile.Source>): Array<KubbFile.Source> {
   return uniqueBy(sources, (obj) => [obj.name, obj.isExportable, obj.isTypeOnly] as const)
 }
@@ -65,79 +60,100 @@ export function combineExports(exports: Array<KubbFile.Export>): Array<KubbFile.
 }
 
 export function combineImports(imports: Array<KubbFile.Import>, exports: Array<KubbFile.Export>, source?: string): Array<KubbFile.Import> {
-  return orderBy(imports, [
-    (v) => !!Array.isArray(v.name),
-    (v) => !v.isTypeOnly,
-    (v) => v.path,
-    (v) => !!v.name,
-    (v) => (Array.isArray(v.name) ? orderBy(v.name) : v.name),
-  ]).reduce(
-    (prev, curr) => {
-      let name = Array.isArray(curr.name) ? [...new Set(curr.name)] : curr.name
-
-      const hasImportInSource = (importName: string) => {
-        if (!source) {
-          return true
-        }
-
-        const checker = (name?: string) => {
-          return name && source.includes(name)
+  const exportedNameLookup = new Set<string>()
+  for (const item of exports) {
+    const { name } = item
+    if (!name) {
+      continue
+    }
+
+    if (Array.isArray(name)) {
+      for (const value of name) {
+        if (value) {
+          exportedNameLookup.add(value)
         }
-
-        return checker(importName) || exports.some(({ name }) => (Array.isArray(name) ? name.some(checker) : checker(name)))
-      }
-
-      if (curr.path === curr.root) {
-        // root and path are the same file, remove the "./" import
-        return prev
-      }
-
-      // merge all names and check if the importName is being used in the generated source and if not filter those imports out
-      if (Array.isArray(name)) {
-        name = name.filter((item) => (typeof item === 'string' ? hasImportInSource(item) : hasImportInSource(item.propertyName)))
       }
+      continue
+    }
 
-      const prevByPath = prev.findLast((imp) => imp.path === curr.path && imp.isTypeOnly === curr.isTypeOnly)
-      const uniquePrev = prev.findLast((imp) => imp.path === curr.path && isDeepEqual(imp.name, name) && imp.isTypeOnly === curr.isTypeOnly)
-      const prevByPathNameAndIsTypeOnly = prev.findLast((imp) => imp.path === curr.path && isDeepEqual(imp.name, name) && imp.isTypeOnly)
-
-      if (prevByPathNameAndIsTypeOnly) {
-        // we already have an export that has the same path but uses `isTypeOnly` (import type ...)
-        return prev
-      }
-
-      // already unique enough or name is empty
-      if (uniquePrev || (Array.isArray(name) && !name.length)) {
-        return prev
-      }
+    exportedNameLookup.add(name)
+  }
 
-      // new item, append name
-      if (!prevByPath) {
-        return [
-          ...prev,
-          {
-            ...curr,
-            name,
-          },
-        ]
-      }
+  const usageCache = new Map<string, boolean>()
+  const hasImportInSource = (importName: string): boolean => {
+    if (!source) {
+      return true
+    }
 
-      // merge all names when prev and current both have the same isTypeOnly set
-      if (prevByPath && Array.isArray(prevByPath.name) && Array.isArray(name) && prevByPath.isTypeOnly === curr.isTypeOnly) {
-        prevByPath.name = [...new Set([...prevByPath.name, ...name])]
+    const cached = usageCache.get(importName)
+    if (cached !== undefined) {
+      return cached
+    }
 
-        return prev
-      }
+    const isUsed = source.includes(importName) || exportedNameLookup.has(importName)
+    usageCache.set(importName, isUsed)
 
-      // no import was found in the source, ignore import
-      if (!Array.isArray(name) && name && !hasImportInSource(name)) {
-        return prev
-      }
+    return isUsed
+  }
 
-      return [...prev, curr]
-    },
-    [] as Array<KubbFile.Import>,
-  )
+  return orderBy(imports, [
+    (v) => !!Array.isArray(v.name),
+    (v) => !v.isTypeOnly,
+    (v) => v.path,
+    (v) => !!v.name,
+    (v) => (Array.isArray(v.name) ? orderBy(v.name) : v.name),
+  ]).reduce<Array<KubbFile.Import>>((prev, curr) => {
+    let name = Array.isArray(curr.name) ? [...new Set(curr.name)] : curr.name
+
+    if (curr.path === curr.root) {
+      // root and path are the same file, remove the "./" import
+      return prev
+    }
+
+    // merge all names and check if the importName is being used in the generated source and if not filter those imports out
+    if (Array.isArray(name)) {
+      name = name.filter((item) => (typeof item === 'string' ? hasImportInSource(item) : hasImportInSource(item.propertyName)))
+    }
+
+    const prevByPath = prev.findLast((imp) => imp.path === curr.path && imp.isTypeOnly === curr.isTypeOnly)
+    const uniquePrev = prev.findLast((imp) => imp.path === curr.path && isDeepEqual(imp.name, name) && imp.isTypeOnly === curr.isTypeOnly)
+    const prevByPathNameAndIsTypeOnly = prev.findLast((imp) => imp.path === curr.path && isDeepEqual(imp.name, name) && imp.isTypeOnly)
+
+    if (prevByPathNameAndIsTypeOnly) {
+      // we already have an export that has the same path but uses `isTypeOnly` (import type ...)
+      return prev
+    }
+
+    // already unique enough or name is empty
+    if (uniquePrev || (Array.isArray(name) && !name.length)) {
+      return prev
+    }
+
+    // new item, append name
+    if (!prevByPath) {
+      return [
+        ...prev,
+        {
+          ...curr,
+          name,
+        },
+      ]
+    }
+
+    // merge all names when prev and current both have the same isTypeOnly set
+    if (prevByPath && Array.isArray(prevByPath.name) && Array.isArray(name) && prevByPath.isTypeOnly === curr.isTypeOnly) {
+      prevByPath.name = [...new Set([...prevByPath.name, ...name])]
+
+      return prev
+    }
+
+    // no import was found in the source, ignore import
+    if (!Array.isArray(name) && name && !hasImportInSource(name)) {
+      return prev
+    }
+
+    return [...prev, curr]
+  }, [])
 }
 
 /**
@@ -156,7 +172,7 @@ export function createFile<TMeta extends object = object>(file: KubbFile.File<TM
 
   return {
     ...file,
-    id: hashObject({ path: file.path }),
+    id: createHash('sha256').update(file.path).digest('hex'),
     name: trimExtName(file.baseName),
     extname,
     imports: imports,

package/src/defineFabric.ts

@@ -5,22 +5,40 @@ import type { Parser } from './parsers/types.ts'
 import type { Plugin } from './plugins/types.ts'
 import { AsyncEventEmitter } from './utils/AsyncEventEmitter.ts'
 
-type RootRenderFunction<TOptions extends FabricOptions> = (fabric: Fabric<TOptions>) => void | Promise<void>
+/**
+ * Function that initializes the root Fabric instance.
+ *
+ * Used for setting up plugins, parsers, or performing side effects
+ * once the Fabric context is ready.
+ */
+type FabricInitializer<T extends FabricOptions> = (fabric: Fabric<T>) => void | Promise<void>
 
-export type DefineFabric<TOptions extends FabricOptions> = (config?: FabricConfig<TOptions>) => Fabric<TOptions>
+/**
+ * A function returned by {@link defineFabric} that creates a Fabric instance.
+ */
+export type CreateFabric<T extends FabricOptions> = (config?: FabricConfig<T>) => Fabric<T>
 
-export function defineFabric<TOptions extends FabricOptions>(instance?: RootRenderFunction<TOptions>): DefineFabric<TOptions> {
-  function creator(config?: FabricConfig<TOptions>): Fabric<TOptions> {
+/**
+ * Defines a new Fabric factory function.
+ *
+ * @example
+ * export const createFabric = defineFabric((fabric) => {
+ *   fabric.use(myPlugin())
+ * })
+ */
+export function defineFabric<T extends FabricOptions>(init?: FabricInitializer<T>): CreateFabric<T> {
+  function create(config?: FabricConfig<T>): Fabric<T> {
     const events = new AsyncEventEmitter<FabricEvents>()
     const installedPlugins = new Set<Plugin<any>>()
     const installedParsers = new Set<Parser<any>>()
     const fileManager = new FileManager({ events })
-    const context = {
+
+    const context: FabricContext<T> = {
       get files() {
         return fileManager.files
       },
-      async addFile(...newFiles) {
-        await fileManager.add(...newFiles)
+      async addFile(...files) {
+        await fileManager.add(...files)
       },
       config,
       fileManager,
@@ -31,57 +49,56 @@ export function defineFabric<TOptions extends FabricOptions>(instance?: RootRend
       onOnce: events.onOnce.bind(events),
       removeAll: events.removeAll.bind(events),
       emit: events.emit.bind(events),
-    } as FabricContext<TOptions>
+    } as FabricContext<T>
 
-    const fabric = {
+    const fabric: Fabric<T> = {
       context,
       get files() {
         return fileManager.files
       },
-      async addFile(...newFiles) {
-        await fileManager.add(...newFiles)
+      async addFile(...files) {
+        await fileManager.add(...files)
       },
       async use(pluginOrParser, ...options) {
-        const args = options
-
         if (pluginOrParser.type === 'plugin') {
           if (installedPlugins.has(pluginOrParser)) {
-            console.warn(`Plugin ${pluginOrParser.name} has already been applied to target fabric.`)
+            console.warn(`Plugin "${pluginOrParser.name}" already applied.`)
           } else {
             installedPlugins.add(pluginOrParser)
           }
 
-          if (pluginOrParser.inject && isFunction(pluginOrParser.inject)) {
+          if (isFunction(pluginOrParser.inject)) {
             const injecter = pluginOrParser.inject
 
-            const extraApp = (injecter as any)(context, ...args)
-            Object.assign(fabric, extraApp)
+            const injected = (injecter as any)(context, ...options)
+            Object.assign(fabric, injected)
           }
         }
+
         if (pluginOrParser.type === 'parser') {
           if (installedParsers.has(pluginOrParser)) {
-            console.warn(`Parser ${pluginOrParser.name} has already been applied to target fabric.`)
+            console.warn(`Parser "${pluginOrParser.name}" already applied.`)
           } else {
             installedParsers.add(pluginOrParser)
           }
         }
 
-        if (pluginOrParser && isFunction(pluginOrParser.install)) {
+        if (isFunction(pluginOrParser.install)) {
           const installer = pluginOrParser.install
 
-          await (installer as any)(context, ...args)
+          await (installer as any)(context, ...options)
         }
 
         return fabric
       },
-    } as Fabric<TOptions>
+    } as Fabric<T>
 
-    if (instance) {
-      instance(fabric)
+    if (init) {
+      init(fabric)
     }
 
     return fabric
   }
 
-  return creator
+  return create
 }

package/src/plugins/barrelPlugin.ts

@@ -24,14 +24,6 @@ type ExtendOptions = {
   writeEntry(options: WriteEntryOptions): Promise<void>
 }
 
-// biome-ignore lint/suspicious/noTsIgnore: production ready
-// @ts-ignore
-declare module '@kubb/fabric-core' {
-  interface Fabric {
-    writeEntry(options: WriteEntryOptions): Promise<void>
-  }
-}
-
 declare global {
   namespace Kubb {
     interface Fabric {

package/src/plugins/fsPlugin.ts

@@ -77,14 +77,6 @@ export async function write(path: string, data: string | undefined, options: { s
   return data
 }
 
-// biome-ignore lint/suspicious/noTsIgnore: production ready
-// @ts-ignore
-declare module '@kubb/fabric-core' {
-  interface Fabric {
-    write(options?: WriteOptions): Promise<void>
-  }
-}
-
 declare global {
   namespace Kubb {
     interface Fabric {

package/src/types.ts

@@ -1,3 +1,2 @@
-export type { DefineFabric } from './defineFabric.ts'
 export type { FabricConfig, FabricContext, FabricMode, FabricOptions } from './Fabric.ts'
 export * as KubbFile from './KubbFile.ts'

package/src/utils/AsyncEventEmitter.ts

@@ -1,27 +1,47 @@
 import { EventEmitter as NodeEventEmitter } from 'node:events'
+import type { FabricMode } from '../Fabric.ts'
+
+type Options = {
+  mode?: FabricMode
+  maxListener?: number
+}
 
 export class AsyncEventEmitter<TEvents extends Record<string, any>> {
-  constructor(maxListener = 100) {
+  constructor({ maxListener = 100, mode = 'sequential' }: Options = {}) {
     this.#emitter.setMaxListeners(maxListener)
+    this.#mode = mode
   }
+
   #emitter = new NodeEventEmitter()
+  #mode: FabricMode
 
   async emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void> {
     const listeners = this.#emitter.listeners(eventName) as Array<(...args: TEvents[TEventName]) => any>
 
     if (listeners.length === 0) {
-      return undefined
+      return
     }
 
-    await Promise.all(
-      listeners.map(async (listener) => {
+    if (this.#mode === 'sequential') {
+      // Run listeners one by one, in order
+      for (const listener of listeners) {
+        try {
+          await listener(...eventArgs)
+        } catch (err) {
+          console.error(`Error in listener for "${eventName}":`, err)
+        }
+      }
+    } else {
+      // Run all listeners concurrently
+      const promises = listeners.map(async (listener) => {
         try {
-          return await listener(...eventArgs)
+          await listener(...eventArgs)
         } catch (err) {
-          console.error(`Error in async listener for "${eventName}":`, err)
+          console.error(`Error in listener for "${eventName}":`, err)
         }
-      }),
-    )
+      })
+      await Promise.all(promises)
+    }
   }
 
   on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void {
@@ -39,6 +59,7 @@ export class AsyncEventEmitter<TEvents extends Record<string, any>> {
   off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void {
     this.#emitter.off(eventName, handler as any)
   }
+
   removeAll(): void {
     this.#emitter.removeAllListeners()
   }