@plugjs/plug 0.4.0 → 0.4.2

package/src/types.ts

@@ -38,21 +38,23 @@ export interface State {
  * The {@link Task} interface normalizes a task definition, associating it with
  * its build file, its sibling {@link Task}s and available _properties_.
  */
-export interface Task<T extends Result = Result, P extends Props = Record<string, string>> {
-  /** Simply invoke this task stand alone */
-  (props?: Partial<P>): Promise<T>
+export interface Task<T extends Result = Result> {
+  /** The unique ID of this {@link Task} */
+  readonly id: number,
+  /** The _original_ name of this task */
+  readonly name: string
   /** All _properties_ siblings to this {@link Task} */
   readonly props: Props
   /** All {@link Tasks} sibling to this {@link Task} */
   readonly tasks: Tasks
   /** The absolute file name where this {@link Task} was defined */
   readonly buildFile: AbsolutePath,
-  /** Invoke a task from in the context of a {@link Build} */
-  invoke(state: State, taskName: string): Promise<T>
   /** Other {@link Task}s hooked _before_ this one */
   readonly before: Task[]
   /** Other {@link Task}s hooked _after_ this one */
   readonly after: Task[]
+  /** Invoke a task from in the context of a {@link Build} */
+  invoke(state: State, taskName: string): Promise<T>
 }
 
 /**
@@ -64,6 +66,12 @@ 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>
 
+/** A callable, compiled {@link Task} from a {@link TaskDef} */
+export type TaskCall<D extends BuildDef = BuildDef, R extends Result = Result> = {
+  (props?: Partial<Props<D>>): Promise<R>
+  task: Task<R>
+}
+
 /* ========================================================================== *
  * TASKS AND PROPERTIES                                                       *
  * ========================================================================== */
@@ -75,12 +83,12 @@ export type Props<D extends BuildDef = BuildDef> = {
 
 /** A type identifying all _tasks_ in a {@link Build} */
 export type Tasks<D extends BuildDef = BuildDef> = {
-  readonly [ k in string & keyof D as D[k] extends TaskDef | Task ? k : never ] :
+  readonly [ k in string & keyof D as D[k] extends TaskDef | TaskCall ? k : never ] :
     D[k] extends TaskDef<infer R> ?
-      R extends void | undefined ? Task<undefined, Props<D>> :
-      R extends Pipe | Files ? Task<Files, Props<D>> :
+      R extends void | undefined ? TaskCall<D, undefined> :
+      R extends Pipe | Files ? TaskCall<D, Files> :
       never :
-    D[k] extends Task ? D[k] :
+    D[k] extends TaskCall ? D[k] :
     never
 }
 
@@ -93,7 +101,7 @@ export type Tasks<D extends BuildDef = BuildDef> = {
  * all its properties and tasks.
  */
 export interface BuildDef {
-  [ k : string ] : string | TaskDef | Task
+  [ k : string ] : string | TaskDef | TaskCall
 }
 
 /**
@@ -101,24 +109,45 @@ export interface BuildDef {
  * {@link TaskDef | task definitions }.
  */
 export type ThisBuild<D extends BuildDef> = {
-  readonly [ k in keyof D ] :
-    k extends string ?
-      D[k] extends TaskDef<infer R> ?
-        R extends Promise<undefined> | void | undefined ? () => Promise<undefined> :
-        R extends Pipe | Files ? () => Pipe :
-        never :
-      D[k] extends Task<infer R> ?
-        R extends undefined ? () => Promise<undefined> :
-        R extends Files ? () => Pipe :
-        never :
-      D[k] extends string ?
-        string :
+  readonly [ k in keyof D as k extends string ? k : never ] :
+    D[k] extends TaskDef<infer R> ?
+      R extends Promise<undefined> | void | undefined ? () => Promise<undefined> :
+      R extends Pipe | Files ? () => Pipe :
+      never :
+    D[k] extends TaskCall<any, infer R> ?
+      R extends undefined ? () => Promise<undefined> :
+      R extends Files ? () => Pipe :
       never :
+    D[k] extends string ?
+      string :
     never
 }
 
+/**
+ * Symbol indicating that an object is a {@link Build}.
+ *
+ * In a compiled {@link Build} this symbol will be associated with a function
+ * taking an array of strings (task names) and record of props to override
+ */
+export const buildMarker = Symbol.for('plugjs:plug:types:Build')
+
 /**
  * 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> = Tasks<D> & Props<D>
+export type Build<D extends BuildDef = BuildDef> = Props<D> & Tasks<D> & {
+  readonly [buildMarker]: (
+    tasks: readonly string[],
+    props?: Record<string, string | undefined>,
+  ) => Promise<void>
+}
+
+/** A type identifying all _task names_ in a {@link Build}. */
+export type BuildTasks<B extends Build> = string & keyof {
+  [ name in keyof B as B[name] extends Function ? name : never ] : any
+}
+
+/** A type identifying a subset of _properties_ for a {@link Build}. */
+export type BuildProps<B extends Build> = {
+  [ name in keyof B as B[name] extends string ? name : never ]? : string
+}

package/src/utils/diff.ts

@@ -3,7 +3,6 @@ import { inspect, isDeepStrictEqual } from 'node:util'
 
 import { assert } from '../asserts'
 import { $grn, $red, logOptions } from '../logging'
-import { getTypeOf } from './types'
 
 import type { InspectOptions } from 'node:util'
 
@@ -326,13 +325,9 @@ export function textDiff(
   let lhsLines: string[]
   let rhsLines: string[]
 
-  // Get the _real_ types of both arguments
-  const lhsType = getTypeOf(lhs)
-  const rhsType = getTypeOf(rhs)
-
   // If _both_ arguments are strings, then just split and compare, otherwise
   // we nuse NodeJS' inspect to prep their string version
-  if ((lhsType === 'string') && (rhsType === 'string')) {
+  if ((typeof lhs === 'string') && (typeof rhs === 'string')) {
     lhsLines = lhs.split('\n')
     rhsLines = rhs.split('\n')
   } else {

package/src/utils/singleton.ts

@@ -0,0 +1,19 @@
+/**
+ * Get the instance of a _singleton_ variable.
+ *
+ * Sometimes we need unique instances _per process_ (for example our async
+ * context). The problem is that the code might get called from two (or three)
+ * different versions of this file: the .cjs transpiled code, the .mjs
+ * transpiled one, or the .ts dynamically transpiled by our dynamic loader.
+ *
+ * A _singleton_ associates an instance with a symbol in `globalThis` and ensure
+ * there is only _one_ instance per process (per `globalThis`).
+ */
+export function getSingleton<T>(symbol: symbol, factory: () => T): T {
+  const anyGlobalThis = globalThis as any
+  if (anyGlobalThis[symbol]) return anyGlobalThis[symbol] as T
+
+  const value = factory()
+  Object.defineProperty(anyGlobalThis, symbol, { value })
+  return value
+}

package/src/utils.ts

@@ -2,5 +2,5 @@ export * from './utils/diff'
 export * from './utils/exec'
 export * from './utils/match'
 export * from './utils/options'
-export * from './utils/types'
+export * from './utils/singleton'
 export * from './utils/walk'

package/dist/utils/types.cjs.map

@@ -1,6 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/utils/types.ts"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMO,SAAS,UAAU,MAA0B;AAClD,MAAI,MAAM,QAAQ,IAAI;AAAG,WAAO;AAChC,MAAI,SAAS;AAAM,WAAO;AAC1B,SAAO,OAAO;AAChB;",
-  "names": []
-}

package/dist/utils/types.d.ts

@@ -1,4 +0,0 @@
-/** A type adding the values `null` or `array` to the result of `typeof` */
-export type BasicType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'null' | 'array';
-/** Get the _real_ type of a value, including `null` or `array` */
-export declare function getTypeOf(what: unknown): BasicType;

package/dist/utils/types.mjs

@@ -1,12 +0,0 @@
-// utils/types.ts
-function getTypeOf(what) {
-  if (Array.isArray(what))
-    return "array";
-  if (what === null)
-    return "null";
-  return typeof what;
-}
-export {
-  getTypeOf
-};
-//# sourceMappingURL=types.mjs.map

package/dist/utils/types.mjs.map

@@ -1,6 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/utils/types.ts"],
-  "mappings": ";AAMO,SAAS,UAAU,MAA0B;AAClD,MAAI,MAAM,QAAQ,IAAI;AAAG,WAAO;AAChC,MAAI,SAAS;AAAM,WAAO;AAC1B,SAAO,OAAO;AAChB;",
-  "names": []
-}

package/src/utils/types.ts

@@ -1,11 +0,0 @@
-/** A type adding the values `null` or `array` to the result of `typeof` */
-export type BasicType =
-  | 'string' | 'number' | 'bigint' | 'boolean' | 'symbol'
-  | 'undefined' | 'object' | 'function' | 'null' | 'array'
-
-/** Get the _real_ type of a value, including `null` or `array` */
-export function getTypeOf(what: unknown): BasicType {
-  if (Array.isArray(what)) return 'array'
-  if (what === null) return 'null'
-  return typeof what
-}