@warp-drive/build-config 5.8.0-alpha.4 → 5.8.0-alpha.6

package/declarations/index.d.ts

@@ -1,7 +1,26 @@
 import { getDeprecations } from "./-private/utils/deprecations.js";
 import { getFeatures } from "./-private/utils/features.js";
 import * as LOGGING from "./debugging.js";
-export type WarpDriveConfig = {
+import type { PluginItem } from "@babel/core";
+/**
+* Create the Babel plugin for WarpDrive
+*
+* Note: If your project already uses [@embroider/macros](https://www.npmjs.com/package/@embroider/macros)
+* then you should use {@link setConfig} instead of this function.
+*
+* @param options WarpDrive configuration options
+* @returns An array of Babel plugins
+*/
+export declare function babelPlugin(options: WarpDriveConfig): {
+	gts: Function[];
+	js: PluginItem[];
+};
+/**
+* Build Configuration options for WarpDrive that
+* allow adjusting logging, deprecations, canary features
+* and optional features.
+*/
+export interface WarpDriveConfig {
 	/**
 	* An object of key/value pairs of logging flags
 	*
@@ -44,6 +63,13 @@ export type WarpDriveConfig = {
 	* `5.3` will remove all the support for the deprecated
 	* features for associated deprecations.
 	*
+	* :::caution **Universal Apps**
+	* This value should be at least `5.6` for universal/non-ember
+	* applications as that was the first version that builds
+	* without any ember-source dependencies provided all deprecations
+	* are resolved.
+	* :::
+	*
 	* See {@link DEPRECATIONS | deprecations} for more details.
 	*/
 	compatWith?: `${number}.${number}`;
@@ -81,8 +107,8 @@ export type WarpDriveConfig = {
 	* @private
 	*/
 	forceMode?: "testing" | "production" | "development";
-};
-type InternalWarpDriveConfig = {
+}
+interface InternalWarpDriveConfig {
 	debug: typeof LOGGING;
 	polyfillUUID: boolean;
 	includeDataAdapter: boolean;
@@ -95,7 +121,57 @@ type InternalWarpDriveConfig = {
 		PRODUCTION: boolean;
 		DEBUG: boolean;
 	};
-};
+}
+/**
+* Sets the build configuration for WarpDrive that ensures
+* environment specific behaviors are activated/deactivated
+* and enables adjusting log instrumentation, removing code
+* that supports deprecated features, enabling canary features
+* and enabling/disabling optional features.
+*
+* The library uses [@embroider/macros](https://www.npmjs.com/package/@embroider/macros)
+* to perform this final configuration code transform.
+*
+* This is a low level API for configuring WarpDrive. If your
+* project does not use `@embroider/macros` then you should use
+* {@link babelPlugin} instead of this function.
+*
+* ### Example
+*
+* ```ts
+* import { setConfig } from '@warp-drive/core/build-config';
+* import { buildMacros } from '@embroider/macros/babel';
+*
+* const Macros = buildMacros({
+*   configure: (config) => {
+*     setConfig(config, {
+*       compatWith: '5.6'
+*     });
+*   },
+* });
+*
+* export default {
+*   plugins: [
+*     // babel-plugin-debug-macros is temporarily needed
+*     // to convert deprecation/warn calls into console.warn
+*     [
+*       'babel-plugin-debug-macros',
+*       {
+*         flags: [],
+*
+*         debugTools: {
+*           isDebug: true,
+*           source: '@ember/debug',
+*           assertPredicateIndex: 1,
+*         },
+*       },
+*       'ember-data-specific-macros-stripping-test',
+*     ],
+*     ...Macros.babelMacros,
+*   ],
+* };
+* ```
+*/
 export declare function setConfig(macros: object, config: WarpDriveConfig): void;
 export declare function setConfig(context: object, appRoot: string, config: WarpDriveConfig): void;
 export {};

package/dist/cjs-set-config.cjs

@@ -7,6 +7,7 @@ const semver = require('semver');
 const fs = require('fs');
 const path = require('path');
 const url = require('url');
+require('@embroider/macros/src/babel.js');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function getEnv(forceMode) {
@@ -593,17 +594,75 @@ function createLoggingConfig(env, debug) {
  * - {@link WarpDriveConfig.includeDataAdapterInProduction | includeDataAdapterInProduction}
  * - {@link WarpDriveConfig.compatWith | compatWith}
  *
- *
- *
  * @module
  */
+
 const _MacrosConfig = EmbroiderMacros.MacrosConfig;
+
+/**
+ * Build Configuration options for WarpDrive that
+ * allow adjusting logging, deprecations, canary features
+ * and optional features.
+ */
+
 function recastMacrosConfig(macros) {
   if (!('globalConfig' in macros)) {
     throw new Error('Expected MacrosConfig to have a globalConfig property');
   }
   return macros;
 }
+
+/**
+ * Sets the build configuration for WarpDrive that ensures
+ * environment specific behaviors are activated/deactivated
+ * and enables adjusting log instrumentation, removing code
+ * that supports deprecated features, enabling canary features
+ * and enabling/disabling optional features.
+ *
+ * The library uses [@embroider/macros](https://www.npmjs.com/package/@embroider/macros)
+ * to perform this final configuration code transform.
+ *
+ * This is a low level API for configuring WarpDrive. If your
+ * project does not use `@embroider/macros` then you should use
+ * {@link babelPlugin} instead of this function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { setConfig } from '@warp-drive/core/build-config';
+ * import { buildMacros } from '@embroider/macros/babel';
+ *
+ * const Macros = buildMacros({
+ *   configure: (config) => {
+ *     setConfig(config, {
+ *       compatWith: '5.6'
+ *     });
+ *   },
+ * });
+ *
+ * export default {
+ *   plugins: [
+ *     // babel-plugin-debug-macros is temporarily needed
+ *     // to convert deprecation/warn calls into console.warn
+ *     [
+ *       'babel-plugin-debug-macros',
+ *       {
+ *         flags: [],
+ *
+ *         debugTools: {
+ *           isDebug: true,
+ *           source: '@ember/debug',
+ *           assertPredicateIndex: 1,
+ *         },
+ *       },
+ *       'ember-data-specific-macros-stripping-test',
+ *     ],
+ *     ...Macros.babelMacros,
+ *   ],
+ * };
+ * ```
+ */
+
 function setConfig(context, appRootOrConfig, config) {
   const isEmberClassicUsage = arguments.length === 3;
   const macros = recastMacrosConfig(isEmberClassicUsage ? _MacrosConfig.for(context, appRootOrConfig) : context);

package/dist/index.js

@@ -5,6 +5,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { C as CURRENT_FEATURES } from './canary-features-BM0to_ys.js';
 import { L as LOGGING } from './debugging-DgRWKeE4.js';
+import { buildMacros } from '@embroider/macros/src/babel.js';
 
 function getEnv(forceMode) {
   const FORCE_TESTING = forceMode === 'testing' || forceMode === 'development' || forceMode === 'debug';
@@ -229,17 +230,115 @@ function createLoggingConfig(env, debug) {
  * - {@link WarpDriveConfig.includeDataAdapterInProduction | includeDataAdapterInProduction}
  * - {@link WarpDriveConfig.compatWith | compatWith}
  *
+ * @module
+ */
+
+
+/**
+ * Create the Babel plugin for WarpDrive
  *
+ * Note: If your project already uses [@embroider/macros](https://www.npmjs.com/package/@embroider/macros)
+ * then you should use {@link setConfig} instead of this function.
  *
- * @module
+ * @param options WarpDrive configuration options
+ * @returns An array of Babel plugins
  */
+function babelPlugin(options) {
+  const macros = buildMacros({
+    configure: config => {
+      setConfig(config, options);
+    }
+  });
+  const env = getEnv(options.forceMode);
+  return {
+    gts: macros.templateMacros,
+    js: [
+    // babel-plugin-debug-macros is temporarily needed
+    // to convert deprecation/warn calls into console.warn
+    [resolve('babel-plugin-debug-macros'), {
+      flags: [],
+      debugTools: {
+        isDebug: env.DEBUG,
+        source: '@ember/debug',
+        assertPredicateIndex: 1
+      }
+    }, 'ember-data-specific-macros-stripping-test'], ...macros.babelMacros]
+  };
+}
+function resolve(module) {
+  const filePath = import.meta.resolve(module);
+  const file = filePath.replace('/node_modules/.vite-temp/', '/');
+  if (file.startsWith('file://')) {
+    return file.slice(7);
+  }
+  return file;
+}
 const _MacrosConfig = EmbroiderMacros.MacrosConfig;
+
+/**
+ * Build Configuration options for WarpDrive that
+ * allow adjusting logging, deprecations, canary features
+ * and optional features.
+ */
+
 function recastMacrosConfig(macros) {
   if (!('globalConfig' in macros)) {
     throw new Error('Expected MacrosConfig to have a globalConfig property');
   }
   return macros;
 }
+
+/**
+ * Sets the build configuration for WarpDrive that ensures
+ * environment specific behaviors are activated/deactivated
+ * and enables adjusting log instrumentation, removing code
+ * that supports deprecated features, enabling canary features
+ * and enabling/disabling optional features.
+ *
+ * The library uses [@embroider/macros](https://www.npmjs.com/package/@embroider/macros)
+ * to perform this final configuration code transform.
+ *
+ * This is a low level API for configuring WarpDrive. If your
+ * project does not use `@embroider/macros` then you should use
+ * {@link babelPlugin} instead of this function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { setConfig } from '@warp-drive/core/build-config';
+ * import { buildMacros } from '@embroider/macros/babel';
+ *
+ * const Macros = buildMacros({
+ *   configure: (config) => {
+ *     setConfig(config, {
+ *       compatWith: '5.6'
+ *     });
+ *   },
+ * });
+ *
+ * export default {
+ *   plugins: [
+ *     // babel-plugin-debug-macros is temporarily needed
+ *     // to convert deprecation/warn calls into console.warn
+ *     [
+ *       'babel-plugin-debug-macros',
+ *       {
+ *         flags: [],
+ *
+ *         debugTools: {
+ *           isDebug: true,
+ *           source: '@ember/debug',
+ *           assertPredicateIndex: 1,
+ *         },
+ *       },
+ *       'ember-data-specific-macros-stripping-test',
+ *     ],
+ *     ...Macros.babelMacros,
+ *   ],
+ * };
+ * ```
+ */
+
 function setConfig(context, appRootOrConfig, config) {
   const isEmberClassicUsage = arguments.length === 3;
   const macros = recastMacrosConfig(isEmberClassicUsage ? _MacrosConfig.for(context, appRootOrConfig) : context);
@@ -284,4 +383,4 @@ function setConfig(context, appRootOrConfig, config) {
   macros.setGlobalConfig(import.meta.filename, 'WarpDrive', finalizedConfig);
 }
 
-export { setConfig };
+export { babelPlugin, setConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/build-config",
-  "version": "5.8.0-alpha.4",
+  "version": "5.8.0-alpha.6",
   "description": "Provides Build Configuration for projects using WarpDrive or EmberData",
   "keywords": [
     "ember-data",
@@ -36,13 +36,14 @@
     }
   },
   "dependencies": {
+    "babel-plugin-debug-macros": "^2.0.0",
     "@embroider/macros": "^1.18.1",
     "@embroider/addon-shim": "^1.10.0",
     "babel-import-util": "^2.1.1",
     "semver": "^7.7.2"
   },
   "devDependencies": {
-    "@warp-drive/internal-config": "5.8.0-alpha.4",
+    "@warp-drive/internal-config": "5.8.0-alpha.6",
     "@types/babel__core": "^7.20.5",
     "@types/node": "^20.19.11",
     "@babel/plugin-transform-typescript": "^7.28.0",