Add extends field to JSON configs (#118)

You can now set the extends property of a JSON config to another config file URL, and they'll be fetched and merged recursively. Useful for when we have a base config for a site that we want to inherit across a bunch of playgrounds.

Author: aomarks

CHANGELOG.md

@@ -26,6 +26,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Added support for JSON files with syntax highlighting.
 
+- Added `extends` property to JSON config file, an optional URL of another JSON
+  config file to extend from. Useful for setting side-wide defaults.
+
 ### Fixed
 
 - Fixed bug where editor did not immediately switch to newly created files.

README.md

@@ -163,22 +163,16 @@ There are 3 ways to specify the files of a playground project:
 
 ### Option 1: Inline scripts
 
-Add one or more `<script type="sample/..." filename="...">` tags as children of
-your `<playground-ide>` or `<playground-project>`. The following attributes are
-available:
+Add one or more `<script>` tags as children of
+your `<playground-ide>` or `<playground-project>`, using the following attributes:
 
-- `type`: Required filetype. Valid options: `sample/html`, `sample/css`,
-  `sample/js`, `sample/ts`, `sample/json`, `sample/importmap`.
-
-- `filename`: Required filename.
-
-- `label`: Optional label for display in `playground-tab-bar`. If omitted, the
-  filename is displayed.
-
-- `hidden`: If present, the file won't be visible in `playground-tab-bar`.
-
-- `preserve-whitespace`: Disable the default behavior where leading whitespace
-  that is common to all lines is removed.
+| Attribute             |  Description                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `type`                | Required filetype. Options: `sample/html`, `sample/css`, `sample/js`, `sample/ts`, `sample/json`, `sample/importmap`. |
+| `filename`            | Required filename.                                                                                                    |
+| `label`               | Optional label for display in `playground-tab-bar`. If omitted, the filename is displayed.                            |
+| `hidden`              | If present, the file won't be visible in `playground-tab-bar`.                                                        |
+| `preserve-whitespace` | Disable the default behavior where leading whitespace that is common to all lines is removed.                         |
 
 Be sure to escape closing `</script>` tags within your source as `<&lt;script>`.
 
@@ -210,23 +204,18 @@ Be sure to escape closing `</script>` tags within your source as `<&lt;script>`.
 </playground-project>
 ```
 
-### Option 2: JSON manifest
-
-Serve a JSON file containing a `files` object. Keys are filenames relative to
-the manifest URL. Values are objects with any of the following optional
-properties:
-
-- `content`: Optional text content of the file. If omitted, a `fetch` is made to
-  retrieve the file by filename, relative to the manifest URL.
-
-- `contentType`: Optional MIME type of the file. If omitted, type is taken from
-  either the `fetch` response `Content-Type` header, or inferred from the
-  filename extension when `content` is set.
+### Option 2: JSON configuration
 
-- `label`: Optional label for display in `playground-tab-bar`. If omitted, the
-  filename is displayed.
+Set the `project-src` attribute or `projectSrc` property to a JSON file with format:
 
-- `hidden`: If `true`, the file won't be visible in `playground-tab-bar`.
+| Property            |  Description                                                                                                                                                                     |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `files`             | An object mapping filenames to file data.                                                                                                                                        |
+| `files.content`     | Optional text content of the file. If omitted, a `fetch` is made to retrieve the file by filename, relative to the manifest URL.                                                 |
+| `files.contentType` | Optional MIME type of the file. If omitted, type is taken from either the `fetch` response `Content-Type` header, or inferred from the filename extension when `content` is set. |
+| `files.label`       | Optional label for display in `playground-tab-bar`. If omitted, the filename is displayed.                                                                                       |
+| `files.hidden`      | If `true`, the file won't be visible in `playground-tab-bar`.                                                                                                                    |
+| `extends`           | Optional URL to another JSON config file to extend from. Configs are deeply merged. URLs are interpreted relative to the URL of each extendee config.                            |
 
 ```html
 <playground-ide project-src="/path/to/my/project.json"> </playground-ide>

src/playground-project.ts

@@ -261,7 +261,9 @@ export class PlaygroundProject extends LitElement {
         this._importMap = source.importMap;
         break;
       case 'url':
-        const {files, importMap} = await fetchProject(source.url);
+        const {files, importMap} = await fetchProjectConfig(
+          new URL(source.url, document.baseURI).href
+        );
         // Note the source could have changed while fetching, hence the
         // double-check here.
         if (source !== this._source) {
@@ -519,39 +521,93 @@ export class PlaygroundProject extends LitElement {
   }
 }
 
-const fetchProject = async (url: string) => {
-  const projectUrl = new URL(url, document.baseURI);
-  const manifestFetched = await fetch(url);
-  const manifest = (await manifestFetched.json()) as ProjectManifest;
-
-  const files = await Promise.all(
-    Object.entries(manifest.files ?? {}).map(
-      async ([name, {content, contentType, label, hidden}]) => {
-        if (content === undefined) {
-          const fileUrl = new URL(name, projectUrl);
-          const response = await fetch(fileUrl.href);
-          if (response.status === 404) {
-            throw new Error(`Could not find file ${name}`);
-          }
-          content = await response.text();
-          if (!contentType) {
-            contentType = response.headers.get('Content-Type') ?? undefined;
-          }
-        }
-        if (!contentType) {
-          contentType = typeFromFilename(name) ?? 'text/plain';
-        }
-        return {
-          name,
-          label,
-          hidden,
-          content,
-          contentType,
-        };
-      }
-    )
-  );
-  return {files, importMap: manifest.importMap ?? {}};
+const fetchProjectConfig = async (
+  configUrl: string,
+  alreadyFetchedFilenames = new Set<string>(),
+  alreadyFetchedConfigUrls = new Set<string>()
+): Promise<{files: Array<SampleFile>; importMap: ModuleImportMap}> => {
+  if (alreadyFetchedConfigUrls.has(configUrl)) {
+    throw new Error(
+      `Circular project config extends: ${[
+        ...alreadyFetchedConfigUrls.values(),
+        configUrl,
+      ].join(' extends ')}`
+    );
+  }
+  alreadyFetchedConfigUrls.add(configUrl);
+  const resp = await fetch(configUrl);
+  if (resp.status !== 200) {
+    throw new Error(
+      `Error ${
+        resp.status
+      } fetching project config from ${configUrl}: ${await resp.text()}`
+    );
+  }
+
+  let config;
+  try {
+    config = (await resp.json()) as ProjectManifest;
+  } catch (e) {
+    throw new Error(
+      `Error parsing project config JSON from ${configUrl}: ${e.message}`
+    );
+  }
+
+  const filePromises: Array<Promise<SampleFile>> = [];
+  for (const [filename, info] of Object.entries(config.files ?? {})) {
+    // A higher precedence config is already handling this file.
+    if (alreadyFetchedFilenames.has(filename)) {
+      continue;
+    }
+    alreadyFetchedFilenames.add(filename);
+    if (info.content === undefined) {
+      filePromises.push(
+        (async () => {
+          const resp = await fetch(new URL(filename, configUrl).href);
+          return {
+            ...info,
+            name: filename,
+            content: await resp.text(),
+            contentType: resp.headers.get('Content-Type') ?? undefined,
+          };
+        })()
+      );
+    } else {
+      filePromises.push(
+        Promise.resolve({
+          ...info,
+          name: filename,
+          content: info.content ?? '',
+          contentType: typeFromFilename(filename) ?? 'text/plain',
+        })
+      );
+    }
+  }
+
+  // Start extends config fetch before we block on file fetches.
+  const extendsConfigPromise = config.extends
+    ? fetchProjectConfig(
+        new URL(config.extends, configUrl).href,
+        alreadyFetchedFilenames,
+        alreadyFetchedConfigUrls
+      )
+    : undefined;
+
+  const files = await Promise.all(filePromises);
+  const importMap = config.importMap ?? {};
+
+  if (extendsConfigPromise) {
+    const extendsConfig = await extendsConfigPromise;
+    // Parent files go after our own.
+    files.push(...extendsConfig.files);
+    importMap.imports = {
+      ...extendsConfig.importMap?.imports,
+      // Our imports take precedence over our parents.
+      ...importMap.imports,
+    };
+  }
+
+  return {files, importMap};
 };
 
 const typeFromFilename = (filename: string) => {

src/shared/worker-api.ts

@@ -99,6 +99,8 @@ export interface FileOptions {
 }
 
 export interface ProjectManifest {
+  /** Optional project manifest URL to extend from */
+  extends?: string;
   files?: {[filename: string]: FileOptions};
   importMap?: ModuleImportMap;
 }