@plugjs/plug 0.0.15 → 0.0.16

package/src/pipe.ts

@@ -1,9 +1,17 @@
-import type { Files } from './files'
-import { getLogger, Logger } from './log'
-import { AbsolutePath, getAbsoluteParent, getCurrentWorkingDirectory, resolveAbsolutePath } from './paths'
+import {
+  AbsolutePath,
+  commonPath,
+  getAbsoluteParent,
+  getCurrentWorkingDirectory,
+  resolveAbsolutePath,
+} from './paths'
 
-import { ForkingPlug } from './fork'
 import { sep } from 'path'
+import { assert } from './assert'
+import { requireContext } from './async'
+import { Files } from './files'
+import { ForkingPlug } from './fork'
+import { getLogger, Logger } from './log'
 
 /* ========================================================================== *
  * PLUGS                                                                      *
@@ -50,6 +58,14 @@ export class Context {
     this.log = getLogger(taskName)
   }
 
+  /**
+   * Resolve a (set of) path(s) in this {@link Context}.
+   *
+   * If the path (or first component thereof) starts with `@...`, then the
+   * resolved path will be relative to the directory containing the build file
+   * where the current task was defined, otherwise it will be relative to the
+   * current working directory.
+   */
   resolve(path: string, ...paths: string[]): AbsolutePath {
     // Paths starting with "@" are relative to the build file directory
     if (path && path.startsWith('@')) {
@@ -79,16 +95,72 @@ abstract class PipeProto {
 }
 
 /**
- * The {@link Pipe} abstract defines processing pipeline where multiple
+ * The {@link Pipe} class defines processing pipeline where multiple
  * {@link Plug}s can transform lists of {@link Files}.
  */
-export abstract class Pipe extends PipeProto {
-  abstract plug(plug: Plug<Files>): Pipe
-  abstract plug(plug: PlugFunction<Files>): Pipe
-  abstract plug(plug: Plug<void | undefined>): Promise<undefined>
-  abstract plug(plug: PlugFunction<void | undefined>): Promise<undefined>
+export class Pipe extends PipeProto {
+  constructor(
+      private readonly _context: Context,
+      private readonly _run: () => Promise<Files>,
+  ) {
+    super()
+  }
 
-  abstract run(): Promise<Files>
+  plug(plug: Plug<Files>): Pipe
+  plug(plug: PlugFunction<Files>): Pipe
+  plug(plug: Plug<void | undefined>): Promise<undefined>
+  plug(plug: PlugFunction<void | undefined>): Promise<undefined>
+  plug(arg: Plug<PlugResult> | PlugFunction<PlugResult>): Pipe | Promise<undefined> {
+    const plug = typeof arg === 'function' ? { pipe: arg } : arg
+
+    const parent = this
+    const context = this._context
+    return new Pipe(context, async (): Promise<Files> => {
+      const previous = await parent.run()
+      const current = await plug.pipe(previous, context)
+      assert(current, 'Unable to extend pipe')
+      return current
+    })
+  }
+
+  run(): Promise<Files> {
+    return this._run()
+  }
+
+  /**
+   * Merge the results of several {@link Pipe}s into a single one.
+   *
+   * Merging is performed _in parallel_. When serial execution is to be desired,
+   * we can merge the awaited _result_ of the {@link Pipe}.
+   *
+   * For example:
+   *
+   * ```
+   * const pipe: Pipe = merge([
+   *   // other tasks return `Pipe & Promise<Files>` so we can
+   *   // direcrly await their result without invoking `run()`
+   *   await this.anotherTask1(),
+   *   await this.anotherTask2(),
+   * ])
+   * ```
+   */
+  static merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
+    const context = requireContext()
+    return new Pipe(context, async (): Promise<Files> => {
+      if (pipes.length === 0) return Files.builder(getCurrentWorkingDirectory()).build()
+
+      const [ first, ...other ] = await Promise.all(pipes.map((pipe) => {
+        return 'run' in pipe ? pipe.run() : pipe
+      }))
+
+      const firstDir = first.directory
+      const otherDirs = other.map((f) => f.directory)
+
+      const directory = commonPath(firstDir, ...otherDirs)
+
+      return Files.builder(directory).merge(first, ...other).build()
+    })
+  }
 }
 
 /* ========================================================================== *

package/src/plugs/copy.ts

@@ -95,7 +95,7 @@ install('copy', class Copy implements Plug<Files> {
       }
 
       /* Record this file */
-      builder.add(relative)
+      builder.add(target)
     }
 
     const result = builder.build()

package/src/plugs/debug.ts

@@ -1,11 +1,11 @@
 import { Files } from '../files'
-import { $gry, $p, $und } from '../log'
-import { install, Plug, Context } from '../pipe'
+import { $gry, $p, $und, $ylw } from '../log'
+import { install, Plug, Context, PipeParameters } from '../pipe'
 
 declare module '../pipe' {
   export interface Pipe {
     /** Log some info about the current {@link Files} being passed around. */
-    debug(): Pipe
+    debug(title?: string): Pipe
   }
 }
 
@@ -15,8 +15,15 @@ declare module '../pipe' {
 
 /** Writes some info about the current {@link Files} being passed around. */
 install('debug', class Debug implements Plug<Files> {
+  private readonly _title: string
+
+  constructor(...args: PipeParameters<'debug'>) {
+    const [ title = 'Debugging' ] = args
+    this._title = title
+  }
+
   async pipe(files: Files, context: Context): Promise<Files> {
-    context.log.notice('Debugging', files.length, 'files')
+    context.log.notice(this._title, `${$gry('(')}${$ylw(files.length)} ${$gry('files)')}`)
     context.log.notice('-        base dir:', $p(context.resolve('@')))
     context.log.notice('-  build file dir:', $p(context.resolve('.')))
     context.log.notice('-       files dir:', $p(files.directory))

package/src/types.ts

@@ -51,7 +51,7 @@ export interface Task<T extends Result = Result> {
  * The {@link TaskResult} type identifies _what_ can be returned by a
  * {@link TaskDef | _task definition_}.
  */
-export type TaskResult = Pipe | Promise<undefined> | Files | void | undefined
+export type TaskResult = Pipe | Files | void | undefined
 
 /** The {@link TaskDef} type identifies the _definition_ of a task. */
 export type TaskDef<R extends TaskResult = TaskResult> = () => R | Promise<R>
@@ -70,9 +70,7 @@ export type Tasks<D extends BuildDef = BuildDef> = {
   readonly [ k in string & keyof D as D[k] extends TaskDef | Task ? k : never ] :
     D[k] extends TaskDef<infer R> ?
       R extends void | undefined ? Task<undefined> :
-      R extends Promise<undefined> ? Task<undefined> :
-      R extends Pipe ? Task<Files> :
-      R extends Files ? Task<Files> :
+      R extends Pipe | Files ? Task<Files> :
       never :
     D[k] extends Task ? D[k] :
     never
@@ -83,9 +81,8 @@ export type Tasks<D extends BuildDef = BuildDef> = {
  * ========================================================================== */
 
 /**
- * The {@link BuildDef} interface describes the _definition_ of a
- * {@link Context}, that is the object passed to {@link build} to produce
- * a {@link Build}.
+ * The {@link BuildDef} interface describes the _definition_ of a {@link Build},
+ * all its properties and tasks.
  */
 export interface BuildDef {
   [ k : string ] : string | TaskDef | Task
@@ -116,8 +113,4 @@ export type ThisBuild<D extends BuildDef> = {
  * The {@link Build} type represents the collection of {@link Task}s
  * and _properties_ compiled from a {@link BuildDef | build definition}.
  */
-export type Build<
-  D extends BuildDef = BuildDef,
-  T extends Tasks<D> = Tasks<D>,
-  P extends Props<D> = Props<D>,
-> = T & P
+export type Build<D extends BuildDef = BuildDef> = Tasks<D> & Props<D>