@omriashke/dynamico-core 0.1.0

package/src/react/createRuntime.tsx

@@ -0,0 +1,189 @@
+import * as React from "react";
+import { Registry } from "../registry.js";
+import type {
+  ComponentFactory,
+  DynamicError,
+  PropsSchema,
+  RegistryEntry,
+  Scope,
+  Source,
+} from "../types.js";
+import { validateProps } from "../propsSchema.js";
+
+export interface RuntimeAPI {
+  DynamicoProvider: React.ComponentType<DynamicoProviderProps>;
+  DynamicComponent: React.ComponentType<DynamicComponentProps>;
+  useDynamico: (name: string) => RegistryEntry | undefined;
+}
+
+export interface DynamicoProviderProps {
+  source: Source;
+  scope?: Scope;
+  children?: React.ReactNode;
+}
+
+export interface DynamicComponentProps {
+  name: string;
+  props?: Record<string, unknown>;
+  fallback?: React.ReactNode;
+  errorFallback?: React.ComponentType<{ error: DynamicError }> | React.ReactNode;
+}
+
+interface RuntimeContextValue {
+  registry: Registry;
+}
+
+export function createRuntime(defaultScope: Scope): RuntimeAPI {
+  const Ctx = React.createContext<RuntimeContextValue | null>(null);
+
+  function DynamicoProvider({ source, scope, children }: DynamicoProviderProps) {
+    const registry = React.useMemo(() => {
+      const merged: Scope = { ...defaultScope, ...(scope ?? {}) };
+      return new Registry(source, merged);
+    }, [source, scope]);
+
+    const value = React.useMemo<RuntimeContextValue>(() => ({ registry }), [registry]);
+    return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+  }
+
+  function useRegistry(): Registry {
+    const ctx = React.useContext(Ctx);
+    if (!ctx) {
+      throw new Error("dynamico: useDynamico/DynamicComponent must be inside <DynamicoProvider>");
+    }
+    return ctx.registry;
+  }
+
+  function useDynamico(name: string): RegistryEntry | undefined {
+    const registry = useRegistry();
+    const subscribe = React.useCallback(
+      (cb: () => void) => registry.subscribe(name, cb),
+      [registry, name],
+    );
+    const getSnapshot = React.useCallback(() => registry.peek(name), [registry, name]);
+    const entry = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+    React.useEffect(() => {
+      if (!registry.peek(name)) void registry.ensure(name);
+    }, [registry, name]);
+
+    return entry;
+  }
+
+  function DynamicComponent({
+    name,
+    props,
+    fallback = null,
+    errorFallback,
+  }: DynamicComponentProps): React.ReactElement | null {
+    const entry = useDynamico(name);
+
+    if (!entry) return <>{fallback}</>;
+
+    if (entry.error) {
+      return <>{renderError(errorFallback, entry.error)}</>;
+    }
+
+    if (!entry.factory) return <>{fallback}</>;
+
+    const Comp = pickDefault(entry.factory);
+    if (typeof Comp !== "function") {
+      const err: DynamicError = {
+        kind: "load",
+        name,
+        version: entry.version,
+        message: `component '${name}' has no default export of a function/class`,
+      };
+      return <>{renderError(errorFallback, err)}</>;
+    }
+
+    const schema = entry.factory.propsSchema as PropsSchema | undefined;
+    const validation = validateProps(schema, props ?? {});
+    if (!validation.ok) {
+      const err: DynamicError = {
+        kind: "render",
+        name,
+        version: entry.version,
+        message: `props validation failed: ${validation.errors.join("; ")}`,
+      };
+      return <>{renderError(errorFallback, err)}</>;
+    }
+
+    return (
+      <ErrorBoundary
+        key={`${name}@${entry.version}`}
+        onError={(message, stack) => ({
+          kind: "render",
+          name,
+          version: entry.version,
+          message,
+          stack,
+        })}
+        renderFallback={(err) => renderError(errorFallback, err)}
+      >
+        {React.createElement(Comp as React.ComponentType<Record<string, unknown>>, props ?? {})}
+      </ErrorBoundary>
+    );
+  }
+
+  return { DynamicoProvider, DynamicComponent, useDynamico };
+}
+
+function pickDefault(factory: ComponentFactory): unknown {
+  if (factory && typeof factory === "object") {
+    if ("default" in factory && factory.default) return factory.default;
+    // CommonJS interop: the value itself may be the component
+    if (typeof factory === "function") return factory;
+  }
+  if (typeof factory === "function") return factory;
+  return undefined;
+}
+
+function renderError(
+  errorFallback: DynamicComponentProps["errorFallback"],
+  error: DynamicError,
+): React.ReactNode {
+  if (!errorFallback) return defaultErrorView(error);
+  if (typeof errorFallback === "function") {
+    const Fallback = errorFallback as React.ComponentType<{ error: DynamicError }>;
+    return <Fallback error={error} />;
+  }
+  return errorFallback;
+}
+
+function defaultErrorView(error: DynamicError): React.ReactElement {
+  // Renderer-agnostic: plain text node so it works on both DOM and RN.
+  return React.createElement(
+    React.Fragment,
+    null,
+    `[dynamico ${error.kind} error] ${error.name}: ${error.message}`,
+  );
+}
+
+interface ErrorBoundaryProps {
+  onError: (message: string, stack: string | undefined) => DynamicError;
+  renderFallback: (err: DynamicError) => React.ReactNode;
+  children: React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+  err: DynamicError | null;
+}
+
+class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { err: null };
+
+  static getDerivedStateFromError(): ErrorBoundaryState | null {
+    return null; // we set state in componentDidCatch where we have the message
+  }
+
+  componentDidCatch(error: unknown): void {
+    const e = error instanceof Error ? error : new Error(String(error));
+    this.setState({ err: this.props.onError(e.message, e.stack) });
+  }
+
+  render(): React.ReactNode {
+    if (this.state.err) return this.props.renderFallback(this.state.err);
+    return this.props.children;
+  }
+}

package/src/registry.ts

@@ -0,0 +1,240 @@
+import type {
+  ComponentFactory,
+  DynamicError,
+  RegistryEntry,
+  RegistryListener,
+  Scope,
+  Source,
+  Version,
+} from "./types.js";
+import { loadModule } from "./loader.js";
+
+/**
+ * In-memory, versioned registry of dynamic components.
+ *
+ * The registry is the single source of truth that runtime packages
+ * (@omriashke/dynamico-web, @omriashke/dynamico-native) subscribe to. It receives compiled
+ * modules from a Source, evaluates them via the loader using a host-provided
+ * Scope, and notifies subscribers when a component's version changes.
+ */
+export class Registry {
+  private entries = new Map<string, RegistryEntry>();
+  private listeners = new Map<string, Set<RegistryListener>>();
+  private anyListeners = new Set<RegistryListener>();
+  private inflight = new Map<string, Promise<RegistryEntry>>();
+
+  constructor(
+    private readonly source: Source,
+    private scope: Scope,
+  ) {
+    this.source.subscribe(({ module }) => {
+      this.ingest(module.name, module);
+    });
+  }
+
+  /** Replace or extend the current scope (rare; typically set once). */
+  setScope(scope: Scope): void {
+    this.scope = scope;
+  }
+
+  /** Get the current entry for a name, if any. */
+  peek(name: string): RegistryEntry | undefined {
+    return this.entries.get(name);
+  }
+
+  /**
+   * Ensure a component is loaded. Triggers an initial fetch if we don't yet
+   * have an entry for this name. Returns the latest known entry.
+   */
+  async ensure(name: string): Promise<RegistryEntry> {
+    const existing = this.entries.get(name);
+    if (existing) return existing;
+    const pending = this.inflight.get(name);
+    if (pending) return pending;
+    const p = this.source
+      .fetch(name)
+      .then((module) => this.ingest(name, module))
+      .finally(() => {
+        this.inflight.delete(name);
+      });
+    this.inflight.set(name, p);
+    return p;
+  }
+
+  /** Subscribe to changes for a specific component. */
+  subscribe(name: string, listener: RegistryListener): () => void {
+    let set = this.listeners.get(name);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(name, set);
+    }
+    set.add(listener);
+    return () => {
+      set!.delete(listener);
+      if (set!.size === 0) this.listeners.delete(name);
+    };
+  }
+
+  /** Subscribe to all changes (used internally / for debugging). */
+  subscribeAll(listener: RegistryListener): () => void {
+    this.anyListeners.add(listener);
+    return () => {
+      this.anyListeners.delete(listener);
+    };
+  }
+
+  /**
+   * Resolve a relative-path require from inside a dynamic component.
+   * Cross-component imports look up other components by name in the registry.
+   * v1: we map "./Other" -> "Other" (basename, no extension).
+   *
+   * The returned value is a *lazy proxy module*: it has the same shape as
+   * a real CommonJS module (`{ default, ...rest }`), but every member is a
+   * React function component that re-resolves the target on each render.
+   * This means:
+   *   - Card can `require("./Hello")` at eval time even before Hello has
+   *     loaded — the proxy is returned immediately.
+   *   - When Hello actually arrives (or hot-swaps to a new version), Card's
+   *     next render automatically picks it up; no manual preload needed.
+   */
+  requireByPath(specifier: string): unknown {
+    const base = specifier
+      .replace(/^\.+\//, "")
+      .replace(/\.[tj]sx?$/, "")
+      .split("/")
+      .pop();
+    if (!base) {
+      throw new Error(`dynamico: cannot resolve relative require '${specifier}'`);
+    }
+    if (!this.entries.has(base) && !this.inflight.has(base)) {
+      void this.ensure(base);
+    }
+    return this.makeLazyProxy(base);
+  }
+
+  private lazyProxies = new Map<string, Record<string, unknown>>();
+
+  private makeLazyProxy(name: string): Record<string, unknown> {
+    const cached = this.lazyProxies.get(name);
+    if (cached) return cached;
+    const registry = this;
+    const proxy: Record<string, unknown> = {};
+    const make = (key: string) => {
+      const Comp = function LazyDynamic(props: Record<string, unknown>) {
+        const entry = registry.entries.get(name);
+        // Not loaded yet — render nothing. When the dependency arrives, the
+        // cross-dep notification in `notify()` refreshes our parent's entry,
+        // which causes useSyncExternalStore to re-render and we'll resolve
+        // for real on the next pass.
+        if (!entry || (!entry.factory && !entry.error)) return null;
+        if (entry.error) {
+          // Surface the dep error inline. Parent can wrap in errorFallback at
+          // its own level if it wants; we don't have access to it here.
+          return null;
+        }
+        const target = entry.factory?.[key];
+        if (typeof target !== "function") return null;
+        // The host-scope's React.createElement is what invoked us; we just
+        // call the real component function. props is what the parent passed.
+        return (target as (p: Record<string, unknown>) => unknown)(props);
+      };
+      Object.defineProperty(Comp, "name", { value: `Lazy(${name}.${key})` });
+      return Comp;
+    };
+    proxy.default = make("default");
+    // Allow named imports via Proxy: any key access returns a fresh lazy
+    // component bound to that key. Default is set above; everything else
+    // is created on demand.
+    const handler: ProxyHandler<Record<string, unknown>> = {
+      get(target, prop) {
+        if (typeof prop !== "string") return undefined;
+        if (prop in target) return target[prop];
+        const c = make(prop);
+        target[prop] = c;
+        return c;
+      },
+    };
+    const wrapped = new Proxy(proxy, handler);
+    this.lazyProxies.set(name, wrapped);
+    return wrapped;
+  }
+
+  /**
+   * Take a CompiledModule from the source, evaluate it (or record a compile
+   * error), update the entry, and notify listeners.
+   */
+  private ingest(name: string, module: import("./types.js").CompiledModule): RegistryEntry {
+    if (module.removed) {
+      this.entries.delete(name);
+      this.lazyProxies.delete(name);
+      const removalEntry: RegistryEntry = {
+        name,
+        version: module.version,
+        error: {
+          kind: "load",
+          name,
+          version: module.version,
+          message: `'${name}' was removed from the registry`,
+        },
+      };
+      this.notify(name, removalEntry);
+      return removalEntry;
+    }
+    let entry: RegistryEntry;
+    if (module.error) {
+      entry = {
+        name,
+        version: module.version,
+        error: {
+          kind: module.error.kind === "typecheck" ? "load" : "compile",
+          name,
+          version: module.version,
+          message: module.error.message,
+          stack: module.error.stack,
+        },
+      };
+    } else {
+      try {
+        const factory = loadModule(module.code, this.scope, (rel) =>
+          this.requireByPath(rel),
+        ) as ComponentFactory;
+        entry = { name, version: module.version, factory };
+      } catch (err) {
+        entry = {
+          name,
+          version: module.version,
+          error: toLoadError(name, module.version, err),
+        };
+      }
+    }
+    this.entries.set(name, entry);
+    this.notify(name, entry);
+    return entry;
+  }
+
+  private notify(name: string, entry: RegistryEntry): void {
+    const set = this.listeners.get(name);
+    if (set) for (const l of set) l(entry);
+    for (const l of this.anyListeners) l(entry);
+
+    // A new/updated component may be a dependency of others that are already
+    // mounted via lazy proxies. For v1 we don't track an explicit dep graph;
+    // instead we notify every other subscribed name with a *fresh entry
+    // object* (same content, new identity) so that useSyncExternalStore
+    // picks up the change and React re-renders, which causes the lazy
+    // proxy's render path to re-resolve the now-loaded dependency.
+    for (const [otherName, listeners] of this.listeners) {
+      if (otherName === name) continue;
+      const other = this.entries.get(otherName);
+      if (!other) continue;
+      const refreshed: RegistryEntry = { ...other };
+      this.entries.set(otherName, refreshed);
+      for (const l of listeners) l(refreshed);
+    }
+  }
+}
+
+function toLoadError(name: string, version: Version, err: unknown): DynamicError {
+  const e = err instanceof Error ? err : new Error(String(err));
+  return { kind: "load", name, version, message: e.message, stack: e.stack };
+}

package/src/sources/remote.ts

@@ -0,0 +1,119 @@
+import type { CompiledModule, Source, SourceUpdate } from "../types.js";
+
+export interface RemoteSourceOptions {
+  /** Base URL of the registry server, e.g. "http://localhost:4000" or "https://reg.example.com". */
+  url: string;
+  /** Optional WebSocket URL override. Defaults to `url` with http(s) -> ws(s). */
+  wsUrl?: string;
+  /** Custom fetch (for environments without a global fetch). */
+  fetch?: typeof fetch;
+  /** Custom WebSocket constructor (RN provides one globally; Node 18+ has it too). */
+  WebSocket?: typeof WebSocket;
+  /** Reconnection backoff in ms. Default: 1000. */
+  reconnectMs?: number;
+}
+
+/**
+ * Talks to @omriashke/dynamico-registry (or any compatible server).
+ *
+ *   GET  {url}/component/:name      -> CompiledModule (initial fetch)
+ *   WS   {wsUrl}/subscribe          -> stream of CompiledModule updates
+ */
+export function createRemoteSource(options: RemoteSourceOptions): Source {
+  const fetchImpl: typeof fetch =
+    options.fetch ??
+    (typeof fetch !== "undefined"
+      ? fetch
+      : ((() => {
+          throw new Error("dynamico: no fetch implementation available");
+        }) as unknown as typeof fetch));
+  const WSCtor: typeof WebSocket =
+    options.WebSocket ??
+    (typeof WebSocket !== "undefined"
+      ? WebSocket
+      : (function MissingWS() {
+          throw new Error("dynamico: no WebSocket implementation available");
+        } as unknown as typeof WebSocket));
+
+  const httpUrl = options.url.replace(/\/$/, "");
+  const wsUrl =
+    options.wsUrl ?? httpUrl.replace(/^http/, "ws") + "/subscribe";
+
+  const listeners = new Set<(u: SourceUpdate) => void>();
+  let socket: WebSocket | null = null;
+  let disposed = false;
+  const reconnectMs = options.reconnectMs ?? 1000;
+
+  function connect(): void {
+    if (disposed) return;
+    try {
+      socket = new WSCtor(wsUrl);
+    } catch (err) {
+      scheduleReconnect();
+      return;
+    }
+    socket.onmessage = (ev: MessageEvent) => {
+      try {
+        const data =
+          typeof ev.data === "string"
+            ? JSON.parse(ev.data)
+            : JSON.parse(new TextDecoder().decode(ev.data as ArrayBuffer));
+        if (data && typeof data.name === "string" && typeof data.version === "string") {
+          const module: CompiledModule = data;
+          for (const l of listeners) l({ module });
+        }
+      } catch {
+        /* ignore malformed frames */
+      }
+    };
+    socket.onclose = () => {
+      socket = null;
+      scheduleReconnect();
+    };
+    socket.onerror = () => {
+      try {
+        socket?.close();
+      } catch {
+        /* noop */
+      }
+    };
+  }
+
+  function scheduleReconnect(): void {
+    if (disposed) return;
+    setTimeout(connect, reconnectMs);
+  }
+
+  connect();
+
+  return {
+    async fetch(name: string): Promise<CompiledModule> {
+      const res = await fetchImpl(`${httpUrl}/component/${encodeURIComponent(name)}`);
+      if (!res.ok) {
+        return {
+          name,
+          version: "0",
+          error: {
+            kind: "compile",
+            message: `registry returned ${res.status} for ${name}`,
+          },
+        };
+      }
+      return (await res.json()) as CompiledModule;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      disposed = true;
+      try {
+        socket?.close();
+      } catch {
+        /* noop */
+      }
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+export type Version = string;
+
+export type Scope = Record<string, unknown>;
+
+export interface PropsSchemaField {
+  type: "string" | "number" | "boolean" | "object" | "array" | "any";
+  required?: boolean;
+}
+
+export type PropsSchema = Record<string, PropsSchemaField>;
+
+export interface Diagnostic {
+  severity: "error" | "warning";
+  message: string;
+  /** 1-based line in the source. */
+  line?: number;
+  /** 1-based column. */
+  column?: number;
+  /** TypeScript or Babel diagnostic code, e.g. "TS2304". */
+  code?: string;
+  /** A short snippet of the offending line, when available. */
+  snippet?: string;
+}
+
+export interface CompiledModuleOk {
+  name: string;
+  version: Version;
+  code: string;
+  /** Type-check warnings that didn't block compilation. */
+  warnings?: Diagnostic[];
+  error?: undefined;
+  removed?: undefined;
+}
+
+export interface CompiledModuleError {
+  name: string;
+  version: Version;
+  code?: undefined;
+  error: {
+    kind: "compile" | "typecheck";
+    message: string;
+    stack?: string;
+    diagnostics?: Diagnostic[];
+  };
+  removed?: undefined;
+}
+
+/** A removal event broadcast over WS when DELETE /component/:name is called. */
+export interface CompiledModuleRemoved {
+  name: string;
+  version: Version;
+  removed: true;
+  code?: undefined;
+  error?: undefined;
+}
+
+export type CompiledModule =
+  | CompiledModuleOk
+  | CompiledModuleError
+  | CompiledModuleRemoved;
+
+export interface DynamicError {
+  kind: "compile" | "load" | "render";
+  name: string;
+  version: Version;
+  message: string;
+  stack?: string;
+}
+
+export type ComponentFactory = {
+  default?: unknown;
+  propsSchema?: PropsSchema;
+  [key: string]: unknown;
+};
+
+export interface RegistryEntry {
+  name: string;
+  version: Version;
+  factory?: ComponentFactory;
+  error?: DynamicError;
+}
+
+export type RegistryListener = (entry: RegistryEntry) => void;
+
+export interface SourceUpdate {
+  module: CompiledModule;
+}
+
+export interface Source {
+  /** Fetch the latest version of a single component (initial load). */
+  fetch(name: string): Promise<CompiledModule>;
+  /** Subscribe to updates for any component. Returns unsubscribe fn. */
+  subscribe(listener: (update: SourceUpdate) => void): () => void;
+  /** Optional disposal hook. */
+  dispose?(): void;
+}