@atlaskit/node-data-provider 4.1.2 → 4.3.0

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

@@ -1,191 +1,4 @@
-import _defineProperty from "@babel/runtime/helpers/defineProperty";
-/**
- * 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 class NodeDataProvider {
-  /**
-   * 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.
-   */
-
-  constructor({
-    existingCache = {},
-    nodeName,
-    nodeToKey,
-    resolve
-  }) {
-    /**
-     * 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}
-   *
-   */
-  updateCache(cache, options) {
-    switch (options.strategy) {
-      case 'merge-override':
-        this.__cache = {
-          ...this.__cache,
-          ...cache
-        };
-        return;
-      case 'replace':
-        this.__cache = cache;
-        return;
-    }
-  }
-
-  /**
-   * This is the cache for the provider.
-   */
-  get cache() {
-    return this.__cache;
-  }
-  get(node, _) {
-    const key = this.nodeToKey(node);
-    const 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.
-
-    const originalSignal = (_ === null || _ === void 0 ? void 0 : _.signal) || new AbortController().signal;
-    if (!this.pending[key]) {
-      const abortController = new AbortController();
-      this.pending[key] = {
-        // eslint-disable-next-line no-async-promise-executor
-        resolving: new Promise(async (res, rej) => {
-          try {
-            const result = await this.resolve(node, {
-              signal: abortController.signal
-            }).catch(res => res(undefined));
-            res(result);
-          } catch {
-            res(undefined);
-          }
-        }),
-        abortController,
-        activeSignals: [originalSignal]
-      };
-    }
-    const handleAbort = () => {
-      this.pending[key].activeSignals = this.pending[key].activeSignals.filter(activeSignal => 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 ? void 0 : originalSignal.addEventListener('abort', handleAbort);
-    this.pending[key].resolving.then(resolvedValue => {
-      if (resolvedValue) {
-        this.cache[key] = resolvedValue;
-      }
-      // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
-      originalSignal === null || originalSignal === void 0 ? 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/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);
+}