npm - smaoog - Versions diffs - 0.0.1 - Mend

smaoog 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/LICENSE +21 -0
package/README.md +102 -0
package/package.json +50 -0
package/src/assets.js +118 -0
package/src/build.js +216 -0
package/src/cli.js +58 -0
package/src/client/index.d.ts +6 -0
package/src/client/index.js +12 -0
package/src/client/navigation.js +209 -0
package/src/client/runtime.js +47 -0
package/src/client/store.js +31 -0
package/src/conventions.js +47 -0
package/src/dev.js +84 -0
package/src/dispatch.js +75 -0
package/src/errors.js +11 -0
package/src/form.js +121 -0
package/src/index.d.ts +120 -0
package/src/index.js +95 -0
package/src/link.js +22 -0
package/src/meta.js +87 -0
package/src/protocol.js +14 -0
package/src/render.js +55 -0
package/src/request.js +133 -0
package/src/response.js +256 -0
package/src/router.js +497 -0
package/src/routes.js +175 -0
package/src/serialize.js +17 -0
package/src/server-only.js +122 -0
package/src/server.js +42 -0
package/src/start.js +60 -0
package/src/tailwind.js +20 -0
package/src/vite.js +69 -0

package/src/index.d.ts ADDED Viewed

@@ -0,0 +1,120 @@
+import * as React from "react";
+export const version: string;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type FormBodyValue = string | string[];
+export type ParsedBody = Record<string, JsonValue | FormBodyValue>;
+export type RouteParams = Record<string, string>;
+export type HeadersObject = Record<string, string | number | readonly string[]>;
+export interface SmaoogRequest<
+  Params extends RouteParams = RouteParams,
+  Body extends object = ParsedBody,
+> {
+  raw: unknown;
+  method: string;
+  path: string;
+  params: Params;
+  query: URLSearchParams;
+  headers: Headers;
+  rawBody(): Promise<Uint8Array>;
+  body(): Promise<Body>;
+}
+export interface SmaoogResponse<Props = unknown> {
+  raw: unknown;
+  status(code: number): this;
+  headers(headers: HeadersObject): this;
+  text(body: string | number | boolean | null | undefined): TerminalResponse;
+  json(data: unknown): TerminalResponse;
+  redirect(location: string, code?: number): TerminalResponse;
+  render(props?: Props): RenderResponse<Props>;
+  notFound(props?: Props): NotFoundResponse<Props>;
+}
+export type RouteHandler<
+  Params extends RouteParams = RouteParams,
+  Body extends object = ParsedBody,
+  Props = unknown,
+> = (
+  req: SmaoogRequest<Params, Body>,
+  res: SmaoogResponse<Props>,
+) => TerminalResponse | Promise<TerminalResponse>;
+export interface TerminalResponse {
+  readonly kind: string;
+}
+export interface RenderResponse<Props = unknown> extends TerminalResponse {
+  readonly kind: "render";
+  readonly props: Props;
+}
+export interface NotFoundResponse<Props = unknown> extends TerminalResponse {
+  readonly kind: "notFound";
+  readonly props: Props;
+}
+export interface MetaDescriptor {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  robots?: string;
+  meta?: Array<Record<string, string | number | boolean>>;
+  links?: Array<Record<string, string | number | boolean>>;
+}
+export type MetaFunction<Props = unknown> = (context: {
+  props: Props;
+}) => MetaDescriptor;
+export type Meta<Props = unknown> = MetaDescriptor | MetaFunction<Props>;
+export interface DocumentProps {
+  children?: React.ReactNode;
+  head?: React.ReactNode;
+}
+export interface StylesheetProps {
+  href: string;
+}
+export function Stylesheet(props: StylesheetProps): React.ReactElement | null;
+export interface ClientEntryProps {
+  src: string;
+}
+export function ClientEntry(props: ClientEntryProps): React.ReactElement | null;
+export function ReactRefresh(): React.ReactElement | null;
+export interface LinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "onClick"> {
+  href: string;
+  replace?: boolean;
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  children?: React.ReactNode;
+}
+export function Link(props: LinkProps): React.ReactElement;
+export interface FormState {
+  submitting: boolean;
+}
+export interface FormProps
+  extends Omit<
+    React.FormHTMLAttributes<HTMLFormElement>,
+    "action" | "children" | "method" | "onError" | "onSubmit"
+  > {
+  action?: string;
+  method?: "get" | "post" | "put" | "patch" | "delete" | (string & {});
+  onSuccess?: (data: unknown, response: Response) => void;
+  onError?: (data: unknown, response?: Response) => void;
+  children?: React.ReactNode | ((state: FormState) => React.ReactNode);
+}
+export function Form(props: FormProps): React.ReactElement;

package/src/index.js ADDED Viewed

@@ -0,0 +1,95 @@
+import React from "react";
+import { appPath } from "./assets.js";
+import { PROPS_SCRIPT_ID, ROUTE_SCRIPT_ID, serializeJsonForScript } from "./serialize.js";
+export { Link } from "./link.js";
+export { Form } from "./form.js";
+export const version = "0.0.1";
+// Server-render context installed by the active render path (see render.js). It
+// lets the Document helpers resolve dev/prod asset URLs and emit the hydration
+// bootstrap.
+//
+// It lives on globalThis under a shared symbol, not a module variable, on
+// purpose: in dev the Document renders inside Vite's SSR module graph, a
+// different `smaoog` instance than the host renderer — a module-local slot would
+// not be the one the renderer set. renderToString is synchronous, so a single
+// global slot is safe; no other request can interleave between install/restore.
+const CONTEXT_KEY = Symbol.for("smaoog.renderContext");
+function currentContext() {
+  return globalThis[CONTEXT_KEY] ?? null;
+}
+export function __withSmaoogContext(context, fn) {
+  const previous = globalThis[CONTEXT_KEY] ?? null;
+  globalThis[CONTEXT_KEY] = context ?? null;
+  try {
+    return fn();
+  } finally {
+    globalThis[CONTEXT_KEY] = previous;
+  }
+}
+// Link a source stylesheet, resolved to its dev source URL or built asset.
+export function Stylesheet({ href }) {
+  const ctx = currentContext();
+  const resolved = ctx ? ctx.stylesheetHref(href) : appPath(href);
+  return React.createElement("link", { rel: "stylesheet", href: resolved });
+}
+function jsonScript(key, id, value) {
+  return React.createElement("script", {
+    key,
+    id,
+    type: "application/json",
+    // Pre-escaped JSON: React must not touch it, and the escaping (see
+    // serializeJsonForScript) is what keeps props from breaking out of <script>.
+    dangerouslySetInnerHTML: { __html: serializeJsonForScript(value) },
+  });
+}
+// Loads the browser entry and, alongside it, the hydration bootstrap: the page's
+// props and its route id/module. The client runtime (smaoog/client, pulled in by
+// the entry) reads these to hydrate the server-rendered page.
+export function ClientEntry({ src }) {
+  const ctx = currentContext();
+  if (!ctx) return null;
+  const entryHref = ctx.entryHref(src);
+  const page = ctx.page;
+  const moduleHref = page ? ctx.pageModuleHref(page.routeId) : null;
+  const nodes = [];
+  // The bootstrap is only useful when there is both a runtime entry to read it
+  // and a resolvable page module to hydrate (static/error pages have neither).
+  if (entryHref && page && moduleHref) {
+    nodes.push(jsonScript("props", PROPS_SCRIPT_ID, page.props ?? {}));
+    nodes.push(jsonScript("route", ROUTE_SCRIPT_ID, { id: page.routeId, module: moduleHref }));
+  }
+  if (entryHref) {
+    nodes.push(React.createElement("script", { key: "entry", type: "module", src: entryHref }));
+  }
+  if (nodes.length === 0) return null;
+  return React.createElement(React.Fragment, null, ...nodes);
+}
+// Vite's React Refresh preamble. It must run before any refreshable module, so
+// it belongs in the document <head>. Dev only; nothing in production.
+const REACT_REFRESH_PREAMBLE =
+  'import RefreshRuntime from "/@react-refresh";\n' +
+  "RefreshRuntime.injectIntoGlobalHook(window);\n" +
+  "window.$RefreshReg$ = () => {};\n" +
+  "window.$RefreshSig$ = () => (type) => type;\n" +
+  "window.__vite_plugin_react_preamble_installed__ = true;";
+export function ReactRefresh() {
+  const ctx = currentContext();
+  if (!ctx || !ctx.dev) return null;
+  return React.createElement("script", {
+    type: "module",
+    dangerouslySetInnerHTML: { __html: REACT_REFRESH_PREAMBLE },
+  });
+}

package/src/link.js ADDED Viewed

@@ -0,0 +1,22 @@
+import React from "react";
+import { navigate, shouldInterceptClick } from "./client/navigation.js";
+// A navigational anchor. It renders a plain `<a href>` — so it works on the
+// server, before hydration, and with JavaScript disabled — and, once hydrated,
+// upgrades same-origin clicks to client navigation (no full reload).
+//
+// Modifier clicks (cmd/ctrl/shift/alt, middle-click), `target`/`download`
+// anchors, and external links are left entirely to the browser. `replace`
+// swaps the current history entry instead of pushing a new one.
+export function Link({ href, replace = false, onClick, children, ...rest }) {
+  function handleClick(event) {
+    if (onClick) onClick(event);
+    // `download` is a native anchor behavior we never intercept.
+    if (rest.download === undefined && shouldInterceptClick(event, href, rest.target)) {
+      event.preventDefault();
+      navigate(href, { history: replace ? "replace" : "push" });
+    }
+  }
+  return React.createElement("a", { ...rest, href, onClick: handleClick }, children);
+}

package/src/meta.js ADDED Viewed

@@ -0,0 +1,87 @@
+import React from "react";
+// True only for object literals (and null-prototype objects), so arrays, Dates,
+// Maps, class instances, promises, etc. are rejected as meta.
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+// Resolve a route module's `meta` export against the render props. `meta` may be
+// a static plain object or a synchronous function ({ props }) => object. Async
+// meta and non-object meta are clear errors rather than silent no-ops.
+export function resolveMeta(routeModule, props) {
+  const meta = routeModule?.meta;
+  if (meta === undefined || meta === null) return {};
+  let resolved = meta;
+  if (typeof meta === "function") {
+    resolved = meta({ props });
+    if (resolved && typeof resolved.then === "function") {
+      throw new Error("Route meta must be synchronous; async meta is not supported.");
+    }
+    if (resolved === undefined || resolved === null) return {};
+  }
+  if (!isPlainObject(resolved)) {
+    throw new Error(
+      "Route meta must be a plain object, or a synchronous function returning one.",
+    );
+  }
+  return resolved;
+}
+// Attribute stamped on every framework-managed head element. It marks the tags
+// the framework owns so client navigation can find and replace them when the
+// route's metadata changes, without disturbing the user's own <head> contents.
+export const HEAD_MARKER = "data-smaoog-head";
+// Turn resolved meta fields into a flat, renderer-agnostic list of head tag
+// descriptors. Both consumers build from this one list so the SSR head and the
+// client-side head update can never drift:
+//   { tag: "title", text }            -> <title>text</title>
+//   { tag: "meta" | "link", attrs }   -> <tag ...attrs>
+export function metaToTags(meta) {
+  const tags = [];
+  if (typeof meta.title === "string") tags.push({ tag: "title", text: meta.title });
+  if (typeof meta.description === "string") {
+    tags.push({ tag: "meta", attrs: { name: "description", content: meta.description } });
+  }
+  if (typeof meta.canonical === "string") {
+    tags.push({ tag: "link", attrs: { rel: "canonical", href: meta.canonical } });
+  }
+  if (typeof meta.robots === "string") {
+    tags.push({ tag: "meta", attrs: { name: "robots", content: meta.robots } });
+  }
+  // Custom entries are raw attribute objects (e.g. { property: "og:title", content }).
+  addCustom("meta", "meta", meta.meta);
+  addCustom("links", "link", meta.links);
+  return tags;
+  function addCustom(field, tag, entries) {
+    if (entries === undefined) return;
+    if (!Array.isArray(entries)) {
+      throw new Error(`Route meta.${field} must be an array.`);
+    }
+    for (const attrs of entries) {
+      if (!isPlainObject(attrs)) {
+        throw new Error(`Route meta.${field} entries must be plain attribute objects.`);
+      }
+      tags.push({ tag, attrs });
+    }
+  }
+}
+// Turn resolved meta fields into managed React head elements. The result is an
+// array passed to Document as its `head` prop. There is no user-facing <Head>
+// component: head entries are declared through the `meta` export only. Each tag
+// carries HEAD_MARKER so client navigation can replace them later.
+export function metaToElements(meta) {
+  return metaToTags(meta).map((tag, key) => {
+    if (tag.tag === "title") {
+      return React.createElement("title", { key, [HEAD_MARKER]: "" }, tag.text);
+    }
+    return React.createElement(tag.tag, { key, ...tag.attrs, [HEAD_MARKER]: "" });
+  });
+}

package/src/protocol.js ADDED Viewed

@@ -0,0 +1,14 @@
+// Wire protocol shared by the server and the browser runtime. Kept in its own
+// dependency-free module so the client can import it without pulling in any
+// server-only code.
+// Request header an enhanced <Form> mutation sends. It tells the server to
+// serialize render() and redirect() results as JSON envelopes (the same
+// page-swap payloads client navigation uses) instead of HTML, while leaving a
+// handler's own res.json()/res.text() response untouched for onSuccess/onError.
+export const SUBMIT_HEADER = "x-smaoog-submit";
+// Response header marking a framework envelope and its kind ("render" or
+// "redirect"). It is absent on a handler's own res.json()/res.text() response,
+// which is how the form client tells a page-swap apart from callback data.
+export const RESPONSE_HEADER = "x-smaoog-response";

package/src/render.js ADDED Viewed

@@ -0,0 +1,55 @@
+import React from "react";
+import { renderToString } from "react-dom/server";
+import { __withSmaoogContext } from "./index.js";
+import { metaToElements, resolveMeta } from "./meta.js";
+function FallbackDocument({ children, head }) {
+  return React.createElement(
+    "html",
+    null,
+    React.createElement("head", null, React.createElement("meta", { charSet: "utf-8" }), head),
+    React.createElement("body", null, React.createElement("main", { id: "root" }, children)),
+  );
+}
+// Serialize a RenderIntent for a normal document request. Managed head tags are
+// resolved from the route's `meta` export here — after the handler ran and right
+// before HTML is flushed — and passed to Document as its `head` prop. Props
+// scripts and hydration hooks are layered on this path in later phases.
+export function renderIntentToHtml(intent) {
+  if (typeof intent.Page !== "function") {
+    throw new Error("Cannot render route: missing default export");
+  }
+  // Attach this render's page bootstrap (route id + props) to the client context
+  // so <ClientEntry> can emit the hydration scripts. No context (standalone
+  // render) -> the Document helpers degrade to static output.
+  const context = intent.client
+    ? { ...intent.client, page: { routeId: intent.routeId ?? null, props: intent.props ?? {} } }
+    : null;
+  return __withSmaoogContext(context, () => {
+    const Document = intent.Document ?? FallbackDocument;
+    const head = metaToElements(resolveMeta(intent.routeModule, intent.props));
+    const page = React.createElement(intent.Page, intent.props);
+    const document = React.createElement(Document, { children: page, head });
+    return "<!doctype html>" + renderToString(document);
+  });
+}
+// Serialize a RenderIntent for a /_smaoog/nav request as the client navigation
+// payload. It is the same intent the HTML path renders, but reduced to what the
+// client runtime needs to swap the page: the page module to import, the props to
+// render it with, the resolved meta to update the head, and the status. There is
+// no second render here — the client renders the page in the browser.
+export function renderIntentToNav(intent) {
+  if (typeof intent.Page !== "function") {
+    throw new Error("Cannot render route: missing default export");
+  }
+  return {
+    kind: "render",
+    routeId: intent.routeId ?? null,
+    module: intent.client?.pageModuleHref?.(intent.routeId) ?? null,
+    props: intent.props ?? {},
+    meta: resolveMeta(intent.routeModule, intent.props),
+    status: intent.status,
+  };
+}

package/src/request.js ADDED Viewed

@@ -0,0 +1,133 @@
+import { HttpError } from "./errors.js";
+// Default maximum request body size.
+export const DEFAULT_BODY_LIMIT = 1024 * 1024; // 1 MB
+// Read the Node request stream once into a Buffer, enforcing a size limit.
+// On overflow we stop accumulating and reject with 413, but do not destroy the
+// socket — the dispatcher still needs to send the 413 response.
+function readStream(nodeReq, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let overflowed = false;
+    nodeReq.on("data", (chunk) => {
+      if (overflowed) return;
+      size += chunk.length;
+      if (size > limit) {
+        overflowed = true;
+        reject(new HttpError(413, "Payload Too Large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    nodeReq.on("end", () => resolve(Buffer.concat(chunks)));
+    nodeReq.on("error", reject);
+  });
+}
+// Parse a cached body Buffer according to its content type.
+function parseBody(buffer, contentType) {
+  // Empty body short-circuits before any content-type handling.
+  if (buffer.length === 0) return {};
+  const mime = (contentType ?? "").split(";")[0].trim().toLowerCase();
+  if (!mime) return {};
+  if (mime === "application/json") {
+    let value;
+    try {
+      value = JSON.parse(buffer.toString("utf8"));
+    } catch {
+      throw new HttpError(400, "Bad Request");
+    }
+    // The body model is object-shaped: arrays, primitives, and null are
+    // rejected so handlers can always rely on body being an object.
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new HttpError(400, "Bad Request");
+    }
+    return value;
+  }
+  if (mime === "application/x-www-form-urlencoded") {
+    const params = new URLSearchParams(buffer.toString("utf8"));
+    const result = {};
+    for (const key of new Set(params.keys())) {
+      const values = params.getAll(key);
+      // defineProperty (not assignment) so user-controlled keys like
+      // "__proto__" are stored as ordinary data, never invoking the prototype
+      // setter — form data can't restructure the parsed object.
+      Object.defineProperty(result, key, {
+        value: values.length > 1 ? values : values[0],
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    }
+    return result;
+  }
+  // multipart/form-data and any other type: {} in v0.
+  return {};
+}
+// Wrap a Node IncomingMessage in smaoog's request surface. `params` comes from
+// the route matcher; it is `{}` for routes with no dynamic segments. `url`
+// overrides the request target used to derive path/query — the navigation
+// endpoint sets it so a handler sees the target URL it is rendering for, not the
+// internal `/_smaoog/nav` URL.
+export function createRequest(
+  nodeReq,
+  { bodyLimit = DEFAULT_BODY_LIMIT, params = {}, url: target } = {},
+) {
+  // Dummy origin lets the URL parser handle path-only request targets.
+  const url = new URL(target ?? nodeReq.url, "http://localhost");
+  // Web Headers give a case-insensitive .get() that returns string | null.
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(nodeReq.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(key, item);
+    } else if (value != null) {
+      headers.set(key, value);
+    }
+  }
+  // The stream is read at most once; body() and rawBody() share this read.
+  let rawPromise;
+  function readRawOnce() {
+    if (!rawPromise) rawPromise = readStream(nodeReq, bodyLimit);
+    return rawPromise;
+  }
+  let parsed;
+  let hasParsed = false;
+  return {
+    // Escape hatch: the raw Node IncomingMessage.
+    raw: nodeReq,
+    // Uppercase HTTP method (GET, POST, ...).
+    method: (nodeReq.method ?? "GET").toUpperCase(),
+    // Path without the query string.
+    path: url.pathname,
+    // URLSearchParams: query.get(name) returns a string or null.
+    query: url.searchParams,
+    // Case-insensitive: headers.get(name) returns a string or null.
+    headers,
+    // Dynamic route params from the matcher (e.g. { id: "42" }); {} for static routes.
+    params,
+    // Exact request bytes (cached Buffer).
+    async rawBody() {
+      return readRawOnce();
+    },
+    // Parsed body, from the same cached read.
+    async body() {
+      if (hasParsed) return parsed;
+      const buffer = await readRawOnce();
+      parsed = parseBody(buffer, headers.get("content-type"));
+      hasParsed = true;
+      return parsed;
+    },
+  };
+}