Add @parcel/macros package with macro context TS definitions (#9544)

packages/transformers/js/src/JSTransformer.js

@@ -165,6 +165,7 @@ type MacroAsset = {|
   content: string,
 |};
 
+// NOTE: Make sure this is in sync with the TypeScript definition in the @parcel/macros package.
 type MacroContext = {|
   addAsset(asset: MacroAsset): void,
   invalidateOnFileChange(FilePath): void,

packages/utils/macros/macros.d.ts

@@ -0,0 +1,42 @@
+export interface MacroContext {
+  /** Adds an asset as a dependency of the JS module that called this macro. */
+  addAsset(asset: MacroAsset): void;
+  /** Invalidate the macro call whenever the given file changes. */
+  invalidateOnFileChange(filePath: string): void;
+  /** Invalidate the macro call when a file matching the given pattern is created. */
+  invalidateOnFileCreate(options: FileCreateInvalidation): void;
+  /** Invalidate the macro whenever the given environment variable changes. */
+  invalidateOnEnvChange(env: string): void;
+  /** Invalidate the macro whenever Parcel restarts. */
+  invalidateOnStartup(): void;
+  /** Invalidate the macro on every build. */
+  invalidateOnBuild(): void;
+}
+
+export interface MacroAsset {
+  /** The type of the asset (e.g. `'css'`). */
+  type: string;
+  /** The content of the asset. */
+  content: string;
+}
+
+export type FileCreateInvalidation =
+  | FileInvalidation
+  | GlobInvalidation
+  | FileAboveInvalidation;
+
+/** Invalidate when a file matching a glob is created. */
+export interface GlobInvalidation {
+  glob: string;
+}
+
+/** Invalidate when a specific file is created. */
+export interface FileInvalidation {
+  filePath: string;
+}
+
+/** Invalidate when a file of a specific name is created above a certain directory in the hierarchy. */
+export interface FileAboveInvalidation {
+  fileName: string;
+  aboveFilePath: string;
+}

packages/utils/macros/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@parcel/macros",
+  "version": "2.11.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/parcel"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parcel-bundler/parcel.git"
+  },
+  "types": "macros.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">= 12.0.0",
+    "parcel": "^2.11.0"
+  }
+}