solid-tag-runtime 0.0.6 → 0.0.8

package/src/runtime.js

@@ -5,6 +5,7 @@ import {
   SolidTagRuntimeError,
 } from "./errors.js";
 import { createDefaultModuleUrlBackend } from "./url-backend.js";
+import { createEventDispatcher } from "./events.js";
 
 const HOST_REGISTRY_KEY = "__solidTagRuntimeHostModules__";
 let runtimeSequence = 0;
@@ -27,6 +28,13 @@ export function createRuntime(options = {}) {
   const records = new Map();
   let anonymousSequence = 0;
   let disposed = false;
+  const events = createEventDispatcher({
+    onListenerError(error) {
+      globalThis.console?.error?.("solid-tag-runtime lifecycle subscriber error", error);
+    },
+  });
+  let eventBufferDepth = 0;
+  const eventBuffer = [];
 
   const globalRegistry = getHostRegistry();
   const hostNamespaces = new Map();
@@ -34,6 +42,7 @@ export function createRuntime(options = {}) {
 
   const api = {
     define,
+    defineMany,
     defineModule,
     defineUrl,
     update,
@@ -43,6 +52,9 @@ export function createRuntime(options = {}) {
     toComponent,
     has,
     invalidate,
+    remove,
+    clear,
+    subscribe,
     modules: listModules,
     dependencies,
     dependents,
@@ -61,11 +73,63 @@ export function createRuntime(options = {}) {
   }
 
   function define(id, source, defineOptions = {}) {
+    return defineSource(id, source, defineOptions, "define");
+  }
+
+  function defineMany(definitions) {
+    assertActive();
+    if (!Array.isArray(definitions)) {
+      throw new TypeError("defineMany(definitions) expects an array of source module definitions.");
+    }
+
+    const prepared = definitions.map((definition, index) => {
+      if (!definition || typeof definition !== "object") {
+        throw new TypeError(`defineMany() item ${index} must be an object with id and source.`);
+      }
+      if (definition.id == null) {
+        throw new TypeError(`defineMany() item ${index} is missing id.`);
+      }
+      const id = normalizeDefinedId(definition.id);
+      return {
+        id,
+        source: String(definition.source ?? ""),
+        format: definition.format ?? "jsx",
+      };
+    });
+
+    const seen = new Set();
+    for (const item of prepared) {
+      if (seen.has(item.id)) {
+        throw new SolidTagRuntimeError(`defineMany() contains duplicate module id ${JSON.stringify(item.id)}.`);
+      }
+      seen.add(item.id);
+    }
+
+    eventBufferDepth += 1;
+    try {
+      const ids = prepared.map(item => defineSource(item.id, item.source, { format: item.format }, "defineMany"));
+      emit({
+        type: "modules-defined",
+        ids: [...ids],
+        modules: ids.map(id => toModuleInfo(records.get(id))),
+      });
+      return ids;
+    } finally {
+      eventBufferDepth -= 1;
+      if (eventBufferDepth === 0) flushEventBuffer();
+    }
+  }
+
+  function update(id, source, updateOptions = {}) {
+    return defineSource(id, source, updateOptions, "update");
+  }
+
+  function defineSource(id, source, defineOptions = {}, operation = "define") {
     assertActive();
     const normalized = normalizeDefinedId(id);
     const existing = records.get(normalized);
 
-    if (existing) invalidate(normalized, { dependents: true });
+    if (existing) invalidate(normalized, { dependents: true, reason: operation });
 
     const record = {
       id: normalized,
@@ -84,18 +148,34 @@ export function createRuntime(options = {}) {
     };
 
     records.set(normalized, record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation,
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
+    });
+    if (operation === "update") {
+      emit({
+        type: "module-updated",
+        id: normalized,
+        kind: record.kind,
+        previousVersion: existing?.version ?? 0,
+        version: record.version,
+        format: record.format,
+        module: toModuleInfo(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 (existing) invalidate(normalized, { dependents: true, reason: "defineModule" });
 
     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.");
@@ -103,7 +183,7 @@ export function createRuntime(options = {}) {
 
     hostNamespaces.set(normalized, namespace);
 
-    records.set(normalized, {
+    const record = {
       id: normalized,
       kind: "host",
       namespace,
@@ -112,6 +192,16 @@ export function createRuntime(options = {}) {
       dependencies: new Set(),
       dependents: existing?.dependents ?? new Set(),
       url: undefined,
+    };
+    records.set(normalized, record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation: "defineModule",
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
     });
 
     return normalized;
@@ -121,10 +211,10 @@ export function createRuntime(options = {}) {
     assertActive();
     const normalized = normalizeDefinedId(id);
     const existing = records.get(normalized);
-    if (existing) invalidate(normalized, { dependents: true });
+    if (existing) invalidate(normalized, { dependents: true, reason: "defineUrl" });
 
     const href = String(url);
-    records.set(normalized, {
+    const record = {
       id: normalized,
       kind: "url",
       externalUrl: href,
@@ -134,6 +224,16 @@ export function createRuntime(options = {}) {
       dependents: existing?.dependents ?? new Set(),
       importPromise: undefined,
       namespace: undefined,
+    };
+    records.set(normalized, record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation: "defineUrl",
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
     });
 
     return normalized;
@@ -155,23 +255,38 @@ export function createRuntime(options = {}) {
 
     if (record.kind === "url") {
       if (!record.importPromise) {
+        record.state = "evaluating";
+        emit({ type: "module-evaluating", id: record.id, kind: record.kind, version: record.version });
         record.importPromise = import(record.externalUrl).then(namespace => {
           record.namespace = namespace;
           record.state = "ready";
+          emit({ type: "module-evaluated", id: record.id, kind: record.kind, version: record.version, module: toModuleInfo(record) });
           return namespace;
+        }).catch(error => {
+          record.importPromise = undefined;
+          record.state = "error";
+          emitError(record, "evaluate", error);
+          throw error;
         });
       }
       return record.importPromise;
     }
 
     if (!record.importPromise) {
-      record.importPromise = ensureSourceUrl(record, []).then(url => import(url)).then(namespace => {
+      record.importPromise = ensureSourceUrl(record, []).then(url => {
+        record.state = "evaluating";
+        emit({ type: "module-evaluating", id: record.id, kind: record.kind, version: record.version });
+        return import(url);
+      }).then(namespace => {
         record.namespace = namespace;
         record.state = "ready";
+        emit({ type: "module-evaluated", id: record.id, kind: record.kind, version: record.version, module: toModuleInfo(record) });
         return namespace;
       }).catch(error => {
         record.importPromise = undefined;
+        const alreadyReported = record.state === "error";
         record.state = "error";
+        if (!alreadyReported) emitError(record, "evaluate", error);
         throw error;
       });
     }
@@ -241,6 +356,7 @@ export function createRuntime(options = {}) {
     assertActive();
     const normalized = normalizeLookupId(id);
     const includeDependents = invalidateOptions.dependents ?? true;
+    const reason = invalidateOptions.reason ?? "explicit";
     const seen = new Set();
 
     invalidateOne(normalized);
@@ -271,7 +387,67 @@ export function createRuntime(options = {}) {
         record.namespace = undefined;
         record.state = "defined";
       }
+
+      emit({
+        type: "module-invalidated",
+        id: record.id,
+        kind: record.kind,
+        version: record.version,
+        reason,
+      });
+    }
+  }
+
+  function remove(id, removeOptions = {}) {
+    assertActive();
+    const normalized = normalizeLookupId(id);
+    const record = records.get(normalized);
+    if (!record) return false;
+
+    if (removeOptions.invalidateDependents !== false) {
+      for (const dependent of [...record.dependents]) {
+        invalidate(dependent, { dependents: true, reason: `dependency-removed:${normalized}` });
+      }
     }
+
+    for (const dependency of record.dependencies) {
+      records.get(dependency)?.dependents.delete(normalized);
+    }
+
+    revokeRecordUrl(record);
+    if (record.kind === "host") hostNamespaces.delete(normalized);
+    records.delete(normalized);
+
+    emit({
+      type: "module-removed",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      invalidateDependents: removeOptions.invalidateDependents !== false,
+    });
+    return true;
+  }
+
+  function clear(clearOptions = {}) {
+    assertActive();
+    const preserveHostModules = clearOptions.preserveHostModules !== false;
+    const ids = [...records.values()]
+      .filter(record => !(preserveHostModules && record.kind === "host"))
+      .map(record => record.id);
+
+    for (const id of ids) remove(id, { invalidateDependents: false });
+
+    emit({
+      type: "runtime-cleared",
+      ids: [...ids],
+      preserveHostModules,
+    });
+    return ids;
+  }
+
+  function subscribe(typesOrListener, maybeListener) {
+    assertActive();
+    return events.subscribe(typesOrListener, maybeListener);
   }
 
   function listModules() {
@@ -296,11 +472,13 @@ export function createRuntime(options = {}) {
   function dispose() {
     if (disposed) return;
     disposed = true;
+    emit({ type: "runtime-disposed" });
 
     for (const record of records.values()) revokeRecordUrl(record);
     records.clear();
     hostNamespaces.clear();
     globalRegistry.delete(runtimeId);
+    events.clear();
   }
 
   function resolvePublic(specifier, importer) {
@@ -312,93 +490,159 @@ export function createRuntime(options = {}) {
 
     if (stack.includes(record.id)) {
       const cycleStart = stack.indexOf(record.id);
-      throw new CircularDependencyError([...stack.slice(cycleStart), record.id]);
+      const error = new CircularDependencyError([...stack.slice(cycleStart), record.id]);
+      emitError(record, "link", error);
+      throw error;
     }
 
     const nextStack = [...stack, record.id];
     record.state = "linking";
+    emit({
+      type: "module-linking",
+      id: record.id,
+      kind: record.kind,
+      version: record.version,
+    });
 
     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 wrapped = new ModuleCompileError(record.id, error);
+      emitError(record, "analyze", wrapped);
+      throw wrapped;
     }
 
     const resolvedImports = [];
+    const linkedDependencies = [];
     const nextDependencies = new Set();
 
     for (const reference of analysis.imports ?? []) {
-      const resolved = resolveSpecifier(reference.specifier, record.id);
+      let resolved;
+      try {
+        resolved = resolveSpecifier(reference.specifier, record.id);
+      } catch (error) {
+        record.state = "error";
+        emitError(record, "resolve", error);
+        throw error;
+      }
+
       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;
+      try {
+        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);
         }
-      } 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);
+      } catch (error) {
+        record.state = "error";
+        emitError(record, error instanceof ModuleResolutionError ? "resolve" : "link", error);
+        throw error;
       }
 
       resolvedImports.push({ ...reference, replacement });
+      linkedDependencies.push({
+        specifier: reference.specifier,
+        resolvedId: dependencyRecord?.id ?? resolved,
+      });
     }
 
-    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);
+    let linkedSource;
+    try {
+      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);
+        }
+
+        linkedDependencies.push({
+          specifier: "@solidjs/html",
+          resolvedId: htmlRecord?.id ?? htmlResolved,
+        });
       }
-    }
 
-    syncDependencyEdges(record, nextDependencies);
+      syncDependencyEdges(record, nextDependencies);
+      emit({
+        type: "module-linked",
+        id: record.id,
+        kind: record.kind,
+        version: record.version,
+        dependencies: linkedDependencies,
+        module: toModuleInfo(record),
+      });
 
-    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 ?? [])];
+      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";
+        const wrapped = new ModuleCompileError(record.id, error);
+        emitError(record, "compile", wrapped);
+        throw wrapped;
       }
     } catch (error) {
-      record.state = "error";
-      throw new ModuleCompileError(record.id, error);
+      if (record.state !== "error") {
+        record.state = "error";
+        emitError(record, error instanceof ModuleResolutionError ? "resolve" : "link", error);
+      }
+      throw error;
     }
 
-    record.url = moduleUrlBackend.create(appendSourceUrl(record.compiledCode, record.id));
+    try {
+      record.url = moduleUrlBackend.create(appendSourceUrl(record.compiledCode, record.id));
+    } catch (error) {
+      record.state = "error";
+      emitError(record, "url-create", error);
+      throw error;
+    }
     record.state = "compiled";
+    emit({
+      type: "module-compiled",
+      id: record.id,
+      kind: record.kind,
+      version: record.version,
+      module: toModuleInfo(record),
+    });
     return record.url;
   }
 
@@ -428,30 +672,69 @@ export function createRuntime(options = {}) {
       );
     }
 
-    record.url = moduleUrlBackend.create(appendSourceUrl(lines.join("\n"), `host:${record.id}`));
+    try {
+      record.url = moduleUrlBackend.create(appendSourceUrl(lines.join("\n"), `host:${record.id}`));
+    } catch (error) {
+      emitError(record, "host-bridge", error);
+      throw error;
+    }
     return record.url;
   }
 
   function resolveSpecifier(specifier, importer) {
     const raw = String(specifier);
+    emit({
+      type: "module-resolving",
+      specifier: raw,
+      importer: importer ?? null,
+    });
 
-    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;
+    let resolved;
+    let resolutionKind;
 
-    if (raw.startsWith("/")) return normalizePath(raw);
+    try {
+      if (typeof customResolve === "function") {
+        const custom = customResolve(raw, importer, api);
+        if (typeof custom === "string" && custom) {
+          resolved = normalizeResolved(custom, importer);
+          resolutionKind = "custom";
+        }
+      }
 
-    if (isRelativeSpecifier(raw)) {
-      if (!importer) return normalizePath(`/${raw}`);
-      if (isAbsoluteUrl(importer)) return new URL(raw, importer).href;
-      return normalizePath(`${dirname(importer)}/${raw}`);
+      if (resolved == null && records.has(raw)) {
+        resolved = raw;
+        resolutionKind = "registered";
+      }
+      if (resolved == null && isAbsoluteUrl(raw)) {
+        resolved = raw;
+        resolutionKind = "url";
+      }
+      if (resolved == null && raw.startsWith("/")) {
+        resolved = normalizePath(raw);
+        resolutionKind = "absolute";
+      }
+      if (resolved == null && isRelativeSpecifier(raw)) {
+        if (!importer) resolved = normalizePath(`/${raw}`);
+        else if (isAbsoluteUrl(importer)) resolved = new URL(raw, importer).href;
+        else resolved = normalizePath(`${dirname(importer)}/${raw}`);
+        resolutionKind = "relative";
+      }
+      if (resolved == null) {
+        resolved = raw;
+        resolutionKind = "native";
+      }
+    } catch (error) {
+      throw error;
     }
 
-    return raw;
+    emit({
+      type: "module-resolved",
+      specifier: raw,
+      importer: importer ?? null,
+      resolvedId: resolved,
+      resolutionKind,
+    });
+    return resolved;
   }
 
   function syncDependencyEdges(record, nextDependencies) {
@@ -472,6 +755,37 @@ export function createRuntime(options = {}) {
     }
   }
 
+  function emit(event) {
+    if (events.size === 0) return;
+    const payload = {
+      runtimeId,
+      timestamp: Date.now(),
+      ...event,
+    };
+    if (eventBufferDepth > 0) {
+      eventBuffer.push(payload);
+      return;
+    }
+    events.emit(payload);
+  }
+
+  function flushEventBuffer() {
+    if (eventBuffer.length === 0) return;
+    const pending = eventBuffer.splice(0, eventBuffer.length);
+    for (const event of pending) events.emit(event);
+  }
+
+  function emitError(record, phase, error) {
+    emit({
+      type: "module-error",
+      id: record?.id,
+      kind: record?.kind,
+      version: record?.version,
+      phase,
+      error,
+    });
+  }
+
   function toModuleInfo(record) {
     return {
       id: record.id,