@warp-drive-mirror/build-config 5.6.0-beta.0 → 5.6.0-beta.1

package/declarations/index.d.ts

@@ -0,0 +1,101 @@
+import { getDeprecations } from "./-private/utils/deprecations.js";
+import { getFeatures } from "./-private/utils/features.js";
+import * as LOGGING from "./debugging.js";
+export type WarpDriveConfig = {
+	/**
+	* An object of key/value pairs of logging flags
+	*
+	* see {@link LOGGING | debugging} for the available flags.
+	*
+	* ```ts
+	* {
+	*  LOG_CACHE: true,
+	* }
+	* ```
+	*
+	* @public
+	*/
+	debug?: Partial<InternalWarpDriveConfig["debug"]>;
+	/**
+	* If you are using the library in an environment that does not
+	* support `window.crypto.randomUUID` you can enable a polyfill
+	* for it.
+	*
+	* @public
+	*/
+	polyfillUUID?: boolean;
+	/**
+	* 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.
+	*
+	* @public
+	*/
+	includeDataAdapterInProduction?: boolean;
+	/**
+	* The most recent version of the library from which all
+	* deprecations have been resolved.
+	*
+	* For instance if all deprecations released prior to or
+	* within `5.3` have been resolved, then setting this to
+	* `5.3` will remove all the support for the deprecated
+	* features for associated deprecations.
+	*
+	* See {@link DEPRECATIONS | deprecations} for more details.
+	*/
+	compatWith?: `${number}.${number}`;
+	/**
+	* An object of key/value pairs of logging flags
+	*
+	* see {@link DEPRECATIONS | deprecations} for the available flags.
+	*
+	* ```ts
+	* {
+	*   DEPRECATE_THING: false,
+	* }
+	* ```
+	*
+	* @public
+	*/
+	deprecations?: Partial<InternalWarpDriveConfig["deprecations"]>;
+	/**
+	* An object of key/value pairs of canary feature flags
+	* for use when testing new features gated behind a flag
+	* in a canary release version.
+	*
+	* see {@link FEATURES | features} for the available flags.
+	*
+	* ```ts
+	* {
+	*   FEATURE_A: true,
+	* }
+	* ```
+	*
+	* @public
+	*/
+	features?: Partial<InternalWarpDriveConfig["features"]>;
+	/**
+	* @private
+	*/
+	forceMode?: "testing" | "production" | "development";
+};
+type InternalWarpDriveConfig = {
+	debug: typeof LOGGING;
+	polyfillUUID: boolean;
+	includeDataAdapter: boolean;
+	compatWith: `${number}.${number}` | null;
+	deprecations: ReturnType<typeof getDeprecations>;
+	features: ReturnType<typeof getFeatures>;
+	activeLogging: typeof LOGGING;
+	env: {
+		TESTING: boolean;
+		PRODUCTION: boolean;
+		DEBUG: boolean;
+	};
+};
+export declare function setConfig(macros: object, config: WarpDriveConfig): void;
+export declare function setConfig(context: object, appRoot: string, config: WarpDriveConfig): void;
+export {};

package/declarations/macros.d.ts

@@ -0,0 +1,18 @@
+/**
+* Internal functions for instrumenting the library's code with behaviors
+* that are removed from production builds.
+*
+* @hidden
+* @module
+*/
+/**
+* A type-narrowing assertion function that throws an error with the supplied
+* message if the condition is falsy.
+*
+* Asserts are removed from production builds, making this a "zero cost abstraction"
+* so liberal usage of this function to ensure runtime correctness is encouraged.
+*
+* @internal
+*/
+export declare function assert(message: string, condition: unknown): asserts condition;
+export declare function assert(message: string): never;

package/dist/addon-shim.cjs

@@ -10,4 +10,3 @@ Object.defineProperty(exports, "addonShim", {
 	enumerable: true,
 	get: () => addonShim.addonV1Shim
 });
-//# sourceMappingURL=addon-shim.cjs.map

package/dist/babel-macros.js

@@ -1,7 +1,28 @@
-import { L as LOGGING } from './debugging-BtpYr1v0.js';
-import { C as CURRENT_FEATURES } from './canary-features-D1wplYmb.js';
-import { C as CURRENT_DEPRECATIONS } from './deprecations-D_dBAPC9.js';
+import { L as LOGGING } from './debugging-VdsvkNjX.js';
+import { C as CURRENT_FEATURES } from './canary-features-CuKgaVtX.js';
+import { C as CURRENT_DEPRECATIONS } from './deprecations-BNNGFAiG.js';
 
+/**
+ * Babel plugins that convert constants and expressions into [macroConditions](https://www.npmjs.com/package/@embroider/macros#the-macros)
+ * so that they can be stripped from the code during the build process.
+ *
+ * This allows us to have great DX around common configuration patterns
+ * while still being able to ship a small and fast library.
+ *
+ * Transforms
+ *
+ * - deprecation constants imported from `@warp-drive-mirror/build-config/deprecations`
+ * - feature flags imported from `@warp-drive-mirror/build-config/canary-features`
+ * - debug logging constants imported from `@warp-drive-mirror/build-config/debugging`
+ * - environment constants imported from `@warp-drive-mirror/build-config/env`
+ * - expressionts imported from `@warp-drive-mirror/build-config/macros`
+ *
+ * Addons and apps can use these plugins to match the code-stripping behaviors of
+ * ***Warp*Drive**. This is useful when managing migrations for canary features
+ * and deprecations.
+ *
+ * @module
+ */
 const features = Object.keys(CURRENT_FEATURES);
 const FEATURES = Object.assign({}, CURRENT_FEATURES);
 features.forEach(feature => {
@@ -15,24 +36,36 @@ const config = {
   deprecations: Object.assign({}, CURRENT_DEPRECATIONS),
   debug: Object.assign({}, LOGGING)
 };
+/**
+ * @returns an array of Babel plugins that can be used for code-stripping
+ *   based on the configuration supplied to `setConfig` and the current ENV.
+ *
+ * - deprecation constants imported from `@warp-drive-mirror/build-config/deprecations`
+ * - feature flags imported from `@warp-drive-mirror/build-config/canary-features`
+ * - debug logging constants imported from `@warp-drive-mirror/build-config/debugging`
+ * - environment constants imported from `@warp-drive-mirror/build-config/env`
+ * - expressionts imported from `@warp-drive-mirror/build-config/macros`
+ */
 function macros() {
   const TransformAsserts = import.meta.resolve('./babel-plugin-transform-asserts.cjs').slice(7);
   const TransformDeprecations = import.meta.resolve('./babel-plugin-transform-deprecations.cjs').slice(7);
   const TransformDebugLogging = import.meta.resolve('./babel-plugin-transform-logging.cjs').slice(7);
   const TransformFeatures = import.meta.resolve('./babel-plugin-transform-features.cjs').slice(7);
-  let plugins = [[TransformAsserts, {}, '@warp-drive-mirror/build-config/asserts-stripping'], [TransformFeatures, {
-    source: '@warp-drive-mirror/build-config/canary-features',
+  let plugins = [[TransformAsserts, {
+    sources: ['@warp-drive-mirror/build-config/macros', '@warp-drive-mirror/core/build-config/macros']
+  }, '@warp-drive-mirror/core/build-config/asserts-stripping'], [TransformFeatures, {
+    sources: ['@warp-drive-mirror/build-config/canary-features', '@warp-drive-mirror/core/build-config/canary-features'],
     flags: config.features
-  }, '@warp-drive-mirror/build-config/canary-features-stripping'], [TransformDeprecations, {
-    source: '@warp-drive-mirror/build-config/deprecations',
+  }, '@warp-drive-mirror/core/build-config/canary-features-stripping'], [TransformDeprecations, {
+    sources: ['@warp-drive-mirror/build-config/deprecations', '@warp-drive-mirror/core/build-config/deprecations'],
     flags: config.deprecations
-  }, '@warp-drive-mirror/build-config/deprecation-stripping'], [TransformDebugLogging, {
-    source: '@warp-drive-mirror/build-config/debugging',
+  }, '@warp-drive-mirror/core/build-config/deprecation-stripping'], [TransformDebugLogging, {
+    sources: ['@warp-drive-mirror/build-config/debugging', '@warp-drive-mirror/core/build-config/debugging'],
     configKey: 'debug',
     runtimeKey: 'activeLogging',
     flags: config.debug
-  }, '@warp-drive-mirror/build-config/debugging-stripping'], [TransformDebugLogging, {
-    source: '@warp-drive-mirror/build-config/env',
+  }, '@warp-drive-mirror/core/build-config/debugging-stripping'], [TransformDebugLogging, {
+    sources: ['@warp-drive-mirror/build-config/env', '@warp-drive-mirror/core/build-config/env'],
     configKey: 'env',
     flags: {
       TESTING: true,
@@ -42,9 +75,8 @@ function macros() {
       IS_CI: true,
       SHOULD_RECORD: true
     }
-  }, '@warp-drive-mirror/build-config/env']];
+  }, '@warp-drive-mirror/core/build-config/env']];
   return plugins;
 }
 
 export { macros };
-//# sourceMappingURL=babel-macros.js.map

package/dist/babel-plugin-transform-asserts.cjs

@@ -1,8 +1,7 @@
 'use strict';
 
-const {
-  ImportUtil
-} = require('babel-import-util');
+const babelImportUtil = require('babel-import-util');
+
 const Utils = new Set(['assert']);
 
 /*
@@ -63,12 +62,12 @@ function babelPluginTransformAsserts (babel) {
     visitor: {
       ImportDeclaration(path, state) {
         const importPath = path.node.source.value;
-        if (importPath === '@warp-drive-mirror/build-config/macros') {
+        if (state.opts.sources.includes(importPath)) {
           const specifiers = path.get('specifiers');
           specifiers.forEach(specifier => {
             const name = specifier.node.imported.name;
             if (!Utils.has(name)) {
-              throw new Error(`Unexpected import '${name}' imported from '@warp-drive-mirror/build-config/macros'`);
+              throw new Error(`Unexpected import '${name}' imported from '${importPath}'`);
             }
             const localBindingName = specifier.node.local.name;
             const binding = specifier.scope.getBinding(localBindingName);
@@ -89,11 +88,10 @@ function babelPluginTransformAsserts (babel) {
         }
       },
       Program(path, state) {
-        state.importer = new ImportUtil(t, path);
+        state.importer = new babelImportUtil.ImportUtil(t, path);
       }
     }
   };
 }
 
 module.exports = babelPluginTransformAsserts;
-//# sourceMappingURL=babel-plugin-transform-asserts.cjs.map

package/dist/babel-plugin-transform-deprecations.cjs

@@ -17,12 +17,12 @@ function babelPluginTransformDeprecations (babel) {
     visitor: {
       ImportDeclaration(path, state) {
         const importPath = path.node.source.value;
-        if (importPath === state.opts.source) {
+        if (state.opts.sources.includes(importPath)) {
           const specifiers = path.get('specifiers');
           specifiers.forEach(specifier => {
             let name = specifier.node.imported.name;
             if (!(name in state.opts.flags)) {
-              throw new Error(`Unexpected flag ${name} imported from ${state.opts.source}`);
+              throw new Error(`Unexpected flag ${name} imported from ${importPath}`);
             }
             let localBindingName = specifier.node.local.name;
             let binding = specifier.scope.getBinding(localBindingName);
@@ -70,4 +70,3 @@ function babelPluginTransformDeprecations (babel) {
 }
 
 module.exports = babelPluginTransformDeprecations;
-//# sourceMappingURL=babel-plugin-transform-deprecations.cjs.map

package/dist/babel-plugin-transform-features.cjs

@@ -23,12 +23,12 @@ function babelPluginTransformFeatures (babel) {
     visitor: {
       ImportDeclaration(path, state) {
         const importPath = path.node.source.value;
-        if (importPath === state.opts.source) {
+        if (state.opts.sources.includes(importPath)) {
           const specifiers = path.get('specifiers');
           specifiers.forEach(specifier => {
             let name = specifier.node.imported.name;
             if (!(name in state.opts.flags)) {
-              throw new Error(`Unexpected flag ${name} imported from ${state.opts.source}`);
+              throw new Error(`Unexpected flag ${name} imported from ${importPath}`);
             }
             let localBindingName = specifier.node.local.name;
             let binding = specifier.scope.getBinding(localBindingName);
@@ -62,4 +62,3 @@ function babelPluginTransformFeatures (babel) {
 }
 
 module.exports = babelPluginTransformFeatures;
-//# sourceMappingURL=babel-plugin-transform-features.cjs.map

package/dist/babel-plugin-transform-logging.cjs

@@ -18,12 +18,12 @@ function babelPluginTransformLogging (babel) {
     visitor: {
       ImportDeclaration(path, state) {
         const importPath = path.node.source.value;
-        if (importPath === state.opts.source) {
+        if (state.opts.sources.includes(importPath)) {
           const specifiers = path.get('specifiers');
           specifiers.forEach(specifier => {
             let name = specifier.node.imported.name;
             if (!(name in state.opts.flags)) {
-              throw new Error(`Unexpected flag ${name} imported from ${state.opts.source}`);
+              throw new Error(`Unexpected flag ${name} imported from ${importPath}`);
             }
             let localBindingName = specifier.node.local.name;
             let binding = specifier.scope.getBinding(localBindingName);
@@ -100,4 +100,3 @@ function babelPluginTransformLogging (babel) {
 }
 
 module.exports = babelPluginTransformLogging;
-//# sourceMappingURL=babel-plugin-transform-logging.cjs.map

package/dist/canary-features-CuKgaVtX.js

@@ -0,0 +1,146 @@
+/**
+ *
+ * # Canary Features <Badge type="warning" text="requires 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 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, beginning the process of it landing in a stable release.
+ *
+ * ### Installing Canary
+ *
+ * ::: warning To test a feature guarded behind a flag, you MUST be using a canary build.
+ * :::
+ *
+ * Canary builds are published to `npm` and can be installed using a precise tag
+ * (such as `@warp-drive-mirror/core@5.6.0-alpha.1`) or by installing the latest dist-tag
+ * published to the `canary` channel.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Add/remove packages from this list to match your project.
+ *
+ * ::: code-group
+ *
+ * ```sh [pnpm]
+ * pnpm add -E @warp-drive-mirror/core@canary \
+ *   @warp-drive-mirror/json-api@canary \
+ *   @warp-drive-mirror/ember@canary;
+ * ```
+ *
+ * ```sh [npm]
+ * npm add -E @warp-drive-mirror/core@canary \
+ *   @warp-drive-mirror/json-api@canary \
+ *   @warp-drive-mirror/ember@canary;
+ * ```
+ *
+ * ```sh [yarn]
+ * yarn add -E @warp-drive-mirror/core@canary \
+ *   @warp-drive-mirror/json-api@canary \
+ *   @warp-drive-mirror/ember@canary;
+ * ```
+ *
+ * ```sh [bun]
+ * bun add --exact @warp-drive-mirror/core@canary \
+ *   @warp-drive-mirror/json-api@canary \
+ *   @warp-drive-mirror/ember@canary;
+ * ```
+ *
+ * :::
+ *
+ * ### Activating a Feature
+ *
+ * Once you have installed canary, feature-flags can be activated at build-time
+ *
+ * ```ts
+ * setConfig(app, __dirname, {
+ *   features: {
+ *     FEATURE_A: false, // utilize existing behavior
+ *     FEATURE_B: true // utilize the new behavior
+ *   }
+ * })
+ * ```
+ *
+ * by setting an environment variable:
+ *
+ * ```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 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('@warp-drive-mirror/core', '5.6'))) {
+ *   // do thing
+ * }
+ * ```
+ *
+ * For more complex projects and migrations, configure [@warp-drive-mirror/build-config/babel-macros](./babel-macros)
+ *
+ * The current list of features used at build time for canary releases is defined below.
+ *
+ * ::: tip 💡 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.
+ *
+ * @module
+ * @public
+ */
+
+/**
+ * We use this for some tests etc.
+ *
+ * @internal
+ */
+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.
+ *
+ * @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' }));
+
+export { CURRENT_FEATURES as C, JSON_API_CACHE_VALIDATION_ERRORS as J, SAMPLE_FEATURE_FLAG as S };

package/dist/canary-features.js

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