feat: accept DurationLike values and use assertions to avoid rendering an invalid component

Author: brianrodri

src/render/preact/lib/__tests__/__snapshots__/obsidian.test.tsx.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ObsidianMarkdown > should throw when 'prop.delay' is invalid 1`] = `[Error: Unknown duration argument 0 of type string]`;

src/render/preact/lib/__tests__/obsidian.test.tsx

@@ -1,88 +1,89 @@
 import { render } from "@testing-library/preact";
-import { Duration } from "luxon";
+import { DurationLike } from "luxon";
+import { OmitByValue } from "utility-types";
 import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
 import { App, Component, MarkdownRenderer } from "@/lib/obsidian/types";
 
-import { ObsidianMarkdown } from "../obsidian";
+import { ObsidianMarkdown, ObsidianMarkdownProps } from "../obsidian";
 
 vi.mock("@/lib/obsidian/types");
 afterEach(() => vi.restoreAllMocks());
 
 describe(`${ObsidianMarkdown.name}`, () => {
+    const required: OmitByValue<ObsidianMarkdownProps, undefined> = {
+        app: new App(),
+        component: new Component(),
+        sourcePath: "/vault/diary.md",
+        markdown: "Foo",
+    };
+
     beforeAll(() => vi.useFakeTimers());
     afterAll(() => vi.useRealTimers());
 
     it("should rerender when markdown changes stay stable for a while", async () => {
-        const props = {
-            app: new App(),
-            component: new Component(),
-            sourcePath: "/vault/diary.md",
-            delay: Duration.fromMillis(500),
-        } as const;
-
-        const { rerender } = render(<ObsidianMarkdown {...props} markdown="Apple" />);
+        const { rerender } = render(<ObsidianMarkdown {...required} markdown="Apple" delay={{ milliseconds: 500 }} />);
         await vi.runAllTimersAsync();
-        rerender(<ObsidianMarkdown {...props} markdown="Banana" />);
+        rerender(<ObsidianMarkdown {...required} markdown="Banana" delay={{ milliseconds: 500 }} />);
         await vi.advanceTimersByTimeAsync(300);
-        rerender(<ObsidianMarkdown {...props} markdown="Banana" />);
+        rerender(<ObsidianMarkdown {...required} markdown="Banana" delay={{ milliseconds: 500 }} />);
         await vi.advanceTimersByTimeAsync(300);
 
-        const anySpanElement = expect.any(HTMLSpanElement);
         expect(MarkdownRenderer.render).toHaveBeenCalledTimes(2);
         expect(MarkdownRenderer.render).toHaveBeenCalledWith(
-            props.app,
+            required.app,
             "Apple",
-            anySpanElement,
-            props.sourcePath,
-            props.component,
+            expect.any(HTMLSpanElement),
+            required.sourcePath,
+            required.component,
         );
         expect(MarkdownRenderer.render).toHaveBeenCalledWith(
-            props.app,
+            required.app,
             "Banana",
-            anySpanElement,
-            props.sourcePath,
-            props.component,
+            expect.any(HTMLSpanElement),
+            required.sourcePath,
+            required.component,
         );
     });
 
     it("should not rerender when markdown changes too frequently", async () => {
-        const props = {
-            app: new App(),
-            component: new Component(),
-            sourcePath: "/vault/diary.md",
-            delay: Duration.fromMillis(500),
-        } as const;
-
-        const { rerender } = render(<ObsidianMarkdown {...props} markdown="Apple" />);
+        const { rerender } = render(<ObsidianMarkdown {...required} markdown="Apple" delay={{ milliseconds: 500 }} />);
         await vi.runAllTimersAsync();
-        rerender(<ObsidianMarkdown {...props} markdown="Banana" />);
+        rerender(<ObsidianMarkdown {...required} markdown="Banana" delay={{ milliseconds: 500 }} />);
         await vi.advanceTimersByTimeAsync(300);
-        rerender(<ObsidianMarkdown {...props} markdown="Cherry" />);
+        rerender(<ObsidianMarkdown {...required} markdown="Cherry" delay={{ milliseconds: 500 }} />);
         await vi.advanceTimersByTimeAsync(300);
 
-        const anySpanElement = expect.any(HTMLSpanElement);
         expect(MarkdownRenderer.render).toHaveBeenCalledTimes(1);
         expect(MarkdownRenderer.render).toHaveBeenCalledWith(
-            props.app,
+            required.app,
             "Apple",
-            anySpanElement,
-            props.sourcePath,
-            props.component,
+            expect.any(HTMLSpanElement),
+            required.sourcePath,
+            required.component,
         );
         expect(MarkdownRenderer.render).not.toHaveBeenCalledWith(
-            props.app,
+            required.app,
             "Banana",
-            anySpanElement,
-            props.sourcePath,
-            props.component,
+            expect.any(HTMLSpanElement),
+            required.sourcePath,
+            required.component,
         );
         expect(MarkdownRenderer.render).not.toHaveBeenCalledWith(
-            props.app,
+            required.app,
             "Cherry",
-            anySpanElement,
-            props.sourcePath,
-            props.component,
+            expect.any(HTMLSpanElement),
+            required.sourcePath,
+            required.component,
         );
     });
+
+    it("should not throw when default props get used", () => {
+        expect(() => render(<ObsidianMarkdown {...required} />)).not.toThrow();
+    });
+
+    it("should throw when 'prop.delay' is invalid", () => {
+        const invalid = "0" as DurationLike;
+        expect(() => render(<ObsidianMarkdown {...required} delay={invalid} />)).toThrowErrorMatchingSnapshot();
+    });
 });

src/render/preact/lib/obsidian.const.ts

@@ -1,3 +1,3 @@
 import { Duration } from "luxon";
 
-export const MARKDOWN_RENDER_DEBOUNCE_TIME = Duration.fromDurationLike({ milliseconds: 500 });
+export const MARKDOWN_RENDER_DEBOUNCE_TIME = Duration.fromMillis(500);

src/render/preact/lib/obsidian.tsx

@@ -1,30 +1,32 @@
-import { Duration } from "luxon";
+import { Duration, DurationLike } from "luxon";
 import { createElement, FunctionalComponent, JSX } from "preact";
-import { useEffect, useRef } from "preact/hooks";
+import { useEffect, useMemo, useRef } from "preact/hooks";
 import { useDebounceCallback } from "usehooks-ts";
 
 import { App, Component, MarkdownRenderer } from "@/lib/obsidian/types";
+import { assertLuxonValidity } from "@/util/luxon-utils";
 
 import { MARKDOWN_RENDER_DEBOUNCE_TIME } from "./obsidian.const";
 
 /**
- * Asynchronously renders the given markdown source code as Obsidian (the app) would.
- * Debounces values so that, ideally, renders have enough time to finish before being discarded for newer values.
- * @param props - configures how the markdown is rendered.
- * @returns component for asynchronously rendering the given markdown source code as Obsidian (the app) would.
+ * @param props - props for the component.
+ * @returns component that asynchronously renders the given markdown source code just as Obsidian (the app) would.
  */
 export const ObsidianMarkdown: FunctionalComponent<ObsidianMarkdownProps> = (props) => {
-    const { app, component, markdown, sourcePath, tagName = "span", delay = MARKDOWN_RENDER_DEBOUNCE_TIME } = props;
+    const { app, component, markdown, sourcePath, tagName = "span" } = props;
+    const delay = useMemo(() => Duration.fromDurationLike(props.delay ?? MARKDOWN_RENDER_DEBOUNCE_TIME), [props.delay]);
+    assertLuxonValidity(delay);
+
     const elRef = useRef<HTMLElement>();
-    const render = useDebounceCallback(MarkdownRenderer.render, delay.toMillis());
+    const renderObsidianMarkdown = useDebounceCallback(MarkdownRenderer.render, delay.toMillis());
 
     useEffect(() => {
-        const { current: el } = elRef;
+        const el = elRef.current;
         if (el) {
-            render(app, markdown, el, sourcePath, component);
-            return render.cancel;
+            renderObsidianMarkdown(app, markdown, el, sourcePath, component);
+            return renderObsidianMarkdown.cancel;
         }
-    }, [render, app, markdown, sourcePath, component]);
+    }, [renderObsidianMarkdown, app, markdown, sourcePath, component]);
 
     return createElement(tagName, { ref: elRef });
 };
@@ -42,5 +44,5 @@ export interface ObsidianMarkdownProps {
     /** The tag used to contain the rendered Markdown source code. */
     tagName?: keyof JSX.IntrinsicElements;
     /** Custom debounce time for renders. */
-    delay?: Duration<true>;
+    delay?: DurationLike;
 }