feat(handleError): add the ability to handle errors (#15)

* feat(handleError): add the ability to handle errors

* test: add another test case

Author: kentcdodds

README.md

@@ -108,6 +108,8 @@ async function go() {
   // <p>This is a CodeSandbox:</p>
   // <iframe src="https://codesandbox.io/embed/css-variables-vs-themeprovider-df90h" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"></iframe>
 }
+
+go()
 ```
 
 ### Options
@@ -169,7 +171,56 @@ return `<div><blockquote>...</blockquote><a href="...">...</a></div>`
 Some services have endpoints that you can use to get the embed HTML ([like
 twitter for example][twitter-oembed-docs]).
 
-#### `cache: Map<string, string | null>`
+#### `handleError?: (errorInfo: ErrorInfo) => GottenHTML | Promise<GottenHTML>
+
+```ts
+type ErrorInfo = {
+  error: Error
+  url: string
+  transformer: Transformer<unknown>
+  config: TransformerConfig
+}
+```
+
+If remark-embedder encounters an error with any transformer, then compilation
+will fail. I've found this to be problematic when using
+[`@remark-embedder/transformer-oembed`][@remark-embedder/transformer-oembed] for
+tweets and the tweet author deletes their tweet. It'll prevent you from building
+and that's annoying.
+
+So `handleError` allows you to handle any error that's thrown by a transformer.
+This way you can gracefully fallback to something rather than crashing
+everything. Even if you provide a `handleError`, we'll log to the console so you
+can fix the problem in the future.
+
+Here's a quick example of an error handler that would handle deleted tweets:
+
+```typescript
+function handleError({error, url, transformer}) {
+  if (
+    transformer.name !== '@remark-embedder/transformer-oembed' ||
+    !url.includes('twitter.com')
+  ) {
+    // we're only handling errors from this specific transformer and the twitter URL
+    // so we'll rethrow errors from any other transformer/url
+    throw error
+  }
+  return `<p>Unable to embed <a href="${url}">this tweet</a>.</p>`
+}
+
+const result = await remark()
+  .use(remarkEmbedder, {
+    transformers: [oembedTransformer],
+    handleError,
+  })
+  .use(html)
+  .process(exampleMarkdown)
+```
+
+You'll get an error logged, but it won't break your build. It also won't be
+cached (if you're using the `cache` option).
+
+#### `cache?: Map<string, string | null>`
 
 **You'll mostly likely want to use
 [`@remark-embedder/cache`][@remark-embedder/cache]**

src/__tests__/index.ts

@@ -12,6 +12,12 @@ const unquoteSerializer = {
 
 expect.addSnapshotSerializer(unquoteSerializer)
 
+const consoleError = jest.spyOn(console, 'error')
+afterEach(() => {
+  expect(consoleError).not.toHaveBeenCalled()
+  consoleError.mockReset()
+})
+
 const getTransformer = <ConfigType>(
   overrides: Partial<Transformer<ConfigType>> = {},
 ): Transformer<ConfigType> => ({
@@ -201,6 +207,48 @@ https://some-site.com/do-not-transform
   `)
 })
 
+test('can handle errors', async () => {
+  consoleError.mockImplementationOnce(() => {})
+  const transformer = getTransformer({
+    getHTML: () => Promise.reject(new Error('OH_NO_AN_ERROR_HAPPENED')),
+  })
+  const handleError = jest.fn(({error}) => `<div>${error.message}</div>`)
+  const result = await remark()
+    .use(remarkEmbedder, {transformers: [transformer], handleError})
+    .use(remarkHTML)
+    .process(`[https://some-site.com](https://some-site.com)`)
+
+  expect(result.toString()).toMatchInlineSnapshot(
+    `<div>OH_NO_AN_ERROR_HAPPENED</div>`,
+  )
+
+  expect(consoleError).toHaveBeenCalledTimes(1)
+  expect(consoleError).toHaveBeenCalledWith(expect.any(String))
+  expect(consoleError.mock.calls[0][0]).toMatchInlineSnapshot(`
+    The following error occurred while processing \`https://some-site.com/\` with the remark-embedder transformer \`TEST\`:
+
+    OH_NO_AN_ERROR_HAPPENED
+  `)
+  consoleError.mockClear()
+})
+
+test('handleError can return null', async () => {
+  consoleError.mockImplementationOnce(() => {})
+  const transformer = getTransformer({
+    getHTML: () => Promise.reject(new Error('OH_NO_AN_ERROR_HAPPENED')),
+  })
+  const handleError = jest.fn(() => null)
+  const result = await remark()
+    .use(remarkEmbedder, {transformers: [transformer], handleError})
+    .use(remarkHTML)
+    .process(`[https://some-site.com](https://some-site.com)`)
+
+  expect(result.toString()).toMatchInlineSnapshot(
+    `<p><a href="https://some-site.com">https://some-site.com</a></p>`,
+  )
+  consoleError.mockClear()
+})
+
 // no idea why TS and remark aren't getting along here,
 // but I don't have time to look into it right now...
 /*

src/index.ts

@@ -26,6 +26,12 @@ type RemarkEmbedderOptions = {
         [key: string]: unknown
       }
   transformers: Array<Transformer<any> | [Transformer<any>, TransformerConfig]>
+  handleError?: (errorInfo: {
+    error: Error
+    url: string
+    transformer: Transformer<unknown>
+    config: TransformerConfig
+  }) => GottenHTML | Promise<GottenHTML>
 }
 
 // results in an AST node of type "root" with a single "children" node of type "element"
@@ -46,6 +52,7 @@ const getUrlString = (url: string): string | null => {
 const remarkEmbedder: Plugin<[RemarkEmbedderOptions]> = ({
   cache,
   transformers,
+  handleError,
 }) => {
   // convert the array of transformers to one with both the transformer and the config tuple
   const transformersAndConfig: Array<{
@@ -103,14 +110,26 @@ const remarkEmbedder: Plugin<[RemarkEmbedderOptions]> = ({
 
     const promises = nodesToTransform.map(
       async ({parentNode, url, transformer, config}) => {
+        const errorMessageBanner = `The following error occurred while processing \`${url}\` with the remark-embedder transformer \`${transformer.name}\`:`
         try {
           const cacheKey = `remark-embedder:${transformer.name}:${url}`
           let html: GottenHTML | undefined = await cache?.get(cacheKey)
 
           if (!html) {
-            html = await transformer.getHTML(url, config)
-            html = html?.trim() ?? null
-            await cache?.set(cacheKey, html)
+            try {
+              html = await transformer.getHTML(url, config)
+              html = html?.trim() ?? null
+              await cache?.set(cacheKey, html)
+            } catch (e: unknown) {
+              if (handleError) {
+                const error = e as Error
+                console.error(`${errorMessageBanner}\n\n${error.message}`)
+                html = await handleError({error, url, transformer, config})
+                html = html?.trim() ?? null
+              } else {
+                throw e
+              }
+            }
           }
 
           // if nothing's returned from getHTML, then no modifications are needed
@@ -128,9 +147,8 @@ const remarkEmbedder: Plugin<[RemarkEmbedderOptions]> = ({
             hProperties: htmlElement.properties,
           }
         } catch (e: unknown) {
-          // https://github.com/microsoft/TypeScript/issues/20024#issuecomment-344511199
           const error = e as Error
-          error.message = `The following error occurred while processing \`${url}\` with the remark-embedder transformer \`${transformer.name}\`:\n\n${error.message}`
+          error.message = `${errorMessageBanner}\n\n${error.message}`
 
           throw error
         }