WordPress/wp-includes/js/dist/private-apis.js

245 lines
8.5 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/******/ (function() { // webpackBootstrap
/******/ "use strict";
/******/ // The require scope
/******/ var __webpack_require__ = {};
/******/
/************************************************************************/
/******/ /* webpack/runtime/define property getters */
/******/ !function() {
/******/ // define getter functions for harmony exports
/******/ __webpack_require__.d = function(exports, definition) {
/******/ for(var key in definition) {
/******/ if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {
/******/ Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });
/******/ }
/******/ }
/******/ };
/******/ }();
/******/
/******/ /* webpack/runtime/hasOwnProperty shorthand */
/******/ !function() {
/******/ __webpack_require__.o = function(obj, prop) { return Object.prototype.hasOwnProperty.call(obj, prop); }
/******/ }();
/******/
/******/ /* webpack/runtime/make namespace object */
/******/ !function() {
/******/ // define __esModule on exports
/******/ __webpack_require__.r = function(exports) {
/******/ if(typeof Symbol !== 'undefined' && Symbol.toStringTag) {
/******/ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
/******/ }
/******/ Object.defineProperty(exports, '__esModule', { value: true });
/******/ };
/******/ }();
/******/
/************************************************************************/
var __webpack_exports__ = {};
// ESM COMPAT FLAG
__webpack_require__.r(__webpack_exports__);
// EXPORTS
__webpack_require__.d(__webpack_exports__, {
"__dangerousOptInToUnstableAPIsOnlyForCoreModules": function() { return /* reexport */ __dangerousOptInToUnstableAPIsOnlyForCoreModules; }
});
;// CONCATENATED MODULE: ./node_modules/@wordpress/private-apis/build-module/implementation.js
/**
* wordpress/private-apis the utilities to enable private cross-package
* exports of private APIs.
*
* This "implementation.js" file is needed for the sake of the unit tests. It
* exports more than the public API of the package to aid in testing.
*/
/**
* The list of core modules allowed to opt-in to the private APIs.
*/
const CORE_MODULES_USING_PRIVATE_APIS = ['@wordpress/block-editor', '@wordpress/block-library', '@wordpress/blocks', '@wordpress/commands', '@wordpress/components', '@wordpress/core-commands', '@wordpress/core-data', '@wordpress/customize-widgets', '@wordpress/data', '@wordpress/edit-post', '@wordpress/edit-site', '@wordpress/edit-widgets', '@wordpress/editor', '@wordpress/router'];
/**
* A list of core modules that already opted-in to
* the privateApis package.
*
* @type {string[]}
*/
const registeredPrivateApis = [];
/*
* Warning for theme and plugin developers.
*
* The use of private developer APIs is intended for use by WordPress Core
* and the Gutenberg plugin exclusively.
*
* Dangerously opting in to using these APIs is NOT RECOMMENDED. Furthermore,
* the WordPress Core philosophy to strive to maintain backward compatibility
* for third-party developers DOES NOT APPLY to private APIs.
*
* THE CONSENT STRING FOR OPTING IN TO THESE APIS MAY CHANGE AT ANY TIME AND
* WITHOUT NOTICE. THIS CHANGE WILL BREAK EXISTING THIRD-PARTY CODE. SUCH A
* CHANGE MAY OCCUR IN EITHER A MAJOR OR MINOR RELEASE.
*/
const requiredConsent = 'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.';
/** @type {boolean} */
let allowReRegistration; // The safety measure is meant for WordPress core where IS_WORDPRESS_CORE
// is set to true.
// For the general use-case, the re-registration should be allowed by default
// Let's default to true, then. Try/catch will fall back to "true" even if the
// environment variable is not explicitly defined.
try {
allowReRegistration = true ? false : 0;
} catch (error) {
allowReRegistration = true;
}
/**
* Called by a @wordpress package wishing to opt-in to accessing or exposing
* private private APIs.
*
* @param {string} consent The consent string.
* @param {string} moduleName The name of the module that is opting in.
* @return {{lock: typeof lock, unlock: typeof unlock}} An object containing the lock and unlock functions.
*/
const __dangerousOptInToUnstableAPIsOnlyForCoreModules = (consent, moduleName) => {
if (!CORE_MODULES_USING_PRIVATE_APIS.includes(moduleName)) {
throw new Error(`You tried to opt-in to unstable APIs as module "${moduleName}". ` + 'This feature is only for JavaScript modules shipped with WordPress core. ' + 'Please do not use it in plugins and themes as the unstable APIs will be removed ' + 'without a warning. If you ignore this error and depend on unstable features, ' + 'your product will inevitably break on one of the next WordPress releases.');
}
if (!allowReRegistration && registeredPrivateApis.includes(moduleName)) {
// This check doesn't play well with Story Books / Hot Module Reloading
// and isn't included in the Gutenberg plugin. It only matters in the
// WordPress core release.
throw new Error(`You tried to opt-in to unstable APIs as module "${moduleName}" which is already registered. ` + 'This feature is only for JavaScript modules shipped with WordPress core. ' + 'Please do not use it in plugins and themes as the unstable APIs will be removed ' + 'without a warning. If you ignore this error and depend on unstable features, ' + 'your product will inevitably break on one of the next WordPress releases.');
}
if (consent !== requiredConsent) {
throw new Error(`You tried to opt-in to unstable APIs without confirming you know the consequences. ` + 'This feature is only for JavaScript modules shipped with WordPress core. ' + 'Please do not use it in plugins and themes as the unstable APIs will removed ' + 'without a warning. If you ignore this error and depend on unstable features, ' + 'your product will inevitably break on the next WordPress release.');
}
registeredPrivateApis.push(moduleName);
return {
lock,
unlock
};
};
/**
* Binds private data to an object.
* It does not alter the passed object in any way, only
* registers it in an internal map of private data.
*
* The private data can't be accessed by any other means
* than the `unlock` function.
*
* @example
* ```js
* const object = {};
* const privateData = { a: 1 };
* lock( object, privateData );
*
* object
* // {}
*
* unlock( object );
* // { a: 1 }
* ```
*
* @param {any} object The object to bind the private data to.
* @param {any} privateData The private data to bind to the object.
*/
function lock(object, privateData) {
if (!object) {
throw new Error('Cannot lock an undefined object.');
}
if (!(__private in object)) {
object[__private] = {};
}
lockedData.set(object[__private], privateData);
}
/**
* Unlocks the private data bound to an object.
*
* It does not alter the passed object in any way, only
* returns the private data paired with it using the `lock()`
* function.
*
* @example
* ```js
* const object = {};
* const privateData = { a: 1 };
* lock( object, privateData );
*
* object
* // {}
*
* unlock( object );
* // { a: 1 }
* ```
*
* @param {any} object The object to unlock the private data from.
* @return {any} The private data bound to the object.
*/
function unlock(object) {
if (!object) {
throw new Error('Cannot unlock an undefined object.');
}
if (!(__private in object)) {
throw new Error('Cannot unlock an object that was not locked before. ');
}
return lockedData.get(object[__private]);
}
const lockedData = new WeakMap();
/**
* Used by lock() and unlock() to uniquely identify the private data
* related to a containing object.
*/
const __private = Symbol('Private API ID'); // Unit tests utilities:
/**
* Private function to allow the unit tests to allow
* a mock module to access the private APIs.
*
* @param {string} name The name of the module.
*/
function allowCoreModule(name) {
CORE_MODULES_USING_PRIVATE_APIS.push(name);
}
/**
* Private function to allow the unit tests to set
* a custom list of allowed modules.
*/
function resetAllowedCoreModules() {
while (CORE_MODULES_USING_PRIVATE_APIS.length) {
CORE_MODULES_USING_PRIVATE_APIS.pop();
}
}
/**
* Private function to allow the unit tests to reset
* the list of registered private apis.
*/
function resetRegisteredPrivateApis() {
while (registeredPrivateApis.length) {
registeredPrivateApis.pop();
}
}
;// CONCATENATED MODULE: ./node_modules/@wordpress/private-apis/build-module/index.js
(window.wp = window.wp || {}).privateApis = __webpack_exports__;
/******/ })()
;