npm - @vizhub/runtime - Versions diffs - 0.0.1 - Mend

@vizhub/runtime 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/README.md +173 -0
package/package.json +37 -0
package/src/computeSrcDoc.ts +68 -0
package/src/index.ts +7 -0
package/src/useRuntime.ts +394 -0
package/src/v2Runtime/bundle/bubleJSXOnly.ts +34 -0
package/src/v2Runtime/bundle/getLibraries.js +31 -0
package/src/v2Runtime/bundle/hypothetical.js +232 -0
package/src/v2Runtime/bundle/index.js +88 -0
package/src/v2Runtime/bundle/packageJson.ts +49 -0
package/src/v2Runtime/bundle/rollup.browser.js +28414 -0
package/src/v2Runtime/bundle.test.js +151 -0
package/src/v2Runtime/computeSrcDocV2.test.ts +163 -0
package/src/v2Runtime/computeSrcDocV2.ts +34 -0
package/src/v2Runtime/getComputedIndexHtml.test.ts +33 -0
package/src/v2Runtime/getComputedIndexHtml.ts +106 -0
package/src/v2Runtime/getText.ts +19 -0
package/src/v2Runtime/magicSandbox.js +291 -0
package/src/v2Runtime/packageJson.js +42 -0
package/src/v2Runtime/transformFiles.test.js +18 -0
package/src/v2Runtime/transformFiles.ts +15 -0
package/src/v2Runtime/v3FilesToV2Files.test.ts +20 -0
package/src/v2Runtime/v3FilesToV2Files.ts +14 -0
package/src/v3Runtime/build.test.ts +474 -0
package/src/v3Runtime/build.ts +270 -0
package/src/v3Runtime/cleanRollupErrorMessage.ts +15 -0
package/src/v3Runtime/computeSrcDocV3.ts +151 -0
package/src/v3Runtime/extractVizImport.test.ts +41 -0
package/src/v3Runtime/extractVizImport.ts +34 -0
package/src/v3Runtime/generateRollupErrorMessage.ts +84 -0
package/src/v3Runtime/importFromViz.ts +36 -0
package/src/v3Runtime/index.ts +1 -0
package/src/v3Runtime/parseId.ts +14 -0
package/src/v3Runtime/setupV3Runtime.ts +478 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/bundle-modified-src.js +121 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/bundle-modified.js +121 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/bundle.js +239 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/index.js +1 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/package-lock.json +475 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/package.json +19 -0
package/src/v3Runtime/transformDSV/d3-dsv-custom-build/rollup.config.js +9 -0
package/src/v3Runtime/transformDSV/index.ts +71 -0
package/src/v3Runtime/transformSvelte.ts +111 -0
package/src/v3Runtime/types.ts +158 -0
package/src/v3Runtime/urlLoad.ts +33 -0
package/src/v3Runtime/virtual.ts +27 -0
package/src/v3Runtime/vizCache.test.ts +126 -0
package/src/v3Runtime/vizCache.ts +60 -0
package/src/v3Runtime/vizLoad.ts +68 -0
package/src/v3Runtime/vizLoadSvelte.ts +46 -0
package/src/v3Runtime/vizResolve.ts +100 -0
package/src/v3Runtime/worker.ts +231 -0

package/README.md ADDED Viewed

@@ -0,0 +1,173 @@
+# @vizhub-core/runtime
+The `@vizhub-core/runtime` package is a core component of the VizHub platform, responsible for executing and rendering visualizations in an isolated environment. It supports multiple runtime versions (V2 and V3) and provides a flexible system for handling dependencies, file transformations, and hot reloading.
+## Features
+- **Multi-version runtime support**: Supports both V2 and V3 runtime environments, allowing for backward compatibility and future-proofing.
+- **Hot reloading**: Automatically reloads visualizations when files are updated, providing a smooth development experience.
+- **Dependency management**: Handles external dependencies via CDN and supports custom package configurations.
+- **File transformations**: Transforms various file types (e.g., JavaScript, CSS, CSV, Svelte) to be used in the runtime environment.
+- **Virtual file system**: Implements a virtual file system for handling imports and file loading within the runtime.
+- **Web Worker-based build system**: Uses Web Workers to offload the build process, ensuring a responsive UI during development.
+## Installation
+Install the package using npm:
+```bash
+npm install @vizhub-core/runtime
+```
+## Usage
+The `@vizhub-core/runtime` package is designed to be used within the VizHub platform but can also be utilized in other environments where isolated execution of visualizations is required.
+### Example
+Here's an example of how to use the runtime to compute the `srcdoc` for a visualization:
+```javascript
+import { computeSrcDoc } from '@vizhub-core/runtime';
+import { rollup } from 'rollup';
+import { createVizCache } from '@vizhub-core/runtime/v3Runtime/vizCache';
+const vizCache = createVizCache({
+  initialContents: [],
+  handleCacheMiss: async (vizId) => {
+    // Fetch the content for the vizId
+  },
+});
+const content = {
+  id: 'example-viz',
+  files: {
+    'index.js': {
+      name: 'index.js',
+      text: 'console.log("Hello World");',
+    },
+    'index.html': {
+      name: 'index.html',
+      text: '<html><body><h1>Hello World</h1></body></html>',
+    },
+  },
+};
+const { initialSrcdoc, initialSrcdocError } =
+  await computeSrcDoc({
+    rollup,
+    content,
+    vizCache,
+    resolveSlug: async ({ userName, slug }) => {
+      // Resolve slug to vizId
+    },
+    getSvelteCompiler: async () => {
+      // Return the Svelte compiler
+    },
+  });
+if (initialSrcdocError) {
+  console.error(
+    'Error computing srcdoc:',
+    initialSrcdocError,
+  );
+} else {
+  console.log('Computed srcdoc:', initialSrcdoc);
+}
+```
+## API Documentation
+### `computeSrcDoc`
+Computes the `srcdoc` for a visualization based on its content and dependencies.
+#### Parameters
+- **`rollup`**: The Rollup instance used for bundling.
+- **`content`**: The content of the visualization, including files like `index.js` and `index.html`.
+- **`vizCache`**: A cache of visualizations used to resolve imports from other visualizations.
+- **`resolveSlug`**: A function to resolve slug-based imports to a viz ID.
+- **`getSvelteCompiler`**: A function to get the Svelte compiler.
+#### Returns
+A promise that resolves to an object containing:
+- **`initialSrcdoc`**: The computed `srcdoc` for the visualization.
+- **`initialSrcdocError`**: Any error that occurred during the computation.
+### `createVizCache`
+Creates a cache for visualizations, used to resolve imports from other visualizations.
+#### Parameters
+- **`initialContents`**: An array of initial contents to populate the cache.
+- **`handleCacheMiss`**: A function called when a visualization is not found in the cache.
+#### Returns
+A `VizCache` object with the following methods:
+- **`get(vizId)`**: Retrieves the content of a visualization by its ID.
+- **`set(content)`**: Adds or updates the content of a visualization in the cache.
+- **`invalidate(vizId)`**: Invalidates the cache for a specific visualization.
+### `setJSDOM`
+Sets the DOM parser for environments where the native `DOMParser` is not available (e.g., Node.js).
+#### Parameters
+- **`JSDOM`**: The `JSDOM` instance to use for parsing HTML.
+### `cleanRollupErrorMessage`
+Cleans up Rollup error messages by removing unnecessary details like the viz ID.
+#### Parameters
+- **`rawMessage`**: The raw error message from Rollup.
+- **`vizId`**: The ID of the visualization.
+#### Returns
+- A cleaned-up error message string.
+## Development
+To contribute to the development of this package, follow these steps:
+### Clone the Repository
+```bash
+git clone https://github.com/vizhub-core/vizhub3.git
+cd vizhub3
+```
+### Install Dependencies
+```bash
+npm install
+```
+### Run Tests
+The package uses Vitest for testing. Run the tests with:
+```bash
+npm run test
+```
+### Build the Package
+To build the package, use:
+```bash
+npm run build
+```
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "@vizhub/runtime",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "src/index",
+  "scripts": {
+    "tsc": "tsc --noEmit",
+    "test": "vitest run --reporter verbose",
+    "prettier": "prettier {*.*,**/*.*} --single-quote --write"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vizhub-core/vizhub3.git"
+  },
+  "author": "Curran Kelleher",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/vizhub-core/vizhub3/issues"
+  },
+  "homepage": "https://github.com/vizhub-core/vizhub3#readme",
+  "dependencies": {
+    "d3-dsv": "^3.0.1",
+    "react": "^18.3.1",
+    "rollup": "^4.24.0",
+    "svelte": "^4.2.19"
+  },
+  "devDependencies": {
+    "@types/d3-dsv": "^3.0.7",
+    "i": "^0.3.7",
+    "npm": "^10.9.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/computeSrcDoc.ts ADDED Viewed

@@ -0,0 +1,68 @@
+// import { rollup } from 'rollup';
+import {
+  Content,
+  VizId,
+  getRuntimeVersion,
+} from 'entities';
+import { computeSrcDocV2 } from './v2Runtime/computeSrcDocV2';
+import { computeSrcDocV3 } from './v3Runtime/computeSrcDocV3';
+import { build } from './v3Runtime/build';
+import { VizCache } from './v3Runtime/vizCache';
+const debug = false;
+export const computeSrcDoc = async ({
+  rollup,
+  content,
+  vizCache,
+  resolveSlug,
+  getSvelteCompiler,
+}: {
+  rollup: any;
+  content: Content;
+  vizCache: VizCache;
+  // Resolves a slug import to a viz ID.
+  resolveSlug: ({ userName, slug }) => Promise<VizId>;
+  getSvelteCompiler: () => Promise<any>;
+}) => {
+  // `runtimeVersion` is used to determine which runtime
+  // to use. It's either 2 or 3.
+  const runtimeVersion: number = getRuntimeVersion(content);
+  let initialSrcdoc = '';
+  let initialSrcdocError: string | null = null;
+  if (debug) {
+    console.log('computeSrcDoc.ts: computeSrcDoc()');
+    console.log('  runtimeVersion:', runtimeVersion);
+    console.log('  content:', content);
+  }
+  try {
+    if (runtimeVersion === 2) {
+      initialSrcdoc = await computeSrcDocV2(content);
+    } else if (runtimeVersion === 3) {
+      const buildResult = await build({
+        vizId: content.id,
+        enableSourcemap: true,
+        rollup,
+        vizCache,
+        resolveSlug,
+        getSvelteCompiler,
+      });
+      initialSrcdoc = await computeSrcDocV3({
+        vizCache,
+        buildResult,
+      });
+    }
+  } catch (error) {
+    // initialSrcdocError = e.toString();
+    initialSrcdocError = error.message;
+  }
+  return {
+    // Escape ending tags in strings like "</script>",
+    // so that they don't break the HTML.
+    initialSrcdoc,
+    initialSrcdocError,
+  };
+};

package/src/index.ts ADDED Viewed

@@ -0,0 +1,7 @@
+export type { V3BuildResult } from './v3Runtime';
+export type { VizCache } from './v3Runtime/vizCache';
+export { computeSrcDoc } from './computeSrcDoc';
+export { setJSDOM } from './v2Runtime/getComputedIndexHtml';
+export { useRuntime } from './useRuntime';
+export { createVizCache } from './v3Runtime/vizCache';
+export { cleanRollupErrorMessage } from './v3Runtime/cleanRollupErrorMessage';

package/src/useRuntime.ts ADDED Viewed

@@ -0,0 +1,394 @@
+import {
+  RefObject,
+  useEffect,
+  useMemo,
+  useRef,
+  useCallback,
+} from 'react';
+import {
+  Content,
+  FileId,
+  SlugKey,
+  VizId,
+  generateFileId,
+  getRuntimeVersion,
+} from 'entities';
+import { V3Runtime } from './v3Runtime/setupV3Runtime';
+const debug = false;
+// Sets up either the v2 or v3 runtime environment.
+// Meant to support dynamic switching between the two.
+export const useRuntime = ({
+  content,
+  iframeRef,
+  srcdocErrorMessage,
+  setSrcdocErrorMessage,
+  vizCacheContents,
+  isVisual,
+  slugResolutionCache,
+  submitContentOperation,
+}: {
+  content: Content;
+  iframeRef: RefObject<HTMLIFrameElement>;
+  srcdocErrorMessage: string | null;
+  setSrcdocErrorMessage: (error: string | null) => void;
+  vizCacheContents: Record<string, Content>;
+  // If this is false, there is no iframeRef.current.
+  isVisual: boolean;
+  slugResolutionCache: Record<SlugKey, VizId>;
+  submitContentOperation: (
+    next: (content: Content) => Content,
+  ) => void;
+}) => {
+  // This ref is used to skip the first mount.
+  const initialMount = useRef(true);
+  // `runtimeVersion` is used to determine which runtime
+  // to use. It's either 2 or 3.
+  const runtimeVersion: number = useMemo(
+    () => getRuntimeVersion(content),
+    [content],
+  );
+  const v3RuntimeRef = useRef<V3Runtime | null>(null);
+  const getV3Runtime = useCallback(async () => {
+    if (v3RuntimeRef.current === null) {
+      // throw new Error('v3Runtime.current is null');
+      // Poll for this to be defined.
+      // const interval = setInterval(() => {
+      //   if (debug) {
+      //     console.log('polling for v3Runtime.current...');
+      //   }
+      //   if (v3RuntimeRef.current !== null) {
+      //     clearInterval(interval);
+      //     return v3RuntimeRef.current;
+      //   }
+      // }, 100);
+      return new Promise<V3Runtime>((resolve) => {
+        const interval = setInterval(() => {
+          if (debug) {
+            console.log('polling for v3Runtime.current...');
+          }
+          if (v3RuntimeRef.current !== null) {
+            clearInterval(interval);
+            resolve(v3RuntimeRef.current);
+          }
+        }, 100);
+      });
+    }
+    return v3RuntimeRef.current;
+  }, []);
+  const vizCacheContentsRef = useRef(vizCacheContents);
+  useEffect(() => {
+    vizCacheContentsRef.current = vizCacheContents;
+  }, [vizCacheContents]);
+  // Handles cache misses for viz content,
+  // when a viz imports from another viz.
+  const getLatestContent = useCallback(
+    async (vizId: VizId): Promise<Content> => {
+      // Sanity check, should never happen.
+      if (!vizCacheContentsRef.current) {
+        throw new Error(
+          'vizCacheContentsRef.current is null',
+        );
+      }
+      const content = vizCacheContentsRef.current[vizId];
+      // If the viz content for this import is already tracked,
+      // then return it.
+      if (content) {
+        return content;
+      } else {
+        // TODO make this happen by:
+        // * Fetching the viz content from the server
+        // * Using a new API endpoint that returns the viz content
+        // * Ingesting the snapshot and incorporating it into the vizCacheContents
+        throw new Error(
+          `TODO client-side fetching of newly imported vizzes. Current workaround: refresh the page`,
+        );
+      }
+    },
+    [],
+  );
+  // Handles cache misses for slug resolution,
+  // when a viz imports from another viz.
+  const resolveSlugKey = useCallback(
+    async (slugKey: SlugKey): Promise<VizId> => {
+      // Sanity check, should never happen.
+      if (!slugResolutionCache) {
+        throw new Error('slugResolutionCache is null');
+      }
+      const vizId = slugResolutionCache[slugKey];
+      // If the viz ID for this slug is already tracked,
+      // then return it.
+      if (vizId) {
+        return vizId;
+      } else {
+        // TODO make this happen by:
+        // * Resolving the slug from the server
+        // * Using a new API endpoint that returns the viz id for a slugKey
+        throw new Error(
+          `TODO client-side resolution of newly imported vizzes. Current workaround: refresh the page`,
+        );
+      }
+    },
+    [],
+  );
+  // Set up the v3 runtime.
+  // TODO QA the following:
+  //  * Adding and removing index.js
+  //  * Adding and removing index.html
+  //  * Switching between versions of the runtime
+  useEffect(() => {
+    // If the viz is not visual (README.md only), then
+    // we don't need to set up the v3 runtime.
+    if (isVisual === false) {
+      return;
+    }
+    if (runtimeVersion === 3) {
+      // Load the v3 runtime.
+      import('./v3Runtime/setupV3Runtime').then(
+        ({ setupV3Runtime }) => {
+          const iframe = iframeRef.current;
+          // Should never happen. Added to pacify TypeScript.
+          if (iframe === null) {
+            throw new Error('iframe is null');
+          }
+          if (!content.id) {
+            throw new Error('content.id is not defined');
+          }
+          // Writes the content of a file.
+          const writeFile = (
+            name: string,
+            text: string,
+          ) => {
+            submitContentOperation((content: Content) => {
+              // For new files, generate a fileId.
+              let fileId: FileId = generateFileId();
+              // For existing files, get the fileId.
+              const { files } = content;
+              if (files !== undefined) {
+                const fileIds = Object.keys(files);
+                const foundFileId = fileIds.find(
+                  (fileId) => files[fileId].name === name,
+                );
+                if (foundFileId) {
+                  fileId = foundFileId;
+                }
+              }
+              return {
+                ...content,
+                files: {
+                  ...content.files,
+                  [fileId]: {
+                    name,
+                    text,
+                  },
+                },
+                // Trigger a re-run.
+                isInteracting: true,
+              };
+            });
+            // Clear the `isInteracting` property.
+            setTimeout(() => {
+              // This somewhat cryptic logic
+              // deletes the `isInteracting` property
+              // from the document.
+              submitContentOperation(
+                ({ isInteracting, ...newDocument }) =>
+                  newDocument,
+              );
+            }, 0);
+          };
+          v3RuntimeRef.current = setupV3Runtime({
+            vizId: content.id,
+            iframe,
+            setSrcdocErrorMessage,
+            getLatestContent,
+            resolveSlugKey,
+            writeFile,
+          });
+        },
+      );
+    }
+  }, [runtimeVersion, isVisual, submitContentOperation]);
+  // Send updates of imported vizzes to the V3 runtime.
+  const previousVizCacheContents = useRef(vizCacheContents);
+  // Track the srcdoc error message, but only check it
+  // when we are attempting to run (do not re-run when
+  // the error message changes or is cleared).
+  const srcdocErrorMessageRef = useRef(srcdocErrorMessage);
+  useEffect(() => {
+    srcdocErrorMessageRef.current = srcdocErrorMessage;
+  }, [srcdocErrorMessage]);
+  useEffect(() => {
+    // Don't crash for v2 runtime!
+    if (runtimeVersion !== 3) {
+      return;
+    }
+    // Don't run on first render.
+    if (initialMount.current === true) {
+      return;
+    }
+    // Don't run if the viz is not visual (README.md only).
+    if (isVisual === false) {
+      return;
+    }
+    // console.log(
+    //   'TODO update the v3 runtime when imported vizzes change',
+    // );
+    // Find the imported vizzes that have changed.
+    const changedVizIds = Object.keys(
+      vizCacheContents,
+    ).filter((vizId) => {
+      return (
+        previousVizCacheContents.current[vizId] !==
+        vizCacheContents[vizId]
+      );
+    });
+    previousVizCacheContents.current = vizCacheContents;
+    if (debug) {
+      console.log(
+        '[useRuntime] changedVizIds',
+        changedVizIds,
+      );
+    }
+    if (changedVizIds.length === 0) {
+      return;
+    }
+    // // See if any of the vizzes we import from are interacting.
+    let isInteracting = false;
+    for (const vizId of changedVizIds) {
+      if (vizCacheContents[vizId].isInteracting) {
+        isInteracting = true;
+        break;
+      }
+    }
+    if (debug) {
+      console.log('isInteracting', isInteracting);
+    }
+    const update = async () => {
+      const v3Runtime = await getV3Runtime();
+      // Sanity check, should never happen.
+      if (v3Runtime === null) {
+        throw new Error('v3Runtime is null');
+      }
+      if (isInteracting) {
+        // console.log('Running the code!');
+        // console.log(
+        //   'srcdocErrorMessageRef.current',
+        //   srcdocErrorMessageRef.current,
+        // );
+        // If we are recovering from an error,
+        // clear the error message, and run the code
+        // totally fresh by re-computing the srcdoc.
+        if (srcdocErrorMessageRef.current) {
+          v3Runtime.resetSrcdoc(changedVizIds);
+          // try {
+          //   const srcdoc = await computeSrcDocV3(content);
+          //   if (iframeRef.current) {
+          //     iframeRef.current.srcdoc = srcdoc;
+          //   }
+          // } catch (error) {
+          //   console.error(error);
+          //   setSrcdocErrorMessage(error.message);
+          // }
+        } else {
+          // Re-run the code with hot reloading.
+          v3Runtime.invalidateVizCache(changedVizIds);
+        }
+      }
+    };
+    update();
+  }, [vizCacheContents, runtimeVersion]);
+  // Compute V2 updates on the main thread.
+  useEffect(() => {
+    // We don't need to execute a "run" on first render,
+    // because SSR handles the initial run by injecting
+    // the srcdoc into the page server-side.
+    if (initialMount.current) {
+      return;
+    }
+    // The following code only runs after the user
+    // has edited the code and the files have changed.
+    if (runtimeVersion === 2) {
+      // // Debounce the updates.
+      const v2Run = async () => {
+        // Clear the console before each run.
+        console.clear();
+        // Clear out the old error.
+        setSrcdocErrorMessage(null);
+        // v2RuntimeWorker.current.postMessage({ content });
+        // Set process on global scope so computeSrcDoc doesn't break.
+        // @ts-ignore
+        globalThis.process = {};
+        // Lazy load computeSrcDoc because it's a large chunk.
+        const { computeSrcDocV2 } = await import(
+          './v2Runtime/computeSrcDocV2'
+        );
+        // console.log(computeSrcDoc);
+        try {
+          const srcdoc = await computeSrcDocV2(content);
+          if (iframeRef.current) {
+            iframeRef.current.srcdoc = srcdoc;
+          }
+        } catch (error) {
+          console.error(error);
+          setSrcdocErrorMessage(error.message);
+        }
+      };
+      if (content.isInteracting) {
+        v2Run();
+      }
+    }
+  }, [
+    content.files,
+    content.isInteracting,
+    runtimeVersion,
+  ]);
+  // Track the initial mount.
+  useEffect(() => {
+    if (initialMount.current) {
+      initialMount.current = false;
+      return;
+    }
+  }, []);
+};