@atlaskit/node-data-provider 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @atlaskit/node-data-provider
 
+## 4.3.0
+
+### Minor Changes
+
+- [#191314](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/pull-requests/191314)
+  [`ff7de5572e25d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ff7de5572e25d) -
+  [https://product-fabric.atlassian.net/browse/ED-28587](ED-28587) - implement NodeDataProvider and
+  prefetchNodeDataProvidersData for One Tick Provider project
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 4.2.0
 
 ### Minor Changes

package/dist/cjs/index.js

@@ -1 +1,19 @@
-"use strict";
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "NodeDataProvider", {
+  enumerable: true,
+  get: function get() {
+    return _nodeDataProvider.NodeDataProvider;
+  }
+});
+Object.defineProperty(exports, "prefetchNodeDataProvidersData", {
+  enumerable: true,
+  get: function get() {
+    return _prefetchNodeDataProvidersData.prefetchNodeDataProvidersData;
+  }
+});
+var _nodeDataProvider = require("./node-data-provider");
+var _prefetchNodeDataProvidersData = require("./utils/prefetch-node-data-providers-data");

package/dist/cjs/node-data-provider.js

@@ -0,0 +1,252 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NodeDataProvider = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+var _coreUtils = require("@atlaskit/editor-common/core-utils");
+/**
+ * Represents the SSR data for a single provider.
+ * It's a map where each key is a unique node data key and the value is the prefetched data for that node.
+ *
+ * @example
+ * {
+ *   'node-id-1': { value: 'some data' },
+ *   'node-id-2': { value: 'other data' }
+ * }
+ */
+/**
+ * Represents the cached data for a Node Data Provider.
+ * Each key is a unique node data key, and the value is an object containing:
+ * - `source`: Indicates whether the data was fetched from SSR or the network.
+ * - `data`: The actual data, which can be either a resolved value or a Promise.
+ *
+ * @example
+ * {
+ *   'node-id-1': { source: 'ssr', data: { value: 'some data' } },
+ *   'node-id-2': { source: 'network', data: Promise.resolve({ value: 'other data' }) }
+ * }
+ */
+/**
+ * A Node Data Provider is responsible for fetching and caching data associated with specific ProseMirror nodes.
+ * It supports a cache-first-then-network strategy, with initial data potentially provided via SSR.
+ *
+ * @template Node The specific type of JSONNode this provider supports.
+ * @template Data The type of data this provider fetches and manages.
+ */
+var NodeDataProvider = exports.NodeDataProvider = /*#__PURE__*/function () {
+  function NodeDataProvider() {
+    (0, _classCallCheck2.default)(this, NodeDataProvider);
+    this.cacheVersion = 0;
+    this.cache = {};
+  }
+
+  /**
+   * Sets the SSR data for the provider.
+   * This pre-populates the cache with data rendered on the server, preventing redundant network requests on the client.
+   * Calling this method will invalidate the existing cache.
+   *
+   * @example
+   * ```
+   * const ssrData = window.__SSR_NODE_DATA__ || {};
+   * nodeDataProvider.setSSRData(ssrData);
+   * ```
+   *
+   * @param ssrData A map of node data keys to their corresponding data.
+   */
+  return (0, _createClass2.default)(NodeDataProvider, [{
+    key: "setSSRData",
+    value: function setSSRData() {
+      var ssrData = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      this.cacheVersion++;
+      this.cache = Object.entries(ssrData).reduce(function (acc, _ref) {
+        var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
+          key = _ref2[0],
+          data = _ref2[1];
+        acc[key] = {
+          source: 'ssr',
+          data: data
+        };
+        return acc;
+      }, {});
+    }
+
+    /**
+     * Clears all cached data.
+     * This increments the internal cache version, invalidating any pending network requests.
+     *
+     * @example
+     * ```
+     * function useMyNodeDataProvider(contentId: string) {
+     *  const nodeDataProvider = new MyNodeDataProvider();
+     *
+     *  // Reset the cache when the contentId changes (e.g., when the user navigates to a different page).
+     *  useEffect(() => {
+     *    nodeDataProvider.resetCache();
+     *  }, [contentId]);
+     *
+     *  return nodeDataProvider;
+     * }
+     * ```
+     */
+  }, {
+    key: "resetCache",
+    value: function resetCache() {
+      this.cacheVersion++;
+      this.cache = {};
+    }
+
+    /**
+     * Fetches data for a given node using a cache-first-then-network strategy.
+     *
+     * The provided callback may be called multiple times:
+     * 1. Immediately with data from the SSR cache, if available.
+     * 2. Asynchronously with data fetched from the network.
+     *
+     * @example
+     * ```
+     * const nodeDataProvider = new MyNodeDataProvider();
+     *
+     * nodeDataProvider.getData(node, (data) => {
+     * 	console.log('Node data:', data);
+     * });
+     * ```
+     *
+     * @param node The node (or its ProseMirror representation) for which to fetch data.
+     * @param callback The function to call when data is available.
+     */
+  }, {
+    key: "getData",
+    value: function getData(node, callback) {
+      // Move implementation to a separate async method
+      // to keep this method synchronous and avoid async/await in the public API.
+      void this.getDataAsync(node, callback);
+    }
+  }, {
+    key: "getDataAsync",
+    value: function () {
+      var _getDataAsync = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(node, callback) {
+        var jsonNode, dataKey, dataFromCache, cacheVersionBeforeRequest, dataPromise, data;
+        return _regenerator.default.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              jsonNode = 'toJSON' in node ? node.toJSON() : node;
+              if (this.isNodeSupported(jsonNode)) {
+                _context.next = 4;
+                break;
+              }
+              // eslint-disable-next-line no-console
+              console.error("The ".concat(this.constructor.name, " doesn't support Node ").concat(jsonNode.type, "."));
+              return _context.abrupt("return");
+            case 4:
+              dataKey = this.nodeDataKey(jsonNode);
+              dataFromCache = this.cache[dataKey];
+              if (!(dataFromCache !== undefined)) {
+                _context.next = 18;
+                break;
+              }
+              if (!isPromise(dataFromCache.data)) {
+                _context.next = 15;
+                break;
+              }
+              _context.t0 = callback;
+              _context.next = 11;
+              return dataFromCache.data;
+            case 11:
+              _context.t1 = _context.sent;
+              (0, _context.t0)(_context.t1);
+              _context.next = 16;
+              break;
+            case 15:
+              callback(dataFromCache.data);
+            case 16:
+              if (!(0, _coreUtils.isSSR)()) {
+                _context.next = 18;
+                break;
+              }
+              return _context.abrupt("return");
+            case 18:
+              if (!((dataFromCache === null || dataFromCache === void 0 ? void 0 : dataFromCache.source) !== 'network')) {
+                _context.next = 27;
+                break;
+              }
+              // Store the current cache version before making the request,
+              // so we can check if the cache has changed while we are waiting for the network response.
+              cacheVersionBeforeRequest = this.cacheVersion;
+              dataPromise = this.fetchNodesData([jsonNode]).then(function (_ref3) {
+                var _ref4 = (0, _slicedToArray2.default)(_ref3, 1),
+                  value = _ref4[0];
+                return value;
+              }); // Store the promise in the cache to avoid multiple requests for the same data
+              this.cache[dataKey] = {
+                source: 'network',
+                data: dataPromise
+              };
+              _context.next = 24;
+              return dataPromise;
+            case 24:
+              data = _context.sent;
+              // We need to call the callback with the data with result even if the cache version has changed,
+              // so all promises that are waiting for the data can resolve.
+              callback(data);
+
+              // If the cache version has changed, we don't want to use the data from the network
+              // because it could be stale data.
+              if (cacheVersionBeforeRequest === this.cacheVersion) {
+                // Replace promise with the resolved data in the cache
+                this.cache[dataKey] = {
+                  source: 'network',
+                  data: data
+                };
+              }
+            case 27:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee, this);
+      }));
+      function getDataAsync(_x, _x2) {
+        return _getDataAsync.apply(this, arguments);
+      }
+      return getDataAsync;
+    }()
+    /**
+     * Fetches data for a given node and returns it as a Promise.
+     * This is a convenience wrapper around the `data` method for use with async/await.
+     *
+     * Note: This promise resolves with the *first* available data, which could be from the SSR cache or the network.
+     * It may not provide the most up-to-date data if a network fetch is in progress.
+     *
+     * Note: This method is only for migration purposes. Use {@link getData} in new code instead.
+     *
+     * @private
+     * @deprecated Don't use this method, use {@link getData} method instead.
+     *             This method is only for migration purposes.
+     *
+     * @param node The node (or its ProseMirror representation) for which to fetch data.
+     * @returns A promise that resolves with the node's data.
+     */
+  }, {
+    key: "getDataAsPromise_DO_NOT_USE_OUTSIDE_MIGRATIONS",
+    value: function getDataAsPromise_DO_NOT_USE_OUTSIDE_MIGRATIONS(node) {
+      var _this = this;
+      return new Promise(function (resolve, reject) {
+        try {
+          return _this.getData(node, resolve);
+        } catch (error) {
+          reject(error);
+        }
+      });
+    }
+  }]);
+}();
+function isPromise(value) {
+  return (0, _typeof2.default)(value) === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
+}

package/dist/cjs/utils/find-nodes-to-prefetch.js

@@ -0,0 +1,68 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.findNodesToPrefetch = findNodesToPrefetch;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
+/**
+ * Finds nodes in the document that are supported by the given providers, up to a maximum number of nodes.
+ *
+ * @param doc The document to search for nodes.
+ * @param providers An array of providers with their maximum nodes to prefetch.
+ * @param maxNodesToVisit The maximum number of nodes to visit in the document.
+ * @returns An array of objects, each containing a provider and the nodes that are supported by that provider.
+ */
+function findNodesToPrefetch(doc, providers, maxNodesToVisit) {
+  var totalVisitedNodesCount = 0;
+  var resultMap = providers.reduce(function (acc, _ref) {
+    var provider = _ref.provider;
+    acc[provider.name] = {
+      provider: provider,
+      nodes: []
+    };
+    return acc;
+  }, {});
+
+  // It doesn't use `filter` function from `@atlaskit/adf-utils/traverse` because it does not support early stopping.
+  // We need to stop traversing when we reach the maximum number of nodes to visit to support large documents.
+
+  var providersToLookup = providers.filter(function (_ref2) {
+    var maxNodesToPrefetch = _ref2.maxNodesToPrefetch;
+    return maxNodesToPrefetch > 0;
+  }).map(function (_ref3) {
+    var provider = _ref3.provider,
+      maxNodesToPrefetch = _ref3.maxNodesToPrefetch;
+    return {
+      provider: provider,
+      maxNodesToPrefetch: maxNodesToPrefetch,
+      foundNodes: 0
+    };
+  });
+  var nodesToVisit = [doc];
+  var currentIndex = 0;
+  while (currentIndex < nodesToVisit.length && providersToLookup.length > 0 && totalVisitedNodesCount < maxNodesToVisit) {
+    totalVisitedNodesCount += 1;
+    var currentNode = nodesToVisit[currentIndex];
+    currentIndex++;
+
+    // Using reverse loop to avoid issues with array mutation
+    for (var i = providersToLookup.length - 1; i >= 0; i--) {
+      var providerToFind = providersToLookup[i];
+      if (providerToFind.provider.isNodeSupported(currentNode)) {
+        resultMap[providerToFind.provider.name].nodes.push(currentNode);
+        providerToFind.foundNodes += 1;
+        if (providerToFind.foundNodes >= providerToFind.maxNodesToPrefetch) {
+          providersToLookup.splice(i, 1);
+        }
+      }
+    }
+    if (currentNode.content) {
+      nodesToVisit.push.apply(nodesToVisit, (0, _toConsumableArray2.default)(currentNode.content.filter(function (node) {
+        return node !== undefined;
+      })));
+    }
+  }
+  return Object.values(resultMap);
+}

package/dist/cjs/utils/prefetch-node-data-providers-data.js

@@ -0,0 +1,165 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.prefetchNodeDataProvidersData = prefetchNodeDataProvidersData;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _findNodesToPrefetch = require("./find-nodes-to-prefetch");
+/**
+ * Represents the SSR data for a single provider.
+ * It's a map where each key is a unique node data key and the value is the prefetched data for that node.
+ *
+ * @example
+ * {
+ *   'node-id-1': { value: 'some data' },
+ *   'node-id-2': { value: 'other data' }
+ * }
+ */
+/**
+ * Represents the aggregated SSR data for all node data providers.
+ * It's a map where each key is a provider's name and the value is the {@link SsrData} for that provider.
+ * This structure is used to hydrate the client-side caches.
+ *
+ * @example
+ * {
+ *   'mentionProvider': { 'mention-1': { id: '1', name: 'John Doe' } },
+ *   'emojiProvider': { 'emoji-123': { shortName: ':smile:', representation: '😊' } }
+ * }
+ */
+/**
+ * Fetches data for nodes in the document that are supported by the given providers.
+ * This function will traverse the document and call the `fetchData` method for each node that is supported by the providers.
+ *
+ * @example
+ * ```
+ * const doc = JSON.parse('{"type": "doc", "content": [...] }');
+ * const providers = [
+ *   {
+ *     provider: new EditorCardProvider(),
+ *  	  maxNodesToPrefetch: 10,
+ *  	  timeout: 500,
+ *  	},
+ *   {
+ *     provider: new EditorMentionsProvider(),
+ *     maxNodesToPrefetch: 50,
+ *  	  timeout: 500,
+ *   },
+ * ];
+ *
+ * window['__SSR_EDITOR_NODE_DATA_PROVIDERS_DATA__'] = await prefetchNodeDataProvidersData({
+ *   providers,
+ *   doc,
+ *   timeout: 1_000,
+ *   maxNodesToVisit: 2_000
+ * });
+ * ```
+ *
+ * @param props The properties for prefetching node data.
+ * @returns Record of provider names to their respective SSR data,
+ *          where each SSR data is a record of node data keys to the fetched data.
+ */
+function prefetchNodeDataProvidersData(_x) {
+  return _prefetchNodeDataProvidersData.apply(this, arguments);
+}
+function _prefetchNodeDataProvidersData() {
+  _prefetchNodeDataProvidersData = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2(_ref) {
+    var providers, doc, timeout, _ref$maxNodesToVisit, maxNodesToVisit, providersWithDefaults, providerTimeouts, nodesWithProviders, promises, results;
+    return _regenerator.default.wrap(function _callee2$(_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          providers = _ref.providers, doc = _ref.doc, timeout = _ref.timeout, _ref$maxNodesToVisit = _ref.maxNodesToVisit, maxNodesToVisit = _ref$maxNodesToVisit === void 0 ? Infinity : _ref$maxNodesToVisit;
+          providersWithDefaults = providers.map(function (_ref2) {
+            var provider = _ref2.provider,
+              _ref2$maxNodesToPrefe = _ref2.maxNodesToPrefetch,
+              maxNodesToPrefetch = _ref2$maxNodesToPrefe === void 0 ? Infinity : _ref2$maxNodesToPrefe,
+              _ref2$timeout = _ref2.timeout,
+              providerTimeout = _ref2$timeout === void 0 ? Infinity : _ref2$timeout;
+            return {
+              provider: provider,
+              maxNodesToPrefetch: maxNodesToPrefetch,
+              // Use the minimum of the global timeout and the provider-specific timeout
+              timeout: Math.min(providerTimeout, timeout)
+            };
+          });
+          providerTimeouts = providersWithDefaults.reduce(function (acc, _ref3) {
+            var provider = _ref3.provider,
+              timeout = _ref3.timeout;
+            acc[provider.name] = timeout;
+            return acc;
+          }, {});
+          nodesWithProviders = (0, _findNodesToPrefetch.findNodesToPrefetch)(doc, providersWithDefaults, maxNodesToVisit).map(function (_ref4) {
+            var provider = _ref4.provider,
+              nodes = _ref4.nodes;
+            return {
+              provider: provider,
+              nodes: nodes,
+              timeout: providerTimeouts[provider.name]
+            };
+          });
+          promises = nodesWithProviders.map( /*#__PURE__*/function () {
+            var _ref6 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(_ref5) {
+              var nodes, provider, timeout, timeoutPromise, data;
+              return _regenerator.default.wrap(function _callee$(_context) {
+                while (1) switch (_context.prev = _context.next) {
+                  case 0:
+                    nodes = _ref5.nodes, provider = _ref5.provider, timeout = _ref5.timeout;
+                    _context.prev = 1;
+                    timeoutPromise = new Promise(function (resolve) {
+                      setTimeout(function () {
+                        resolve([]);
+                      }, timeout);
+                    });
+                    _context.next = 5;
+                    return Promise.race([provider.fetchNodesData(nodes), timeoutPromise]);
+                  case 5:
+                    data = _context.sent;
+                    return _context.abrupt("return", {
+                      provider: provider,
+                      nodes: nodes,
+                      data: data
+                    });
+                  case 9:
+                    _context.prev = 9;
+                    _context.t0 = _context["catch"](1);
+                    return _context.abrupt("return", {
+                      provider: provider,
+                      nodes: nodes,
+                      data: []
+                    });
+                  case 12:
+                  case "end":
+                    return _context.stop();
+                }
+              }, _callee, null, [[1, 9]]);
+            }));
+            return function (_x2) {
+              return _ref6.apply(this, arguments);
+            };
+          }());
+          _context2.next = 7;
+          return Promise.all(promises);
+        case 7:
+          results = _context2.sent;
+          return _context2.abrupt("return", results.reduce(function (acc, _ref7) {
+            var provider = _ref7.provider,
+              nodes = _ref7.nodes,
+              data = _ref7.data;
+            acc[provider.name] = data.reduce(function (providerSsrData, nodeData, nodeIndex) {
+              var node = nodes[nodeIndex];
+              var nodeDataKey = provider.nodeDataKey(node);
+              providerSsrData[nodeDataKey] = nodeData;
+              return providerSsrData;
+            }, {});
+            return acc;
+          }, {}));
+        case 9:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee2);
+  }));
+  return _prefetchNodeDataProvidersData.apply(this, arguments);
+}

package/dist/es2019/index.js

@@ -0,0 +1,4 @@
+/* eslint-disable @atlaskit/editor/no-re-export */
+
+export { NodeDataProvider } from './node-data-provider';
+export { prefetchNodeDataProvidersData } from './utils/prefetch-node-data-providers-data';