@atlaskit/node-data-provider 4.2.0 → 4.4.0

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

@@ -0,0 +1,237 @@
+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' }) }
+ * }
+ */
+
+/**
+ * Represents the payload passed to the callback function when data is fetched.
+ * It can either contain an error or the fetched 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.fromEntries(Object.entries(ssrData).map(([key, data]) => [key, {
+      data,
+      source: 'ssr'
+    }]));
+  }
+
+  /**
+   * 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 callback function to call with the fetched data or an error.
+   */
+  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) {
+    try {
+      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({
+            data: await dataFromCache.data
+          });
+        } else {
+          callback({
+            data: 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
+          };
+        }
+      }
+    } catch (error) {
+      // If an error occurs, we call the callback with the error
+      callback({
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+
+  /**
+   * 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 {
+        this.getData(node, payload => {
+          if (payload.error) {
+            reject(payload.error);
+          } else {
+            resolve(payload.data);
+          }
+        });
+      } 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,74 @@
+/**
+ * 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) {
+  // Counter for the total number of visited nodes to limit the traversal.
+  let totalVisitedNodesCount = 0;
+  // A map to store the results, with the provider name as the key.
+  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.
+
+  // Create a list of providers for which we still need to find nodes.
+  const providersToLookup = providers.filter(({
+    maxNodesToPrefetch
+  }) => maxNodesToPrefetch > 0).map(({
+    provider,
+    maxNodesToPrefetch
+  }) => ({
+    provider,
+    maxNodesToPrefetch,
+    foundNodes: 0 // Counter for nodes found for each provider.
+  }));
+
+  // Queue for the breadth-first search (BFS), starting with the root document node.
+  const nodesToVisit = [doc];
+  let currentIndex = 0;
+  // The loop continues as long as there are nodes to visit, providers to look for,
+  // and the visited nodes limit has not been reached.
+  while (currentIndex < nodesToVisit.length && providersToLookup.length > 0 && totalVisitedNodesCount < maxNodesToVisit) {
+    totalVisitedNodesCount += 1;
+    const currentNode = nodesToVisit[currentIndex];
+    currentIndex++;
+
+    // Using a reverse loop to avoid issues with array mutation (when removing elements).
+    for (let i = providersToLookup.length - 1; i >= 0; i--) {
+      const providerToFind = providersToLookup[i];
+
+      // Check if the current provider supports this node.
+      if (providerToFind.provider.isNodeSupported(currentNode)) {
+        // If provider supports the node, add it to the result map.
+        resultMap[providerToFind.provider.name].nodes.push(currentNode);
+        // Increment the count of found nodes for this provider.
+        providerToFind.foundNodes += 1;
+
+        // If the provider has found enough nodes, remove it from the lookup list.
+        if (providerToFind.foundNodes >= providerToFind.maxNodesToPrefetch) {
+          providersToLookup.splice(i, 1);
+        }
+      }
+    }
+
+    // If the current node has children, add them to the queue to be visited.
+    if (currentNode.content) {
+      nodesToVisit.push(...currentNode.content.filter(node => node !== undefined));
+    }
+  }
+
+  // Return an array of the found nodes, grouped by provider.
+  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';