mates-fullstack 1.0.0-beta.1

package/dist/errors.d.ts

@@ -0,0 +1,146 @@
+/**
+ * mates-fullstack — errors.ts
+ *
+ * Error class hierarchy for server functions.
+ * These errors are serialized over the wire and reconstructed
+ * on the client as the same class — instanceof checks work correctly.
+ *
+ * Throwing these from any server function, main.ts, or middleware
+ * results in a typed JSON error response. Plain Error throws result
+ * in a 500 with the message hidden in production.
+ *
+ * Wire format:
+ *   { __type: "NotFoundError", message: "...", status: 404, ...extra }
+ */
+/**
+ * Base class for all mates-fullstack server errors.
+ * Use AppError or one of the semantic subclasses instead of this directly.
+ */
+export declare class ServerError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+/**
+ * Generic application error. Use when none of the semantic subclasses fit.
+ *
+ * @example
+ * throw new AppError("Payment failed", { status: 402, code: "PAYMENT_FAILED" });
+ */
+export declare class AppError extends ServerError {
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+    });
+}
+/**
+ * Resource not found. Sends HTTP 404.
+ *
+ * @example
+ * throw new NotFoundError("User not found");
+ */
+export declare class NotFoundError extends ServerError {
+    constructor(message?: string);
+}
+/**
+ * Authentication required. Sends HTTP 401.
+ * Use when the caller is not logged in.
+ * Use ForbiddenError when the caller is logged in but lacks permission.
+ *
+ * @example
+ * if (!ctx.auth) throw new AuthError("Not logged in");
+ */
+export declare class AuthError extends ServerError {
+    constructor(message?: string);
+}
+/**
+ * Access denied. Sends HTTP 403.
+ * Use when the caller is authenticated but lacks the required permission.
+ *
+ * @example
+ * if (ctx.auth.role !== "admin") throw new ForbiddenError("Admins only");
+ */
+export declare class ForbiddenError extends ServerError {
+    constructor(message?: string);
+}
+/**
+ * Validation failed. Sends HTTP 400.
+ * Includes a fields map for per-field error messages.
+ *
+ * @example
+ * throw new ValidationError("Invalid input", {
+ *   fields: {
+ *     email: "Must be a valid email address",
+ *     name: "Required",
+ *   }
+ * });
+ */
+export declare class ValidationError extends ServerError {
+    readonly fields: Record<string, string>;
+    constructor(message?: string, options?: {
+        fields?: Record<string, string>;
+    });
+}
+/**
+ * Rate limit exceeded. Sends HTTP 429.
+ * Optionally includes retryAfter (seconds) for the Retry-After header.
+ *
+ * @example
+ * throw new RateLimitError("Too many requests", { retryAfter: 60 });
+ */
+export declare class RateLimitError extends ServerError {
+    readonly retryAfter?: number;
+    constructor(message?: string, options?: {
+        retryAfter?: number;
+    });
+}
+/**
+ * Register a custom error class for client-side reconstruction.
+ * Call this in your addon's setup code.
+ *
+ * @example
+ * registerErrorClass("PaymentError", PaymentError);
+ */
+export declare function registerErrorClass(name: string, ctor: new (...args: any[]) => ServerError): void;
+export interface SerializedError {
+    __type: string;
+    message: string;
+    status: number;
+    code: string;
+    fields?: Record<string, string>;
+    retryAfter?: number;
+    stack?: string;
+}
+/**
+ * Serialize a ServerError (or plain Error) to the wire format.
+ *
+ * Plain Error (not a ServerError) → 500 AppError.
+ * In production, the message is replaced with "Internal Server Error"
+ * and the stack is never included.
+ */
+export declare function serializeError(err: unknown, dev: boolean): SerializedError;
+/**
+ * Reconstruct a ServerError from its wire format.
+ * Used on the client side by the RPC stub.
+ * Unknown __type falls back to AppError.
+ */
+export declare function reconstructError(data: SerializedError): ServerError;
+/**
+ * Returns true if the serialized object looks like a mates error.
+ * Used by the Fetch client to distinguish error responses from
+ * regular non-ok responses.
+ */
+export declare function isMatesError(data: unknown): data is SerializedError;
+/**
+ * Get the HTTP status code for a throw value.
+ * Returns 500 for unknown throws.
+ */
+export declare function getErrorStatus(err: unknown): number;
+/**
+ * Browser-side ESM module served at /_mates/errors.js.
+ *
+ * Kept here, next to the canonical error hierarchy, so virtual dev/prod helper
+ * generation cannot silently drift from the public client decoder behavior.
+ */
+export declare const BROWSER_ERRORS_JS: string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQ1D;AAID;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,WAAW;gBAErC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;CAKnD;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBAChC,OAAO,SAAc;CAIlC;AAED;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,WAAW;gBAC5B,OAAO,SAAiB;CAIrC;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,WAAW;gBACjC,OAAO,SAAc;CAIlC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAGtC,OAAO,SAAsB,EAC7B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAO;CAMpD;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,OAAO,SAAsB,EAC7B,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;CAMxC;AAkBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,WAAW,GACxC,IAAI,CAEN;AAID,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,eAAe,CA6C1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAuCnE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,eAAe,CASnE;AAuBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAGnD;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAsGjB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,386 @@
+/**
+ * mates-fullstack — errors.ts
+ *
+ * Error class hierarchy for server functions.
+ * These errors are serialized over the wire and reconstructed
+ * on the client as the same class — instanceof checks work correctly.
+ *
+ * Throwing these from any server function, main.ts, or middleware
+ * results in a typed JSON error response. Plain Error throws result
+ * in a 500 with the message hidden in production.
+ *
+ * Wire format:
+ *   { __type: "NotFoundError", message: "...", status: 404, ...extra }
+ */
+// ─── Base ─────────────────────────────────────────────────────────────────────
+/**
+ * Base class for all mates-fullstack server errors.
+ * Use AppError or one of the semantic subclasses instead of this directly.
+ */
+export class ServerError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = this.constructor.name;
+        this.status = status;
+        this.code = code;
+        // Maintain proper prototype chain in transpiled environments
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ─── Concrete error classes ───────────────────────────────────────────────────
+/**
+ * Generic application error. Use when none of the semantic subclasses fit.
+ *
+ * @example
+ * throw new AppError("Payment failed", { status: 402, code: "PAYMENT_FAILED" });
+ */
+export class AppError extends ServerError {
+    constructor(message, options = {}) {
+        super(message, options.status ?? 500, options.code ?? "APP_ERROR");
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Resource not found. Sends HTTP 404.
+ *
+ * @example
+ * throw new NotFoundError("User not found");
+ */
+export class NotFoundError extends ServerError {
+    constructor(message = "Not found") {
+        super(message, 404, "NOT_FOUND");
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Authentication required. Sends HTTP 401.
+ * Use when the caller is not logged in.
+ * Use ForbiddenError when the caller is logged in but lacks permission.
+ *
+ * @example
+ * if (!ctx.auth) throw new AuthError("Not logged in");
+ */
+export class AuthError extends ServerError {
+    constructor(message = "Unauthorized") {
+        super(message, 401, "UNAUTHORIZED");
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Access denied. Sends HTTP 403.
+ * Use when the caller is authenticated but lacks the required permission.
+ *
+ * @example
+ * if (ctx.auth.role !== "admin") throw new ForbiddenError("Admins only");
+ */
+export class ForbiddenError extends ServerError {
+    constructor(message = "Forbidden") {
+        super(message, 403, "FORBIDDEN");
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Validation failed. Sends HTTP 400.
+ * Includes a fields map for per-field error messages.
+ *
+ * @example
+ * throw new ValidationError("Invalid input", {
+ *   fields: {
+ *     email: "Must be a valid email address",
+ *     name: "Required",
+ *   }
+ * });
+ */
+export class ValidationError extends ServerError {
+    fields;
+    constructor(message = "Validation failed", options = {}) {
+        super(message, 400, "VALIDATION_ERROR");
+        this.fields = options.fields ?? {};
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Rate limit exceeded. Sends HTTP 429.
+ * Optionally includes retryAfter (seconds) for the Retry-After header.
+ *
+ * @example
+ * throw new RateLimitError("Too many requests", { retryAfter: 60 });
+ */
+export class RateLimitError extends ServerError {
+    retryAfter;
+    constructor(message = "Too many requests", options = {}) {
+        super(message, 429, "RATE_LIMIT");
+        this.retryAfter = options.retryAfter;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ─── Error registry ───────────────────────────────────────────────────────────
+/**
+ * Maps __type strings to error constructors for client-side reconstruction.
+ * Extendable by addons via registerErrorClass().
+ */
+const _errorRegistry = new Map([
+    ["ServerError", ServerError],
+    ["AppError", AppError],
+    ["NotFoundError", NotFoundError],
+    ["AuthError", AuthError],
+    ["ForbiddenError", ForbiddenError],
+    ["ValidationError", ValidationError],
+    ["RateLimitError", RateLimitError],
+]);
+/**
+ * Register a custom error class for client-side reconstruction.
+ * Call this in your addon's setup code.
+ *
+ * @example
+ * registerErrorClass("PaymentError", PaymentError);
+ */
+export function registerErrorClass(name, ctor) {
+    _errorRegistry.set(name, ctor);
+}
+/**
+ * Serialize a ServerError (or plain Error) to the wire format.
+ *
+ * Plain Error (not a ServerError) → 500 AppError.
+ * In production, the message is replaced with "Internal Server Error"
+ * and the stack is never included.
+ */
+export function serializeError(err, dev) {
+    // Known server error — serialize faithfully
+    if (err instanceof ServerError) {
+        const serialized = {
+            __type: err.constructor.name,
+            message: err.message,
+            status: err.status,
+            code: err.code,
+        };
+        // Include subclass-specific fields
+        if (err instanceof ValidationError && Object.keys(err.fields).length > 0) {
+            serialized.fields = err.fields;
+        }
+        if (err instanceof RateLimitError && err.retryAfter !== undefined) {
+            serialized.retryAfter = err.retryAfter;
+        }
+        // Stack only in development
+        if (dev && err.stack) {
+            serialized.stack = err.stack;
+        }
+        // Safety: ensure the serialized object is JSON-safe
+        return _safeSerialize(serialized);
+    }
+    // Plain Error or unknown throw — hide details in production
+    if (err instanceof Error) {
+        return {
+            __type: "AppError",
+            message: dev ? err.message : "Internal Server Error",
+            status: 500,
+            code: "INTERNAL_ERROR",
+            ...(dev && err.stack ? { stack: err.stack } : {}),
+        };
+    }
+    // Non-Error throw (string, number, etc.)
+    return {
+        __type: "AppError",
+        message: dev ? String(err) : "Internal Server Error",
+        status: 500,
+        code: "INTERNAL_ERROR",
+    };
+}
+/**
+ * Reconstruct a ServerError from its wire format.
+ * Used on the client side by the RPC stub.
+ * Unknown __type falls back to AppError.
+ */
+export function reconstructError(data) {
+    const Ctor = _errorRegistry.get(data.__type);
+    if (!Ctor) {
+        // Unknown type — reconstruct as AppError
+        const err = new AppError(data.message, {
+            status: data.status,
+            code: data.code,
+        });
+        return err;
+    }
+    // Reconstruct using the registered constructor
+    let err;
+    if (Ctor === ValidationError) {
+        err = new ValidationError(data.message, { fields: data.fields ?? {} });
+    }
+    else if (Ctor === RateLimitError) {
+        err = new RateLimitError(data.message, { retryAfter: data.retryAfter });
+    }
+    else if (Ctor === AppError) {
+        err = new AppError(data.message, { status: data.status, code: data.code });
+    }
+    else {
+        // NotFoundError, AuthError, ForbiddenError, custom classes
+        try {
+            err = new Ctor(data.message);
+        }
+        catch {
+            err = new AppError(data.message, {
+                status: data.status,
+                code: data.code,
+            });
+        }
+    }
+    // Restore stack if present (development)
+    if (data.stack) {
+        err.stack = data.stack;
+    }
+    return err;
+}
+/**
+ * Returns true if the serialized object looks like a mates error.
+ * Used by the Fetch client to distinguish error responses from
+ * regular non-ok responses.
+ */
+export function isMatesError(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "__type" in data &&
+        "message" in data &&
+        "status" in data &&
+        "code" in data);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Ensure serialized error data is JSON-safe.
+ * Strips any circular references or non-serializable values.
+ */
+function _safeSerialize(obj) {
+    try {
+        JSON.stringify(obj);
+        return obj;
+    }
+    catch {
+        // Fallback: rebuild with only safe scalar fields
+        return {
+            __type: obj.__type,
+            message: typeof obj.message === "string" ? obj.message : "Error",
+            status: typeof obj.status === "number" ? obj.status : 500,
+            code: typeof obj.code === "string" ? obj.code : "ERROR",
+        };
+    }
+}
+/**
+ * Get the HTTP status code for a throw value.
+ * Returns 500 for unknown throws.
+ */
+export function getErrorStatus(err) {
+    if (err instanceof ServerError)
+        return err.status;
+    return 500;
+}
+/**
+ * Browser-side ESM module served at /_mates/errors.js.
+ *
+ * Kept here, next to the canonical error hierarchy, so virtual dev/prod helper
+ * generation cannot silently drift from the public client decoder behavior.
+ */
+export const BROWSER_ERRORS_JS = /* js */ `
+export class ServerError extends Error {
+  constructor(message, status = 500, code = "ERROR") {
+    super(message);
+    this.name = this.constructor.name;
+    this.status = status;
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class AppError extends ServerError {
+  constructor(message, options = {}) {
+    super(message, options.status ?? 500, options.code ?? "APP_ERROR");
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class NotFoundError extends ServerError {
+  constructor(message = "Not found") {
+    super(message, 404, "NOT_FOUND");
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class AuthError extends ServerError {
+  constructor(message = "Unauthorized") {
+    super(message, 401, "UNAUTHORIZED");
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class ForbiddenError extends ServerError {
+  constructor(message = "Forbidden") {
+    super(message, 403, "FORBIDDEN");
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class ValidationError extends ServerError {
+  constructor(message = "Validation failed", options = {}) {
+    super(message, 400, "VALIDATION_ERROR");
+    this.fields = options.fields ?? {};
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class RateLimitError extends ServerError {
+  constructor(message = "Too many requests", options = {}) {
+    super(message, 429, "RATE_LIMIT");
+    this.retryAfter = options.retryAfter;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isMatesError(data) {
+  return typeof data === "object" &&
+    data !== null &&
+    "__type" in data &&
+    "message" in data &&
+    "status" in data &&
+    "code" in data;
+}
+
+export function reconstructError(data) {
+  let err;
+  switch (data.__type) {
+    case "ValidationError":
+      err = new ValidationError(data.message, { fields: data.fields ?? {} });
+      break;
+    case "RateLimitError":
+      err = new RateLimitError(data.message, { retryAfter: data.retryAfter });
+      break;
+    case "NotFoundError":
+      err = new NotFoundError(data.message);
+      break;
+    case "AuthError":
+      err = new AuthError(data.message);
+      break;
+    case "ForbiddenError":
+      err = new ForbiddenError(data.message);
+      break;
+    case "AppError":
+      err = new AppError(data.message, { status: data.status, code: data.code });
+      break;
+    case "ServerError":
+      err = new ServerError(data.message, data.status, data.code);
+      break;
+    default:
+      err = new AppError(data.message ?? "Unknown error", {
+        status: data.status,
+        code: data.code,
+      });
+      break;
+  }
+  if (data.stack) err.stack = data.stack;
+  return err;
+}
+
+export function getErrorStatus(err) {
+  return err instanceof ServerError ? err.status : 500;
+}
+`.trimStart();
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/head.d.ts

@@ -0,0 +1,31 @@
+/**
+ * mates-fullstack — head.ts
+ *
+ * Builds the final HTML page by reading client/index.html as a template and
+ * replacing three markers:
+ *   - <!-- mates:css -->     → CSS bundle link
+ *   - <!-- mates:ssr -->     → SSR-rendered app HTML
+ *   - <!-- mates:scripts --> → dev helpers + client bundle script
+ */
+export declare const MARKER_CSS = "<!-- mates:css -->";
+export declare const MARKER_SSR = "<!-- mates:ssr -->";
+export declare const MARKER_SCRIPTS = "<!-- mates:scripts -->";
+export interface BuildShellOptions {
+    /** Project root — used to locate client/index.html. */
+    projectRoot: string;
+    /** SSR-rendered app HTML. */
+    bodyHtml: string;
+    /** When true, injects dev-only scripts. */
+    dev?: boolean;
+    /** Browser bundle URL. */
+    clientEntry: string;
+    /** CSS bundle URL. */
+    cssUrl?: string | null;
+    /** CSS-in-JS styles collected during SSR. */
+    ssrStyles?: string | null;
+    /** Dev no-bundle import map for bare package specifiers. */
+    importMap?: Record<string, string> | null;
+}
+export declare function buildShell({ projectRoot, bodyHtml, dev, clientEntry, cssUrl, ssrStyles, importMap, }: BuildShellOptions): string;
+export declare function readIndexHtml(projectRoot: string): string;
+//# sourceMappingURL=head.d.ts.map

package/dist/head.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"head.d.ts","sourceRoot":"","sources":["../src/head.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,eAAO,MAAM,UAAU,uBAAuB,CAAC;AAC/C,eAAO,MAAM,UAAU,uBAAuB,CAAC;AAC/C,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAkLvD,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC3C;AAED,wBAAgB,UAAU,CAAC,EACzB,WAAW,EACX,QAAQ,EACR,GAAW,EACX,WAAW,EACX,MAAM,EACN,SAAS,EACT,SAAgB,GACjB,EAAE,iBAAiB,GAAG,MAAM,CA6C5B;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKzD"}