@evjs/runtime 0.0.1-alpha.7 → 0.0.1-alpha.8

package/AGENT.md

@@ -0,0 +1,66 @@
+# @evjs/runtime
+
+Core runtime for the ev React framework. Provides client-side routing, data fetching, and server-side handling.
+
+## Client API (`@evjs/runtime/client`)
+
+### App Bootstrap
+- `createApp({ routeTree, routerOptions?, queryClientConfig? })` — Bootstrap Router + Query + DOM. Injects `queryClient` into router context.
+- `createAppRootRoute(options)` — Create root route with typed `context.queryClient` for route loaders.
+
+### Server Function Proxies
+Always use these instead of raw `useQuery`/`useMutation` for server functions:
+
+```tsx
+import { query, mutation, createQueryProxy, createMutationProxy } from "@evjs/runtime/client";
+import { getUsers, createUser } from "./api/users.server";
+
+// Direct wrapper
+const { data } = query(getUsers).useQuery([]);
+const { mutate } = mutation(createUser).useMutation();
+
+// Module proxy
+const api = { query: createQueryProxy({ getUsers }), mutation: createMutationProxy({ createUser }) };
+api.query.getUsers.useQuery([]);
+
+// queryOptions (for loaders, prefetch)
+const opts = query(getUsers).queryOptions([]);
+queryClient.ensureQueryData(opts);
+
+// Query key (for invalidation)
+queryClient.invalidateQueries({ queryKey: query(getUsers).queryKey() });
+```
+
+### Route Loader Pattern
+```tsx
+const rootRoute = createAppRootRoute({ component: Root });
+const usersRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/users",
+  loader: ({ context }) =>
+    context.queryClient.ensureQueryData(query(getUsers).queryOptions([])),
+  component: UsersPage,
+});
+```
+
+### Routing (re-exports from @tanstack/react-router)
+`createRootRoute`, `createRoute`, `createRouter`, `Link`, `Outlet`, `Navigate`, `useParams`, `useSearch`, `useNavigate`, `useLocation`, `useMatch`, `useLoaderData`, `redirect`, `notFound`, `lazyRouteComponent`
+
+### Data (re-exports from @tanstack/react-query)
+`useQuery`, `useMutation`, `useQueryClient`, `useSuspenseQuery`, `QueryClient`, `QueryClientProvider`
+
+### Transport
+```tsx
+import { configureTransport } from "@evjs/runtime/client";
+configureTransport({ transport: { send: async (fnId, args) => { /* custom */ } } });
+```
+
+## Server API (`@evjs/runtime/server`)
+
+- `createApp(options?)` — Create Hono app with RPC middleware.
+- `runNodeServer(app, { port?, host? })` — Start on Node.js (default port 3001).
+- `registerServerFn(fnId, fn)` — Register server function (called by build-tools).
+- `createRpcMiddleware()` — Standalone Hono RPC sub-app.
+
+## Server Functions
+Files must start with `"use server";`, use named async exports, and end in `.server.ts`.

package/esm/client/context.d.ts

@@ -0,0 +1,25 @@
+import type { QueryClient } from "@tanstack/react-query";
+/** Default context available in route loaders. */
+export interface AppRouteContext {
+    queryClient: QueryClient;
+}
+/**
+ * Create a root route with the app's default context (queryClient).
+ *
+ * Use this instead of `createRootRoute` when you want typed access
+ * to `context.queryClient` in `loader` / `beforeLoad`.
+ *
+ * @example
+ * ```tsx
+ * const rootRoute = createAppRootRoute({ component: Root });
+ *
+ * const usersRoute = createRoute({
+ *   getParentRoute: () => rootRoute,
+ *   path: "/users",
+ *   loader: ({ context }) =>
+ *     context.queryClient.ensureQueryData(query(getUsers).queryOptions([])),
+ * });
+ * ```
+ */
+export declare const createAppRootRoute: <TRegister = import("@tanstack/router-core").Register, TRouteContextFn = import("@tanstack/router-core").AnyContext, TBeforeLoadFn = import("@tanstack/router-core").AnyContext, TSearchValidator = undefined, TLoaderDeps extends Record<string, any> = {}, TLoaderFn = undefined, TSSR = unknown, TServerMiddlewares = unknown>(options?: import("@tanstack/router-core").RootRouteOptions<TRegister, TSearchValidator, AppRouteContext, TRouteContextFn, TBeforeLoadFn, TLoaderDeps, TLoaderFn, TSSR, TServerMiddlewares, undefined> | undefined) => import("@tanstack/react-router").RootRoute<TRegister, TSearchValidator, AppRouteContext, TRouteContextFn, TBeforeLoadFn, TLoaderDeps, TLoaderFn, unknown, unknown, TSSR, TServerMiddlewares, undefined>;
+//# sourceMappingURL=context.d.ts.map

package/esm/client/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/client/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,iuBAAgD,CAAC"}

package/esm/client/context.js

@@ -0,0 +1,21 @@
+import { createRootRouteWithContext } from "@tanstack/react-router";
+/**
+ * Create a root route with the app's default context (queryClient).
+ *
+ * Use this instead of `createRootRoute` when you want typed access
+ * to `context.queryClient` in `loader` / `beforeLoad`.
+ *
+ * @example
+ * ```tsx
+ * const rootRoute = createAppRootRoute({ component: Root });
+ *
+ * const usersRoute = createRoute({
+ *   getParentRoute: () => rootRoute,
+ *   path: "/users",
+ *   loader: ({ context }) =>
+ *     context.queryClient.ensureQueryData(query(getUsers).queryOptions([])),
+ * });
+ * ```
+ */
+export const createAppRootRoute = createRootRouteWithContext();
+//# sourceMappingURL=context.js.map

package/esm/client/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/client/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAOpE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,0BAA0B,EAAmB,CAAC"}

package/esm/client/create-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../../src/client/create-app.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EAEvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAIlE;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,UAAU,SAAS,QAAQ;IAC3D,uEAAuE;IACvE,SAAS,EAAE,UAAU,CAAC;IACtB;;OAEG;IACH,aAAa,CAAC,EAAE,IAAI,CAClB,UAAU,CAAC,cAAc,wBAAwB,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,EACnE,WAAW,CACZ,CAAC;IACF;;OAEG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,oCAAoC;IACpC,MAAM,EAAE,SAAS,CAAC;IAClB,0CAA0C;IAC1C,WAAW,EAAE,WAAW,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;CAC/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,UAAU,SAAS,QAAQ,EACnD,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC,GACpC,GAAG,CA+BL"}
+{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../../src/client/create-app.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EAEvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAIlE;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,UAAU,SAAS,QAAQ;IAC3D,uEAAuE;IACvE,SAAS,EAAE,UAAU,CAAC;IACtB;;OAEG;IACH,aAAa,CAAC,EAAE,IAAI,CAClB,UAAU,CAAC,cAAc,wBAAwB,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,EACnE,WAAW,CACZ,CAAC;IACF;;OAEG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,oCAAoC;IACpC,MAAM,EAAE,SAAS,CAAC;IAClB,0CAA0C;IAC1C,WAAW,EAAE,WAAW,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;CAC/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,UAAU,SAAS,QAAQ,EACnD,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC,GACpC,GAAG,CAgCL"}

package/esm/client/create-app.js

@@ -23,6 +23,7 @@ export function createApp(options) {
     const router = createRouter({
         ...routerOptions,
         routeTree,
+        context: { queryClient, ...routerOptions?.context },
     });
     function render(container) {
         const el = typeof container === "string"

package/esm/client/create-app.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-app.js","sourceRoot":"","sources":["../../src/client/create-app.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,WAAW,EAEX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoC9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CACvB,OAAqC;IAErC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAEhE,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,GAAG,aAAa;QAChB,SAAS;KAC4B,CAAC,CAAC;IAEzC,SAAS,MAAM,CAAC,SAA+B;QAC7C,MAAM,EAAE,GACN,OAAO,SAAS,KAAK,QAAQ;YAC3B,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAc,SAAS,CAAC;YAChD,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,IAAI,KAAK,CACb,0CAA0C,MAAM,CAAC,SAAS,CAAC,EAAE,CAC9D,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,CACT,KAAC,mBAAmB,IAAC,MAAM,EAAE,WAAW,YACtC,KAAC,cAAc,IAAC,MAAM,EAAE,MAAM,GAAI,GACd,CACvB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"create-app.js","sourceRoot":"","sources":["../../src/client/create-app.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,WAAW,EAEX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoC9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CACvB,OAAqC;IAErC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC;IAEhE,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,GAAG,aAAa;QAChB,SAAS;QACT,OAAO,EAAE,EAAE,WAAW,EAAE,GAAG,aAAa,EAAE,OAAO,EAAE;KACd,CAAC,CAAC;IAEzC,SAAS,MAAM,CAAC,SAA+B;QAC7C,MAAM,EAAE,GACN,OAAO,SAAS,KAAK,QAAQ;YAC3B,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAc,SAAS,CAAC;YAChD,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,IAAI,KAAK,CACb,0CAA0C,MAAM,CAAC,SAAS,CAAC,EAAE,CAC9D,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,CACT,KAAC,mBAAmB,IAAC,MAAM,EAAE,WAAW,YACtC,KAAC,cAAc,IAAC,MAAM,EAAE,MAAM,GAAI,GACd,CACvB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC"}

package/esm/client/index.d.ts

@@ -2,6 +2,8 @@
  * Client-side runtime utilities.
  */
 export * from "@tanstack/react-query";
+export type { AppRouteContext } from "./context";
+export { createAppRootRoute } from "./context";
 export type { App, CreateAppOptions } from "./create-app";
 export { createApp } from "./create-app";
 export * from "./query";

package/esm/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,YAAY,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/esm/client/index.js

@@ -2,6 +2,7 @@
  * Client-side runtime utilities.
  */
 export * from "@tanstack/react-query";
+export { createAppRootRoute } from "./context";
 export { createApp } from "./create-app";
 export * from "./query";
 export * from "./route";

package/esm/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AAEtC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AAMxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AAEtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AAMxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evjs/runtime",
-  "version": "0.0.1-alpha.7",
+  "version": "0.0.1-alpha.8",
   "description": "",
   "dependencies": {
     "@hono/node-server": "^1.19.11",
@@ -54,6 +54,7 @@
     "prepublishOnly": "npm run build"
   },
   "files": [
-    "esm"
+    "esm",
+    "AGENT.md"
   ]
 }