repl-sdk 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 NullVoxPopuli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# REPL SDK
+
+A Runtime compiler for anything that you could want to build a lighting fast REPL with.
+
+
+Features:
+- Uses [es-module-shims](https://github.com/guybedford/es-module-shims)
+- Built in support for JavaScript, Mermaid, React, Vue, Svelte, Ember, Markdown
+  - On-Demand Runtime: only pay for what you compile for - the async APIs mean that your users only load what they need.
+- Supports nested languages (for markdown) 
+- Add any additional compiler/renderer at any time -- the flexible API allows for new libraries/frameworks to be added easily
+
+## Usage 
+
+

package/declarations/index.d.ts

@@ -0,0 +1,73 @@
+export declare class Compiler {
+    constructor(options?: Options);
+
+    compile(format: string, text: string): Promise<HTMLElement>;
+}
+
+export declare const defaultFormats: Options['formats'];
+
+export declare const defaults: Options;
+
+declare interface Options {
+    formats: {
+        [fileExtension: string]: {
+            /**
+             * When using this file extension in markdown documents,
+             * should we only evaluate the code block if the "live"
+             * meta is attached to the codefence?
+             *
+             * If you don't use markdown-embedded rendering,
+             * you can ignore this option. Default behavior is "false",
+             * but it doesn't matter if you don't render markdown anyway.
+             *
+             * For example, with `needsLiveMeta: false`:
+             * \`\`\`js
+             * console.log('hello');
+             * \`\`\`
+             * will be evaluated and log to the console.
+             * However, with `needsLiveMeta: true`, the above snippet would not
+             * be evaluated. To evaluate a snippet with `needsLiveMeta: true`:
+             * \`\`\`js live
+             * console.log('hello');
+             * \`\`\`
+             */
+            needsLiveMeta?: boolean;
+            compiler: () => Promise<{
+                /**
+                 * Convert a string from "fileExtension" to standard JavaScript.
+                 * This will be loaded as a module and then passed to the render method.
+                 */
+                compile: (text: string) => Promise<string>;
+                /**
+                 * For the root of a node rendered for this compiler,
+                 * how will this particular library / framework
+                 * render in to the given element?
+                 *
+                 * Example:
+                 * ```js
+                 * {
+                 *   async compiler() {
+                 *     const { createRoot } = await import('react-dom/client');
+                 *
+                 *     return {
+                 *        render(element, defaultExport) {
+                 *          const root = createRoot(element);
+                 *
+                 *          root.render(defaultExport);
+                 *        },
+                 *        // ...
+                 *     }
+                 *   }
+                 * }
+                 * ```
+                 *
+                 * @param {HTMLElement} the element to render in to, this is provided by repl-sdk.
+                 * @param {any} the default export from the compiled module.
+                 */
+                render: (element: HTMLElement, defaultExport: any) => void;
+            }>;
+        };
+    };
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,107 @@
+function assert(message, test) {
+  if (!test) {
+    throw new Error(message);
+  }
+}
+assert(`There is no document. repl-sdk is meant to be ran in a browser`, globalThis.document);
+const defaultFormats = {
+  mermaid: {
+    compiler: async () => {
+      return {
+        compile: async (text) => {
+        }
+      };
+    }
+  }
+};
+const defaults = {
+  formats: defaultFormats
+};
+const secret = Symbol.for("__repl-sdk__compiler__");
+assert(
+  `There is already an instance of repl-sdk, and there can only be one. Make sure that your dependency graph is correct.`,
+  !globalThis[secret]
+);
+class Compiler {
+  /** @type {Options} */
+  #options;
+  /**
+   * Options may be passed to the compiler to add to its behavior.
+   */
+  constructor(options = defaults) {
+    this.#options = options;
+    globalThis[secret] = this;
+    globalThis.window.esmsInitOptions = {
+      shimMode: true,
+      skip: `https://esm.sh/`,
+      revokeBlobURLs: true,
+      // default false
+      // Permit overrides to import maps
+      mapOverrides: true,
+      // default false
+      // Hook all module resolutions
+      resolve: (id, parentUrl, resolve) => {
+        if (id.startsWith("blob:")) return id;
+        if (id.startsWith("https://")) return id;
+        console.log("Resolving", id);
+        return `https://esm.sh/*${id}`;
+      },
+      // Hook source fetch function
+      fetch: async (url, options2) => {
+        console.log(`Fetching`, url);
+        if (url.endsWith("example.js")) {
+          const transformed = `export const js = 'transformed'`;
+          return new Response(new Blob([transformed], { type: "application/javascript" }));
+        }
+        const response = await fetch(url, options2);
+        return response;
+      }
+    };
+  }
+  /**
+   * @param {string} format
+   * @param {string} text
+   */
+  async compile(format, text) {
+    await import("es-module-shims");
+    const compiler = await this.#getCompiler(format);
+    const compiledText = await compiler.compile(text);
+    const asBlobUrl = textToBlobUrl(compiledText);
+    const { default: defaultExport } = await importShim(
+      /* @vite-ignore */
+      asBlobUrl
+    );
+    return this.#render(compiler, defaultExport);
+  }
+  async #getCompiler(format) {
+    const config = this.#options.formats[format];
+    assert(
+      `${format} is not a configured format. The currently configured formats are ${Object.keys(this.#options.formats).join(", ")}`,
+      config
+    );
+    const compiler = await config.compiler();
+    return compiler;
+  }
+  async #render(compiler, whatToRender) {
+    const div = this.#createDiv();
+    await compiler.render(div, whatToRender);
+    return div;
+  }
+  #createDiv() {
+    let div = document.createElement("div");
+    div.setAttribute("data-repl-output", "");
+    div.id = "some-random-string";
+    return div;
+  }
+}
+function textToBlobUrl(text) {
+  const blob = new Blob([text], { type: "text/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  return blobUrl;
+}
+export {
+  Compiler,
+  defaultFormats,
+  defaults
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/utils.js","../src/index.js"],"sourcesContent":["/**\n * @param {string} message\n * @param {unknown} test\n * @asserts test\n */\nexport function assert(message, test) {\n  if (!test) {\n    throw new Error(message);\n  }\n}\n","/**\n * @typedef {import(\"./types.ts\").Options} Options\n */\nimport { assert } from './utils.js';\n\nassert(`There is no document. repl-sdk is meant to be ran in a browser`, globalThis.document);\n\nexport const defaultFormats = {\n  mermaid: {\n    compiler: async () => {\n      return {\n        compile: async (text) => {},\n      };\n    },\n  },\n};\n\nexport const defaults = {\n  formats: defaultFormats,\n};\n\nconst secret = Symbol.for('__repl-sdk__compiler__');\n\nassert(\n  `There is already an instance of repl-sdk, and there can only be one. Make sure that your dependency graph is correct.`,\n  !globalThis[secret]\n);\n\nexport class Compiler {\n  /** @type {Options} */\n  #options;\n\n  /**\n   * Options may be passed to the compiler to add to its behavior.\n   */\n  constructor(options = defaults) {\n    this.#options = options;\n\n    globalThis[secret] = this;\n    globalThis.window.esmsInitOptions = {\n      shimMode: true,\n      skip: `https://esm.sh/`,\n      revokeBlobURLs: true, // default false\n      // Permit overrides to import maps\n      mapOverrides: true, // default false\n      // Hook all module resolutions\n      resolve: (id, parentUrl, resolve) => {\n        if (id.startsWith('blob:')) return id;\n        if (id.startsWith('https://')) return id;\n\n        console.log('Resolving', id);\n        /**\n         * TODO: locally defined scope\n         *       vs\n         *       proxy to esm.sh\n         */\n\n        /**\n         * For esm.sh, we want all imports to declare they don't want\n         * their dependencies bundled. We want to have every import go\n         * through this resolve/fetch combo of things so we have a chance\n         * to compile if we need to.\n         */\n        return `https://esm.sh/*${id}`;\n      },\n      // Hook source fetch function\n      fetch: async (url, options) => {\n        console.log(`Fetching`, url);\n        /**\n         * Do transformations here based on file extension\n         */\n        if (url.endsWith('example.js')) {\n          const transformed = `export const js = 'transformed'`;\n          return new Response(new Blob([transformed], { type: 'application/javascript' }));\n        }\n\n        const response = await fetch(url, options);\n\n        // if (response.url.endsWith('.ts')) {\n        //   const source = await response.body();\n        //   const transformed = tsCompile(source);\n        //   return new Response(new Blob([transformed], { type: 'application/javascript' }));\n        // }\n        return response;\n      },\n    };\n    // addShim();\n  }\n\n  /**\n   * @param {string} format\n   * @param {string} text\n   */\n  async compile(format, text) {\n    await import('es-module-shims');\n\n    const compiler = await this.#getCompiler(format);\n\n    // TODO: pass this through es-module-shims\n    //       for getting the actual module back\n    const compiledText = await compiler.compile(text);\n\n    const asBlobUrl = textToBlobUrl(compiledText);\n\n    const { default: defaultExport } = await importShim(/* @vite-ignore */ asBlobUrl);\n\n    return this.#render(compiler, defaultExport);\n  }\n\n  async #getCompiler(format) {\n    const config = this.#options.formats[format];\n\n    assert(\n      `${format} is not a configured format. ` +\n        `The currently configured formats are ${Object.keys(this.#options.formats).join(', ')}`,\n      config\n    );\n\n    const compiler = await config.compiler();\n\n    return compiler;\n  }\n\n  async #render(compiler, whatToRender) {\n    const div = this.#createDiv();\n\n    await compiler.render(div, whatToRender);\n\n    return div;\n  }\n\n  #createDiv() {\n    let div = document.createElement('div');\n    div.setAttribute('data-repl-output', '');\n    div.id = 'some-random-string';\n    return div;\n  }\n}\n\nfunction addShim() {\n  let url = 'https://ga.jspm.io/npm:es-module-shims@1.10.0/dist/es-module-shims.js';\n\n  if (document.querySelector('script[src=\"${url}\"]')) {\n    // Shim is already present\n    return;\n  }\n\n  let script = document.createElement('script');\n  // script.setAttribute('async', '');\n  script.setAttribute('src', `<script async src=\"${url}\"></script>`);\n\n  document.head.appendChild(script);\n}\n\n/**\n * @param {string} text\n */\nfunction textToBlobUrl(text) {\n  const blob = new Blob([text], { type: 'text/javascript' });\n\n  const blobUrl = URL.createObjectURL(blob);\n  return blobUrl;\n}\n"],"names":["options"],"mappings":"AAKO,SAAS,OAAO,SAAS,MAAM;AACpC,MAAI,CAAC,MAAM;AACT,UAAM,IAAI,MAAM,OAAO;AAAA,EACxB;AACH;ACJA,OAAO,kEAAkE,WAAW,QAAQ;AAEhF,MAAC,iBAAiB;AAAA,EAC5B,SAAS;AAAA,IACP,UAAU,YAAY;AACpB,aAAO;AAAA,QACL,SAAS,OAAO,SAAS;AAAA,QAAE;AAAA,MACnC;AAAA,IACK;AAAA,EACF;AACH;AAEY,MAAC,WAAW;AAAA,EACtB,SAAS;AACX;AAEA,MAAM,SAAS,OAAO,IAAI,wBAAwB;AAElD;AAAA,EACE;AAAA,EACA,CAAC,WAAW,MAAM;AACpB;AAEO,MAAM,SAAS;AAAA;AAAA,EAEpB;AAAA;AAAA;AAAA;AAAA,EAKA,YAAY,UAAU,UAAU;AAC9B,SAAK,WAAW;AAEhB,eAAW,MAAM,IAAI;AACrB,eAAW,OAAO,kBAAkB;AAAA,MAClC,UAAU;AAAA,MACV,MAAM;AAAA,MACN,gBAAgB;AAAA;AAAA;AAAA,MAEhB,cAAc;AAAA;AAAA;AAAA,MAEd,SAAS,CAAC,IAAI,WAAW,YAAY;AACnC,YAAI,GAAG,WAAW,OAAO,EAAG,QAAO;AACnC,YAAI,GAAG,WAAW,UAAU,EAAG,QAAO;AAEtC,gBAAQ,IAAI,aAAa,EAAE;AAa3B,eAAO,mBAAmB,EAAE;AAAA,MAC7B;AAAA;AAAA,MAED,OAAO,OAAO,KAAKA,aAAY;AAC7B,gBAAQ,IAAI,YAAY,GAAG;AAI3B,YAAI,IAAI,SAAS,YAAY,GAAG;AAC9B,gBAAM,cAAc;AACpB,iBAAO,IAAI,SAAS,IAAI,KAAK,CAAC,WAAW,GAAG,EAAE,MAAM,yBAA0B,CAAA,CAAC;AAAA,QAChF;AAED,cAAM,WAAW,MAAM,MAAM,KAAKA,QAAO;AAOzC,eAAO;AAAA,MACR;AAAA,IACP;AAAA,EAEG;AAAA;AAAA;AAAA;AAAA;AAAA,EAMD,MAAM,QAAQ,QAAQ,MAAM;AAC1B,UAAM,OAAO,iBAAiB;AAE9B,UAAM,WAAW,MAAM,KAAK,aAAa,MAAM;AAI/C,UAAM,eAAe,MAAM,SAAS,QAAQ,IAAI;AAEhD,UAAM,YAAY,cAAc,YAAY;AAE5C,UAAM,EAAE,SAAS,cAAa,IAAK,MAAM;AAAA;AAAA,MAA8B;AAAA,IAAS;AAEhF,WAAO,KAAK,QAAQ,UAAU,aAAa;AAAA,EAC5C;AAAA,EAED,MAAM,aAAa,QAAQ;AACzB,UAAM,SAAS,KAAK,SAAS,QAAQ,MAAM;AAE3C;AAAA,MACE,GAAG,MAAM,qEACiC,OAAO,KAAK,KAAK,SAAS,OAAO,EAAE,KAAK,IAAI,CAAC;AAAA,MACvF;AAAA,IACN;AAEI,UAAM,WAAW,MAAM,OAAO;AAE9B,WAAO;AAAA,EACR;AAAA,EAED,MAAM,QAAQ,UAAU,cAAc;AACpC,UAAM,MAAM,KAAK;AAEjB,UAAM,SAAS,OAAO,KAAK,YAAY;AAEvC,WAAO;AAAA,EACR;AAAA,EAED,aAAa;AACX,QAAI,MAAM,SAAS,cAAc,KAAK;AACtC,QAAI,aAAa,oBAAoB,EAAE;AACvC,QAAI,KAAK;AACT,WAAO;AAAA,EACR;AACH;AAoBA,SAAS,cAAc,MAAM;AAC3B,QAAM,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,MAAM,kBAAiB,CAAE;AAEzD,QAAM,UAAU,IAAI,gBAAgB,IAAI;AACxC,SAAO;AACT;"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "repl-sdk",
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./declarations/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "repl",
+    "playground",
+    "SDK",
+    "render",
+    "play",
+    "javascript",
+    "live",
+    "interactive"
+  ],
+  "author": "NullVoxPopuli",
+  "files": [
+    "dist",
+    "declarations",
+    "src"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@tsconfig/ember": "^3.0.7",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11",
+    "vite-plugin-dts": "4.0.0-beta.1"
+  },
+  "dependencies": {
+    "es-module-shims": "^1.10.0"
+  },
+  "scripts": {
+    "start": "vite build --watch"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,10 @@
+import type { Options } from "./types.ts";
+
+export const defaultFormats: Options['formats'];
+export const defaults: Options;
+
+export class Compiler {
+  constructor(options?: Options);
+
+  compile(format: string, text: string): Promise<HTMLElement>;
+}

package/src/index.js

@@ -0,0 +1,163 @@
+/**
+ * @typedef {import("./types.ts").Options} Options
+ */
+import { assert } from './utils.js';
+
+assert(`There is no document. repl-sdk is meant to be ran in a browser`, globalThis.document);
+
+export const defaultFormats = {
+  mermaid: {
+    compiler: async () => {
+      return {
+        compile: async (text) => {},
+      };
+    },
+  },
+};
+
+export const defaults = {
+  formats: defaultFormats,
+};
+
+const secret = Symbol.for('__repl-sdk__compiler__');
+
+assert(
+  `There is already an instance of repl-sdk, and there can only be one. Make sure that your dependency graph is correct.`,
+  !globalThis[secret]
+);
+
+export class Compiler {
+  /** @type {Options} */
+  #options;
+
+  /**
+   * Options may be passed to the compiler to add to its behavior.
+   */
+  constructor(options = defaults) {
+    this.#options = options;
+
+    globalThis[secret] = this;
+    globalThis.window.esmsInitOptions = {
+      shimMode: true,
+      skip: `https://esm.sh/`,
+      revokeBlobURLs: true, // default false
+      // Permit overrides to import maps
+      mapOverrides: true, // default false
+      // Hook all module resolutions
+      resolve: (id, parentUrl, resolve) => {
+        if (id.startsWith('blob:')) return id;
+        if (id.startsWith('https://')) return id;
+
+        console.log('Resolving', id);
+        /**
+         * TODO: locally defined scope
+         *       vs
+         *       proxy to esm.sh
+         */
+
+        /**
+         * For esm.sh, we want all imports to declare they don't want
+         * their dependencies bundled. We want to have every import go
+         * through this resolve/fetch combo of things so we have a chance
+         * to compile if we need to.
+         */
+        return `https://esm.sh/*${id}`;
+      },
+      // Hook source fetch function
+      fetch: async (url, options) => {
+        console.log(`Fetching`, url);
+        /**
+         * Do transformations here based on file extension
+         */
+        if (url.endsWith('example.js')) {
+          const transformed = `export const js = 'transformed'`;
+          return new Response(new Blob([transformed], { type: 'application/javascript' }));
+        }
+
+        const response = await fetch(url, options);
+
+        // if (response.url.endsWith('.ts')) {
+        //   const source = await response.body();
+        //   const transformed = tsCompile(source);
+        //   return new Response(new Blob([transformed], { type: 'application/javascript' }));
+        // }
+        return response;
+      },
+    };
+    // addShim();
+  }
+
+  /**
+   * @param {string} format
+   * @param {string} text
+   */
+  async compile(format, text) {
+    await import('es-module-shims');
+
+    const compiler = await this.#getCompiler(format);
+
+    // TODO: pass this through es-module-shims
+    //       for getting the actual module back
+    const compiledText = await compiler.compile(text);
+
+    const asBlobUrl = textToBlobUrl(compiledText);
+
+    const { default: defaultExport } = await importShim(/* @vite-ignore */ asBlobUrl);
+
+    return this.#render(compiler, defaultExport);
+  }
+
+  async #getCompiler(format) {
+    const config = this.#options.formats[format];
+
+    assert(
+      `${format} is not a configured format. ` +
+        `The currently configured formats are ${Object.keys(this.#options.formats).join(', ')}`,
+      config
+    );
+
+    const compiler = await config.compiler();
+
+    return compiler;
+  }
+
+  async #render(compiler, whatToRender) {
+    const div = this.#createDiv();
+
+    await compiler.render(div, whatToRender);
+
+    return div;
+  }
+
+  #createDiv() {
+    let div = document.createElement('div');
+    div.setAttribute('data-repl-output', '');
+    div.id = 'some-random-string';
+    return div;
+  }
+}
+
+function addShim() {
+  let url = 'https://ga.jspm.io/npm:es-module-shims@1.10.0/dist/es-module-shims.js';
+
+  if (document.querySelector('script[src="${url}"]')) {
+    // Shim is already present
+    return;
+  }
+
+  let script = document.createElement('script');
+  // script.setAttribute('async', '');
+  script.setAttribute('src', `<script async src="${url}"></script>`);
+
+  document.head.appendChild(script);
+}
+
+/**
+ * @param {string} text
+ */
+function textToBlobUrl(text) {
+  const blob = new Blob([text], { type: 'text/javascript' });
+
+  const blobUrl = URL.createObjectURL(blob);
+  return blobUrl;
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+export interface Options {
+  formats: {
+    [fileExtension: string]: {
+      /**
+       * When using this file extension in markdown documents,
+       * should we only evaluate the code block if the "live" 
+       * meta is attached to the codefence?
+       *
+       * If you don't use markdown-embedded rendering, 
+       * you can ignore this option. Default behavior is "false",
+       * but it doesn't matter if you don't render markdown anyway.
+       *
+       * For example, with `needsLiveMeta: false`:
+       * \`\`\`js
+       * console.log('hello');
+       * \`\`\`
+       * will be evaluated and log to the console.
+       * However, with `needsLiveMeta: true`, the above snippet would not
+       * be evaluated. To evaluate a snippet with `needsLiveMeta: true`:
+       * \`\`\`js live 
+       * console.log('hello');
+       * \`\`\`
+       */
+      needsLiveMeta?: boolean;
+      compiler: () => Promise<{
+        /**
+         * Convert a string from "fileExtension" to standard JavaScript.
+         * This will be loaded as a module and then passed to the render method.
+         */
+        compile: (text: string) => Promise<string>;
+        /**
+         * For the root of a node rendered for this compiler,
+         * how will this particular library / framework
+         * render in to the given element?
+         *
+         * Example:
+         * ```js
+         * {
+         *   async compiler() {
+         *     const { createRoot } = await import('react-dom/client');
+         *   
+         *     return {
+         *        render(element, defaultExport) {
+         *          const root = createRoot(element);
+         *
+         *          root.render(defaultExport);
+         *        },
+         *        // ...
+         *     }
+         *   }
+         * }
+         * ```
+         *
+         * @param {HTMLElement} the element to render in to, this is provided by repl-sdk.
+         * @param {any} the default export from the compiled module.
+         */
+        render: (element: HTMLElement, defaultExport: any) => void;
+      }>;
+    }
+  }
+}
+

package/src/utils.js

@@ -0,0 +1,10 @@
+/**
+ * @param {string} message
+ * @param {unknown} test
+ * @asserts test
+ */
+export function assert(message, test) {
+  if (!test) {
+    throw new Error(message);
+  }
+}