@warp-drive/build-config 5.6.0-alpha.1 → 5.6.0-alpha.11

package/dist/cjs-set-config.cjs

@@ -32,9 +32,6 @@ function getEnv() {
   };
 }
 
-/**
- * @module @warp-drive/build-config
- */
 // ========================
 // FOR CONTRIBUTING AUTHORS
 //
@@ -52,496 +49,18 @@ function getEnv() {
 //
 // ========================
 //
-
-/**
- * ## Deprecation Management
- *
- * EmberData allows users to opt-in and remove code that exists to support deprecated
- * behaviors.
- *
- * If your app has resolved all deprecations present in a given version,
- * you may specify that version as your "compatibility" version to remove
- * the code that supported the deprecated behavior from your app.
- *
- * For instance, if a deprecation was introduced in 3.13, and the app specifies
- * 3.13 as its minimum version compatibility, any deprecations introduced before
- * or during 3.13 would be stripped away.
- *
- * An app can use a different version than what it specifies as it's compatibility
- * version. For instance, an App could be using `3.16` while specifying compatibility
- * 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`.
- *
- * 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: {
- *     // resolve individual deprecations here
- *   },
- * });
- * ```
- *
- * > [!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
- */
 const DEPRECATE_CATCH_ALL = '99.0';
-/**
- * **id: ember-data:deprecate-non-strict-types**
- *
- * Currently, EmberData expects that the `type` property associated with
- * a resource follows several conventions.
- *
- * - The `type` property must be a non-empty string
- * - The `type` property must be singular
- * - The `type` property must be dasherized
- *
- * We are deprecating support for types that do not match this pattern
- * in order to unlock future improvements in which we can support `type`
- * being any string of your choosing.
- *
- * The goal is that in the future, you will be able to use any string
- * so long as it matches what your configured cache, identifier generation,
- * and schemas expect.
- *
- * E.G. It will matter not that your string is in a specific format like
- * singular, dasherized, etc. so long as everywhere you refer to the type
- * you use the same string.
- *
- * If using @ember-data/model, there will always be a restriction that the
- * `type` must match the path on disk where the model is defined.
- *
- * e.g. `app/models/foo/bar-bem.js` must have a type of `foo/bar-bem`
- *
- * @property DEPRECATE_NON_STRICT_TYPES
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_NON_STRICT_TYPES = '5.3';
-
-/**
- * **id: ember-data:deprecate-non-strict-id**
- *
- * Currently, EmberData expects that the `id` property associated with
- * a resource is a string.
- *
- * However, for legacy support in many locations we would accept a number
- * which would then immediately be coerced into a string.
- *
- * We are deprecating this legacy support for numeric IDs.
- *
- * The goal is that in the future, you will be able to use any ID format
- * so long as everywhere you refer to the ID you use the same format.
- *
- * However, for identifiers we will always use string IDs and so any
- * custom identifier configuration should provide a string ID.
- *
- * @property DEPRECATE_NON_STRICT_ID
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_NON_STRICT_ID = '5.3';
-
-/**
- * **id: <none yet assigned>**
- *
- * This is a planned deprecation which will trigger when observer or computed
- * chains are used to watch for changes on any EmberData LiveArray, CollectionRecordArray,
- * ManyArray or PromiseManyArray.
- *
- * Support for these chains is currently guarded by the deprecation flag
- * listed here, enabling removal of the behavior if desired.
- *
- * The instrumentation was added in 5.0 but the version number
- * is set to 7.0 as we do not want to strip support without
- * adding a deprecation message.
- *
- * Once we've added the deprecation message, we will
- * update this version number to the proper version.
- *
- * @property DEPRECATE_COMPUTED_CHAINS
- * @type {Boolean}
- * @since 5.0
- * @until 8.0
- * @public
- */
 const DEPRECATE_COMPUTED_CHAINS = '7.0';
-
-/**
- * **id: ember-data:deprecate-legacy-imports**
- *
- * Deprecates when importing from `ember-data/*` instead of `@ember-data/*`
- * in order to prepare for the eventual removal of the legacy `ember-data/*`
- *
- * All imports from `ember-data/*` should be updated to `@ember-data/*`
- * except for `ember-data/store`. When you are using `ember-data` (as opposed to
- * installing the indivudal packages) you should import from `ember-data/store`
- * instead of `@ember-data/store` in order to receive the appropriate configuration
- * of defaults.
- *
- * @property DEPRECATE_LEGACY_IMPORTS
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_LEGACY_IMPORTS = '5.3';
-
-/**
- * **id: ember-data:deprecate-non-unique-collection-payloads**
- *
- * Deprecates when the data for a hasMany relationship contains
- * duplicate identifiers.
- *
- * Previously, relationships would silently de-dupe the data
- * when received, but this behavior is being removed in favor
- * of erroring if the same related record is included multiple
- * times.
- *
- * For instance, in JSON:API the below relationship data would
- * be considered invalid:
- *
- * ```json
- * {
- *  "data": {
- *   "type": "article",
- *    "id": "1",
- *    "relationships": {
- *      "comments": {
- *        "data": [
- *          { "type": "comment", "id": "1" },
- *          { "type": "comment", "id": "2" },
- *          { "type": "comment", "id": "1" } // duplicate
- *        ]
- *     }
- *  }
- * }
- * ```
- *
- * To resolve this deprecation, either update your server to
- * not include duplicate data, or implement normalization logic
- * in either a request handler or serializer which removes
- * duplicate data from relationship payloads.
- *
- * @property DEPRECATE_NON_UNIQUE_PAYLOADS
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_NON_UNIQUE_PAYLOADS = '5.3';
-
-/**
- * **id: ember-data:deprecate-relationship-remote-update-clearing-local-state**
- *
- * Deprecates when a relationship is updated remotely and the local state
- * is cleared of all changes except for "new" records.
- *
- * Instead, any records not present in the new payload will be considered
- * "removed" while any records present in the new payload will be considered "added".
- *
- * This allows us to "commit" local additions and removals, preserving any additions
- * or removals that are not yet reflected in the remote state.
- *
- * For instance, given the following initial state:
- *
- * remote: A, B, C
- * local: add D, E
- *        remove B, C
- * => A, D, E
- *
- *
- * If after an update, the remote state is now A, B, D, F then the new state will be
- *
- * remote: A, B, D, F
- * local: add E
- *        remove B
- * => A, D, E, F
- *
- * Under the old behavior the updated local state would instead have been
- * => A, B, D, F
- *
- * Similarly, if a belongsTo remote State was A while its local state was B,
- * then under the old behavior if the remote state changed to C, the local state
- * would be updated to C. Under the new behavior, the local state would remain B.
- *
- * If the remote state was A while its local state was `null`, then under the old
- * behavior if the remote state changed to C, the local state would be updated to C.
- * Under the new behavior, the local state would remain `null`.
- *
- * Thus the new correct mental model is that the state of the relationship at any point
- * in time is whatever the most recent remote state is, plus any local additions or removals
- * you have made that have not yet been reflected by the remote state.
- *
- * > Note: The old behavior extended to modifying the inverse of a relationship. So if
- * > you had local state not reflected in the new remote state, inverses would be notified
- * > and their state reverted as well when "resetting" the relationship.
- * > Under the new behavior, since the local state is preserved the inverses will also
- * > not be reverted.
- *
- * ### Resolving this deprecation
- *
- * Resolving this deprecation can be done individually for each relationship
- * or globally for all relationships.
- *
- * To resolve it globally, set the `DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE`
- * to `false` in ember-cli-build.js
- *
- * ```js
- * const { setConfig } = await import('@warp-drive/build-config');
- *
- * let app = new EmberApp(defaults, {});
- *
- * setConfig(app, __dirname, {
- *   deprecations: {
- *     // set to false to strip the deprecated code (thereby opting into the new behavior)
- *     DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE: false
- *   }
- * });
- * ```
- *
- * To resolve this deprecation on an individual relationship, adjust the `options` passed to
- * the relationship. For relationships with inverses, both sides MUST be migrated to the new
- * behavior at the same time.
- *
- * ```js
- * class Person extends Model {
- *  @hasMany('person', {
- *    async: false,
- *    inverse: null,
- *    resetOnRemoteUpdate: false
- *  }) children;
- *
- *  @belongsTo('person', {
- *    async: false,
- *    inverse: null,
- *    resetOnRemoteUpdate: false
- *  }) parent;
- * }
- * ```
- *
- * > Note: false is the only valid value here, all other values (including missing)
- * > will be treated as true, where `true` is the legacy behavior that is now deprecated.
- *
- * Once you have migrated all relationships, you can remove the the resetOnRemoteUpdate
- * option and set the deprecation flag to false in ember-cli-build.
- *
- * ### What if I don't want the new behavior?
- *
- * EmberData's philosophy is to not make assumptions about your application. Where possible
- * we seek out "100%" solutions – solutions that work for all use cases - and where that is
- * not possible we default to "90%" solutions – solutions that work for the vast majority of use
- * cases. In the case of "90%" solutions we look for primitives that allow you to resolve the
- * 10% case in your application. If no such primitives exist, we provide an escape hatch that
- * ensures you can build the behavior you need without adopting the cost of the default solution.
- *
- * In this case, the old behavior was a "40%" solution. The inability for an application developer
- * to determine what changes were made locally, and thus what changes should be preserved, made
- * it impossible to build certain features easily, or in some cases at all. The proliferation of
- * feature requests, bug reports (from folks surprised by the prior behavior) and addon attempts
- * in this space are all evidence of this.
- *
- * We believe the new behavior is a "90%" solution. It works for the vast majority of use cases,
- * often without noticeable changes to existing application behavior, and provides primitives that
- * allow you to build the behavior you need for the remaining 10%.
- *
- * The great news is that this behavior defaults to trusting your API similar to the old behavior.
- * If your API is correct, you will not need to make any changes to your application to adopt
- * the new behavior.
- *
- * This means the 10% cases are those where you can't trust your API to provide the correct
- * information. In these cases, because you now have cheap access to a diff of the relationship
- * state, there are a few options that weren't available before:
- *
- * - you can adjust returned API payloads to contain the expected changes that it doesn't include
- * - you can modify local state by adding or removing records on the HasMany record array to remove
- *   any local changes that were not returned by the API.
- * - you can use `<Cache>.mutate(mutation)` to directly modify the local cache state of the relationship
- *   to match the expected state.
- *
- * What this version (5.3) does not yet provide is a way to directly modify the cache's remote state
- * for the relationship via public APIs other than via the broader action of upserting a response via
- * `<Cache>.put(document)`. However, such an API was sketched in the Cache 2.1 RFC
- * `<Cache>.patch(operation)` and is likely to be added in a future 5.x release of EmberData.
- *
- * This version (5.3) also does not yet provide a way to directly modify the graph (a general purpose
- * subset of cache behaviors specific to relationships) via public APIs. However, during the
- * 5.x release series we will be working on finalizing the Graph API and making it public.
- *
- * If none of these options work for you, you can always opt-out more broadly by implementing
- * a custom Cache with the relationship behaviors you need.
- *
- * @property DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE = '5.3';
-
-/**
- * **id: ember-data:deprecate-many-array-duplicates**
- *
- * When the flag is `true` (default), adding duplicate records to a `ManyArray`
- * is deprecated in non-production environments. In production environments,
- * duplicate records added to a `ManyArray` will be deduped and no error will
- * be thrown.
- *
- * When the flag is `false`, an error will be thrown when duplicates are added.
- *
- * @property DEPRECATE_MANY_ARRAY_DUPLICATES
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_MANY_ARRAY_DUPLICATES = '5.3';
-
-/**
- * **id: ember-data:deprecate-store-extends-ember-object**
- *
- * When the flag is `true` (default), the Store class will extend from `@ember/object`.
- * When the flag is `false` or `ember-source` is not present, the Store will not extend
- * from EmberObject.
- *
- * @property DEPRECATE_STORE_EXTENDS_EMBER_OBJECT
- * @type {Boolean}
- * @since 5.4
- * @until 6.0
- * @public
- */
 const DEPRECATE_STORE_EXTENDS_EMBER_OBJECT = '5.4';
-
-/**
- * **id: ember-data:schema-service-updates**
- *
- * When the flag is `true` (default), the legacy schema
- * service features will be enabled on the store and
- * the service, and deprecations will be thrown when
- * they are used.
- *
- * Deprecated features include:
- *
- * - `Store.registerSchema` method is deprecated in favor of the `Store.createSchemaService` hook
- * - `Store.registerSchemaDefinitionService` method is deprecated in favor of the `Store.createSchemaService` hook
- * - `Store.getSchemaDefinitionService` method is deprecated in favor of `Store.schema` property
- * - `SchemaService.doesTypeExist` method is deprecated in favor of the `SchemaService.hasResource` method
- * - `SchemaService.attributesDefinitionFor` method is deprecated in favor of the `SchemaService.fields` method
- * - `SchemaService.relationshipsDefinitionFor` method is deprecated in favor of the `SchemaService.fields` method
- *
- * @property ENABLE_LEGACY_SCHEMA_SERVICE
- * @type {Boolean}
- * @since 5.4
- * @until 6.0
- * @public
- */
 const ENABLE_LEGACY_SCHEMA_SERVICE = '5.4';
-
-/**
- * **id: warp-drive.ember-inflector**
- *
- * Deprecates the use of ember-inflector for pluralization and singularization in favor
- * of the `@ember-data/request-utils` package.
- *
- * Rule configuration methods (singular, plural, uncountable, irregular) and
- * usage methods (singularize, pluralize) are are available as imports from
- * `@ember-data/request-utils/string`
- *
- * Notable differences with ember-inflector:
- * - there cannot be multiple inflector instances with separate rules
- * - pluralization does not support a count argument
- * - string caches now default to 10k entries instead of 1k, and this
- *   size is now configurable. Additionally, the cache is now a LRU cache
- *   instead of a first-N cache.
- *
- * This deprecation can be resolved by removing usage of ember-inflector or by using
- * both ember-inflector and @ember-data/request-utils in parallel and updating your
- * EmberData/WarpDrive build config to mark the deprecation as resolved
- * in ember-cli-build
- *
- * ```js
- * setConfig(app, __dirname, { deprecations: { DEPRECATE_EMBER_INFLECTOR: false }});
- * ```
- *
- * @property DEPRECATE_EMBER_INFLECTOR
- * @type {Boolean}
- * @since 5.3
- * @until 6.0
- * @public
- */
 const DEPRECATE_EMBER_INFLECTOR = '5.3';
-
-/**
- * This is a special flag that can be used to opt-in early to receiving deprecations introduced in 6.x
- * which have had their infra backported to 5.x versions of EmberData.
- *
- * When this flag is not present or set to `true`, the deprecations from the 6.x branch
- * will not print their messages and the deprecation cannot be resolved.
- *
- * When this flag is present and set to `false`, the deprecations from the 6.x branch will
- * print and can be resolved.
- *
- * @property DISABLE_7X_DEPRECATIONS
- * @type {Boolean}
- * @since 5.3
- * @until 7.0
- * @public
- */
 const DISABLE_7X_DEPRECATIONS = '7.0';
-
-/**
- * **id: warp-drive:deprecate-tracking-package**
- *
- * Deprecates the use of the @ember-data/tracking package which
- * historically provided bindings into Ember's reactivity system.
- *
- * This package is no longer needed as the configuration is now
- * provided by the @warp-drive/ember package.
- *
- * This deprecation can be resolved by removing the
- * @ember-data/tracking package from your project and ensuring
- * that your app.js file has the following import:
- *
- * ```js
- * import '@warp-drive/ember/install';
- * ```
- *
- * Once this import is present, you can remove the deprecation
- * by setting the deprecation to `false` in your build config:
- *
- * ```js
- * // inside of ember-cli-build.js
- *
- * const { setConfig } = await import('@warp-drive/build-config');
- *
- * setConfig(app, __dirname, {
- *   deprecations: {
- *     DEPRECATE_TRACKING_PACKAGE: false
- *   }
- * });
- * ```
- *
- * @property DEPRECATE_TRACKING_PACKAGE
- * @type {Boolean}
- * @since 5.5
- * @until 6.0
- * @public
- */
 const DEPRECATE_TRACKING_PACKAGE = '5.5';
 
 const CURRENT_DEPRECATIONS = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
@@ -605,82 +124,112 @@ function getDeprecations(compatVersion, deprecations) {
 
 /**
  *
- * @module @warp-drive/build-config
- */
-
-/**
- *
- * ## Canary Features
+ * # Canary Features <Badge type="warning" text="requires canary" />
  *
- * EmberData allows users to test features that are implemented but not yet
- * available even in canary.
+ * ***Warp*Drive** allows users to test upcoming features that are implemented
+ * but not yet activated in canary builds.
  *
- * Typically these features represent work that might introduce a new concept,
- * new API, change an API, or risk an unintended change in behavior to consuming
- * applications.
+ * Typically these features represent work that carries higher risk of breaking
+ * changes, or are not yet fully ready for production use.
  *
  * Such features have their implementations guarded by a "feature flag", and the
  * flag is only activated once the core-data team is prepared to ship the work
- * in a canary release.
+ * in a canary release, beginning the process of it landing in a stable release.
  *
  * ### Installing Canary
  *
- * To test a feature you MUST be using a canary build. Canary builds are published
- * to `npm` and can be installed using a precise tag (such as `ember-data@3.16.0-alpha.1`)
- * or by installing the latest dist-tag published to the `canary` channel using your javascript
- * package manager of choice. For instance with [pnpm](https://pnpm.io/)
-
-  ```cli
-  pnpm add ember-data@canary
-  ```
+ * ::: warning To test a feature guarded behind a flag, you MUST be using a canary build.
+ * :::
  *
- * ### Activating a Canary Feature
+ * Canary builds are published to `npm` and can be installed using a precise tag
+ * (such as `@warp-drive/core@5.6.0-alpha.1`) or by installing the latest dist-tag
+ * published to the `canary` channel.
  *
- * Once you have installed canary, feature-flags can be activated at build-time
+ * Because ***Warp*Drive** packages operate on a strict lockstep policy with each other,
+ * you must install the matching canary version of all ***Warp*Drive** packages.
  *
- * by setting an environment variable:
+ * Below is an example of installing the latest canary version of all the core
+ * packages that are part of the ***Warp*Drive** project when using EmberJS.
  *
- * ```cli
- * # Activate a single flag
- * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG ember build
+ * Add/remove packages from this list to match your project.
  *
- * # Activate multiple flags by separating with commas
- * WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG ember build
+ * ::: code-group
  *
- * # Activate all flags
- * WARP_DRIVE_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL ember build
+ * ```sh [pnpm]
+ * pnpm add -E @warp-drive/core@canary \
+ *   @warp-drive/json-api@canary \
+ *   @warp-drive/ember@canary;
+ * ```
+ *
+ * ```sh [npm]
+ * npm add -E @warp-drive/core@canary \
+ *   @warp-drive/json-api@canary \
+ *   @warp-drive/ember@canary;
  * ```
  *
- * or by setting the appropriate flag in your `ember-cli-build` file:
+ * ```sh [yarn]
+ * yarn add -E @warp-drive/core@canary \
+ *   @warp-drive/json-api@canary \
+ *   @warp-drive/ember@canary;
+ * ```
+ *
+ * ```sh [bun]
+ * bun add --exact @warp-drive/core@canary \
+ *   @warp-drive/json-api@canary \
+ *   @warp-drive/ember@canary;
+ * ```
+ *
+ * :::
+ *
+ * ### Activating a Feature
+ *
+ * Once you have installed canary, feature-flags can be activated at build-time
  *
  * ```ts
  * 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
+ *     FEATURE_A: false, // utilize existing behavior
+ *     FEATURE_B: true // utilize the new behavior
  *   }
  * })
  * ```
  *
- * **The "off" branch of feature-flagged code is always stripped from production builds.**
+ * by setting an environment variable:
  *
- * 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")
+ * ```sh
+ * # Activate a single flag
+ * export WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG;
+ *
+ * # Activate multiple flags by separating with commas
+ * export WARP_DRIVE_FEATURE_OVERRIDE=SOME_FLAG,OTHER_FLAG;
+ *
+ * # Activate all flags
+ * export WARP_DRIVE_FEATURE_OVERRIDE=ENABLE_ALL_OPTIONAL;
+ * ```
+ *
+ * ::: warning To test a feature guarded behind a flag, you MUST be running a development build.
+ * :::
  *
  *
  * ### Preparing a Project to use a Canary Feature
  *
- * For most projects, simple version detection should be enough.
+ * For most projects and features, simple version detection should be enough.
+ *
  * Using the provided version compatibility helpers from [embroider-macros](https://github.com/embroider-build/embroider/tree/main/packages/macros#readme)
  * the following can be done:
  *
  * ```js
- * if (macroCondition(dependencySatisfies('@ember-data/store', '5.0'))) {
+ * if (macroCondition(dependencySatisfies('@warp-drive/core', '5.6'))) {
  *   // do thing
  * }
  * ```
  *
+ * For more complex projects and migrations, configure [@warp-drive/build-config/babel-macros](./babel-macros)
+ *
  * 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.
+ *
+ * ::: tip 💡 If empty there are no features currently gated by feature flags.
+ * :::
  *
  * The valid values are:
  *
@@ -688,9 +237,15 @@ function getDeprecations(compatVersion, deprecations) {
  *  - `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
+ * @module
  * @public
-*/
+ */
+
+/**
+ * We use this for some tests etc.
+ *
+ * @internal
+ */
 const SAMPLE_FEATURE_FLAG = null;
 
 /**
@@ -701,8 +256,6 @@ const SAMPLE_FEATURE_FLAG = null;
  * `cache.put`, the cache will validate the payload against registered
  * schemas as well as the JSON:API spec.
  *
- * @property JSON_API_CACHE_VALIDATION_ERRORS
- * @type {Boolean|null}
  * @since 5.4
  * @public
  */
@@ -770,10 +323,7 @@ function getFeatures(isProd) {
 }
 
 /**
-  @module @warp-drive/build-config
- */
-/**
- * ## Debug Logging
+ * # Log Instrumentation <Badge type="tip" text="debug only" />
  *
  * Many portions of the internals are helpfully instrumented with logging.
  * This instrumentation is always removed from production builds.
@@ -785,19 +335,11 @@ function getFeatures(isProd) {
  * either in your build config or via the runtime helper.
  *
  *
- * ### Activation Via Runtime Helper
- *
- * A runtime helper is attached to `globalThis` to enable activation of the logs
- * from anywhere in your application including from the devtools panel.
- *
- * The runtime helper overrides any build config settings for the given flag
- * for the current browser tab. It stores the configuration you give it in
- * `sessionStorage` so that it persists across page reloads of the current tab,
- * but not across browser tabs or windows. Thus if you need to deactivate the
- * logging, you can call the helper again with the same flag set to `false` or
- * just open a new tab/window.
+ * ## Runtime Activation
  *
- * Example Usage:
+ * ::: tip 💡 Just Works in browser Dev Tools!
+ * No import is needed, and the logging config is preserved when the page is refreshed
+ * :::
  *
  * ```ts
  * setWarpDriveLogging({
@@ -806,26 +348,34 @@ function getFeatures(isProd) {
  * })
  * ```
  *
- * ### Activation Via Build Config
+ * A runtime helper is attached to `globalThis` to enable activation of the logs
+ * from anywhere in your application including from the devtools panel.
+ *
+ * The runtime helper overrides any build config settings for the given flag
+ * for the current browser tab. It stores the configuration you give it in
+ * `sessionStorage` so that it persists across page reloads of the current tab,
+ * but not across browser tabs or windows.
+ *
+ * If you need to deactivate the logging, you can call the helper again with the
+ * same flag set to `false` or just open a new tab/window.
+ *
+ * ## Buildtime Activation
  *
  * ```ts
  * setConfig(__dirname, app, {
  *   debug: {
- *     LOG_CACHE: false, // data store received to update cache with
- *     LOG_NOTIFICATIONS: false,
+ *     LOG_CACHE: true,
  *     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,
+ *     LOG_NOTIFICATIONS: true,
  *   }
  * });
  * ```
  *
- * @class DebugLogging
- * @public
+ * The build config settings are used to set the default values for the
+ * logging flags. Any logging flag that is not set in the build config
+ * will default to `false`.
+ *
+ * @module
  */
 /**
  * log cache updates for both local
@@ -836,16 +386,50 @@ function getFeatures(isProd) {
  *
  * The others were `LOG_OPERATIONS` and `LOG_MUTATIONS`.
  *
- * @property LOG_CACHE
- * @type {Boolean}
  * @public
+ * @since 5.5
  */
 const LOG_CACHE = false;
+
+/**
+ * <Badge type="danger" text="removed" />
+ *
+ * This flag no longer has any effect.
+ *
+ * Use {@link LOG_CACHE} instead.
+ *
+ * @deprecated removed in version 5.5
+ * @public
+ */
+const LOG_PAYLOADS = false;
+
+/**
+ * <Badge type="danger" text="removed" />
+ *
+ * This flag no longer has any effect.
+ *
+ * Use {@link LOG_CACHE} instead.
+ *
+ * @deprecated removed in version 5.5
+ * @public
+ */
+const LOG_OPERATIONS = false;
+
+/**
+ * <Badge type="danger" text="removed" />
+ *
+ * This flag no longer has any effect.
+ *
+ * Use {@link LOG_CACHE} instead.
+ *
+ * @deprecated removed in version 5.5
+ * @public
+ */
+const LOG_MUTATIONS = false;
+
 /**
  * Log decisions made by the Basic CachePolicy
  *
- * @property LOG_CACHE_POLICY
- * @type {Boolean}
  * @public
  */
 const LOG_CACHE_POLICY = false;
@@ -853,16 +437,12 @@ const LOG_CACHE_POLICY = false;
 /**
  * log notifications received by the NotificationManager
  *
- * @property LOG_NOTIFICATIONS
- * @type {Boolean}
  * @public
  */
 const LOG_NOTIFICATIONS = false;
 /**
  * log requests issued by the RequestManager
  *
- * @property LOG_REQUESTS
- * @type {Boolean}
  * @public
  */
 const LOG_REQUESTS = false;
@@ -870,8 +450,6 @@ const LOG_REQUESTS = false;
  * log updates to requests the store has issued to
  * the network (adapter) to fulfill.
  *
- * @property LOG_REQUEST_STATUS
- * @type {Boolean}
  * @public
  */
 const LOG_REQUEST_STATUS = false;
@@ -879,8 +457,6 @@ const LOG_REQUEST_STATUS = false;
  * log peek, generation and updates to
  * Record Identifiers.
  *
- * @property LOG_IDENTIFIERS
- * @type {Boolean}
 
  * @public
  */
@@ -888,8 +464,6 @@ const LOG_IDENTIFIERS = false;
 /**
  * log updates received by the graph (relationship pointer storage)
  *
- * @property LOG_GRAPH
- * @type {Boolean}
  * @public
  */
 const LOG_GRAPH = false;
@@ -897,8 +471,6 @@ const LOG_GRAPH = false;
  * log creation/removal of RecordData and Record
  * instances.
  *
- * @property LOG_INSTANCE_CACHE
- * @type {Boolean}
  * @public
  */
 const LOG_INSTANCE_CACHE = false;
@@ -906,8 +478,6 @@ const LOG_INSTANCE_CACHE = false;
  * Log key count metrics, useful for performance
  * debugging.
  *
- * @property LOG_METRIC_COUNTS
- * @type {Boolean}
  * @public
  */
 const LOG_METRIC_COUNTS = false;
@@ -915,8 +485,6 @@ const LOG_METRIC_COUNTS = false;
  * Helps when debugging causes of a change notification
  * when processing an update to a hasMany relationship.
  *
- * @property DEBUG_RELATIONSHIP_NOTIFICATIONS
- * @type {Boolean}
  * @public
  */
 const DEBUG_RELATIONSHIP_NOTIFICATIONS = false;
@@ -929,7 +497,7 @@ const DEBUG_RELATIONSHIP_NOTIFICATIONS = false;
  *
  * LOG_METRIC_COUNTS must also be enabled.
  *
- * @typedoc
+ * @internal
  */
 const __INTERNAL_LOG_NATIVE_MAP_SET_COUNTS = false;
 
@@ -942,7 +510,10 @@ const LOGGING = /*#__PURE__*/Object.freeze(/*#__PURE__*/Object.defineProperty({
   LOG_IDENTIFIERS,
   LOG_INSTANCE_CACHE,
   LOG_METRIC_COUNTS,
+  LOG_MUTATIONS,
   LOG_NOTIFICATIONS,
+  LOG_OPERATIONS,
+  LOG_PAYLOADS,
   LOG_REQUESTS,
   LOG_REQUEST_STATUS,
   __INTERNAL_LOG_NATIVE_MAP_SET_COUNTS
@@ -967,17 +538,17 @@ function createLoggingConfig(env, debug) {
  *
  * This configuration is done using `setConfig` in `ember-cli-build`.
  *
- * ```ts
+ * ```ts [ember-cli-build.js]
  * '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 { setConfig } = await import('@warp-drive/build-config'); // [!code focus]
  *
  *   const app = new EmberApp(defaults, {});
  *
- *   setConfig(app, __dirname, {
+ *   setConfig(app, __dirname, { // [!code focus:3]
  *     // settings here
  *   });
  *
@@ -989,38 +560,16 @@ function createLoggingConfig(env, debug) {
  *
  * Available settings include:
  *
- * - [Debug Logging](../classes/DebugLogging)
- * - [Deprecated Code Removal](../classes/CurrentDeprecations)
- * - [Canary Feature Activation](../classes/CanaryFeatures)
- *
- * As well as:
- *
- * ### polyfillUUID
+ * - {@link LOGGING | debugging}
+ * - {@link DEPRECATIONS | deprecations}
+ * - {@link FEATURES | features}
+ * - {@link WarpDriveConfig.polyfillUUID | polyfillUUID}
+ * - {@link WarpDriveConfig.includeDataAdapterInProduction | includeDataAdapterInProduction}
+ * - {@link WarpDriveConfig.compatWith | compatWith}
  *
- * 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
+ * @module
  */
 const _MacrosConfig = EmbroiderMacros.MacrosConfig;
 function recastMacrosConfig(macros) {