@warp-drive/build-config 0.0.1 → 0.0.3

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,26 +620,37 @@ 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;
 
+/**
+ * This upcoming feature adds a validation step to payloads received
+ * by the JSONAPICache implementation.
+ *
+ * When a request completes and the result is given to the cache via
+ * `cache.put`, the cache will validate the payload against registered
+ * schemas as well as the JSON:API spec.
+ *
+ * @property JSON_API_CACHE_VALIDATION_ERRORS
+ * @since 5.4
+ * @public
+ */
+const JSON_API_CACHE_VALIDATION_ERRORS = false;
+
 const CURRENT_FEATURES = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
   __proto__: null,
+  JSON_API_CACHE_VALIDATION_ERRORS,
   SAMPLE_FEATURE_FLAG
 }, Symbol.toStringTag, { value: 'Module' }));
 
@@ -681,7 +671,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,65 +710,43 @@ function getFeatures(isProd) {
 }
 
 /**
- * ## Debugging
- *
- * 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
+  @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`.
-
-```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
- */
-/**
- * log payloads received by the store
- * via `push` or returned from a delete/update/create
- * operation.
+ * 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`.
  *
- * @property {boolean} LOG_PAYLOADS
- * @public
- */
-const LOG_PAYLOADS = false;
-/**
- * log remote-state updates to the cache
+ * ```ts
+ * setConfig(__dirname, app, {
+ *   debug: {
+ *     LOG_CACHE: false, // data store received to update cache with
+ *     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,
+ *   }
+ * });
+ * ```
  *
- * @property {boolean} LOG_OPERATIONS
+ * @class DebugLogging
  * @public
  */
-const LOG_OPERATIONS = false;
 /**
- * log local-state updates to the cache
+ * log cache updates for both local
+ * and remote state.
  *
- * @property {boolean} LOG_MUTATIONS
+ * @property {boolean} LOG_CACHE
  * @public
  */
-const LOG_MUTATIONS = false;
+const LOG_CACHE = false;
+
 /**
  * log notifications received by the NotificationManager
  *
@@ -824,20 +792,121 @@ const LOG_GRAPH = false;
  * @public
  */
 const LOG_INSTANCE_CACHE = false;
+/**
+ * Log key count metrics, useful for performance
+ * debugging.
+ *
+ * @property {boolean} LOG_METRIC_COUNTS
+ * @public
+ */
+const LOG_METRIC_COUNTS = false;
+/**
+ * Helps when debugging causes of a change notification
+ * when processing an update to a hasMany relationship.
+ *
+ * @property {boolean} DEBUG_RELATIONSHIP_NOTIFICATIONS
+ * @public
+ */
+const DEBUG_RELATIONSHIP_NOTIFICATIONS = false;
+
+/**
+ * A private flag to enable logging of the native Map/Set
+ * constructor and method calls.
+ *
+ * EXTREMELY MALPERFORMANT
+ *
+ * LOG_METRIC_COUNTS must also be enabled.
+ *
+ * @typedoc
+ */
+const __INTERNAL_LOG_NATIVE_MAP_SET_COUNTS = false;
 
 const LOGGING = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
   __proto__: null,
+  DEBUG_RELATIONSHIP_NOTIFICATIONS,
+  LOG_CACHE,
   LOG_GRAPH,
   LOG_IDENTIFIERS,
   LOG_INSTANCE_CACHE,
-  LOG_MUTATIONS,
+  LOG_METRIC_COUNTS,
   LOG_NOTIFICATIONS,
-  LOG_OPERATIONS,
-  LOG_PAYLOADS,
   LOG_REQUESTS,
-  LOG_REQUEST_STATUS
+  LOG_REQUEST_STATUS,
+  __INTERNAL_LOG_NATIVE_MAP_SET_COUNTS
 }, Symbol.toStringTag, { value: 'Module' }));
 
+function createLoggingConfig(env, debug) {
+  const config = {};
+  const keys = Object.keys(LOGGING);
+  for (const key of keys) {
+    if (env.DEBUG || env.TESTING) {
+      config[key] = true;
+    } else {
+      config[key] = debug[key] || false;
+    }
+  }
+  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)) {
@@ -845,10 +914,12 @@ function recastMacrosConfig(macros) {
   }
   return macros;
 }
-function setConfig(context, appRoot, config) {
-  const macros = recastMacrosConfig(_MacrosConfig.for(context, appRoot));
-  const isLegacySupport = config.___legacy_support;
-  const hasDeprecatedConfig = isLegacySupport && Object.keys(config).length > 1;
+function setConfig(context, appRootOrConfig, config) {
+  const isEmberClassicUsage = arguments.length === 3;
+  const macros = recastMacrosConfig(isEmberClassicUsage ? _MacrosConfig.for(context, appRootOrConfig) : context);
+  const userConfig = isEmberClassicUsage ? config : appRootOrConfig;
+  const isLegacySupport = userConfig.___legacy_support;
+  const hasDeprecatedConfig = isLegacySupport && Object.keys(userConfig).length > 1;
   const hasInitiatedConfig = macros.globalConfig['WarpDrive'];
 
   // setConfig called by user prior to legacy support called
@@ -859,11 +930,6 @@ function setConfig(context, appRoot, config) {
     return;
   }
 
-  // legacy support called prior to user setConfig
-  if (isLegacySupport && hasDeprecatedConfig) {
-    console.warn(`You are using the legacy emberData key in your ember-cli-build.js file. This key is deprecated and will be removed in the next major version of EmberData/WarpDrive. Please use \`import { setConfig } from '@warp-drive/build-config';\` instead.`);
-  }
-
   // included hooks run during class initialization of the EmberApp instance
   // so our hook will run before the user has a chance to call setConfig
   // else we could print a useful message here
@@ -873,19 +939,20 @@ function setConfig(context, appRoot, config) {
   //   );
   // }
 
-  const debugOptions = Object.assign({}, LOGGING, config.debug);
+  const debugOptions = Object.assign({}, LOGGING, userConfig.debug);
   const env = getEnv();
-  const DEPRECATIONS = getDeprecations(config.compatWith || null, config.deprecations);
+  const DEPRECATIONS = getDeprecations(userConfig.compatWith || null, userConfig.deprecations);
   const FEATURES = getFeatures(env.PRODUCTION);
-  const includeDataAdapterInProduction = typeof config.includeDataAdapterInProduction === 'boolean' ? config.includeDataAdapterInProduction : true;
+  const includeDataAdapterInProduction = typeof userConfig.includeDataAdapterInProduction === 'boolean' ? userConfig.includeDataAdapterInProduction : true;
   const includeDataAdapter = env.PRODUCTION ? includeDataAdapterInProduction : true;
   const finalizedConfig = {
     debug: debugOptions,
-    polyfillUUID: config.polyfillUUID ?? false,
+    polyfillUUID: userConfig.polyfillUUID ?? false,
     includeDataAdapter,
-    compatWith: config.compatWith ?? null,
+    compatWith: userConfig.compatWith ?? null,
     deprecations: DEPRECATIONS,
     features: FEATURES,
+    activeLogging: createLoggingConfig(env, debugOptions),
     env
   };
   macros.setGlobalConfig(undefined, 'WarpDrive', finalizedConfig);