mates-fullstack 1.0.0-beta.1

package/dist/server-fn.d.ts

@@ -0,0 +1,323 @@
+/**
+ * mates-ssr — server-fn.ts
+ *
+ * `serverFn` is the only API surface a developer touches to define a server
+ * function.  It is a near-identity wrapper on the server and is NEVER executed
+ * in the browser — the Bun build plugin (`serverFnPlugin` in cli.ts) intercepts
+ * every import of a file inside `src/api/` during `Bun.build()` and replaces
+ * the entire module with lightweight RPC stubs before Bun ever tries to resolve
+ * the file's own imports (db, secrets, fs, etc.).
+ *
+ * ─── Server behaviour ────────────────────────────────────────────────────────
+ *
+ *   import { serverFn } from "mates-ssr";
+ *   export const getUsers = serverFn(async (filter?: string) => {
+ *     return db.query("SELECT * FROM users WHERE name LIKE ?").all(filter);
+ *   });
+ *
+ *   On the server:
+ *     - serverFn() is called once at module-load time.
+ *     - It marks the function with metadata (__isMatesServerFn__, __fnName__)
+ *       so the fn-registry can index it during startup scanning.
+ *     - It returns the original async function unchanged.
+ *     - When called during an SSR render pass (isSSR() === true) the function
+ *       executes directly, in-process, with zero network overhead.
+ *     - When called from a server-side API handler context the function also
+ *       executes directly.
+ *
+ * ─── Client behaviour ────────────────────────────────────────────────────────
+ *
+ *   The Bun plugin rewrites the entire src/api/*.ts module before bundling.
+ *   What the browser receives is:
+ *
+ *     import { __callServerFn } from "mates-ssr/client";
+ *     export const getUsers   = (...args) => __callServerFn("users", "getUsers",   args);
+ *     export const createUser = (...args) => __callServerFn("users", "createUser", args);
+ *
+ *   `serverFn()` itself is never present in client.js.
+ *   The original function body (db queries, secrets, file I/O) is never present
+ *   in client.js.
+ *   The imports of the api file (db, auth, etc.) are never resolved by Bun for
+ *   the browser target — the plugin replaces the file before resolution.
+ *
+ * ─── Type safety ─────────────────────────────────────────────────────────────
+ *
+ *   serverFn() is generic and preserves the full signature of the wrapped
+ *   function:
+ *
+ *     export const getUser = serverFn(async (id: number): Promise<User> => { … });
+ *     //           ^─────── type: (id: number) => Promise<User>
+ *
+ *   The client stub generated by the plugin also accepts the same argument
+ *   types because TypeScript resolves the import from the original .ts source
+ *   file (which has the real types) — only the runtime implementation is
+ *   replaced in the browser bundle.  Types are never stripped by the plugin.
+ *
+ * ─── Error handling ──────────────────────────────────────────────────────────
+ *
+ *   Errors thrown inside a serverFn are:
+ *
+ *   On the server (direct call):
+ *     - Propagated as normal JS exceptions.
+ *     - The caller (asyncAction, onMount, etc.) handles them via try/catch
+ *       or the error atom of asyncAction.
+ *
+ *   On the client (RPC call via __callServerFn):
+ *     - The RPC endpoint catches the error and returns:
+ *         HTTP 500  { "error": "message", "code": "SERVER_FN_ERROR" }
+ *     - __callServerFn re-throws as a plain Error with the server's message.
+ *     - The caller handles it identically to a direct error.
+ *
+ * ─── Constraints ─────────────────────────────────────────────────────────────
+ *
+ *   1. serverFn MUST be used at the top level of a src/api/ file — not inside
+ *      another function, class, or conditional.  The plugin uses a static regex
+ *      scan to extract export names; dynamic usage is not detected.
+ *
+ *   2. Arguments MUST be JSON-serialisable.  The RPC layer uses JSON.stringify
+ *      on the client and JSON.parse on the server.  Dates, Sets, Maps, and class
+ *      instances are not supported without a custom serialiser.
+ *
+ *   3. Return values MUST be JSON-serialisable for the same reason.
+ *
+ *   4. serverFn files must live under the configured apiDir (default: src/api/).
+ *      Files outside that directory are not intercepted by the plugin and will
+ *      not have their server-only imports stripped.
+ *
+ *   5. Do NOT import serverFn files from client-only code that is NOT also
+ *      imported through a src/api/ path.  If you import a serverFn file
+ *      directly in src/client.ts (bypassing the api/ directory convention)
+ *      the plugin will still intercept it by path, but this is a footgun —
+ *      keep all server function definitions inside src/api/.
+ */
+export declare const SERVER_FN_MARKER: unique symbol;
+/** Any async function — the constraint serverFn imposes on its argument. */
+export type AnyAsyncFn = (...args: any[]) => Promise<any>;
+/**
+ * Context injected as the SECOND argument to every server function.
+ *
+ * Convention: (input, { auth, roles, custom }: ServerContext)
+ *
+ * @example
+ * export async function createPost(
+ *   { content }: { content: string },
+ *   { auth }: ServerContext,
+ * ) {
+ *   checkAuth(auth);
+ *   return PostsDAL.create(auth.sub, content);
+ * }
+ *
+ * @example
+ * // No input
+ * export async function getFeed(_: void, { auth }: ServerContext) {
+ *   checkAuth(auth);
+ * }
+ *
+ * @example
+ * // Custom context from onRequest hook
+ * export async function getItems(_: void, { auth, custom }: ServerContext) {
+ *   const tenant = custom.tenant;
+ * }
+ */
+export interface ServerContext {
+    /**
+     * Verified JWT payload for the current request.
+     * null if the request has no valid auth token.
+     */
+    auth: Record<string, any> | null;
+    /**
+     * Role helpers derived from the auth payload.
+     */
+    roles: {
+        /** Returns true if the user has at least one of the given roles */
+        has(...roles: string[]): boolean;
+        /** Returns true if the user has ALL of the given roles */
+        hasAll(...roles: string[]): boolean;
+        /** Returns the raw roles array */
+        list(): string[];
+    };
+    /**
+     * The raw incoming Request object.
+     * Escape hatch for reading headers, URL, etc. not covered by other helpers.
+     */
+    req: Request | null;
+    /**
+     * Custom data set by onRequest hooks via RequestContext.set().
+     * Use this to pass per-request data (tenant, feature flags, etc.) into server functions.
+     */
+    custom: Record<string, any>;
+}
+/**
+ * Run a function with the given ServerContext available via getContext().
+ * Uses AsyncLocalStorage so concurrent requests are properly isolated.
+ * @internal — called by fn-registry's callServerFn
+ */
+export declare function runWithServerContext<T>(ctx: ServerContext, fn: () => T): T;
+/**
+ * Set the server context for the current function call.
+ * @internal — called by fn-registry's callServerFn
+ * @deprecated Use runWithServerContext() instead for async safety.
+ *             Kept for backward compatibility.
+ */
+export declare function setCurrentServerContext(_ctx: ServerContext | null): void;
+/**
+ * Get the current server context.
+ * Used inside server functions to access auth, roles, and the raw request.
+ *
+ * The framework wraps each server function call in `runWithServerContext()`,
+ * which sets up an AsyncLocalStorage scope. `getContext()` reads from
+ * that scope — fully isolated per request even under high concurrency.
+ *
+ * @example
+ * export async function getUsers(filter: string) {
+ *   const { auth } = getContext();
+ *   checkAuth(auth);
+ *   return UsersDAL.getAll(filter);
+ * }
+ */
+export declare function getContext(): ServerContext;
+/**
+ * Strips the trailing ServerContext parameter from a server function type,
+ * producing the type as seen by client callers.
+ *
+ * The framework always injects ServerContext — client callers never pass it.
+ * This type helper makes that explicit in shared type definitions.
+ *
+ * @example
+ * // Server:
+ * export async function getUsers(filter: string, ctx = {} as ServerContext): Promise<User[]> { }
+ *
+ * // Shared types file:
+ * export type GetUsersFn = ClientFn<typeof getUsers>;
+ * // GetUsersFn = (filter: string) => Promise<User[]>
+ */
+export type ClientFn<T extends (...args: any[]) => any> = T extends (...args: infer Args) => infer Return ? Args extends [...infer Rest, ServerContext?] ? (...args: Rest) => Return : (...args: Args) => Return : never;
+/**
+ * Throw this from any server function to send a specific HTTP status,
+ * error message, and optional structured data to the client.
+ *
+ * The client receives an Error with .status, .code, and .data properties.
+ *
+ * @example
+ * // 404 — not found
+ * throw new ServerError(404, "Post not found");
+ *
+ * @example
+ * // 403 — forbidden with extra context
+ * throw new ServerError(403, "Access denied", {
+ *   code: "POST_PRIVATE",
+ *   postId: id,
+ * });
+ *
+ * @example
+ * // 400 — validation / business rule
+ * throw new ServerError(400, "Title too long", {
+ *   code: "TITLE_TOO_LONG",
+ *   max: 200,
+ *   actual: body.title.length,
+ * });
+ *
+ * @example
+ * // 409 — conflict
+ * throw new ServerError(409, "Email already registered", {
+ *   code: "EMAIL_TAKEN",
+ * });
+ */
+export declare class ServerError extends Error {
+    /** HTTP status code sent to the client */
+    readonly status: number;
+    /** Machine-readable error code. Defaults to HTTP status name if not provided. */
+    readonly code: string;
+    /** Extra structured data sent alongside the error. Never throws — always JSON-serializable. */
+    readonly data: Record<string, unknown>;
+    constructor(status: number, message: string, data?: Record<string, unknown> & {
+        code?: string;
+    });
+}
+/**
+ * A server function — the return type of serverFn().
+ *
+ * On the server  : identical to the original function type T.
+ * On the client  : at runtime this is the RPC stub, but TypeScript still sees
+ *                  type T because it reads the .ts source, not the bundle.
+ *
+ * The marker properties are non-enumerable and invisible to callers.
+ */
+export type ServerFn<T extends AnyAsyncFn> = T & {
+    readonly [SERVER_FN_MARKER]: true;
+    /** Module-relative name used by the registry and RPC endpoint. */
+    readonly __fnName__: string;
+};
+/**
+ * Wrap an async function as a server function.
+ *
+ * On the server the original function is returned as-is (with metadata).
+ * In the client bundle the entire module is replaced by the build plugin —
+ * this wrapper is never present in browser code.
+ *
+ * @param fn   The async function to mark as server-only.
+ * @param name Optional explicit name.  When omitted the function's `.name`
+ *             property is used.  Explicit names are useful for minified builds
+ *             or when the inferred name would be ambiguous.
+ *
+ * @example
+ * export const getUsers = serverFn(async (filter?: string) => {
+ *   return db.query("SELECT * FROM users WHERE name LIKE ?").all(filter);
+ * });
+ *
+ * @example
+ * export const createUser = serverFn(
+ *   async (data: { name: string; email: string }) => {
+ *     if (!data.email) throw new Error("email is required");
+ *     return db.query("INSERT INTO users (name,email) VALUES (?,?) RETURNING *")
+ *              .get(data.name, data.email);
+ *   }
+ * );
+ */
+export declare function serverFn<T extends AnyAsyncFn>(fn: T, name?: string): ServerFn<T>;
+/**
+ * Returns true when `value` is a function wrapped with serverFn().
+ *
+ * Useful for the fn-registry scanner and for defensive checks inside the
+ * RPC endpoint handler.
+ */
+export declare function isServerFn(value: unknown): value is ServerFn<AnyAsyncFn>;
+/**
+ * Retrieve the original HTTP Request for the current request context.
+ *
+ * Returns null when called outside a request context (e.g. from a client-side
+ * asyncAction call via the RPC stub).
+ *
+ * @example
+ * export const getProfile = serverFn(async () => {
+ *   const req = getServerContext();
+ *   const token = req?.headers.get("authorization");
+ *   if (!token) throw new Error("Unauthorized");
+ *   return verifyToken(token);
+ * });
+ */
+export declare function getServerContext(): Request | null;
+/**
+ * Convenience helper — read a cookie from the current request context.
+ *
+ * Returns null when called on the client or when the cookie is absent.
+ *
+ * @example
+ * export const getSession = serverFn(async () => {
+ *   const sessionId = getCookie("session_id");
+ *   if (!sessionId) throw new Error("Not authenticated");
+ *   return sessionStore.get(sessionId);
+ * });
+ */
+export declare function getCookie(name: string): string | null;
+/**
+ * Convenience helper — read a request header from the current request context.
+ *
+ * @example
+ * export const getUser = serverFn(async () => {
+ *   const auth = getHeader("authorization");
+ *   return verifyJWT(auth);
+ * });
+ */
+export declare function getHeader(name: string): string | null;
+//# sourceMappingURL=server-fn.d.ts.map

package/dist/server-fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-fn.d.ts","sourceRoot":"","sources":["../src/server-fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAMH,eAAO,MAAM,gBAAgB,eAA2B,CAAC;AAIzD,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAEjC;;OAEG;IACH,KAAK,EAAE;QACL,mEAAmE;QACnE,GAAG,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACjC,0DAA0D;QAC1D,MAAM,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACpC,kCAAkC;QAClC,IAAI,IAAI,MAAM,EAAE,CAAC;KAClB,CAAC;IAEF;;;OAGG;IACH,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC7B;AAwBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAGxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,IAAI,aAAa,CAc1C;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC,SAAS,CAClE,GAAG,IAAI,EAAE,MAAM,IAAI,KAChB,MAAM,MAAM,GACb,IAAI,SAAS,CAAC,GAAG,MAAM,IAAI,EAAE,aAAa,CAAC,CAAC,GAC1C,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GACzB,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GAC3B,KAAK,CAAC;AAIV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;CAUrD;AA2BD;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,GAAG;IAC/C,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,UAAU,EAC3C,EAAE,EAAE,CAAC,EACL,IAAI,CAAC,EAAE,MAAM,GACZ,QAAQ,CAAC,CAAC,CAAC,CAuCb;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,UAAU,CAAC,CAIxE;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,GAAG,IAAI,CAEjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAerD;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErD"}