solid-tag-runtime 0.0.1

package/src/runtime.js

@@ -0,0 +1,591 @@
+import {
+  CircularDependencyError,
+  ModuleCompileError,
+  ModuleResolutionError,
+  SolidTagRuntimeError,
+} from "./errors.js";
+import { createDefaultModuleUrlBackend } from "./url-backend.js";
+
+const HOST_REGISTRY_KEY = "__solidTagRuntimeHostModules__";
+let runtimeSequence = 0;
+
+export function createRuntime(options = {}) {
+  const {
+    compiler,
+    modules = {},
+    urls = {},
+    allowNativeImports = true,
+    resolve: customResolve,
+    moduleUrlBackend = createDefaultModuleUrlBackend(),
+  } = options;
+
+  if (!compiler || typeof compiler.analyze !== "function" || typeof compiler.transform !== "function") {
+    throw new TypeError("createRuntime() requires a compiler with analyze() and transform() methods.");
+  }
+
+  const runtimeId = `solid-tag-runtime-${++runtimeSequence}-${randomId()}`;
+  const records = new Map();
+  let anonymousSequence = 0;
+  let disposed = false;
+
+  const globalRegistry = getHostRegistry();
+  const hostNamespaces = new Map();
+  globalRegistry.set(runtimeId, hostNamespaces);
+
+  const api = {
+    define,
+    defineModule,
+    defineUrl,
+    update,
+    import: importModule,
+    compile,
+    toModule,
+    toComponent,
+    has,
+    invalidate,
+    modules: listModules,
+    dependencies,
+    dependents,
+    getModuleInfo,
+    dispose,
+    resolve: resolvePublic,
+  };
+
+  for (const [id, namespace] of Object.entries(modules)) defineModule(id, namespace);
+  for (const [id, url] of Object.entries(urls)) defineUrl(id, url);
+
+  return api;
+
+  function assertActive() {
+    if (disposed) throw new SolidTagRuntimeError("This solid-tag-runtime instance has been disposed.");
+  }
+
+  function define(id, source, defineOptions = {}) {
+    assertActive();
+    const normalized = normalizeDefinedId(id);
+    const existing = records.get(normalized);
+
+    if (existing) invalidate(normalized, { dependents: true });
+
+    const record = {
+      id: normalized,
+      kind: "source",
+      source: String(source),
+      format: defineOptions.format ?? "jsx",
+      version: (existing?.version ?? 0) + 1,
+      state: "defined",
+      dependencies: new Set(),
+      dependents: existing?.dependents ?? new Set(),
+      compiledCode: undefined,
+      diagnostics: [],
+      url: undefined,
+      importPromise: undefined,
+      namespace: undefined,
+    };
+
+    records.set(normalized, record);
+    return normalized;
+  }
+
+  function update(id, source, updateOptions = {}) {
+    return define(id, source, updateOptions);
+  }
+
+  function defineModule(id, namespace) {
+    assertActive();
+    const normalized = normalizeDefinedId(id);
+    const existing = records.get(normalized);
+    if (existing) invalidate(normalized, { dependents: true });
+
+    if ((typeof namespace !== "object" || namespace === null) && typeof namespace !== "function") {
+      throw new TypeError("defineModule(id, namespace) expects an object, function, or ES module namespace-like value.");
+    }
+
+    hostNamespaces.set(normalized, namespace);
+
+    records.set(normalized, {
+      id: normalized,
+      kind: "host",
+      namespace,
+      version: (existing?.version ?? 0) + 1,
+      state: "ready",
+      dependencies: new Set(),
+      dependents: existing?.dependents ?? new Set(),
+      url: undefined,
+    });
+
+    return normalized;
+  }
+
+  function defineUrl(id, url) {
+    assertActive();
+    const normalized = normalizeDefinedId(id);
+    const existing = records.get(normalized);
+    if (existing) invalidate(normalized, { dependents: true });
+
+    const href = String(url);
+    records.set(normalized, {
+      id: normalized,
+      kind: "url",
+      externalUrl: href,
+      version: (existing?.version ?? 0) + 1,
+      state: "defined",
+      dependencies: new Set(),
+      dependents: existing?.dependents ?? new Set(),
+      importPromise: undefined,
+      namespace: undefined,
+    });
+
+    return normalized;
+  }
+
+  async function importModule(id) {
+    assertActive();
+    const resolved = resolveSpecifier(String(id), null);
+    const record = records.get(resolved);
+
+    if (!record) {
+      if (!allowNativeImports && !isAbsoluteUrl(resolved)) {
+        throw new ModuleResolutionError(id, null);
+      }
+      return import(resolved);
+    }
+
+    if (record.kind === "host") return record.namespace;
+
+    if (record.kind === "url") {
+      if (!record.importPromise) {
+        record.importPromise = import(record.externalUrl).then(namespace => {
+          record.namespace = namespace;
+          record.state = "ready";
+          return namespace;
+        });
+      }
+      return record.importPromise;
+    }
+
+    if (!record.importPromise) {
+      record.importPromise = ensureSourceUrl(record, []).then(url => import(url)).then(namespace => {
+        record.namespace = namespace;
+        record.state = "ready";
+        return namespace;
+      }).catch(error => {
+        record.importPromise = undefined;
+        record.state = "error";
+        throw error;
+      });
+    }
+
+    return record.importPromise;
+  }
+
+  async function compile(id) {
+    assertActive();
+    const resolved = resolveSpecifier(String(id), null);
+    const record = records.get(resolved);
+    if (!record) throw new ModuleResolutionError(id, null);
+    if (record.kind !== "source") {
+      return {
+        id: record.id,
+        kind: record.kind,
+        code: undefined,
+        url: record.kind === "url" ? record.externalUrl : await ensureHostUrl(record),
+        dependencies: [...record.dependencies],
+        diagnostics: [],
+      };
+    }
+
+    const url = await ensureSourceUrl(record, []);
+    return {
+      id: record.id,
+      kind: record.kind,
+      code: record.compiledCode,
+      url,
+      dependencies: [...record.dependencies],
+      diagnostics: [...(record.diagnostics ?? [])],
+    };
+  }
+
+  async function toModule(source, moduleOptions = {}) {
+    assertActive();
+    const id = moduleOptions.id ?? `/__solid_tag_runtime__/anonymous-${++anonymousSequence}.jsx`;
+    const normalized = define(id, source, { format: moduleOptions.format ?? "jsx" });
+    return importModule(normalized);
+  }
+
+  async function toComponent(source, componentOptions = {}) {
+    const namespace = await toModule(source, componentOptions);
+    const exportName = componentOptions.exportName ?? "default";
+
+    if (!(exportName in namespace)) {
+      throw new SolidTagRuntimeError(
+        `Module does not export ${JSON.stringify(exportName)}. Available exports: ${Object.keys(namespace).join(", ") || "(none)"}.`
+      );
+    }
+
+    const component = namespace[exportName];
+    if (typeof component !== "function") {
+      throw new SolidTagRuntimeError(
+        `Export ${JSON.stringify(exportName)} is not callable and cannot be used as a Solid component.`
+      );
+    }
+
+    return component;
+  }
+
+  function has(id) {
+    return records.has(normalizeLookupId(id));
+  }
+
+  function invalidate(id, invalidateOptions = {}) {
+    assertActive();
+    const normalized = normalizeLookupId(id);
+    const includeDependents = invalidateOptions.dependents ?? true;
+    const seen = new Set();
+
+    invalidateOne(normalized);
+    return [...seen];
+
+    function invalidateOne(targetId) {
+      if (seen.has(targetId)) return;
+      seen.add(targetId);
+      const record = records.get(targetId);
+      if (!record) return;
+
+      if (includeDependents) {
+        for (const dependent of record.dependents) invalidateOne(dependent);
+      }
+
+      if (record.kind === "source") {
+        revokeRecordUrl(record);
+        record.compiledCode = undefined;
+        record.diagnostics = [];
+        record.importPromise = undefined;
+        record.namespace = undefined;
+        record.state = "defined";
+      } else if (record.kind === "host") {
+        revokeRecordUrl(record);
+        record.state = "ready";
+      } else if (record.kind === "url") {
+        record.importPromise = undefined;
+        record.namespace = undefined;
+        record.state = "defined";
+      }
+    }
+  }
+
+  function listModules() {
+    return [...records.values()].map(toModuleInfo);
+  }
+
+  function dependencies(id) {
+    const record = records.get(normalizeLookupId(id));
+    return record ? [...record.dependencies] : [];
+  }
+
+  function dependents(id) {
+    const record = records.get(normalizeLookupId(id));
+    return record ? [...record.dependents] : [];
+  }
+
+  function getModuleInfo(id) {
+    const record = records.get(normalizeLookupId(id));
+    return record ? toModuleInfo(record) : undefined;
+  }
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+
+    for (const record of records.values()) revokeRecordUrl(record);
+    records.clear();
+    hostNamespaces.clear();
+    globalRegistry.delete(runtimeId);
+  }
+
+  function resolvePublic(specifier, importer) {
+    return resolveSpecifier(specifier, importer ?? null);
+  }
+
+  async function ensureSourceUrl(record, stack) {
+    if (record.url) return record.url;
+
+    if (stack.includes(record.id)) {
+      const cycleStart = stack.indexOf(record.id);
+      throw new CircularDependencyError([...stack.slice(cycleStart), record.id]);
+    }
+
+    const nextStack = [...stack, record.id];
+    record.state = "linking";
+
+    let analysis;
+    try {
+      analysis = compiler.analyze(record.source, { id: record.id, format: record.format });
+    } catch (error) {
+      record.state = "error";
+      throw new ModuleCompileError(record.id, error);
+    }
+
+    const resolvedImports = [];
+    const nextDependencies = new Set();
+
+    for (const reference of analysis.imports ?? []) {
+      const resolved = resolveSpecifier(reference.specifier, record.id);
+      const dependencyRecord = records.get(resolved);
+      let replacement = resolved;
+
+      if (dependencyRecord) {
+        nextDependencies.add(dependencyRecord.id);
+
+        if (dependencyRecord.kind === "source") {
+          replacement = await ensureSourceUrl(dependencyRecord, nextStack);
+        } else if (dependencyRecord.kind === "host") {
+          replacement = await ensureHostUrl(dependencyRecord);
+        } else {
+          replacement = dependencyRecord.externalUrl;
+        }
+      } else if (isRelativeSpecifier(reference.specifier) || reference.specifier.startsWith("/")) {
+        throw new ModuleResolutionError(reference.specifier, record.id);
+      } else if (!allowNativeImports && !isAbsoluteUrl(resolved)) {
+        throw new ModuleResolutionError(reference.specifier, record.id);
+      }
+
+      resolvedImports.push({ ...reference, replacement });
+    }
+
+    let linkedSource = applyImportReplacements(record.source, resolvedImports);
+
+    // JSX produced by solid-tag needs @solidjs/html. Resolve it through the
+    // same module system so host applications can share their existing runtime.
+    let htmlImportSource;
+    const needsHtmlRuntime = record.format !== "js" && analysis.needsHtmlRuntime !== false;
+    if (needsHtmlRuntime) {
+      const htmlResolved = resolveSpecifier("@solidjs/html", record.id);
+      const htmlRecord = records.get(htmlResolved);
+
+      if (htmlRecord) {
+        nextDependencies.add(htmlRecord.id);
+        htmlImportSource = htmlRecord.kind === "source"
+          ? await ensureSourceUrl(htmlRecord, nextStack)
+          : htmlRecord.kind === "host"
+            ? await ensureHostUrl(htmlRecord)
+            : htmlRecord.externalUrl;
+      } else if (allowNativeImports) {
+        htmlImportSource = htmlResolved;
+      } else {
+        throw new ModuleResolutionError("@solidjs/html", record.id);
+      }
+    }
+
+    syncDependencyEdges(record, nextDependencies);
+
+    try {
+      if (record.format === "js") {
+        record.compiledCode = linkedSource;
+        record.diagnostics = [];
+      } else {
+        const transformed = compiler.transform(linkedSource, {
+          id: record.id,
+          format: record.format,
+          htmlImportSource,
+        });
+        record.compiledCode = transformed.code;
+        record.diagnostics = [...(transformed.diagnostics ?? [])];
+      }
+    } catch (error) {
+      record.state = "error";
+      throw new ModuleCompileError(record.id, error);
+    }
+
+    record.url = moduleUrlBackend.create(appendSourceUrl(record.compiledCode, record.id));
+    record.state = "compiled";
+    return record.url;
+  }
+
+  async function ensureHostUrl(record) {
+    if (record.url) return record.url;
+
+    const namespace = hostNamespaces.get(record.id);
+    const exportNames = Object.keys(namespace ?? {}).filter(name => name !== "default" && isIdentifierName(name));
+    const lines = [
+      `const __registry = globalThis[${JSON.stringify(HOST_REGISTRY_KEY)}];`,
+      `const __runtime = __registry && __registry.get(${JSON.stringify(runtimeId)});`,
+      `const __module = __runtime && __runtime.get(${JSON.stringify(record.id)});`,
+      `if (!__module) throw new Error(${JSON.stringify(`Host module ${record.id} is unavailable.`)});`,
+    ];
+
+    exportNames.forEach((name, index) => {
+      lines.push(`const __export${index} = __module[${JSON.stringify(name)}];`);
+    });
+
+    if (namespace && Object.prototype.hasOwnProperty.call(namespace, "default")) {
+      lines.push("export default __module.default;");
+    }
+
+    if (exportNames.length) {
+      lines.push(
+        `export { ${exportNames.map((name, index) => `__export${index} as ${name}`).join(", ")} };`
+      );
+    }
+
+    record.url = moduleUrlBackend.create(appendSourceUrl(lines.join("\n"), `host:${record.id}`));
+    return record.url;
+  }
+
+  function resolveSpecifier(specifier, importer) {
+    const raw = String(specifier);
+
+    if (typeof customResolve === "function") {
+      const custom = customResolve(raw, importer, api);
+      if (typeof custom === "string" && custom) return normalizeResolved(custom, importer);
+    }
+
+    if (records.has(raw)) return raw;
+    if (isAbsoluteUrl(raw)) return raw;
+
+    if (raw.startsWith("/")) return normalizePath(raw);
+
+    if (isRelativeSpecifier(raw)) {
+      if (!importer) return normalizePath(`/${raw}`);
+      if (isAbsoluteUrl(importer)) return new URL(raw, importer).href;
+      return normalizePath(`${dirname(importer)}/${raw}`);
+    }
+
+    return raw;
+  }
+
+  function syncDependencyEdges(record, nextDependencies) {
+    for (const previous of record.dependencies) {
+      if (!nextDependencies.has(previous)) records.get(previous)?.dependents.delete(record.id);
+    }
+
+    for (const next of nextDependencies) records.get(next)?.dependents.add(record.id);
+    record.dependencies = nextDependencies;
+  }
+
+  function revokeRecordUrl(record) {
+    if (!record?.url) return;
+    try {
+      moduleUrlBackend.revoke?.(record.url);
+    } finally {
+      record.url = undefined;
+    }
+  }
+
+  function toModuleInfo(record) {
+    return {
+      id: record.id,
+      kind: record.kind,
+      state: record.state,
+      version: record.version,
+      format: record.format,
+      dependencies: [...record.dependencies],
+      dependents: [...record.dependents],
+      url: record.kind === "url" ? record.externalUrl : record.url,
+      diagnostics: [...(record.diagnostics ?? [])],
+    };
+  }
+}
+
+function getHostRegistry() {
+  let registry = globalThis[HOST_REGISTRY_KEY];
+  if (!(registry instanceof Map)) {
+    registry = new Map();
+    Object.defineProperty(globalThis, HOST_REGISTRY_KEY, {
+      value: registry,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return registry;
+}
+
+function applyImportReplacements(source, references) {
+  const replacements = references
+    .map(reference => ({
+      start: reference.start,
+      end: reference.end,
+      text: JSON.stringify(reference.replacement),
+    }))
+    .sort((a, b) => b.start - a.start);
+
+  let output = source;
+  for (const replacement of replacements) {
+    output = output.slice(0, replacement.start) + replacement.text + output.slice(replacement.end);
+  }
+  return output;
+}
+
+function normalizeDefinedId(id) {
+  const value = String(id);
+  if (isAbsoluteUrl(value) || isBareSpecifier(value)) return value;
+  if (value.startsWith("/")) return normalizePath(value);
+  return normalizePath(`/${value}`);
+}
+
+function normalizeLookupId(id) {
+  const value = String(id);
+  if (isAbsoluteUrl(value) || isBareSpecifier(value)) return value;
+  if (value.startsWith("/")) return normalizePath(value);
+  return normalizePath(`/${value}`);
+}
+
+function normalizeResolved(value, importer) {
+  if (isAbsoluteUrl(value) || isBareSpecifier(value)) return value;
+  if (value.startsWith("/")) return normalizePath(value);
+  if (isRelativeSpecifier(value) && importer) {
+    if (isAbsoluteUrl(importer)) return new URL(value, importer).href;
+    return normalizePath(`${dirname(importer)}/${value}`);
+  }
+  return normalizePath(`/${value}`);
+}
+
+function isBareSpecifier(value) {
+  return !value.startsWith(".") && !value.startsWith("/") && !isAbsoluteUrl(value);
+}
+
+function isRelativeSpecifier(value) {
+  return value === "." || value === ".." || value.startsWith("./") || value.startsWith("../");
+}
+
+function isAbsoluteUrl(value) {
+  return /^[A-Za-z][A-Za-z\d+.-]*:/.test(value);
+}
+
+function dirname(id) {
+  const index = id.lastIndexOf("/");
+  return index <= 0 ? "/" : id.slice(0, index);
+}
+
+function normalizePath(path) {
+  const absolute = path.startsWith("/");
+  const parts = [];
+
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      parts.pop();
+    } else {
+      parts.push(part);
+    }
+  }
+
+  return `${absolute ? "/" : ""}${parts.join("/")}` || "/";
+}
+
+function isIdentifierName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+
+function appendSourceUrl(code, id) {
+  return `${code}\n//# sourceURL=${sanitizeSourceUrl(id)}`;
+}
+
+function sanitizeSourceUrl(id) {
+  return `solid-tag-runtime:${String(id).replace(/[\r\n]/g, "")}`;
+}
+
+function randomId() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  return Math.random().toString(36).slice(2);
+}

package/src/url-backend.js

@@ -0,0 +1,33 @@
+function isNodeLike() {
+  return typeof process !== "undefined" && !!process.versions?.node;
+}
+
+export function createDefaultModuleUrlBackend() {
+  if (!isNodeLike() && typeof Blob !== "undefined" && typeof URL?.createObjectURL === "function") {
+    return createBlobModuleUrlBackend();
+  }
+
+  return createDataModuleUrlBackend();
+}
+
+export function createBlobModuleUrlBackend() {
+  return {
+    kind: "blob",
+    create(code) {
+      return URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
+    },
+    revoke(url) {
+      URL.revokeObjectURL(url);
+    },
+  };
+}
+
+export function createDataModuleUrlBackend() {
+  return {
+    kind: "data",
+    create(code) {
+      return `data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`;
+    },
+    revoke() {},
+  };
+}