@vizhub/runtime 0.0.1

package/src/v3Runtime/types.ts

@@ -0,0 +1,158 @@
+import { Content, V3PackageJson, VizId } from 'entities';
+
+// The result of a build.
+export type V3BuildResult = {
+  // Could be undefined if there's no index.js.
+  src: string | undefined;
+  pkg: V3PackageJson | undefined;
+  warnings: Array<V3BuildError>;
+  time: number;
+
+  // A list of CSS files to be injected into the IFrame.
+  // e.g. `['./styles.css']`
+  // TODO e.g. `['@curran/scatter-plot/styles.css']`
+  cssFiles: Array<ResolvedVizFileId>;
+};
+
+// The shape of a build error.
+export type V3BuildError = {
+  code: string;
+  message: string;
+};
+
+// A resolved viz file id is of the form
+// `{idOrSlug}/{fileName}`
+export type ResolvedVizFileId = string;
+
+// Messages sent to and from the build worker.
+export type V3WorkerMessage =
+  // `contentRequest`
+  //  * Sent from the worker to the main thread.
+  //  * When the worker requests the content of an imported viz.
+  //  * The main thread should respond with a `getContentResponse` message.
+  //  * This supports the worker's VizCache when it has a cache miss.
+  | { type: 'contentRequest'; vizId: VizId }
+
+  // `contentResponse`
+  //  * Sent from the main thread to the worker.
+  //  * When the main thread responds to a `contentRequest` message.
+  | {
+      type: 'contentResponse';
+      vizId: VizId;
+      content: Content;
+    }
+
+  // `buildRequest`
+  //  * Sent from the main thread to the worker.
+  //  * When the main thread requests a build.
+  | {
+      type: 'buildRequest';
+      vizId: VizId;
+      enableSourcemap: boolean;
+    }
+
+  // `buildResponse`
+  //  * Sent from the worker to the main thread.
+  //  * When the worker responds to a `buildRequest` message.
+  //  * This message is sent to the main thread.
+  //  * This message includes
+  //  * EITHER `buildResult` the result of the build
+  //  * OR `error` if the build failed.
+  | {
+      type: 'buildResponse';
+      buildResult?: V3BuildResult;
+      error?: Error;
+    }
+
+  // `invalidateVizCache`
+  //  * Sent from the main thread to the worker.
+  //  * When the main thread wants to invalidate the VizCache.
+  //  * This happens when an imported viz changes.
+  | {
+      type: 'invalidateVizCacheRequest';
+      changedVizIds: Array<VizId>;
+    }
+
+  // `invalidateVizCacheResponse`
+  //  * Sent from the worker to the main thread.
+  //  * When the worker responds to a `invalidateVizCacheRequest` message.
+  | {
+      type: 'invalidateVizCacheResponse';
+    }
+
+  // `resolveSlugRequest`
+  //  * Sent from the worker to the main thread.
+  //  * When the worker requests a viz ID for a slug.
+  | {
+      type: 'resolveSlugRequest';
+      slugKey: string;
+      requestId: string;
+    }
+
+  // `resolveSlugResponse`
+  //  * Sent from the main thread to the worker.
+  //  * When the main thread responds to a `resolveSlugRequest` message.
+  | {
+      type: 'resolveSlugResponse';
+      slugKey: string;
+      vizId: VizId;
+      requestId: string;
+    }
+
+  // `resetRequest`
+  //  * Sent from the main thread to the worker.
+  //  * When the main thread wants to reset the runtime
+  //  * This happens when an error occurs.
+  | {
+      type: 'resetSrcdocRequest';
+      vizId: VizId;
+      changedVizIds: Array<VizId>;
+    }
+
+  // `resetResponse`
+  //  * Sent from the worker to the main thread.
+  //  * When the worker responds to a `resetRequest` message.
+  //  * Provides:
+  //  * EITHER a fresh `srcdoc` for the iframe
+  //  * OR an `error` if the build failed.
+  | {
+      type: 'resetSrcdocResponse';
+      srcdoc?: string;
+      error?: Error;
+    };
+
+// Messages sent to and from the IFrame window.
+export type V3WindowMessage =
+  // `runJS`
+  //  * Sent from the main thread to the IFrame.
+  //  * Triggers hot reloading within the V3 runtime.
+  | {
+      type: 'runJS';
+      src: string;
+    }
+
+  // `runCSS`
+  //  * Sent from the main thread to the IFrame.
+  //  * Triggers hot reloading of CSS within the V3 runtime.
+  | {
+      type: 'runCSS';
+      src: string;
+      id: ResolvedVizFileId;
+    }
+
+  // `runDone`
+  //  * Sent from the IFrame to the main thread.
+  //  * Indicates that the V3 runtime has finished running the JS.
+  //  * If this was sent, there were no immediate runtime errors.
+  | {
+      type: 'runDone';
+    }
+
+  // `runError`
+  //  * Sent from the IFrame to the main thread.
+  //  * Indicates that the V3 runtime has finished running the JS.
+  //  * If this was sent, there was an immediate runtime error.
+  | {
+      type: 'runError';
+      error: Error;
+    };

package/src/v3Runtime/urlLoad.ts

@@ -0,0 +1,33 @@
+// import { InputPluginOption } from 'rollup';
+// const debug = false;
+
+// const fetchedFileCache = new Map<string, string>();
+
+// // Responsible for loading Svelte internal imports.
+// // Inspired by:
+// // https://github.com/sveltejs/sites/blob/master/packages/repl/src/lib/workers/bundler/index.js#L345C3-L345C25
+// export const urlLoad = (): InputPluginOption => ({
+//   name: 'urlLoad',
+
+//   // `id` here is of the form
+//   // `{vizId}/{fileName}`
+//   load: async (resolved: string) => {
+//     if (!resolved.startsWith('https://')) {
+//       return;
+//     }
+//     if (debug) {
+//       console.log('[urlLoad]: load() ' + resolved);
+//     }
+
+//     const cachedFile = fetchedFileCache.get(resolved);
+//     if (cachedFile) return cachedFile;
+
+//     const fetchedFile = await fetch(resolved).then((res) =>
+//       res.text(),
+//     );
+
+//     fetchedFileCache.set(resolved, fetchedFile);
+
+//     return fetchedFile;
+//   },
+// });

package/src/v3Runtime/virtual.ts

@@ -0,0 +1,27 @@
+// // Virtual file system for Rollup
+// // A Rollup plugin for a virtual file system.
+// // Inspired by https://github.com/Permutatrix/rollup-plugin-hypothetical/blob/master/index.js
+
+// import { InputPluginOption } from 'rollup';
+// import { V3RuntimeFiles } from '.';
+
+// const js = (name: string) =>
+//   name.endsWith('.js') ? name : name + '.js';
+
+// export const virtual = (
+//   files: V3RuntimeFiles,
+// ): InputPluginOption => ({
+//   name: 'virtual',
+//   // If the id starts with './', then it's a relative path,
+//   // and is the responsibility of the virtual file system.
+//   resolveId: (id: string, importer: string) => {
+//     console.log('virtual: resolveId() ' + id);
+//     console.log('  importer: ' + importer);
+//     // id.startsWith('./') ? id : null,
+//     if (id.startsWith('./')) {
+//       return id;
+//     }
+//     return null;
+//   },
+//   load: (id: string) => files[js(id.substring(2))],
+// });

package/src/v3Runtime/vizCache.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Content } from 'entities';
+import { sampleContent } from 'entities/test/fixtures';
+import { createVizCache } from './vizCache';
+
+describe('VizCache', () => {
+  describe('VizCache - get method', () => {
+    it('should return content from cache if available', async () => {
+      const vizCache = createVizCache({
+        initialContents: [sampleContent],
+        handleCacheMiss: vi.fn(),
+      });
+      const content = await vizCache.get(sampleContent.id);
+      expect(content).toEqual(sampleContent);
+      expect(vi.fn()).toHaveBeenCalledTimes(0); // handleCacheMiss should not be called
+    });
+
+    it('should fetch content on cache miss and store it', async () => {
+      const handleCacheMissMock = vi
+        .fn()
+        .mockResolvedValue(sampleContent);
+      const vizCache = createVizCache({
+        initialContents: [],
+        handleCacheMiss: handleCacheMissMock,
+      });
+
+      const content = await vizCache.get(sampleContent.id);
+      expect(handleCacheMissMock).toHaveBeenCalledWith(
+        sampleContent.id,
+      );
+      expect(content).toEqual(sampleContent);
+      // Verify that the cache now contains the fetched content
+      const cachedContent = await vizCache.get(
+        sampleContent.id,
+      );
+      expect(cachedContent).toEqual(sampleContent);
+    });
+
+    it('should throw an error if handleCacheMiss does not return content', async () => {
+      const handleCacheMissMock = vi
+        .fn()
+        .mockResolvedValue(undefined);
+      const vizCache = createVizCache({
+        initialContents: [],
+        handleCacheMiss: handleCacheMissMock,
+      });
+
+      await expect(
+        vizCache.get('nonexistentId'),
+      ).rejects.toThrow(
+        'Unresolved import from vizId nonexistentId',
+      );
+    });
+
+    // Add tests for set
+  });
+  describe('VizCache - set method', () => {
+    it('should add new content to the cache', async () => {
+      const vizCache = createVizCache({
+        initialContents: [],
+        handleCacheMiss: vi.fn(),
+      });
+
+      const newContent: Content = {
+        id: 'newContent',
+        files: {},
+        title: 'New Content',
+      };
+
+      vizCache.set(newContent);
+
+      // Verify new content is added
+      const content = await vizCache.get(newContent.id);
+      expect(content).toEqual(newContent);
+    });
+
+    it('should update existing content in the cache', async () => {
+      const updatedContent: Content = {
+        ...sampleContent,
+        title: 'Updated Content Title',
+      };
+
+      const vizCache = createVizCache({
+        initialContents: [sampleContent],
+        handleCacheMiss: vi.fn(),
+      });
+
+      // Update existing content
+      vizCache.set(updatedContent);
+
+      // Verify content is updated
+      const content = await vizCache.get(updatedContent.id);
+      expect(content).toEqual(updatedContent);
+    });
+
+    it('should keep the cache consistent after multiple set operations', async () => {
+      const vizCache = createVizCache({
+        initialContents: [],
+        handleCacheMiss: vi.fn(),
+      });
+
+      // Adding multiple contents
+      const contentA: Content = {
+        id: 'contentA',
+        files: {},
+        title: 'Content A',
+      };
+
+      const contentB: Content = {
+        id: 'contentB',
+        files: {},
+        title: 'Content B',
+      };
+
+      vizCache.set(contentA);
+      vizCache.set(contentB);
+
+      // Verify both contents are retrievable
+      const retrievedA = await vizCache.get(contentA.id);
+      const retrievedB = await vizCache.get(contentB.id);
+
+      expect(retrievedA).toEqual(contentA);
+      expect(retrievedB).toEqual(contentB);
+    });
+  });
+});

package/src/v3Runtime/vizCache.ts

@@ -0,0 +1,60 @@
+import { Content, VizId } from 'entities';
+
+export type VizCache = {
+  get: (vizId: string) => Promise<Content>;
+  set: (content: Content) => void;
+  invalidate: (vizId: string) => void;
+};
+
+// A cache of viz content.
+// For use in resolving imports from other vizzes.
+// Runs both on the server and in the browser.
+export const createVizCache = ({
+  initialContents,
+  handleCacheMiss,
+}: {
+  initialContents: Array<Content>;
+  handleCacheMiss: (vizId: VizId) => Promise<Content>;
+}): VizCache => {
+  // Track the content of cached vizzes.
+  const contentMap = new Map<VizId, Content>(
+    initialContents.map((content) => [content.id, content]),
+  );
+
+  // Gets the content of a viz.
+  // Returns the cached content if it exists.
+  // Otherwise, calls handleCacheMiss to fetch the content.
+  const get = async (vizId: string): Promise<Content> => {
+    const cachedContent: Content | undefined =
+      contentMap.get(vizId);
+
+    // Cache hit
+    if (cachedContent !== undefined) {
+      return cachedContent;
+    }
+
+    // Cache miss
+    const freshContent = await handleCacheMiss(vizId);
+
+    if (freshContent) {
+      contentMap.set(vizId, freshContent);
+      return freshContent;
+    }
+
+    // TODO surface this error to the user
+    throw new Error(
+      `Unresolved import from vizId ${vizId}`,
+    );
+  };
+
+  // Updates the content of a viz in the cache.
+  const set = (content: Content) => {
+    contentMap.set(content.id, content);
+  };
+
+  const invalidate = (vizId: string) => {
+    contentMap.delete(vizId);
+  };
+
+  return { get, set, invalidate };
+};

package/src/v3Runtime/vizLoad.ts

@@ -0,0 +1,68 @@
+import { InputPluginOption } from 'rollup';
+import { ResolvedVizFileId } from './types';
+import { parseId } from './parseId';
+import { Content, getFileText } from 'entities';
+import { VizCache } from './vizCache';
+
+const debug = false;
+
+// Responsible for loading all imports and
+// tracking which CSS files are imported.
+// Throws an error if a file is imported but not found.
+export const vizLoad = ({
+  vizCache,
+  trackCSSImport,
+}: {
+  vizCache: VizCache;
+  trackCSSImport: (cssFile: ResolvedVizFileId) => void;
+}): InputPluginOption => ({
+  name: 'vizLoad',
+
+  // `id` here is of the form
+  // `{vizId}/{fileName}`
+  load: async (id: ResolvedVizFileId) => {
+    if (debug) {
+      console.log('[vizLoadCSS]: load() ' + id);
+    }
+
+    const { vizId, fileName } = parseId(id);
+
+    if (debug) {
+      console.log('  [vizLoadCSS] vizId: ' + vizId);
+      console.log('  [vizLoadCSS] fileName: ' + fileName);
+    }
+
+    // For CSS imports, all we need to do here is
+    // keep track of them so they can be injected
+    // into the IFrame later.
+    if (fileName.endsWith('.css')) {
+      if (debug) {
+        console.log(
+          '    [vizResolve] tracking CSS import for ' + id,
+        );
+      }
+      // The import is tracked here so that it can be
+      // injected into the IFrame later, external to the
+      // Rollup build.
+      trackCSSImport(id);
+      // TODO consider using Rollup's `emitFile` to emit a CSS file.
+      return '';
+    }
+
+    const content: Content = await vizCache.get(vizId);
+    const fileText = getFileText(content, fileName);
+
+    // If a file is imported but not found, throw an error.
+    if (fileText === null) {
+      throw new Error(
+        `Imported file "${fileName}" not found.`,
+      );
+      // TODO ideally show username/slug instead of vizId
+      // `Imported file "${fileName}" not found in viz ${vizId}`,
+      // `Imported file "${fileName}" not found.`,
+      // );
+    }
+
+    return fileText;
+  },
+});

package/src/v3Runtime/vizLoadSvelte.ts

@@ -0,0 +1,46 @@
+// import { InputPluginOption } from 'rollup';
+// import { VizCache } from './vizCache';
+// import { ResolvedVizFileId } from './types';
+// import { parseId } from './parseId';
+// import { Content, getFileText } from 'entities';
+
+// const debug = true;
+
+// export const vizLoadSvelte = ({
+//   vizCache,
+// }: {
+//   vizCache: VizCache;
+// }): InputPluginOption => ({
+//   name: 'vizLoadSvelte',
+
+//   // `id` here is of the form
+//   // `{vizId}/{fileName}`
+//   load: async (id: ResolvedVizFileId) => {
+//     if (debug) {
+//       console.log('vizLoadSvelte: load() ' + id);
+//     }
+
+//     const { vizId, fileName } = parseId(id);
+
+//     if (debug) {
+//       console.log('  [vizLoadSvelte] vizId: ' + vizId);
+//       console.log(
+//         '  [vizLoadSvelte] fileName: ' + fileName,
+//       );
+//     }
+
+//     if (fileName.endsWith('.svelte')) {
+//       if (debug) {
+//         console.log(
+//           '    [vizLoadSvelte] tracking Svelte import for ' +
+//             id,
+//         );
+//       }
+
+//       // For Svelte imports, we need to recursively resolve
+//       // the imports of the imported viz.
+//       const content: Content = await vizCache.get(vizId);
+//       return getFileText(content, fileName);
+//     }
+//   },
+// });

package/src/v3Runtime/vizResolve.ts

@@ -0,0 +1,100 @@
+// A custom Rollup plugin to:
+//  * Implement a virtual file system
+//  * Support importing across vizzes
+// Unified Rollup plugin for virtual file system and viz imports
+// Combines functionalities of 'virtual' and 'importFromViz' plugins
+import { InputPluginOption } from 'rollup';
+import { extractVizImport } from './extractVizImport';
+import { VizId, isId } from 'entities';
+import { ResolvedVizFileId } from './types';
+import { parseId } from './parseId';
+
+const debug = false;
+
+export const vizResolve = ({
+  vizId,
+  resolveSlug,
+}: {
+  vizId: VizId;
+  resolveSlug?: ({
+    userName,
+    slug,
+  }: {
+    userName: string;
+    slug: string;
+  }) => Promise<VizId>;
+}): InputPluginOption => ({
+  name: 'vizResolve',
+  resolveId: async (
+    id: string,
+    importer: string | undefined,
+  ): Promise<ResolvedVizFileId | undefined> => {
+    if (debug) {
+      console.log('[vizIdResolve] resolveId() ' + id);
+      console.log('  importer: ' + importer);
+    }
+
+    // Handle virtual file system resolution
+    // .e.g. `import { foo } from './foo.js'`
+    // .e.g. `import { foo } from './foo'`
+    if (
+      id.startsWith('./') &&
+      !importer?.startsWith('https://')
+    ) {
+      // const fileName = js(id.substring(2));
+
+      let fileName = id.substring(2);
+
+      // Handle CSS files
+      // e.g. `import './styles.css'`
+      // Handle JS files
+      // e.g. `import { foo } from './foo.js'`
+      // e.g. `import { foo } from './foo'`
+      if (
+        !fileName.endsWith('.js') &&
+        !fileName.endsWith('.css') &&
+        !fileName.endsWith('.csv') &&
+        !fileName.endsWith('.svelte')
+      ) {
+        fileName += '.js';
+      }
+
+      // const js = (name: string) =>
+      // name.endsWith('.js') ? name : name + '.js';
+
+      // If there is an importer, then the file not part of
+      // the entry point, so it should be resolved relative
+      // to the importer viz.
+      if (importer) {
+        const { vizId: importerVizId } = parseId(importer);
+        return importerVizId + '/' + fileName;
+      }
+      return vizId + '/' + fileName;
+    }
+
+    // Handle viz import resolution
+    // e.g. `import { foo } from '@curran/98e6d6509a1e407897d4f238a330efec'`
+    // e.g. `import { foo } from '@curran/scatter-plot'`
+    const vizImport = extractVizImport(id);
+    if (vizImport) {
+      let vizId: VizId;
+      if (isId(vizImport.idOrSlug)) {
+        vizId = vizImport.idOrSlug;
+      } else {
+        if (!resolveSlug) {
+          throw new Error(
+            'resolveSlug is required to import by slug',
+          );
+        }
+        vizId = await resolveSlug({
+          userName: vizImport.userName,
+          slug: vizImport.idOrSlug,
+        });
+      }
+      return vizId + '/index.js';
+    }
+
+    // If neither condition is met, return undefined.
+    return undefined;
+  },
+});