npm - mono-jsx - Versions diffs - 0.9.14 → 0.10.0-beta.10 - Mend

mono-jsx 0.9.14 → 0.10.0-beta.10

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 (10) hide show

package/README.md CHANGED Viewed

@@ -11,6 +11,7 @@ mono-jsx is a JSX runtime that renders the `<html>` element to a `Response` obje
 - 💡 Complete Web API TypeScript definitions
 - ⏳ Streaming rendering
 - 🗂️ Built-in router (SPA mode)
+- 📡 Built-in remote procedure call (RPC) API
 - 🔑 Session storage
 - 🥷 [htmx](#using-htmx) integration
 - 🌎 Universal, works in Node.js, Deno, Bun, Cloudflare Workers, etc.
@@ -963,8 +964,6 @@ The `<component>` element also supports the `ref` prop, which allows you to cont
 - `refresh`: A method to re-render the component with the current name and props.
 ```tsx
-import type { ComponentElement } from "mono-jsx";
 function App(this: WithRefs<FC, { component: ComponentElement }>) {
   this.effect(() => {
     // updating the component name and props will trigger a re-render of the component
@@ -1109,8 +1108,21 @@ You can access the `params` object in your route components to get the values of
 ```tsx
 // router pattern: "/post/:id"
 function Post(this: FC) {
-  this.request.url         // "http://localhost:3000/post/123"
-  this.request.params?.id  // "123"
+  console.log(this.request.url)         // "http://localhost:3000/post/123"
+  console.log(this.request.params?.id)  // "123"
+}
+```
+You can use `this.app.url` signal to get route URL and parameters:
+```tsx
+function Post(this: FC) {
+  return (
+    <div>
+      <p>Current URL: {this.$(() => this.app.url.href)}</p>
+      <p>Post id: {this.$(() => this.app.url.params?.id)}</p>
+    </div>
+  )
 }
 ```
@@ -1226,7 +1238,7 @@ The `hidden` prop can be used to hide the formslot payload from the form handler
 ### Using `this.app.url` Signal
-`this.app.url` is an app-level signal that contains the current route URL and parameters. The `this.app.url` signal is automatically updated when the route changes, so you can use it to display the current URL in your components or control the view with `<show>`, `<hidden>` or `<switch>` elements:
+The `this.app.url` in a component is an app-level signal that contains the current route URL and parameters. It is automatically updated when the route changes, so you can use it to display the current URL in your components or control the view with `<show>`, `<hidden>` or `<switch>` elements:
 ```tsx
 function App(this: FC) {
@@ -1257,6 +1269,23 @@ export default {
 }
 ```
+You can also use the `navigate` method of the `<router>` element to navigate to a new route programmatically.
+```tsx
+function App(this: FC<{}, { router: RouterElement }>) {
+  return (
+    <>
+      <header>
+        <button
+          onClick={() => this.refs.router.navigate("/about", { replace: false, refresh: false })}
+        >About</button>
+      </header>
+      <router ref={this.refs.router} />
+    </>
+  )
+}
+```
 ### Nav Links
 Links under the `<nav>` element will be treated as navigation links by the router. When the `href` of a nav link matches a route, an active class will be added to the link element. By default, the active class is `active`, but you can customize it by setting the `data-active-class` prop on the `<nav>` element. You can add styles for the active link using nested CSS selectors in the `style` prop of the `<nav>` element.
@@ -1276,6 +1305,63 @@ export default {
 }
 ```
+## Adding Page Metadata
+You can add metadata to the route component by setting the `metadata` property on the route component.
+```tsx
+function Home(this: FC) {
+  return <p>Home</p>
+}
+Home.metadata = {
+  title: "Home",
+  description: "Home page",
+}
+const routes = {
+  "/": Home,
+}
+```
+Or use `getMetadata` property on the route component to dynamically generate the metadata.
+```tsx
+async function Post(this: FC) {
+  const post = await getPost(this.request.params.slug)
+  return <div>
+    <h1>{post.title}</h1>
+    <h2>{post.description}</h2>
+    <div>{post.content}</div>
+  </div>
+}
+Post.getMetadata = async function(this: FC) {
+  const post = await getPost(this.request.params.slug)
+  return {
+    title: post.title,
+    description: post.description,
+  }
+}
+const routes = {
+  "/post/:slug": Post,
+}
+```
+You can also add metadata to the root `<html>` element by setting the `metadata` prop on the root `<html>` element. This will be added to all the pages in your app.
+```tsx
+export default {
+  fetch: (req) => (
+    <html request={req} routes={routes} metadata={{ title: "My App" }}>
+      <head>
+        <metadata />
+      </head>
+    </html>
+  )
+}
+```
 ### Fallback (404)
 You can add fallback(404) content to the `<router>` element as children, which will be displayed when no route matches the current URL.
@@ -1293,9 +1379,33 @@ export default {
 }
 ```
+### Route Caching
+By default, the router client caches the html content from the server. To disable the caching, you can add the `dynamic` option to the route component.
+```tsx
+// Home is a static route that can be cached on the client side
+function Home(this: FC) {
+  return <p>Home</p>
+}
+// Dash is a dynamic route that will not be cached on the client side
+// it will be fetched from the server on every navigation
+function Dash(this: FC) {
+  const user = this.session.get<{ name: string }>("user")
+  return <p>Welcome back, {user?.name}!</p>
+}
+Dash.dynamic = true;
+const routes = {
+  "/": Home,
+  "/dash": Dash,
+}
+```
 ## Using Session
-mono-jsx provides a built-in session storage that allows you to manage user sessions. To use the session storage, you need to set the `session` prop on the root `<html>` element with the `cookie.secret` option.
+mono-jsx provides a built-in session storage that allows you to manage sessions. To use session storage, you need to set the `session` prop on the root `<html>` element with the `cookie.secret` option.
 ```tsx
 function Index(this: FC) {
@@ -1342,43 +1452,132 @@ export default {
 ### Session Storage API
 ```ts
-function Component(this: FC) {
-  // set a value in the session
-  this.session.set("user", { name: "John" })
-  // get a value from the session
-  this.session.get<{ name: string }>("user") // { name: "John" }
-  // get all entries from the session
-  this.session.entries() // [["user", { name: "John" }]]
-  // delete a value from the session
-  this.session.delete("user")
-  // destroy the session
-  this.session.destroy()
+export interface Session {
+  /**
+   * The session ID.
+   */
+  readonly sessionId: string;
+  /**
+   * If true, update the session cookie to the client.
+   */
+  readonly isDirty: boolean;
+  /**
+   * If true, the session is expired.
+   */
+  readonly isExpired: boolean;
+  /**
+   * Gets a value from the session.
+   */
+  get<T = unknown>(key: string): T | undefined;
+  /**
+   * Gets all the entries from the session.
+   */
+  all(): Record<string, unknown>;
+  /**
+   * Sets a value in the session.
+   */
+  set(key: string, value: string | number | boolean | any[] | Record<string, unknown>): void;
+  /**
+   * Deletes a value from the session.
+   */
+  delete(key: string): void;
+  /**
+   * Destroys the session.
+   */
+  destroy(): void;
 }
 ```
-## Caching
+> [!WARNING]
+> The session storage stores data with cookies. **Therefore, you should never store sensitive data in the session storage.**
-mono-jsx renders HTML dynamically per request; large apps may tax your CPU resources. To improve rendering performance, mono-jsx introduces two built-in elements that can cache the rendered HTML of the children:
+## Using RPC
-- `<cache>` with specified `key` and `maxAge`
-- `<static>` for elements that rarely change, such as `<svg>`
+mono-jsx provides a built-in RPC API that allows you to call functions on the server from the client side. You can use the `createRPC` function to create a RPC object that contains the functions you want to call on the client side, and then pass it to the `expose` prop on the root `<html>` element.
 ```tsx
-function BlogPage() {
+import { createRPC } from "mono-jsx"
+const rpc = createRPC({
+  whoami: () => ({ name: "John" })
+})
+function App(this: FC<{ user?: { name: string } }>) {
   return (
-    <cache key="blog" maxAge={86400}>
-      <Blog />
-    </cache>
+    <div>
+      <show when={this.user}>
+        <p>Welcome, {this.user!.name}!</p>
+      </show>
+      <button onClick={async () => this.user = await rpc.whoami()}>Who am I?</button>
+    </div>
   )
 }
-function Icon() {
+export default {
+  fetch: (req) => (
+    <html request={req} expose={{ rpc }}>
+      <App />
+    </html>
+  )
+}
+```
+> [!NOTE]
+> mono-jsx sends the rpc invoke result to the client side as a JSON object.
+### Accessing request info in RPC functions
+You can access the request info in RPC functions by using the `this` scope:
+- `this.request`: The [request](#accessing-request-info) object.
+- `this.context`: The [context](#using-context) object.
+- `this.session`: The [session](#session-storage-api) storage.
+```tsx
+type Admin = {
+  isAdmin: (id: number) => boolean;
+}
+const rpc = createRPC({
+  whoami: function (this: WithContext<RPC, { admin: Admin }>) {
+    const { admin } = this.context;
+    const user =  this.session.get<{ name: string }>("user")
+    return {
+      ip: this.request.headers.get("x-real-ip"),
+      isAdmin: user ? admin.isAdmin(user.id) : false,
+      user: user,
+    }
+  },
+})
+function App(this: FC) {
   return (
-    <static>
-      <svg>...</svg>
-    </static>
+    <button onClick={async () => console.log(await rpc.whoami())}>Who am I?</button>
   )
 }
+export default {
+  fetch: (req) => (
+    <html
+      request={req}
+      expose={{ rpc }}
+      session={{ cookie: { secret: "..." } }}
+      context={{ admin: { isAdmin: (id: number) => id === 1 } }}
+    >
+      <App />
+    </html>
+  )
+}
+```
+To use `this` in RPC functions, you can't use the arrow function syntax. You need to use the function declaration syntax. And the `RPC` type is defined as follows:
+```ts
+type RPC<Context extends Record<string, unknown> = {}> = {
+  request: Request;
+  context: Context;
+  session: Session;
+}
 ```
 ## Customizing HTML Response

package/index.mjs CHANGED Viewed

@@ -1,9 +1,6 @@
 // index.ts
 function buildRoutes(handler) {
   const { routes = {} } = handler(/* @__PURE__ */ Symbol.for("mono.setup"));
-  return monoRoutes(routes, handler);
-}
-function monoRoutes(routes, handler) {
   const handlers = {};
   for (const [path, fc] of Object.entries(routes)) {
     handlers[path] = (request) => {
@@ -13,7 +10,17 @@ function monoRoutes(routes, handler) {
   }
   return handlers;
 }
+var rpcIndex = 0;
+function createRPC(rpcFunctions) {
+  for (const [key, value] of Object.entries(rpcFunctions)) {
+    if (typeof value !== "function") {
+      throw new Error(`createRPC: ${key} is not a function`);
+    }
+  }
+  Reflect.set(rpcFunctions, /* @__PURE__ */ Symbol.for("mono.rpc"), rpcIndex++);
+  return rpcFunctions;
+}
 export {
   buildRoutes,
-  monoRoutes
+  createRPC
 };