@atlaskit/node-data-provider 4.2.0 → 4.3.0

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

@@ -0,0 +1,216 @@
+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 class NodeDataProvider {
+  /**
+   * A unique name for the provider. Used for identification in SSR.
+   */
+
+  /**
+   * A type guard to check if a given JSONNode is supported by this provider.
+   * Used to ensure that the provider can handle the node type before attempting to fetch data.
+   *
+   * @param node The node to check.
+   * @returns `true` if the node is of the type supported by this provider, otherwise `false`.
+   */
+
+  /**
+   * Generates a unique key for a given node to be used for caching.
+   *
+   * @param node The node for which to generate a data key.
+   * @returns A unique string key for the node's data.
+   */
+
+  /**
+   * Fetches data for a batch of nodes from the network or another asynchronous source.
+   *
+   * @param nodes An array of nodes for which to fetch data.
+   * @returns A promise that resolves to an array of data corresponding to the input nodes.
+   */
+
+  constructor() {
+    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.
+   */
+  setSSRData(ssrData = {}) {
+    this.cacheVersion++;
+    this.cache = Object.entries(ssrData).reduce((acc, [key, data]) => {
+      acc[key] = {
+        source: 'ssr',
+        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;
+   * }
+   * ```
+   */
+  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.
+   */
+  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);
+  }
+  async getDataAsync(node, callback) {
+    const jsonNode = 'toJSON' in node ? node.toJSON() : node;
+    if (!this.isNodeSupported(jsonNode)) {
+      // eslint-disable-next-line no-console
+      console.error(`The ${this.constructor.name} doesn't support Node ${jsonNode.type}.`);
+      return;
+    }
+    const dataKey = this.nodeDataKey(jsonNode);
+    const dataFromCache = this.cache[dataKey];
+    if (dataFromCache !== undefined) {
+      // If we have the data in the SSR data, we can use it directly
+      if (isPromise(dataFromCache.data)) {
+        callback(await dataFromCache.data);
+      } else {
+        callback(dataFromCache.data);
+      }
+      if (isSSR()) {
+        // If we are in SSR, we don't want to fetch the data again, as it is already available in the SSR data
+        return;
+      }
+    }
+
+    // If no data is available in the cache or the data is from the network,
+    // we need to fetch it from the network.
+    if ((dataFromCache === null || dataFromCache === void 0 ? void 0 : dataFromCache.source) !== 'network') {
+      // 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.
+      const cacheVersionBeforeRequest = this.cacheVersion;
+      const dataPromise = this.fetchNodesData([jsonNode]).then(([value]) => value);
+      // Store the promise in the cache to avoid multiple requests for the same data
+      this.cache[dataKey] = {
+        source: 'network',
+        data: dataPromise
+      };
+      const data = await dataPromise;
+      // 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
+        };
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  getDataAsPromise_DO_NOT_USE_OUTSIDE_MIGRATIONS(node) {
+    return new Promise((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/es2019/utils/find-nodes-to-prefetch.js

@@ -0,0 +1,57 @@
+/**
+ * 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) {
+  let totalVisitedNodesCount = 0;
+  const resultMap = providers.reduce((acc, {
+    provider
+  }) => {
+    acc[provider.name] = {
+      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.
+
+  const providersToLookup = providers.filter(({
+    maxNodesToPrefetch
+  }) => maxNodesToPrefetch > 0).map(({
+    provider,
+    maxNodesToPrefetch
+  }) => ({
+    provider,
+    maxNodesToPrefetch,
+    foundNodes: 0
+  }));
+  const nodesToVisit = [doc];
+  let currentIndex = 0;
+  while (currentIndex < nodesToVisit.length && providersToLookup.length > 0 && totalVisitedNodesCount < maxNodesToVisit) {
+    totalVisitedNodesCount += 1;
+    const currentNode = nodesToVisit[currentIndex];
+    currentIndex++;
+
+    // Using reverse loop to avoid issues with array mutation
+    for (let i = providersToLookup.length - 1; i >= 0; i--) {
+      const 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(...currentNode.content.filter(node => node !== undefined));
+    }
+  }
+  return Object.values(resultMap);
+}

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

@@ -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';

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';
+}