@warp-drive/build-config 5.4.0-alpha.150 → 5.4.0-alpha.152

package/dist/babel-macros.js

@@ -1,5 +1,5 @@
-import { L as LOGGING } from './debugging-PCb4hczb.js';
-import { C as CURRENT_FEATURES } from './canary-features-BzGSGY5j.js';
+import { L as LOGGING } from './debugging-CX6Ul3W_.js';
+import { C as CURRENT_FEATURES } from './canary-features-Bpa1abyy.js';
 import { C as CURRENT_DEPRECATIONS } from './deprecations-ChFQtx-4.js';
 
 const features = Object.keys(CURRENT_FEATURES);

package/dist/{canary-features-BzGSGY5j.js → canary-features-Bpa1abyy.js}

@@ -1,4 +1,10 @@
 /**
+ *
+ * @module @warp-drive/build-config
+ */
+
+/**
+ *
  * ## Canary Features
  *
  * EmberData allows users to test features that are implemented but not yet
@@ -31,24 +37,22 @@
  *
  * ```cli
  * # Activate a single flag
- * EMBER_DATA_FEATURE_OVERRIDE=SOME_FLAG ember build
+ * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG ember build
  *
  * # Activate multiple flags by separating with commas
- * EMBER_DATA_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build
+ * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build
  *
  * # Activate all flags
- * EMBER_DATA_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build
+ * WARP_DRIVE_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build
  * ```
  *
  * or by setting the appropriate flag in your `ember-cli-build` file:
  *
  * ```ts
- * let app = new EmberApp(defaults, {
- *   emberData: {
- *     features: {
- *       SAMPLE_FEATURE_FLAG: false // utliize existing behavior, strip code for the new feature
- *       OTHER_FEATURE_FLAG: true // utilize this new feature, strip code for the older behavior
- *     }
+ * setConfig(app, __dirname, {
+ *   features: {
+ *     SAMPLE_FEATURE_FLAG: false // utliize existing behavior, strip code for the new feature
+ *     OTHER_FEATURE_FLAG: true // utilize this new feature, strip code for the older behavior
  *   }
  * })
  * ```
@@ -70,21 +74,17 @@
  * }
  * ```
  *
-   @module @warp-drive/build-config/canary-features
-   @main @warp-drive/build-config/canary-features
- */
-/**
-  This is the current list of features used at build time for canary releases.
-  If empty there are no features currently gated by feature flags.
-
-  The valid values are:
-
-  - `true` | The feature is **enabled** at all times, and cannot be disabled.
-  - `false` | The feature is **disabled** at all times, and cannot be enabled.
-  - `null` | The feature is **disabled by default**, but can be enabled via configuration.
-
-  @class CanaryFeatureFlags
-  @public
+ * The current list of features used at build time for canary releases is defined below.
+ * If empty there are no features currently gated by feature flags.
+ *
+ * The valid values are:
+ *
+ *  - `true` | The feature is **enabled** at all times, and cannot be disabled.
+ *  - `false` | The feature is **disabled** at all times, and cannot be enabled.
+ *  - `null` | The feature is **disabled by default**, but can be enabled via configuration.
+ *
+ * @class CanaryFeatures
+ * @public
 */
 const SAMPLE_FEATURE_FLAG = null;
 
@@ -94,4 +94,4 @@ const CURRENT_FEATURES = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.definePr
 }, Symbol.toStringTag, { value: 'Module' }));
 
 export { CURRENT_FEATURES as C, SAMPLE_FEATURE_FLAG as S };
-//# sourceMappingURL=canary-features-BzGSGY5j.js.map
+//# sourceMappingURL=canary-features-Bpa1abyy.js.map

package/dist/canary-features-Bpa1abyy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canary-features-Bpa1abyy.js","sources":["../src/canary-features.ts"],"sourcesContent":["/**\n *\n * @module @warp-drive/build-config\n */\n\n/**\n *\n * ## Canary Features\n *\n * EmberData allows users to test features that are implemented but not yet\n * available even in canary.\n *\n * Typically these features represent work that might introduce a new concept,\n * new API, change an API, or risk an unintended change in behavior to consuming\n * applications.\n *\n * Such features have their implementations guarded by a \"feature flag\", and the\n * flag is only activated once the core-data team is prepared to ship the work\n * in a canary release.\n *\n * ### Installing Canary\n *\n * To test a feature you MUST be using a canary build. Canary builds are published\n * to `npm` and can be installed using a precise tag (such as `ember-data@3.16.0-alpha.1`)\n * or by installing the latest dist-tag published to the `canary` channel using your javascript\n * package manager of choice. For instance with [pnpm](https://pnpm.io/)\n\n  ```cli\n  pnpm add ember-data@canary\n  ```\n *\n * ### Activating a Canary Feature\n *\n * Once you have installed canary, feature-flags can be activated at build-time\n *\n * by setting an environment variable:\n *\n * ```cli\n * # Activate a single flag\n * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG ember build\n *\n * # Activate multiple flags by separating with commas\n * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build\n *\n * # Activate all flags\n * WARP_DRIVE_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build\n * ```\n *\n * or by setting the appropriate flag in your `ember-cli-build` file:\n *\n * ```ts\n * setConfig(app, __dirname, {\n *   features: {\n *     SAMPLE_FEATURE_FLAG: false // utliize existing behavior, strip code for the new feature\n *     OTHER_FEATURE_FLAG: true // utilize this new feature, strip code for the older behavior\n *   }\n * })\n * ```\n *\n * **The \"off\" branch of feature-flagged code is always stripped from production builds.**\n *\n * The list of available feature-flags is located [here](https://github.com/emberjs/data/tree/main/packages/build-config/src/virtual/canary-features.ts \"List of EmberData FeatureFlags\")\n *\n *\n * ### Preparing a Project to use a Canary Feature\n *\n * For most projects, simple version detection should be enough.\n * Using the provided version compatibility helpers from [embroider-macros](https://github.com/embroider-build/embroider/tree/main/packages/macros#readme)\n * the following can be done:\n *\n * ```js\n * if (macroCondition(dependencySatisfies('@ember-data/store', '5.0'))) {\n *   // do thing\n * }\n * ```\n *\n * The current list of features used at build time for canary releases is defined below.\n * If empty there are no features currently gated by feature flags.\n *\n * The valid values are:\n *\n *  - `true` | The feature is **enabled** at all times, and cannot be disabled.\n *  - `false` | The feature is **disabled** at all times, and cannot be enabled.\n *  - `null` | The feature is **disabled by default**, but can be enabled via configuration.\n *\n * @class CanaryFeatures\n * @public\n*/\nexport const SAMPLE_FEATURE_FLAG: boolean | null = null;\n"],"names":["SAMPLE_FEATURE_FLAG"],"mappings":"AAAA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,mBAAmC,GAAG;;;;;;;;;"}

package/dist/canary-features.js

@@ -1,2 +1,2 @@
-export { S as SAMPLE_FEATURE_FLAG } from './canary-features-BzGSGY5j.js';
+export { S as SAMPLE_FEATURE_FLAG } from './canary-features-Bpa1abyy.js';
 //# sourceMappingURL=canary-features.js.map

package/dist/cjs-set-config.cjs

@@ -32,6 +32,9 @@ function getEnv() {
   };
 }
 
+/**
+ * @module @warp-drive/build-config
+ */
 // ========================
 // FOR CONTRIBUTING AUTHORS
 //
@@ -51,7 +54,7 @@ function getEnv() {
 //
 
 /**
- * ## Deprecations
+ * ## Deprecation Management
  *
  * EmberData allows users to opt-in and remove code that exists to support deprecated
  * behaviors.
@@ -69,54 +72,26 @@ function getEnv() {
  * with `3.12`. This would remove any deprecations that were present in or before `3.12`
  * but keep support for anything deprecated in or above `3.13`.
  *
- * ### Configuring Compatibility
- *
- * To configure your compatibility version, set the `compatWith` to the version you
- * are compatible with on the `emberData` config in your `ember-cli-build.js` file.
- *
- * ```js
- * const { setConfig } = await import('@warp-drive/build-config');
- *
- * let app = new EmberApp(defaults, {});
- *
- * setConfig(app, __dirname, { compatWith: '3.12' });
- * ```
- *
- * Alternatively, individual deprecations can be resolved (and thus have its support stripped)
- * via one of the flag names listed below. For instance, given a flag named `DEPRECATE_FOO_BEHAVIOR`.
- *
- * This capability is interopable with `compatWith`. You may set `compatWith` and then selectively resolve
- * additional deprecations, or set compatWith and selectively un-resolve specific deprecations.
- *
- * Note: EmberData does not test against permutations of deprecations being stripped, our tests run against
- * "all deprecated code included" and "all deprecated code removed". Unspecified behavior may sometimes occur
- * when removing code for only some deprecations associated to a version number.
- *
- * ```js
- * const { setConfig } = await import('@warp-drive/build-config');
- *
- * let app = new EmberApp(defaults, {});
+ * You may also specify that specific deprecations are resolved. These approaches
+ * may be used together.
  *
+ * ```ts
  * setConfig(app, __dirname, {
+ *   // declare that all deprecations through "5.0" have been fully resolved
+ *   compatWith: '5.0',
+ *
+ *   // mark individual deprecations as resolved by setting them to `false`
  *   deprecations: {
- *     DEPRECATE_FOO_BEHAVIOR: false // set to false to strip this code
- *     DEPRECATE_BAR_BEHAVIOR: true // force to true to not strip this code
- *   }
+ *     // resolve individual deprecations here
+ *   },
  * });
  * ```
  *
- * The complete list of which versions specific deprecations will be removed in
- * can be found [here](https://github.com/emberjs/data/blob/main/packages/build-config/src/virtual/deprecation-versions.ts "List of EmberData Deprecations")
- *
- * @module @warp-drive/build-config/deprecations
- * @main @warp-drive/build-config/deprecations
- */
-
-/**
- * The following list represents deprecations currently active.
- *
- * Some deprecation flags guard multiple deprecation IDs. All
- * associated IDs are listed.
+ * > [!TIP]
+ * > EmberData does not test against permutations of deprecations
+ * > being stripped, our tests run against "all deprecated code included"
+ * > and "all deprecated code removed". Unspecified behavior may sometimes occur
+ * > when removing code for only some deprecations associated to a version number.
  *
  * @class CurrentDeprecations
  * @public
@@ -570,6 +545,12 @@ function getDeprecations(compatVersion, deprecations) {
 }
 
 /**
+ *
+ * @module @warp-drive/build-config
+ */
+
+/**
+ *
  * ## Canary Features
  *
  * EmberData allows users to test features that are implemented but not yet
@@ -602,24 +583,22 @@ function getDeprecations(compatVersion, deprecations) {
  *
  * ```cli
  * # Activate a single flag
- * EMBER_DATA_FEATURE_OVERRIDE=SOME_FLAG ember build
+ * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG ember build
  *
  * # Activate multiple flags by separating with commas
- * EMBER_DATA_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build
+ * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build
  *
  * # Activate all flags
- * EMBER_DATA_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build
+ * WARP_DRIVE_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build
  * ```
  *
  * or by setting the appropriate flag in your `ember-cli-build` file:
  *
  * ```ts
- * let app = new EmberApp(defaults, {
- *   emberData: {
- *     features: {
- *       SAMPLE_FEATURE_FLAG: false // utliize existing behavior, strip code for the new feature
- *       OTHER_FEATURE_FLAG: true // utilize this new feature, strip code for the older behavior
- *     }
+ * setConfig(app, __dirname, {
+ *   features: {
+ *     SAMPLE_FEATURE_FLAG: false // utliize existing behavior, strip code for the new feature
+ *     OTHER_FEATURE_FLAG: true // utilize this new feature, strip code for the older behavior
  *   }
  * })
  * ```
@@ -641,21 +620,17 @@ function getDeprecations(compatVersion, deprecations) {
  * }
  * ```
  *
-   @module @warp-drive/build-config/canary-features
-   @main @warp-drive/build-config/canary-features
- */
-/**
-  This is the current list of features used at build time for canary releases.
-  If empty there are no features currently gated by feature flags.
-
-  The valid values are:
-
-  - `true` | The feature is **enabled** at all times, and cannot be disabled.
-  - `false` | The feature is **disabled** at all times, and cannot be enabled.
-  - `null` | The feature is **disabled by default**, but can be enabled via configuration.
-
-  @class CanaryFeatureFlags
-  @public
+ * The current list of features used at build time for canary releases is defined below.
+ * If empty there are no features currently gated by feature flags.
+ *
+ * The valid values are:
+ *
+ *  - `true` | The feature is **enabled** at all times, and cannot be disabled.
+ *  - `false` | The feature is **disabled** at all times, and cannot be enabled.
+ *  - `null` | The feature is **disabled by default**, but can be enabled via configuration.
+ *
+ * @class CanaryFeatures
+ * @public
 */
 const SAMPLE_FEATURE_FLAG = null;
 
@@ -681,7 +656,7 @@ function getFeatures(isProd) {
     }
     return features;
   }
-  const FEATURE_OVERRIDES = process.env.EMBER_DATA_FEATURE_OVERRIDE;
+  const FEATURE_OVERRIDES = process.env.WARP_DRIVE_FEATURE_OVERRIDE;
   if (FEATURE_OVERRIDES === 'ENABLE_ALL_OPTIONAL') {
     // enable all features with a current value of `null`
     for (const feature of keys) {
@@ -720,41 +695,35 @@ function getFeatures(isProd) {
 }
 
 /**
- * ## Debugging
+  @module @warp-drive/build-config
+ */
+/**
+ * ## Debug Logging
  *
  * Many portions of the internals are helpfully instrumented with logging that can be activated
  * at build time. This instrumentation is always removed from production builds or any builds
  * that has not explicitly activated it. To activate it set the appropriate flag to `true`.
  *
-  @module @warp-drive/build-config/debugging
-  @main @warp-drive/build-config/debugging
- */
-/**
+ * ```ts
+ * setConfig(__dirname, app, {
+ *   debug: {
+ *     LOG_PAYLOADS: false, // data store received to update cache with
+ *     LOG_OPERATIONS: false, // updates to cache remote state
+ *     LOG_MUTATIONS: false, // updates to cache local state
+ *     LOG_NOTIFICATIONS: false,
+ *     LOG_REQUESTS: false,
+ *     LOG_REQUEST_STATUS: false,
+ *     LOG_IDENTIFIERS: false,
+ *     LOG_GRAPH: false,
+ *     LOG_INSTANCE_CACHE: false,
+ *     LOG_METRIC_COUNTS: false,
+ *     DEBUG_RELATIONSHIP_NOTIFICATIONS: false,
+ *   }
+ * });
+ * ```
  *
- * Many portions of the internals are helpfully instrumented with logging that can be activated
-at build time. This instrumentation is always removed from production builds or any builds
-that has not explicitly activated it. To activate it set the appropriate flag to `true`.
-
-```ts
-  let app = new EmberApp(defaults, {
-    emberData: {
-      debug: {
-          LOG_PAYLOADS: false, // data store received to update cache with
-          LOG_OPERATIONS: false, // updates to cache remote state
-          LOG_MUTATIONS: false, // updates to cache local state
-          LOG_NOTIFICATIONS: false,
-          LOG_REQUESTS: false,
-          LOG_REQUEST_STATUS: false,
-          LOG_IDENTIFIERS: false,
-          LOG_GRAPH: false,
-          LOG_INSTANCE_CACHE: false,
-      }
-    }
-  });
-  ```
-
-  @class DebugLogging
-  @public
+ * @class DebugLogging
+ * @public
  */
 /**
  * log payloads received by the store
@@ -882,6 +851,65 @@ function createLoggingConfig(env, debug) {
   return config;
 }
 
+/**
+ * Settings configuration for deprecations, optional features, development/testing
+ * support and debug logging is done using `setConfig` in `ember-cli-build`.
+ *
+ * ```ts
+ * 'use strict';
+ *
+ * const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+ *
+ * module.exports = async function (defaults) {
+ *   const { setConfig } = await import('@warp-drive/build-config');
+ *
+ *   const app = new EmberApp(defaults, {});
+ *
+ *   setConfig(app, __dirname, {
+ *     // settings here
+ *   });
+ *
+ *   const { Webpack } = require('@embroider/webpack');
+ *   return require('@embroider/compat').compatBuild(app, Webpack, {});
+ * };
+ *
+ * ```
+ *
+ * Available settings include:
+ *
+ * - [Debug Logging](../classes/DebugLogging)
+ * - [Deprecated Code Removal](../classes/CurrentDeprecations)
+ * - [Canary Feature Activation](../classes/CanaryFeatures)
+ *
+ * As well as:
+ *
+ * ### polyfillUUID
+ *
+ * If you are using the library in an environment that does not support `window.crypto.randomUUID`
+ * you can enable a polyfill for it.
+ *
+ * ```ts
+ * setConfig(app, __dirname, {
+ *  polyfillUUID: true
+ * });
+ * ```
+ *
+ * ### includeDataAdapterInProduction
+ *
+ * By default, the integration required to support the ember inspector browser extension
+ * is included in production builds only when using the `ember-data` package. Otherwise
+ * the default is to exclude it. This setting allows to explicitly enable/disable it in
+ * production builds.
+ *
+ * ```ts
+ * setConfig(app, __dirname, {
+ *   includeDataAdapterInProduction: true
+ * });
+ * ```
+ *
+ * @module @warp-drive/build-config
+ * @main @warp-drive/build-config
+ */
 const _MacrosConfig = EmbroiderMacros.MacrosConfig;
 function recastMacrosConfig(macros) {
   if (!('globalConfig' in macros)) {