@reactivescript/runtime 0.0.0 → 0.1.0

package/README.md

@@ -1,45 +1,36 @@
 # @reactivescript/runtime
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@reactivescript/runtime`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+ReactiveScript's runtime (spec/11 CP-4a): `createApp` and the `__rt` helpers
+that compiled `.rx` calls, over Solid. Each helper is a Solid primitive, a
+composition of them, or plain JavaScript; nothing in it adds run-time
+behaviour beyond Solid.
+
+There is a browser build and a server build, chosen by export condition as
+`@solidjs/web` chooses (`browser` → the browser build; `node`, `deno`,
+`worker` → the server build; `./web` and `./server` name one explicitly).
+Both create the same owners in the same order, so a page the server streamed
+hydrates (spec/10).
+
+```js
+import { createApp } from "@reactivescript/runtime";
+import main from "./app.rx";   // compiled by @reactivescript/compiler (Solid's Vite plugin loads it)
+
+const app = createApp({ root: document.getElementById("app") });
+app.mount(main(app));
+```
+
+Solid is a peer: `solid-js`, `@solidjs/web` and `@solidjs/signals` (the
+runtime reads owner context from `@solidjs/signals`, which `solid-js` runs on;
+with pnpm, add it to the app).
+
+The source is the reference's runtime, `ref/compile/rt-web.ts` and
+`rt-server.ts`, the one every scenario runs on; `npm run build` transpiles it
+to `dist/` with its declarations. `npm test` checks both builds and renders
+a program compiled by the crate on the server build (it needs the compiler's
+Node-API build: `npm run build` in `../compiler`).
+
+Not yet: the server build's `stream` takes no request (it provides a
+placeholder one); a framework's request handling is to come.
+
+Releases: as `@reactivescript/compiler`'s (`../compiler/README.md`,
+Releasing), by the `runtime` workflow, tagged `runtime-v<version>`.

package/dist/server.d.ts

@@ -0,0 +1 @@
+export * from "./types/rt-server.js";

package/dist/server.js

@@ -0,0 +1,470 @@
+// ../ref/compile/rt-server.ts
+import { Portal as WebPortal } from "@solidjs/web";
+import { getObserver } from "solid-js";
+import { provideRequestEvent } from "@solidjs/web/storage";
+import { Errored, createComponent, createSignal, createMemo, createEffect, createOptimistic, createOptimisticStore, createStore, createProjection, createDeferred, untrack, latest, isPending, deep, NotReadyError, getOwner, runWithOwner, getNextChildId, runInServerComponentScope } from "solid-js";
+import { escape, renderToStream, markSafeError, generateHydrationScript } from "@solidjs/web";
+import { $TARGET } from "@solidjs/signals";
+var readWhole = (v) => {
+  if (v !== null && typeof v === "object") Reflect.ownKeys(v);
+  return v;
+};
+var latestWhole = (v) => v !== null && typeof v === "object" && v[$TARGET] !== void 0 ? deep(v) : v;
+var ERR = { toString: () => "#error" };
+var PENDING_MARK = { toString: () => "#pending" };
+var fmt = (v) => v === ERR ? "#error" : v === PENDING_MARK ? "#pending" : v === void 0 ? "undefined" : typeof v === "string" ? v : JSON.stringify(v);
+var isNode = (v) => typeof v === "function" || typeof v === "object" && v !== null && "t" in v;
+var isView = (v) => isNode(v) || Array.isArray(v) && (v.length === 0 || v.every((x) => x == null || typeof x === "string" || isView(x)) && v.some((x) => x != null && typeof x !== "string"));
+var reserve = (n = 1) => {
+  const o = getOwner();
+  if (o?.id != null) for (let i = 0; i < n; i++) getNextChildId(o);
+};
+var onServer = (what) => () => {
+  throw new Error(`SV-2: ${what} does not run on the server`);
+};
+function errorClass(name, params, message, id) {
+  const C = class extends Error {
+    constructor(...args) {
+      super("");
+      this.name = name;
+      params.forEach((p, i) => {
+        this[p] = args[i];
+      });
+      this.message = String(untrack(() => message(...args)));
+      if (id) this.$class = id;
+      markSafeError(this);
+    }
+  };
+  Object.defineProperty(C, "name", { value: name });
+  Object.defineProperty(C, "declared", { value: true });
+  const f = ((...args) => new C(...args));
+  f.cls = C;
+  f.errorClass = name;
+  f.$class = id;
+  return f;
+}
+var PANIC = { panic: true };
+var isA = (err, classes) => !classes || classes.includes(PANIC) || classes.some((c) => {
+  const k = c?.cls ?? c;
+  return typeof k === "function" && err instanceof k;
+});
+function catchAcc(f, match, alt) {
+  reserve(2);
+  return () => {
+    try {
+      return f();
+    } catch (err) {
+      if (err instanceof NotReadyError || !match(err)) throw err;
+      return alt(err);
+    }
+  };
+}
+function tryCatch(f, match, alt) {
+  try {
+    return f();
+  } catch (err) {
+    if (err instanceof NotReadyError || !match(err)) throw err;
+    return alt(err);
+  }
+}
+function wireCopy(v, where, fail) {
+  if (v === null || v === void 0 || typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+  if (Array.isArray(v)) return v.map((x, i) => wireCopy(x, `${where}[${i}]`, fail));
+  if (typeof v === "object") {
+    const proto = Object.getPrototypeOf(v);
+    if (proto === Object.prototype || proto === null) {
+      const o = {};
+      for (const k of Object.keys(v)) o[k] = wireCopy(v[k], `${where}.${k}`, fail);
+      return o;
+    }
+  }
+  return fail(`${where} is ${typeof v === "function" ? "a function" : `an instance of ${v.constructor?.name ?? "a class"}`}, which the wire cannot carry: send data`);
+}
+var wireFailure = (err) => err instanceof Error && err.constructor.declared ? err : new Error("Internal Server Error");
+var Flight = class {
+  key;
+  first;
+  settleFirst;
+  rejectFirst;
+  queue = [];
+  waiters = [];
+  started = false;
+  constructor(key) {
+    this.key = key;
+    this.first = new Promise((r, j) => {
+      this.settleFirst = r;
+      this.rejectFirst = j;
+    });
+    this.first.catch(() => {
+    });
+  }
+  push(x) {
+    const w = this.waiters.shift();
+    if (w) w(x);
+    else this.queue.push(x);
+  }
+  resolve(v) {
+    if (!this.started) {
+      this.started = true;
+      this.settleFirst(v);
+    }
+    this.push({ v });
+  }
+  reject(e) {
+    if (!this.started) {
+      this.started = true;
+      this.rejectFirst(e);
+    }
+    this.push({ e });
+  }
+  [Symbol.asyncIterator]() {
+    const next = () => new Promise((res, rej) => {
+      const take = (x) => {
+        if ("e" in x) rej(x.e);
+        else res({ value: x.v, done: false });
+      };
+      const q = this.queue.shift();
+      if (q) take(q);
+      else this.waiters.push(take);
+    });
+    return { next, return: async () => ({ value: void 0, done: true }) };
+  }
+};
+function createApp(opts = {}) {
+  const flights = /* @__PURE__ */ new Map();
+  const lastKey = /* @__PURE__ */ new Map();
+  const registry = /* @__PURE__ */ new Map();
+  const modules = /* @__PURE__ */ new Map();
+  const log = [];
+  const declared = [];
+  let currentEq = null;
+  let serverSeq = 0;
+  let classSeq = 0;
+  const jsErrors = /* @__PURE__ */ new Map();
+  const flight = (key) => {
+    let f = flights.get(key);
+    if (!f) {
+      f = new Flight(key);
+      flights.set(key, f);
+    }
+    if (currentEq) lastKey.set(currentEq, key);
+    return f;
+  };
+  const named = (name, fn) => name ? ((...a) => {
+    const was = currentEq;
+    currentEq = name;
+    try {
+      return fn(...a);
+    } finally {
+      currentEq = was;
+    }
+  }) : fn;
+  const ro = (get) => [get, { set: onServer("a write"), path: onServer("a write"), guess: onServer("a write") }];
+  const app = {
+    log,
+    flights,
+    lastKey,
+    asyncError: null,
+    /** Render `view` as a stream: `write` receives each chunk, `end` the close. */
+    /** One request (a request event, as Solid's integrations provide one — a server function called during the render runs
+     *  in it, SF-2b). */
+    stream(view, sink) {
+      return provideRequestEvent({ request: new Request("http://127.0.0.1/"), locals: {} }, () => renderToStream(process.env.SV_SCOPE ? () => runInServerComponentScope(view) : view).pipe(sink));
+    },
+    B: {
+      len: (x) => Array.isArray(x) || typeof x === "string" ? x.length : typeof x === "object" && x ? Object.keys(x).length : 0,
+      str: (x) => fmt(x),
+      map: (xs, f) => xs.map(f),
+      filter: (xs, f) => xs.filter(f),
+      sum: (xs) => xs.reduce((a, b) => a + b, 0),
+      every: (xs, f) => xs.every(f),
+      indexOf: (xs, f) => xs.findIndex(f),
+      fail: (msg) => {
+        throw Object.assign(new Error(msg), { panic: true });
+      },
+      fetch: (key) => opts.api?.fetch ? opts.api.fetch(key) : flight(String(key)),
+      log: (...a) => {
+        log.push(`log(${a.map(fmt).join(", ")})`);
+      }
+    },
+    /** MO-8: a class a `.d.rx` declares — a failure the server sends as it is (SV-5). */
+    jsError(name) {
+      if (jsErrors.has(name)) return jsErrors.get(name);
+      const C = opts.api?.[name] ?? errorClass(name, ["message"], (m) => m ?? name, `${name}#${classSeq++}`);
+      declared.push(C);
+      jsErrors.set(name, C);
+      return C;
+    },
+    /** A JS function's promise: a rejection with a declared class is marked safe to send; any other is redacted (SV-5). */
+    api: (name) => {
+      if (!opts.api) return (...a) => flight(`${name}:${a.map(fmt).join(",")}`);
+      const f = opts.api[name] ?? (() => {
+        throw new Error(`./api has no ${name}`);
+      });
+      return (...a) => {
+        const r = f(...a);
+        return r && typeof r.then === "function" ? Promise.resolve(r).catch((e) => {
+          if (isA(e, declared)) markSafeError(e);
+          throw e;
+        }) : r;
+      };
+    },
+    reg(name, e) {
+      let l = registry.get(name);
+      if (!l) registry.set(name, l = []);
+      l.push(e);
+    },
+    dget(name) {
+      const e = app.lookup(name);
+      return e.get ? app.snapshot(e.get) : e.value;
+    },
+    lookup(name) {
+      const l = registry.get(name);
+      if (!l?.length) {
+        if (jsErrors.has(name)) return { value: jsErrors.get(name) };
+        throw new Error(`unbound ${name}`);
+      }
+      return l[l.length - 1];
+    },
+    // a server function's request has its module's error classes, not the page's registry
+    // ---- declarations: the same primitives, from the server build. Writes do not happen on the server (SV-2). ----
+    source(name, init) {
+      void name;
+      if (typeof init === "object" && init !== null) {
+        const [store] = createStore(init);
+        const [get2] = createSignal(store);
+        return ro(get2);
+      }
+      const [get] = createSignal(init);
+      return ro(get);
+    },
+    question(name, compute, o, mode, key) {
+      const fn = named(name, compute);
+      if (mode.optimistic && mode.structured) {
+        const [store] = createOptimisticStore((draft) => {
+          const r = fn(draft);
+          if (r instanceof Flight || r instanceof Promise) return (async () => assignDraft(draft, r instanceof Flight ? await r.first : await r))();
+          assignDraft(draft, r);
+        }, key ? [] : {}, key ? { key } : void 0);
+        return ro(() => store);
+      }
+      if (mode.optimistic) {
+        const [truth] = createSignal(fn, o);
+        const [get2] = createOptimistic(() => truth());
+        return ro(get2);
+      }
+      if (mode.structured) {
+        const [store] = createStore(async (draft) => {
+          const r = fn(draft);
+          const v = r instanceof Flight ? await r.first : await r;
+          if (v && typeof v === "object") {
+            for (const k of Object.keys(draft)) if (!(k in v)) delete draft[k];
+            Object.assign(draft, v);
+          }
+        }, {});
+        return ro(() => store);
+      }
+      const [get] = createSignal(fn, o);
+      return ro(get);
+    },
+    memo: (name, fn, o) => createMemo(named(name, fn), o),
+    deferred: (name, fn, o) => createDeferred(named(name, fn), o),
+    keyed: (name, key, fn) => {
+      const src = createMemo(named(name, () => fn()));
+      const p = createProjection(() => src(), [], { key });
+      return () => p;
+    },
+    draft: (seed, body) => {
+      const p = createProjection(body, seed);
+      return () => p;
+    },
+    pre: (get) => {
+      const m = createMemo((st) => ({ cur: get(), prev: st ? st.cur : void 0 }));
+      return () => m().prev;
+    },
+    firstPaint: (f) => ({ loadingValue: untrack(f) }),
+    /** SV-2: the apply half runs on the client, after hydration. The compute half is reactive scope — Solid's server runs it;
+     *  an input's failure is an answer (E-12), not a server error. */
+    effect(_n, inputs, _apply) {
+      createEffect((() => {
+        try {
+          return inputs();
+        } catch (e) {
+          if (e instanceof NotReadyError) throw e;
+          return ERR;
+        }
+      }), { effect() {
+      }, error() {
+      } });
+    },
+    action(_gen) {
+      return onServer("an action");
+    },
+    awaited: (v) => v instanceof Flight ? v.first : v,
+    /** RG-8: Solid's Portal — client-only: the server renders nothing for it, the browser renders it once it has the page. */
+    Portal: WebPortal,
+    /** CSS-2: a dynamic class with the view's scope class after it. */
+    scopedClass: (v, hash) => v == null || v === false || v === "" ? hash : `${v} ${hash}`,
+    /** SV-7b: a client question — not asked on the server; the browser asks it once hydrated (Solid's \`ssrSource: "client"\`). */
+    clientQuestion: (o) => ({ ...o ?? {}, ssrSource: "client" }),
+    /** 12 SF-2: a server fn as the client calls it — every call a flight. Asked in reactive scope it is a question, one
+     *  flight per arguments, as a JS import's; in imperative scope each call is a new request. \`fn\` is the module-level
+     *  \`"use server"\` function (SF-7a): the body in place, or — once Solid's \`transformDirectives\` has made it a reference
+     *  — a request to the server. */
+    serverRef(name, fn) {
+      return (...args) => {
+        const key = `${name}:${args.map(fmt).join(",")}`;
+        const question = !!getObserver();
+        if (question && flights.has(key)) return flights.get(key);
+        const fl = question ? flight(key) : new Flight(`${key}#${serverSeq++}`);
+        globalThis.__rx_app = app;
+        let p;
+        try {
+          p = Promise.resolve(fn(...args));
+        } catch (e) {
+          p = Promise.reject(e);
+        }
+        p.then((v) => fl.resolve(v), (e) => fl.reject(e));
+        return fl;
+      };
+    },
+    /** SF-6: a server fn's body (a generator, as an action's), driven by promises — not by an action: it is no change of
+     *  the client's — behind a wire that copies arguments and result and lets only declared failures through. */
+    serverCall(name, gen, args) {
+      return new Promise((resolve, reject) => {
+        const fail = (msg) => {
+          throw new Error(`WIRE_VALUE: ${name}: ${msg}`);
+        };
+        let g;
+        try {
+          g = gen(...args.map((a, i) => wireCopy(a, `argument ${i + 1}`, fail)));
+        } catch (e) {
+          reject(e);
+          return;
+        }
+        const step = (input, thrown) => {
+          const was = currentEq;
+          currentEq = null;
+          let r;
+          try {
+            r = untrack(() => thrown ? g.throw(input) : g.next(input));
+          } catch (e) {
+            reject(wireFailure(e));
+            return;
+          } finally {
+            currentEq = was;
+          }
+          if (r.done) {
+            try {
+              resolve(wireCopy(r.value, "its result", fail));
+            } catch (e) {
+              reject(e);
+            }
+            return;
+          }
+          Promise.resolve(r.value).then((v) => step(v, false), (e) => step(e, true));
+        };
+        step(void 0, false);
+      });
+    },
+    hoisted(_name, _get) {
+    },
+    refresh: onServer("refresh"),
+    affects: onServer("affects"),
+    onSettled: onServer("onSettled"),
+    // EF-7: imperative scope only, and no imperative run happens here (SV-2a)
+    onFlush: onServer("onFlush"),
+    // EF-8
+    preOr: (v, init) => v === void 0 ? init() : v,
+    module(key, factory) {
+      let m = modules.get(key);
+      if (!m) {
+        m = factory(app);
+        modules.set(key, m);
+      }
+      return m;
+    },
+    // ---- context (RG-7): the server build's owner context, keyed by the declaration ----
+    owner: () => getOwner(),
+    context(name, dflt) {
+      return { name, id: Symbol(name), dflt, owner: getOwner(), dv: dflt ? { get: createMemo(dflt) } : null };
+    },
+    provide(c, e) {
+      const o = getOwner();
+      o._context = { ...o._context, [c.id]: e };
+    },
+    use(c, owner) {
+      const e = (owner ?? getOwner())?._context?.[c.id];
+      if (e) return e;
+      if (c.dv) return c.dv;
+      throw new Error(`RG-7b: no provision for ${c.name}`);
+    },
+    useGet(c, owner) {
+      const e = app.use(c, owner);
+      return e.get ? e.get() : e.value;
+    },
+    runWithOwner,
+    snapshot(get) {
+      try {
+        return untrack(get);
+      } catch (e) {
+        if (e instanceof NotReadyError) return PENDING_MARK;
+        throw e;
+      }
+    },
+    errorClass: (name, params, message) => errorClass(name, params, message, `${name}#${classSeq++}`),
+    // a declaration's identity, sent with its failures (SV-5a)
+    isA,
+    PANIC,
+    catchMemo: catchAcc,
+    tryCatch,
+    catchRead: (f, match, alt) => catchAcc(f, match, alt)(),
+    throw: (e) => {
+      throw e;
+    },
+    eq: (a, b) => a === b,
+    untrack,
+    latest: (f) => latest(() => latestWhole(f())),
+    isPending: (f) => isPending(() => readWhole(f())),
+    fmt,
+    // ---- views: compiled JSX (compile/jsx.ts, generate "ssr", hydratable) does the rest ----
+    show: (v) => isView(v) ? v : escape(fmt(v)),
+    /** A failure of another class passes to the boundary above (R-f-4): on the server, a rethrow from the fallback. The
+     *  client's unwrapping memo has no counterpart here: its id is reserved. */
+    TypedErrored(props) {
+      const out = createComponent(Errored, {
+        fallback: (err) => {
+          const ok = createMemo(() => isA(err(), props.classes));
+          if (!ok()) throw err();
+          return props.fallback(err);
+        },
+        get children() {
+          return props.children;
+        }
+      });
+      reserve();
+      return out;
+    }
+  };
+  return app;
+}
+function assignDraft(draft, v) {
+  if (!v || typeof v !== "object") return;
+  if (Array.isArray(draft) && Array.isArray(v)) {
+    draft.length = v.length;
+    v.forEach((x, i) => {
+      draft[i] = x;
+    });
+    return;
+  }
+  for (const k of Object.keys(draft)) if (!(k in v)) delete draft[k];
+  Object.assign(draft, v);
+}
+export {
+  ERR,
+  Flight,
+  PENDING_MARK,
+  createApp,
+  fmt,
+  generateHydrationScript
+};