@backtickjs/bundler 0.0.0-stage → 0.1.1

package/src/bundle/expandJsxElement.ts

@@ -0,0 +1,26 @@
+import type { JsxElement, Spliceable } from "@backtickjs/core";
+
+// The in-flight promise, so two references to one element run its component
+// once. Per bundle, like a function's expansion: an element held at module
+// level is the same object in every bundle, and what its component drew for
+// one request (the request's user) is not the next one's.
+export type ElementExpansions = WeakMap<JsxElement, Promise<Spliceable>>;
+
+// Runs a host component and answers with what it drew. The component itself
+// never leaves the host: a server component expands away here, and only the
+// client component it bottoms out in reaches the bundle.
+export function expandJsxElement(
+  jsx: JsxElement,
+  component: (props: never) => unknown,
+  expansions: ElementExpansions,
+): Promise<Spliceable> {
+  const shared = expansions.get(jsx);
+  if (shared) {
+    return shared;
+  }
+  const expansion = Promise.resolve(
+    component(jsx.props as never) as Spliceable | Promise<Spliceable>,
+  );
+  expansions.set(jsx, expansion);
+  return expansion;
+}

package/src/bundle/params.ts

@@ -0,0 +1,15 @@
+import type { ClientScript, Param } from "@backtickjs/core";
+
+// What a script's module says about its parameters, the same for every run.
+
+// The bindings a hole hands over. A capture hands over none.
+export function bindingsOf(param: Param | undefined): readonly string[] {
+  return param?.kind === "splice" ? param.bindings : [];
+}
+
+// The binding keys a script captures, in parameter order.
+export function capturesOf(script: ClientScript): readonly string[] {
+  return script.module.params.flatMap((param) =>
+    param.kind === "capture" ? [param.key] : [],
+  );
+}

package/src/bundler.ts

@@ -0,0 +1,66 @@
+import type { Spliceable } from "@backtickjs/core";
+import { buildBundle } from "./bundle/buildBundle.js";
+import { printBundle } from "./print/printBundle.js";
+
+export interface BuildOptions {
+  // What to bundle.
+  readonly input: Spliceable;
+  // The packages the client provides, each at its exact version: left out of
+  // the bundle, which requires them. A script's import from any other, or
+  // needing a version it doesn't have, throws.
+  readonly packageVersions: Readonly<Record<string, string>>;
+}
+
+export interface OutputOptions {
+  // `"es"`, an ES module, for a page; `"cjs"`, CommonJS, for a client that
+  // hands the bundle `require` itself, as a React Native app does.
+  readonly format: "es" | "cjs";
+  // A map into the host files, as Rollup's: `"inline"` appends the map to the
+  // code as a `data:` URL, and `"hidden"` answers it alone. None by default.
+  // It carries host files' names and lines, not their content, which stays
+  // the server's.
+  readonly sourcemap?: false | "inline" | "hidden";
+}
+
+/** What `generate` writes: the code, and its map where one was asked for. */
+export interface OutputChunk {
+  readonly code: string;
+  readonly map: string | null;
+}
+
+/** A built bundle, written out by `generate`. */
+export interface Bundle {
+  generate(options: OutputOptions): OutputChunk;
+}
+
+/**
+ * What runs your components and hands back what they drew, shaped as Rollup
+ * is: a build, then output from it.
+ *
+ *     const bundle = await bundler.build({ input: <Home />, packageVersions });
+ *     const { code, map } = bundle.generate({ format: "es", sourcemap: "hidden" });
+ *
+ * The module's default export is the value (CommonJS: `module.exports`). A
+ * namespace rather than a bare function, so `bundle` stays a name a caller can
+ * give what comes back.
+ */
+export const bundler = {
+  async build({ input, packageVersions }: BuildOptions): Promise<Bundle> {
+    // Scripts come compiled for their framework when their host was built, so
+    // the bundle is only put together: nothing is compiled or parsed here.
+    const tree = await buildBundle(input, packageVersions);
+    return {
+      generate: ({ format, sourcemap = false }) => {
+        const { code, map } = printBundle(tree, format);
+        if (sourcemap === false) {
+          return { code, map: null };
+        }
+        if (sourcemap === "hidden") {
+          return { code, map };
+        }
+        const url = `data:application/json;charset=utf-8,${encodeURIComponent(map)}`;
+        return { code: `${code}\n//# sourceMappingURL=${url}`, map };
+      },
+    };
+  },
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  type Bundle,
+  type BuildOptions,
+  bundler,
+  type OutputChunk,
+  type OutputOptions,
+} from "./bundler.js";

package/src/print/code.ts

@@ -0,0 +1,144 @@
+import type { ClientImport } from "@backtickjs/core";
+import semver from "semver";
+
+// What a bundle is written as, and the one place its conventions live: how a
+// name is written, how a literal escapes, and how an element is written as JSX
+// for the framework's compiler. Everything is code, as a string.
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * What a bundle imports, keyed by specifier and export, each bound once; and
+ * the packages it may import them from, which the client provides, by version.
+ */
+export interface Names {
+  readonly imports: Map<string, { from: string; name: string; local: string }>;
+  readonly packageVersions: Readonly<Record<string, string>>;
+}
+
+export function createNames(
+  packageVersions: Readonly<Record<string, string>>,
+): Names {
+  return { imports: new Map(), packageVersions };
+}
+
+// A string, as a literal: `<` escaped, so no `</script>` or `<!--` appears
+// when the bundle is inlined in a page, and the line and paragraph separators,
+// which JSON leaves bare and not every engine reads inside a string.
+export function string(value: string): string {
+  return JSON.stringify(value).replace(
+    /[<\u2028\u2029]/g,
+    (unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+export function literal(value: string | number | boolean | null): string {
+  if (typeof value === "string") {
+    return string(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(`${value} has no literal`);
+    }
+    return Object.is(value, -0) ? "-0" : String(value);
+  }
+  return String(value);
+}
+
+export const undefinedValue = "void 0";
+
+export function call(callee: string, args: readonly string[]): string {
+  return `${callee}(${args.join(", ")})`;
+}
+
+// The body in parentheses, so one that is an object literal is not read as a
+// block.
+export function arrow(params: readonly string[], body: string): string {
+  return `(${params.join(", ")}) => (${body})`;
+}
+
+export function thunk(body: string): string {
+  return arrow([], body);
+}
+
+export function array(elements: readonly string[]): string {
+  return `[${elements.join(", ")}]`;
+}
+
+/** An object literal, each key bare where it can be and a string where not. */
+export function object(
+  entries: readonly (readonly [string, string])[],
+): string {
+  const members = entries.map(([key, value]) => `${member(key)}: ${value}`);
+  return `{ ${members.join(", ")} }`;
+}
+
+// A key as an object literal writes it. `__proto__`, bare or quoted, would set
+// the object's prototype instead, so a key a user may have chosen is computed,
+// which makes it the object's own.
+function member(key: string): string {
+  if (key === "__proto__") {
+    return `[${string(key)}]`;
+  }
+  return IDENTIFIER.test(key) ? key : string(key);
+}
+
+// The package a module is in: its specifier's first segment, or first two
+// when scoped (`solid-js/web` → `solid-js`, `@scope/pkg/x` → `@scope/pkg`).
+function packageOf(from: string): string {
+  const segments = from.split("/");
+  return segments.slice(0, from.startsWith("@") ? 2 : 1).join("/");
+}
+
+/** An export of a module the client provides, imported by the bundle. */
+export function imported(
+  names: Names,
+  { from, name, version }: ClientImport<unknown>,
+): string {
+  // Where a script's import is written: a plugin's own (a framework's compile
+  // step) are the plugin's, trusted as it is.
+  const pkg = packageOf(from);
+  const provided = names.packageVersions[pkg];
+  if (provided === undefined) {
+    const packages = Object.entries(names.packageVersions).map(
+      ([provided, at]) => `${provided}@${at}`,
+    );
+    throw new Error(
+      `Can't import \`${name}\` from "${from}": the client provides ` +
+        `${packages.join(", ") || "no packages"}.`,
+    );
+  }
+  if (!semver.satisfies(provided, version)) {
+    throw new Error(
+      `Can't import \`${name}\` from "${from}": it needs ${pkg}@${version}, ` +
+        `and the client provides ${pkg}@${provided}.`,
+    );
+  }
+  const key = `${from}\0${name}`;
+  let entry = names.imports.get(key);
+  if (entry === undefined) {
+    entry = { from, name, local: `$i${names.imports.size}` };
+    names.imports.set(key, entry);
+  }
+  return entry.local;
+}
+
+/** An import declaration of one export under its local name. */
+export function importDeclaration(
+  from: string,
+  name: string,
+  local: string,
+): string {
+  const exported = IDENTIFIER.test(name) ? name : string(name);
+  return `import { ${exported} as ${local} } from ${string(from)};`;
+}
+
+// The same import as CommonJS writes it: `const { name: local } = require(…);`.
+export function requireDeclaration(
+  from: string,
+  name: string,
+  local: string,
+): string {
+  const exported = IDENTIFIER.test(name) ? name : string(name);
+  return `const { ${exported}: ${local} } = require(${string(from)});`;
+}

package/src/print/printBundle.ts

@@ -0,0 +1,126 @@
+import type { BundleTree } from "../bundle/buildBundle.js";
+import type { ClientModule } from "@backtickjs/core";
+import { importDeclaration, requireDeclaration, string } from "./code.js";
+
+const MODULE_ID = "bundle.js";
+
+// A module table's `require`: a module's exports, its entry run the first time
+// it is asked for.
+const RUNTIME = `const $require = (id) => {
+  if (!(id in $exports)) {
+    const module = { exports: {} };
+    $exports[id] = module.exports;
+    $modules[id](module, module.exports, $require);
+    $exports[id] = module.exports;
+  }
+  return $exports[id];
+};`;
+
+/**
+ * A bundle tree as a module whose default export is the tree's root: the value
+ * bundled, as its scripts wrote it.
+ *
+ * The module is its imports, a module table of its scripts, each compiled for
+ * its framework when its host was built, and the root. Its imports are the
+ * client's to resolve. As an ES module (`"es"`), a page resolves them through
+ * an import map; as CommonJS (`"cjs"`), whatever runs it hands it `require`,
+ * as a React Native app does for the packages it was built with.
+ *
+ * Its map leads into the host files its scripts were written in: an index
+ * map, each script's own map a section where the script stands. What the
+ * bundler wrote around the scripts maps to nothing, since no source wrote it.
+ */
+export function printBundle(
+  tree: BundleTree,
+  format: "es" | "cjs",
+): { code: string; map: string } {
+  const { names } = tree;
+  const module = new ModuleWriter();
+  if (format === "cjs") {
+    // An ES module is strict code, and so are the scripts; CommonJS isn't.
+    module.line('"use strict";');
+  }
+  const declaration = format === "es" ? importDeclaration : requireDeclaration;
+  for (const { from, name, local } of names.imports.values()) {
+    module.line(declaration(from, name, local));
+  }
+  // Each script a module table's entry, as webpack's and Metro's are: its body
+  // under its id, run once by `$require`. The modules they require are the
+  // client's, each imported whole, once.
+  const modules = new Map(tree.modules.map(([, entry]) => [entry.id, entry]));
+  const dependencies = [
+    ...new Set([...modules.values()].flatMap((entry) => entry.dependencies)),
+  ];
+  dependencies.forEach((specifier, index) =>
+    module.line(
+      format === "es"
+        ? `import * as $module${index} from ${string(specifier)};`
+        : `const $module${index} = require(${string(specifier)});`,
+    ),
+  );
+  module.line("const $modules = {");
+  for (const [id, entry] of modules) {
+    module.write(`${string(id)}: `);
+    module.script(entry);
+    module.line(",");
+  }
+  module.line("};");
+  module.line("const $exports = {");
+  dependencies.forEach((specifier, index) =>
+    module.line(`${string(specifier)}: $module${index},`),
+  );
+  module.line("};");
+  module.line(RUNTIME);
+  for (const [label, entry] of tree.modules) {
+    module.line(`const ${label} = $require(${string(entry.id)}).default;`);
+  }
+  // Parenthesized, so a root that is a function isn't a declaration.
+  module.write(
+    format === "es"
+      ? `export default (${tree.root});`
+      : `module.exports = (${tree.root});`,
+  );
+
+  return { code: module.code, map: module.map() };
+}
+
+// The module's code as it is written, and a map of the scripts in it.
+class ModuleWriter {
+  code = "";
+  #line = 0;
+  #column = 0;
+  #sections: { offset: { line: number; column: number }; map: object }[] = [];
+
+  write(text: string): void {
+    this.code += text;
+    const lines = text.split("\n");
+    if (lines.length > 1) {
+      this.#line += lines.length - 1;
+      this.#column = lines[lines.length - 1]!.length;
+    } else {
+      this.#column += text.length;
+    }
+  }
+
+  line(text: string): void {
+    this.write(`${text}\n`);
+  }
+
+  // A script's code, its map a section of the module's where it starts.
+  script({ code, map }: ClientModule): void {
+    this.#sections.push({
+      offset: { line: this.#line, column: this.#column },
+      map: JSON.parse(map) as object,
+    });
+    this.write(code);
+  }
+
+  // An index map: each script's own map, at its offset, decoded by no one here.
+  map(): string {
+    return JSON.stringify({
+      version: 3,
+      file: MODULE_ID,
+      sections: this.#sections,
+    });
+  }
+}