@atlaspack/feature-flags 2.21.0 → 2.23.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atlaspack/feature-flags
 
+## 2.23.0
+
+### Minor Changes
+
+- [#745](https://github.com/atlassian-labs/atlaspack/pull/745) [`f6b3f22`](https://github.com/atlassian-labs/atlaspack/commit/f6b3f2276c7e417580b49c4879563aab51f156b1) Thanks [@matt-koko](https://github.com/matt-koko)! - Use ATLASPACK_BUILD_ENV instead of NODE_ENV to determine if Atlaspack is being run in the context of Atlaspack tests.
+
+## 2.22.0
+
+### Minor Changes
+
+- [#741](https://github.com/atlassian-labs/atlaspack/pull/741) [`73dd7ba`](https://github.com/atlassian-labs/atlaspack/commit/73dd7baab69456ef2f6e4a0cc7dbb04f407eb148) Thanks [@matt-koko](https://github.com/matt-koko)! - combine FeatureFlags and DEFAULT_FEATURE_FLAGS into one object
+
 ## 2.21.0
 
 ### Minor Changes

package/lib/index.js

@@ -12,35 +12,132 @@ exports.setFeatureFlags = setFeatureFlags;
 
 const CONSISTENCY_CHECK_VALUES = exports.CONSISTENCY_CHECK_VALUES = Object.freeze(['NEW', 'OLD', 'NEW_AND_CHECK', 'OLD_AND_CHECK']);
 const DEFAULT_FEATURE_FLAGS = exports.DEFAULT_FEATURE_FLAGS = {
-  exampleConsistencyCheckFeature: 'OLD',
+  // This feature flag mostly exists to test the feature flag system, and doesn't have any build/runtime effect
   exampleFeature: false,
+  exampleConsistencyCheckFeature: 'OLD',
+  /**
+   * Rust backed requests
+   */
   atlaspackV3: false,
+  /**
+   * Use node.js implementation of @parcel/watcher watchman backend
+   */
   useWatchmanWatcher: false,
+  /**
+   * Configure runtime to enable retriable dynamic imports
+   */
   importRetry: false,
+  /**
+   * Fixes quadratic cache invalidation issue
+   */
   fixQuadraticCacheInvalidation: 'OLD',
+  /**
+   * Enables an experimental "conditional bundling" API - this allows the use of `importCond` syntax
+   * in order to have (consumer) feature flag driven bundling. This feature is very experimental,
+   * and requires server-side support.
+   */
   conditionalBundlingApi: false,
+  /**
+   * Enable VCS mode. Expected values are:
+   * - OLD - default value, return watchman result
+   * - NEW_AND_CHECK - Return VCS result but still call watchman
+   * - NEW: Return VCS result, but don't call watchman
+   */
   vcsMode: 'OLD',
+  /**
+   * Refactor cache to:
+   * - Split writes into multiple entries
+   * - Remove "large file blob" writes
+   * - Reduce size of the caches by deduplicating data
+   */
+  cachePerformanceImprovements: process.env.ATLASPACK_BUILD_ENV === 'test',
+  /**
+   * Deduplicates environments across cache / memory entities
+   */
+  environmentDeduplication: false,
+  /**
+   * Enable scanning for the presence of loadable to determine side effects
+   */
   loadableSideEffects: false,
+  /**
+   * Enable performance optimization for the resolver specifier to_string
+   * conversions
+   */
   reduceResolverStringCreation: false,
+  /**
+   * Add verbose metrics for request tracker invalidation.
+   * Default to true as it's a monitoring change. Can be turned off if necessary.
+   */
+  verboseRequestInvalidationStats: true,
+  /**
+   * Fixes source maps for inline bundles
+   */
   inlineBundlesSourceMapFixes: false,
+  /** Enable patch project paths. This will patch the project paths to be relative to the project root.
+   * This feature is experimental and should not be used in production. It will used to test downloadble cache artefacts.
+   */
   patchProjectPaths: false,
-  cachePerformanceImprovements: process.env.NODE_ENV === 'test',
-  environmentDeduplication: false,
+  /**
+   * Enables optimized inline string replacement perf for the packager.
+   * Used heavily for inline bundles.
+   */
   inlineStringReplacementPerf: false,
-  // Default to true as it's a monitoring change. Can be turned off if necessary.
-  verboseRequestInvalidationStats: true,
+  /**
+   * Enable resolution of bundler config starting from the CWD
+   */
   resolveBundlerConfigFromCwd: false,
+  /**
+   * Enable a setting that allows for more assets to be scope hoisted, if
+   * they're safe to do so.
+   */
   applyScopeHoistingImprovement: false,
+  /**
+   * Enable a change where a constant module only have the namespacing object added in bundles where it is required
+   */
   inlineConstOptimisationFix: false,
+  /**
+   * Improves/fixes HMR behaviour by:
+   * - Fixing HMR behaviour with lazy bundle edges
+   * - Moving the functionality of the react-refresh runtime into the react-refresh-wrap transformer
+   */
   hmrImprovements: false,
-  unusedComputedPropertyFix: process.env.NODE_ENV === 'test',
-  emptyFileStarRexportFix: process.env.NODE_ENV === 'test',
+  /**
+   * Fixes a bug where imported objects that are accessed with non-static
+   * properties (e.g. `CONSTANTS['api_' + endpoint`]) would not be recognised as
+   * being used, and thus not included in the bundle.
+   */
+  unusedComputedPropertyFix: process.env.ATLASPACK_BUILD_ENV === 'test',
+  /**
+   * Fixes an issue where star re-exports of empty files (usually occurring in compiled typescript libraries)
+   * could cause exports to undefined at runtime.
+   */
+  emptyFileStarRexportFix: process.env.ATLASPACK_BUILD_ENV === 'test',
+  /**
+   * Enables the new packaging progress CLI experience
+   */
   cliProgressReportingImprovements: false,
-  supportWebpackChunkName: process.env.NODE_ENV === 'test',
+  /**
+   * Adds support for `webpackChunkName` comments in dynamic imports.
+   * Imports with the same `webpackChunkName` will be bundled together.
+   */
+  supportWebpackChunkName: process.env.ATLASPACK_BUILD_ENV === 'test',
+  /**
+   * Enable a change to the conditional bundling loader to use a fallback bundle loading if the expected scripts aren't found
+   *
+   * Split into two flags, to allow usage in the dev or prod packagers separately
+   */
   condbDevFallbackDev: false,
   condbDevFallbackProd: false,
-  incrementalBundlingVersioning: process.env.NODE_ENV === 'test',
-  inlineIsolatedScripts: process.env.NODE_ENV === 'test'
+  /**
+   * Enable the new incremental bundling versioning logic which determines whether
+   * a full bundling pass is required based on the AssetGraph's bundlingVersion.
+   */
+  incrementalBundlingVersioning: process.env.ATLASPACK_BUILD_ENV === 'test',
+  /**
+   * Allow for the use of `data-atlaspack-isolated` on script tags in HTML to produce
+   * inline scripts that are build as "isolated" bundles.
+   */
+  inlineIsolatedScripts: process.env.ATLASPACK_BUILD_ENV === 'test'
 };
 let featureFlagValues = {
   ...DEFAULT_FEATURE_FLAGS

package/lib/{index.d.ts → types/index.d.ts}

@@ -1,14 +1,16 @@
-export type FeatureFlags = {
-    readonly exampleFeature: boolean;
-    readonly exampleConsistencyCheckFeature: ConsistencyCheckFeatureFlagValue;
+export type ConsistencyCheckFeatureFlagValue = (typeof CONSISTENCY_CHECK_VALUES)[number];
+export declare const CONSISTENCY_CHECK_VALUES: ReadonlyArray<string>;
+export declare const DEFAULT_FEATURE_FLAGS: {
+    exampleFeature: boolean;
+    exampleConsistencyCheckFeature: ConsistencyCheckFeatureFlagValue;
     /**
      * Rust backed requests
      */
-    readonly atlaspackV3: boolean;
+    atlaspackV3: boolean;
     /**
      * Use node.js implementation of @parcel/watcher watchman backend
      */
-    readonly useWatchmanWatcher: boolean;
+    useWatchmanWatcher: boolean;
     /**
      * Configure runtime to enable retriable dynamic imports
      */
@@ -51,7 +53,8 @@ export type FeatureFlags = {
      */
     reduceResolverStringCreation: boolean;
     /**
-     * Add verbose metrics for request tracker invalidation
+     * Add verbose metrics for request tracker invalidation.
+     * Default to true as it's a monitoring change. Can be turned off if necessary.
      */
     verboseRequestInvalidationStats: boolean;
     /**
@@ -124,9 +127,7 @@ export type FeatureFlags = {
      */
     inlineIsolatedScripts: boolean;
 };
-export type ConsistencyCheckFeatureFlagValue = (typeof CONSISTENCY_CHECK_VALUES)[number];
-export declare const CONSISTENCY_CHECK_VALUES: ReadonlyArray<string>;
-export declare const DEFAULT_FEATURE_FLAGS: FeatureFlags;
+export type FeatureFlags = typeof DEFAULT_FEATURE_FLAGS;
 export declare function setFeatureFlags(flags: FeatureFlags): void;
 export declare function getFeatureFlag(flagName: keyof FeatureFlags): boolean;
 export declare function getFeatureFlagValue(flagName: keyof FeatureFlags): boolean | string | number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaspack/feature-flags",
-  "version": "2.21.0",
+  "version": "2.23.0",
   "description": "Provides internal feature-flags for the atlaspack codebase.",
   "license": "(MIT OR Apache-2.0)",
   "publishConfig": {
@@ -12,12 +12,13 @@
   },
   "main": "./lib/index.js",
   "source": "./src/index.ts",
-  "types": "./lib/index.d.ts",
+  "types": "./lib/types/index.d.ts",
   "scripts": {
-    "check-ts": "tsc --emitDeclarationOnly --rootDir src"
+    "check-ts": "tsc --emitDeclarationOnly --rootDir src",
+    "build:lib": "gulp build --gulpfile ../../../gulpfile.js --cwd ."
   },
   "engines": {
     "node": ">= 16.0.0"
   },
   "type": "commonjs"
-}
+}

package/src/index.ts

@@ -1,36 +1,46 @@
 // Converted from Flow to TypeScript
 
-export type FeatureFlags = {
+export type ConsistencyCheckFeatureFlagValue =
+  (typeof CONSISTENCY_CHECK_VALUES)[number];
+
+export const CONSISTENCY_CHECK_VALUES: ReadonlyArray<string> = Object.freeze([
+  'NEW',
+  'OLD',
+  'NEW_AND_CHECK',
+  'OLD_AND_CHECK',
+]);
+
+export const DEFAULT_FEATURE_FLAGS = {
   // This feature flag mostly exists to test the feature flag system, and doesn't have any build/runtime effect
-  readonly exampleFeature: boolean;
-  readonly exampleConsistencyCheckFeature: ConsistencyCheckFeatureFlagValue;
+  exampleFeature: false,
+  exampleConsistencyCheckFeature: 'OLD' as ConsistencyCheckFeatureFlagValue,
 
   /**
    * Rust backed requests
    */
-  readonly atlaspackV3: boolean;
+  atlaspackV3: false,
 
   /**
    * Use node.js implementation of @parcel/watcher watchman backend
    */
-  readonly useWatchmanWatcher: boolean;
+  useWatchmanWatcher: false,
 
   /**
    * Configure runtime to enable retriable dynamic imports
    */
-  importRetry: boolean;
+  importRetry: false,
 
   /**
    * Fixes quadratic cache invalidation issue
    */
-  fixQuadraticCacheInvalidation: ConsistencyCheckFeatureFlagValue;
+  fixQuadraticCacheInvalidation: 'OLD' as ConsistencyCheckFeatureFlagValue,
 
   /**
    * Enables an experimental "conditional bundling" API - this allows the use of `importCond` syntax
    * in order to have (consumer) feature flag driven bundling. This feature is very experimental,
    * and requires server-side support.
    */
-  conditionalBundlingApi: boolean;
+  conditionalBundlingApi: false,
 
   /**
    * Enable VCS mode. Expected values are:
@@ -38,7 +48,7 @@ export type FeatureFlags = {
    * - NEW_AND_CHECK - Return VCS result but still call watchman
    * - NEW: Return VCS result, but don't call watchman
    */
-  vcsMode: ConsistencyCheckFeatureFlagValue;
+  vcsMode: 'OLD' as ConsistencyCheckFeatureFlagValue,
 
   /**
    * Refactor cache to:
@@ -46,154 +56,114 @@ export type FeatureFlags = {
    * - Remove "large file blob" writes
    * - Reduce size of the caches by deduplicating data
    */
-  cachePerformanceImprovements: boolean;
+  cachePerformanceImprovements: process.env.ATLASPACK_BUILD_ENV === 'test',
 
   /**
    * Deduplicates environments across cache / memory entities
    */
-  environmentDeduplication: boolean;
+  environmentDeduplication: false,
 
   /**
    * Enable scanning for the presence of loadable to determine side effects
    */
-  loadableSideEffects: boolean;
+  loadableSideEffects: false,
 
   /**
    * Enable performance optimization for the resolver specifier to_string
    * conversions
    */
-  reduceResolverStringCreation: boolean;
+  reduceResolverStringCreation: false,
 
   /**
-   * Add verbose metrics for request tracker invalidation
+   * Add verbose metrics for request tracker invalidation.
+   * Default to true as it's a monitoring change. Can be turned off if necessary.
    */
-  verboseRequestInvalidationStats: boolean;
+  verboseRequestInvalidationStats: true,
 
   /**
    * Fixes source maps for inline bundles
    */
-  inlineBundlesSourceMapFixes: boolean;
+  inlineBundlesSourceMapFixes: false,
 
   /** Enable patch project paths. This will patch the project paths to be relative to the project root.
    * This feature is experimental and should not be used in production. It will used to test downloadble cache artefacts.
    */
-  patchProjectPaths: boolean;
+  patchProjectPaths: false,
 
   /**
    * Enables optimized inline string replacement perf for the packager.
    * Used heavily for inline bundles.
    */
-  inlineStringReplacementPerf: boolean;
+  inlineStringReplacementPerf: false,
 
   /**
    * Enable resolution of bundler config starting from the CWD
    */
-  resolveBundlerConfigFromCwd: boolean;
+  resolveBundlerConfigFromCwd: false,
 
   /**
    * Enable a setting that allows for more assets to be scope hoisted, if
    * they're safe to do so.
    */
-  applyScopeHoistingImprovement: boolean;
+  applyScopeHoistingImprovement: false,
 
   /**
    * Enable a change where a constant module only have the namespacing object added in bundles where it is required
    */
-  inlineConstOptimisationFix: boolean;
+  inlineConstOptimisationFix: false,
 
   /**
    * Improves/fixes HMR behaviour by:
    * - Fixing HMR behaviour with lazy bundle edges
    * - Moving the functionality of the react-refresh runtime into the react-refresh-wrap transformer
    */
-  hmrImprovements: boolean;
+  hmrImprovements: false,
 
   /**
    * Fixes a bug where imported objects that are accessed with non-static
    * properties (e.g. `CONSTANTS['api_' + endpoint`]) would not be recognised as
    * being used, and thus not included in the bundle.
    */
-  unusedComputedPropertyFix: boolean;
+  unusedComputedPropertyFix: process.env.ATLASPACK_BUILD_ENV === 'test',
 
   /**
    * Fixes an issue where star re-exports of empty files (usually occurring in compiled typescript libraries)
    * could cause exports to undefined at runtime.
    */
-  emptyFileStarRexportFix: boolean;
+  emptyFileStarRexportFix: process.env.ATLASPACK_BUILD_ENV === 'test',
 
   /**
    * Enables the new packaging progress CLI experience
    */
-  cliProgressReportingImprovements: boolean;
+  cliProgressReportingImprovements: false,
 
   /**
    * Adds support for `webpackChunkName` comments in dynamic imports.
    * Imports with the same `webpackChunkName` will be bundled together.
    */
-  supportWebpackChunkName: boolean;
+  supportWebpackChunkName: process.env.ATLASPACK_BUILD_ENV === 'test',
 
   /**
    * Enable a change to the conditional bundling loader to use a fallback bundle loading if the expected scripts aren't found
    *
    * Split into two flags, to allow usage in the dev or prod packagers separately
    */
-  condbDevFallbackDev: boolean;
-  condbDevFallbackProd: boolean;
+  condbDevFallbackDev: false,
+  condbDevFallbackProd: false,
 
   /**
    * Enable the new incremental bundling versioning logic which determines whether
    * a full bundling pass is required based on the AssetGraph's bundlingVersion.
    */
-  incrementalBundlingVersioning: boolean;
-
+  incrementalBundlingVersioning: process.env.ATLASPACK_BUILD_ENV === 'test',
   /**
    * Allow for the use of `data-atlaspack-isolated` on script tags in HTML to produce
    * inline scripts that are build as "isolated" bundles.
    */
-  inlineIsolatedScripts: boolean;
+  inlineIsolatedScripts: process.env.ATLASPACK_BUILD_ENV === 'test',
 };
 
-export type ConsistencyCheckFeatureFlagValue =
-  (typeof CONSISTENCY_CHECK_VALUES)[number];
-
-export const CONSISTENCY_CHECK_VALUES: ReadonlyArray<string> = Object.freeze([
-  'NEW',
-  'OLD',
-  'NEW_AND_CHECK',
-  'OLD_AND_CHECK',
-]);
-
-export const DEFAULT_FEATURE_FLAGS: FeatureFlags = {
-  exampleConsistencyCheckFeature: 'OLD',
-  exampleFeature: false,
-  atlaspackV3: false,
-  useWatchmanWatcher: false,
-  importRetry: false,
-  fixQuadraticCacheInvalidation: 'OLD',
-  conditionalBundlingApi: false,
-  vcsMode: 'OLD',
-  loadableSideEffects: false,
-  reduceResolverStringCreation: false,
-  inlineBundlesSourceMapFixes: false,
-  patchProjectPaths: false,
-  cachePerformanceImprovements: process.env.NODE_ENV === 'test',
-  environmentDeduplication: false,
-  inlineStringReplacementPerf: false,
-  // Default to true as it's a monitoring change. Can be turned off if necessary.
-  verboseRequestInvalidationStats: true,
-  resolveBundlerConfigFromCwd: false,
-  applyScopeHoistingImprovement: false,
-  inlineConstOptimisationFix: false,
-  hmrImprovements: false,
-  unusedComputedPropertyFix: process.env.NODE_ENV === 'test',
-  emptyFileStarRexportFix: process.env.NODE_ENV === 'test',
-  cliProgressReportingImprovements: false,
-  supportWebpackChunkName: process.env.NODE_ENV === 'test',
-  condbDevFallbackDev: false,
-  condbDevFallbackProd: false,
-  incrementalBundlingVersioning: process.env.NODE_ENV === 'test',
-  inlineIsolatedScripts: process.env.NODE_ENV === 'test',
-};
+export type FeatureFlags = typeof DEFAULT_FEATURE_FLAGS;
 
 let featureFlagValues: FeatureFlags = {...DEFAULT_FEATURE_FLAGS};