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

package/declarations/-private/utils/deprecations.d.ts

@@ -0,0 +1,5 @@
+import * as CURRENT_DEPRECATIONS from "../../deprecation-versions.js";
+type MajorMinor = `${number}.${number}`;
+type DeprecationFlag = keyof typeof CURRENT_DEPRECATIONS;
+export declare function getDeprecations(compatVersion: MajorMinor | null | undefined, deprecations?: { [key in DeprecationFlag]? : boolean }): { [key in DeprecationFlag] : boolean };
+export {};

package/declarations/-private/utils/features.d.ts

@@ -0,0 +1,4 @@
+import * as CURRENT_FEATURES from "../../canary-features.js";
+type FEATURE = keyof typeof CURRENT_FEATURES;
+export declare function getFeatures(isProd: boolean): { [key in FEATURE] : boolean };
+export {};

package/declarations/-private/utils/get-env.d.ts

@@ -0,0 +1,8 @@
+export declare function getEnv(forceMode?: "testing" | "production" | "development" | "debug"): {
+	TESTING: boolean;
+	PRODUCTION: boolean;
+	DEBUG: boolean;
+	IS_RECORDING: boolean;
+	IS_CI: boolean;
+	SHOULD_RECORD: boolean;
+};

package/declarations/-private/utils/logging.d.ts

@@ -0,0 +1,9 @@
+import * as LOGGING from "../../debugging.js";
+type LOG_CONFIG_KEY = keyof typeof LOGGING;
+export type LOG_CONFIG = { [key in LOG_CONFIG_KEY] : boolean };
+export declare function createLoggingConfig(env: {
+	DEBUG: boolean;
+	TESTING: boolean;
+	PRODUCTION: boolean;
+}, debug: LOG_CONFIG): LOG_CONFIG;
+export {};

package/declarations/babel-macros.d.ts

@@ -0,0 +1,13 @@
+type BabelPlugin = [string, Record<string, unknown>, string];
+/**
+* @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`
+*/
+export declare function macros(): BabelPlugin[];
+export {};

package/declarations/canary-features.d.ts

@@ -0,0 +1,136 @@
+/**
+*
+* # 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
+*/
+export declare const SAMPLE_FEATURE_FLAG: boolean | 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
+*/
+export declare const JSON_API_CACHE_VALIDATION_ERRORS: boolean | null;

package/declarations/debugging.d.ts

@@ -0,0 +1,172 @@
+/**
+* # 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.
+*
+* Log instrumentation is "regionalized" to specific concepts and concerns
+* to enable you to enable/disable just the areas you are interested in.
+*
+* To activate a particular group of logs set the appropriate flag to `true`
+* either in your build config or via the runtime helper.
+*
+*
+* ## Runtime Activation
+*
+* ::: tip 💡 Just Works in browser Dev Tools!
+* No import is needed, and the logging config is preserved when the page is refreshed
+* :::
+*
+* ```ts
+* setWarpDriveLogging({
+*   LOG_CACHE: true,
+*   LOG_REQUESTS: true,
+* })
+* ```
+*
+* 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: true,
+*     LOG_REQUESTS: false,
+*     LOG_NOTIFICATIONS: true,
+*   }
+* });
+* ```
+*
+* 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
+* and remote state. Note in some older versions
+* this was called `LOG_PAYLOADS` and was one
+* of three flags that controlled logging of
+* cache updates. This is now the only flag.
+*
+* The others were `LOG_OPERATIONS` and `LOG_MUTATIONS`.
+*
+* @public
+* @since 5.5
+*/
+export declare const LOG_CACHE: boolean;
+/**
+* <Badge type="danger" text="removed" />
+*
+* This flag no longer has any effect.
+*
+* Use {@link LOG_CACHE} instead.
+*
+* @deprecated removed in version 5.5
+* @public
+*/
+export declare const LOG_PAYLOADS: boolean;
+/**
+* <Badge type="danger" text="removed" />
+*
+* This flag no longer has any effect.
+*
+* Use {@link LOG_CACHE} instead.
+*
+* @deprecated removed in version 5.5
+* @public
+*/
+export declare const LOG_OPERATIONS: boolean;
+/**
+* <Badge type="danger" text="removed" />
+*
+* This flag no longer has any effect.
+*
+* Use {@link LOG_CACHE} instead.
+*
+* @deprecated removed in version 5.5
+* @public
+*/
+export declare const LOG_MUTATIONS: boolean;
+/**
+* Log decisions made by the Basic CachePolicy
+*
+* @public
+*/
+export declare const LOG_CACHE_POLICY: boolean;
+/**
+* log notifications received by the NotificationManager
+*
+* @public
+*/
+export declare const LOG_NOTIFICATIONS: boolean;
+/**
+* log requests issued by the RequestManager
+*
+* @public
+*/
+export declare const LOG_REQUESTS: boolean;
+/**
+* log updates to requests the store has issued to
+* the network (adapter) to fulfill.
+*
+* @public
+*/
+export declare const LOG_REQUEST_STATUS: boolean;
+/**
+* log peek, generation and updates to
+* Record Identifiers.
+*
+
+* @public
+*/
+export declare const LOG_IDENTIFIERS: boolean;
+/**
+* log updates received by the graph (relationship pointer storage)
+*
+* @public
+*/
+export declare const LOG_GRAPH: boolean;
+/**
+* log creation/removal of RecordData and Record
+* instances.
+*
+* @public
+*/
+export declare const LOG_INSTANCE_CACHE: boolean;
+/**
+* Log key count metrics, useful for performance
+* debugging.
+*
+* @public
+*/
+export declare const LOG_METRIC_COUNTS: boolean;
+/**
+* Helps when debugging causes of a change notification
+* when processing an update to a hasMany relationship.
+*
+* @public
+*/
+export declare const DEBUG_RELATIONSHIP_NOTIFICATIONS: boolean;
+/**
+* A private flag to enable logging of the native Map/Set
+* constructor and method calls.
+*
+* EXTREMELY MALPERFORMANT
+*
+* LOG_METRIC_COUNTS must also be enabled.
+*
+* @internal
+*/
+export declare const __INTERNAL_LOG_NATIVE_MAP_SET_COUNTS: boolean;

package/declarations/deprecation-versions.d.ts

@@ -0,0 +1,30 @@
+// ========================
+// FOR CONTRIBUTING AUTHORS
+//
+// Deprecations here should also have guides PR'd to the emberjs deprecation app
+//
+// github: https://github.com/ember-learn/deprecation-app
+// website: https://deprecations.emberjs.com
+//
+// Each deprecation should also be given an associated URL pointing to the
+// relevant guide.
+//
+// URLs should be of the form: https://deprecations.emberjs.com/v<major>.x#toc_<fileName>
+// where <major> is the major version of the deprecation and <fileName> is the
+// name of the markdown file in the guides repo.
+//
+// ========================
+//
+export declare const DEPRECATE_CATCH_ALL = "99.0";
+export declare const DEPRECATE_NON_STRICT_TYPES = "5.3";
+export declare const DEPRECATE_NON_STRICT_ID = "5.3";
+export declare const DEPRECATE_COMPUTED_CHAINS = "7.0";
+export declare const DEPRECATE_LEGACY_IMPORTS = "5.3";
+export declare const DEPRECATE_NON_UNIQUE_PAYLOADS = "5.3";
+export declare const DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE = "5.3";
+export declare const DEPRECATE_MANY_ARRAY_DUPLICATES = "5.3";
+export declare const DEPRECATE_STORE_EXTENDS_EMBER_OBJECT = "5.4";
+export declare const ENABLE_LEGACY_SCHEMA_SERVICE = "5.4";
+export declare const DEPRECATE_EMBER_INFLECTOR = "5.3";
+export declare const DISABLE_7X_DEPRECATIONS = "7.0";
+export declare const DEPRECATE_TRACKING_PACKAGE = "5.5";