@atlaskit/node-data-provider 4.1.2 → 4.3.0

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

@@ -0,0 +1,128 @@
+import { findNodesToPrefetch } from './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.
+ */
+export async function prefetchNodeDataProvidersData({
+  providers,
+  doc,
+  timeout,
+  maxNodesToVisit = Infinity
+}) {
+  const providersWithDefaults = providers.map(({
+    provider,
+    maxNodesToPrefetch = Infinity,
+    timeout: providerTimeout = Infinity
+  }) => ({
+    provider,
+    maxNodesToPrefetch,
+    // Use the minimum of the global timeout and the provider-specific timeout
+    timeout: Math.min(providerTimeout, timeout)
+  }));
+  const providerTimeouts = providersWithDefaults.reduce((acc, {
+    provider,
+    timeout
+  }) => {
+    acc[provider.name] = timeout;
+    return acc;
+  }, {});
+  const nodesWithProviders = findNodesToPrefetch(doc, providersWithDefaults, maxNodesToVisit).map(({
+    provider,
+    nodes
+  }) => ({
+    provider,
+    nodes,
+    timeout: providerTimeouts[provider.name]
+  }));
+  const promises = nodesWithProviders.map(async ({
+    nodes,
+    provider,
+    timeout
+  }) => {
+    try {
+      const timeoutPromise = new Promise(resolve => {
+        setTimeout(() => {
+          resolve([]);
+        }, timeout);
+      });
+      const data = await Promise.race([provider.fetchNodesData(nodes), timeoutPromise]);
+      return {
+        provider,
+        nodes,
+        data
+      };
+    } catch {
+      return {
+        provider,
+        nodes,
+        data: []
+      };
+    }
+  });
+  const results = await Promise.all(promises);
+  return results.reduce((acc, {
+    provider,
+    nodes,
+    data
+  }) => {
+    acc[provider.name] = data.reduce((providerSsrData, nodeData, nodeIndex) => {
+      const node = nodes[nodeIndex];
+      const nodeDataKey = provider.nodeDataKey(node);
+      providerSsrData[nodeDataKey] = nodeData;
+      return providerSsrData;
+    }, {});
+    return acc;
+  }, {});
+}

package/dist/esm/index.js

@@ -1,227 +1,4 @@
-import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
-import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
-import _createClass from "@babel/runtime/helpers/createClass";
-import _defineProperty from "@babel/runtime/helpers/defineProperty";
-import _regeneratorRuntime from "@babel/runtime/regenerator";
-function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
-function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
-/**
- * This is the base class for creating a node data provider for an editor plugin.
- *
- * ## Usage
- *
- * ### Create a provider
- *
- * @example
- * ```ts
- * class EmojiNodeDataProvider extends NodeDataProvider<
- *  { attrs: EmojiAttributes },
- * { resolvedData: string }
- * > {
- *   constructor({ existingCache }?: { existingCache: Record<string, { resolvedData: string }> }) {
- *     super({ existingCache, nodeName: 'emoji' });
- *   }
- *   nodeToKey(node: { attrs: EmojiAttributes }): string {
- *     return `${node.attrs.shortName}-${node.attrs.text}-${node.attrs.id}`;
- *   }
- *   resolve(node: { attrs: EmojiAttributes }, _?: { signal: AbortSignal }) {
- *     return Promise.resolve({ resolvedData: 'resolved' });
- *   }
- * }
- * ```
- *
- * ### Use the provider
- *
- * @example
- * ```ts
- * const emojiNodeDataProvider = new EmojiNodeDataProvider();
- * ```
- *
- * ### Caching
- *
- * @see {@link buildCaches} for more information on building caches.
- *
- * #### Load an existing provider with a cache
- *
- * @example
- * ```
- * await buildCaches({
- *  adf: docFromSomewhere,
- *  nodeDataProviders: [emojiNodeDataProvider],
- *  signal: AbortSignal.timeout(5000),
- * });
- * emojiNodeDataProvider // { 'key': 'value' }
- * ```
- *
- * ### Load an new provider with an existing cache
- *
- * @example
- * ```
- * const provider1 = new ExampleNodeDataProvider();
- * await buildCaches({adf, nodeDataProviders: [provider1]})
- * provider1.cache // { 'key': 'value' }
- *
- * const provider2 = new ExampleNodeDataProvider({existingCache: provider1.cache});
- * ```
- */
-export var NodeDataProvider = /*#__PURE__*/function () {
-  /**
-   * This takes a node and returns a key that can be used to cache the result of the resolve function.
-   */
+/* eslint-disable @atlaskit/editor/no-re-export */
 
-  /**
-   * This returns the information required to render a node.
-   *
-   * If unresolvable, this method will throw an error.
-   *
-   * If signal is aborted, this method will return undefined.
-   */
-
-  /**
-   * The adf node name this provider is responsible for.
-   */
-
-  function NodeDataProvider(_ref) {
-    var _ref$existingCache = _ref.existingCache,
-      existingCache = _ref$existingCache === void 0 ? {} : _ref$existingCache,
-      nodeName = _ref.nodeName,
-      nodeToKey = _ref.nodeToKey,
-      resolve = _ref.resolve;
-    _classCallCheck(this, NodeDataProvider);
-    /**
-     * This is added to ease building types
-     */
-    // @ts-ignore
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _defineProperty(this, "__node", {});
-    _defineProperty(this, "pending", {});
-    this.__cache = existingCache;
-    this.nodeName = nodeName;
-    this.nodeToKey = nodeToKey;
-    this.resolve = resolve;
-  }
-
-  /**
-   * Updates the providers cache.
-   *
-   * Useful in scenarios such as SSR where the cache is built on the server and then passed to the client.
-   *
-   * Avoids the need to provide the cache to the constructor (to allow decoupling creation of node data providers from cache building),
-   * and allow for caching to be managed at a group level across multiple providers.
-   *
-   * This is not expected to be used by consumers, for internal consumption examples;
-   * @see {@link buildCaches}
-   *
-   */
-  return _createClass(NodeDataProvider, [{
-    key: "updateCache",
-    value: function updateCache(cache, options) {
-      switch (options.strategy) {
-        case 'merge-override':
-          this.__cache = _objectSpread(_objectSpread({}, this.__cache), cache);
-          return;
-        case 'replace':
-          this.__cache = cache;
-          return;
-      }
-    }
-
-    /**
-     * This is the cache for the provider.
-     */
-  }, {
-    key: "cache",
-    get: function get() {
-      return this.__cache;
-    }
-  }, {
-    key: "get",
-    value: function get(node, _) {
-      var _this = this;
-      var key = this.nodeToKey(node);
-      var cached = this.cache[key];
-      if (cached) {
-        return cached;
-      }
-
-      // Get could be called from a variety of sources;
-      // - a Node Data Provider
-      // - a cache build
-      // - something else
-      //
-      // We want to avoid triggering multiple resolves for the same node -- so we keep track of pending requests
-      // and share them across any overlapping gets.
-      //
-      // When a get is cancelled -- we only want to cancel the shared resolve if all signals are aborted
-      // so we keep track of all signals that are not aborted.
-
-      var originalSignal = (_ === null || _ === void 0 ? void 0 : _.signal) || new AbortController().signal;
-      if (!this.pending[key]) {
-        var abortController = new AbortController();
-        this.pending[key] = {
-          // eslint-disable-next-line no-async-promise-executor
-          resolving: new Promise( /*#__PURE__*/function () {
-            var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(res, rej) {
-              var result;
-              return _regeneratorRuntime.wrap(function _callee$(_context) {
-                while (1) switch (_context.prev = _context.next) {
-                  case 0:
-                    _context.prev = 0;
-                    _context.next = 3;
-                    return _this.resolve(node, {
-                      signal: abortController.signal
-                    }).catch(function (res) {
-                      return res(undefined);
-                    });
-                  case 3:
-                    result = _context.sent;
-                    res(result);
-                    _context.next = 10;
-                    break;
-                  case 7:
-                    _context.prev = 7;
-                    _context.t0 = _context["catch"](0);
-                    res(undefined);
-                  case 10:
-                  case "end":
-                    return _context.stop();
-                }
-              }, _callee, null, [[0, 7]]);
-            }));
-            return function (_x, _x2) {
-              return _ref2.apply(this, arguments);
-            };
-          }()),
-          abortController: abortController,
-          activeSignals: [originalSignal]
-        };
-      }
-      var handleAbort = function handleAbort() {
-        _this.pending[key].activeSignals = _this.pending[key].activeSignals.filter(function (activeSignal) {
-          return activeSignal !== originalSignal;
-        });
-        if (_this.pending[key].activeSignals.length === 0) {
-          // abort the resolution if all signals are aborted
-          _this.pending[key].abortController.abort();
-        }
-      };
-
-      // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
-      originalSignal === null || originalSignal === void 0 || originalSignal.addEventListener('abort', handleAbort);
-      this.pending[key].resolving.then(function (resolvedValue) {
-        if (resolvedValue) {
-          _this.cache[key] = resolvedValue;
-        }
-        // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
-        originalSignal === null || originalSignal === void 0 || originalSignal.removeEventListener('abort', handleAbort);
-        return resolvedValue;
-      });
-      return this.pending[key].resolving;
-    }
-  }]);
-}();
-
-// The purpose of this type is to ensure that either a DocNode or a PMNode is passed in
-// to the provider.
-// It is not opinionated about which nodes are used, so `any` is used here to allow
-// compatibility with both DocNodes and PMNodes.
+export { NodeDataProvider } from './node-data-provider';
+export { prefetchNodeDataProvidersData } from './utils/prefetch-node-data-providers-data';

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

@@ -0,0 +1,248 @@
+import _typeof from "@babel/runtime/helpers/typeof";
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+import { isSSR } from '@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.
+ */
+export var NodeDataProvider = /*#__PURE__*/function () {
+  function NodeDataProvider() {
+    _classCallCheck(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 _createClass(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 = _slicedToArray(_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 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(node, callback) {
+        var jsonNode, dataKey, dataFromCache, cacheVersionBeforeRequest, dataPromise, data;
+        return _regeneratorRuntime.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 (!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 = _slicedToArray(_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 _typeof(value) === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
+}

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

@@ -0,0 +1,61 @@
+import _toConsumableArray from "@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.
+ */
+export 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, _toConsumableArray(currentNode.content.filter(function (node) {
+        return node !== undefined;
+      })));
+    }
+  }
+  return Object.values(resultMap);
+}