@epoch32/visage 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,142 @@
 {
   "name": "@epoch32/visage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Lightning-fast, zero-VDOM, fine-grained reactive UI library with full TypeScript support",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./signals": {
+      "types": "./src/signals/index.ts",
+      "import": "./src/signals/index.ts"
+    },
+    "./dom": {
+      "types": "./src/dom/index.ts",
+      "import": "./src/dom/index.ts"
+    },
+    "./router": {
+      "types": "./src/router/index.ts",
+      "import": "./src/router/index.ts"
+    },
+    "./template": {
+      "types": "./src/template/index.ts",
+      "import": "./src/template/index.ts"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "import": "./src/server/index.ts"
+    },
+    "./form": {
+      "types": "./src/form/index.ts",
+      "import": "./src/form/index.ts"
+    },
+    "./virtual": {
+      "types": "./src/virtual/index.ts",
+      "import": "./src/virtual/index.ts"
+    },
+    "./query": {
+      "types": "./src/query/index.ts",
+      "import": "./src/query/index.ts"
+    },
+    "./rpc": {
+      "types": "./src/rpc/index.ts",
+      "import": "./src/rpc/index.ts"
+    },
+    "./api": {
+      "types": "./src/api/index.ts",
+      "import": "./src/api/index.ts"
+    },
+    "./style": {
+      "types": "./src/style/index.ts",
+      "import": "./src/style/index.ts"
+    },
+    "./devtools": {
+      "types": "./src/devtools/index.ts",
+      "import": "./src/devtools/index.ts"
+    },
+    "./vite": {
+      "types": "./src/vite/index.ts",
+      "import": "./src/vite/index.ts"
+    },
+    "./ui": {
+      "types": "./src/ui/index.ts",
+      "import": "./src/ui/index.ts"
+    },
+    "./charts": {
+      "types": "./src/charts/index.ts",
+      "import": "./src/charts/index.ts"
+    },
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime/index.ts",
+      "import": "./src/jsx-runtime/index.ts"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./src/jsx-runtime/index.ts",
+      "import": "./src/jsx-runtime/index.ts"
+    }
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Epoch32/visage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Epoch32/visage/issues"
+  },
+  "homepage": "https://github.com/Epoch32/visage#readme",
+  "author": "Epoch32",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts src/signals/index.ts src/dom/index.ts src/template/index.ts src/api/index.ts src/rpc/index.ts src/query/index.ts src/style/index.ts src/devtools/index.ts src/ui/index.ts src/virtual/index.ts src/form/index.ts src/server/index.ts src/router/index.ts src/vite/index.ts src/jsx-runtime/index.ts src/charts/index.ts --outdir dist/",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:vitest": "vitest run",
+    "typecheck": "bun x tsc --noEmit",
+    "check": "bun x @biomejs/biome check --write .",
+    "check:ci": "bun x @biomejs/biome check .",
+    "lint": "bun x @biomejs/biome lint .",
+    "format": "bun x @biomejs/biome format --write .",
+    "verify": "bun test && bun run build",
+    "prepublishOnly": "bun run verify",
+    "example:survey": "bun examples/survey/server.ts",
+    "example:ui": "vite examples/ui-showcase",
+    "example:charts": "vite examples/charts-showcase",
+    "example:auth": "vite examples/enterprise-auth",
+    "example:api": "bun examples/api-showcase/server.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "csstype": "^3.2.3",
+    "lucide": "^1.54.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "keywords": [
+    "reactive",
+    "signals",
+    "no-vdom",
+    "jsx",
+    "ssr",
+    "form",
+    "validation",
+    "router",
+    "template",
+    "typescript",
+    "ui"
+  ],
+  "license": "MPL-2.0"
+}

package/src/api/client.ts

@@ -0,0 +1,371 @@
+/**
+ * Visage File-Based API Typed Client SDK (visage/api)
+ */
+import { createMutation } from "../query/create-mutation";
+import { createQuery } from "../query/create-query";
+import { RPCError } from "../rpc/error";
+import { matchesRulePattern } from "../rpc/server";
+import type {
+  ApiCallOptions,
+  ApiClient,
+  ApiClientOptions,
+  ApiSubscriptionCallbacks,
+  ApiSubscriptionHandle
+} from "./types";
+
+async function resolveHeaders(
+  headers?: ApiClientOptions["headers"],
+  fullPath = ""
+): Promise<Record<string, string>> {
+  if (!headers) return {};
+  if (typeof headers === "function") {
+    return await headers();
+  }
+
+  const result: Record<string, string> = {};
+  for (const [key, val] of Object.entries(headers)) {
+    if (typeof val === "object" || typeof val === "function") {
+      if (matchesRulePattern(key, fullPath, fullPath)) {
+        const resolved = typeof val === "function" ? await val() : val;
+        if (resolved && typeof resolved === "object") {
+          Object.assign(result, resolved);
+        }
+      }
+    } else if (typeof val === "string") {
+      result[key] = val;
+    }
+  }
+  return result;
+}
+
+function buildUrl(baseUrl: string, pathSegments: string[], queryParams?: unknown): string {
+  const cleanBase = baseUrl.replace(/\/+$/, "");
+  const cleanPath = pathSegments.filter(Boolean).join("/");
+  let url = cleanPath ? `${cleanBase}/${cleanPath}` : cleanBase;
+
+  if (queryParams !== undefined && queryParams !== null) {
+    if (typeof queryParams === "object") {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(queryParams as Record<string, any>)) {
+        if (v !== undefined && v !== null) {
+          if (typeof v === "object") {
+            params.set(k, JSON.stringify(v));
+          } else {
+            params.set(k, String(v));
+          }
+        }
+      }
+      const qs = params.toString();
+      if (qs) {
+        url += `${url.includes("?") ? "&" : "?"}${qs}`;
+      }
+    } else {
+      url += `${url.includes("?") ? "&" : "?"}input=${encodeURIComponent(String(queryParams))}`;
+    }
+  }
+
+  return url;
+}
+
+function createApiProxy(options: ApiClientOptions, path: string[] = []): any {
+  const handlerFn = (...args: any[]) => {
+    if (args.length > 0) {
+      return createApiProxy(options, [...path, String(args[0])]);
+    }
+    return createApiProxy(options, path);
+  };
+
+  return new Proxy(handlerFn, {
+    get(_target, prop: string) {
+      if (prop === "then") return undefined;
+
+      const fullPath = path.join("/");
+
+      // 1. GET Method
+      if (prop === "get") {
+        return async (input?: unknown, callOpts?: ApiCallOptions) => {
+          const fetchFn = options.fetch ?? globalThis.fetch;
+          const url = buildUrl(options.baseUrl, path, input);
+          const dynamicHeaders = await resolveHeaders(options.headers, fullPath);
+          const headers = {
+            Accept: "application/json",
+            ...dynamicHeaders,
+            ...callOpts?.headers
+          };
+
+          const devtools =
+            typeof window !== "undefined" ? (window as any).__VISAGE_DEVTOOLS__ : null;
+          const logId = devtools?.logRpcCall({
+            id: `api_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+            path: fullPath,
+            type: "query",
+            input
+          });
+
+          try {
+            const res = await fetchFn(url, {
+              method: "GET",
+              headers,
+              signal: callOpts?.signal
+            });
+
+            const contentType = res.headers.get("Content-Type") || "";
+            if (contentType.includes("application/json")) {
+              const body = await res.json();
+              if (body && typeof body === "object" && "ok" in body) {
+                if (!body.ok) {
+                  devtools?.updateRpcCall(logId, { status: "error", error: body.error });
+                  throw new RPCError({
+                    code: body.error?.code || "INTERNAL_SERVER_ERROR",
+                    message: body.error?.message || "Request failed",
+                    issues: body.error?.issues
+                  });
+                }
+                devtools?.updateRpcCall(logId, { status: "success", response: body.data });
+                return body.data;
+              }
+              if (!res.ok) {
+                throw new Error(`Request failed with status ${res.status}`);
+              }
+              devtools?.updateRpcCall(logId, { status: "success", response: body });
+              return body;
+            }
+
+            if (!res.ok) {
+              throw new Error(`Request failed with status ${res.status}`);
+            }
+            const text = await res.text();
+            devtools?.updateRpcCall(logId, { status: "success", response: text });
+            return text;
+          } catch (err) {
+            devtools?.updateRpcCall(logId, { status: "error", error: err });
+            throw err;
+          }
+        };
+      }
+
+      // 2. Mutations: POST, PUT, PATCH, DELETE
+      if (
+        prop === "post" ||
+        prop === "put" ||
+        prop === "patch" ||
+        prop === "delete" ||
+        prop === "del"
+      ) {
+        const httpMethod =
+          prop === "del" ? "DELETE" : (prop.toUpperCase() as "POST" | "PUT" | "PATCH" | "DELETE");
+
+        return async (body?: unknown, callOpts?: ApiCallOptions) => {
+          const fetchFn = options.fetch ?? globalThis.fetch;
+          const url = buildUrl(options.baseUrl, path);
+          const dynamicHeaders = await resolveHeaders(options.headers, fullPath);
+          const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...dynamicHeaders,
+            ...callOpts?.headers
+          };
+
+          const devtools =
+            typeof window !== "undefined" ? (window as any).__VISAGE_DEVTOOLS__ : null;
+          const logId = devtools?.logRpcCall({
+            id: `api_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+            path: fullPath,
+            type: "mutation",
+            input: body
+          });
+
+          try {
+            const res = await fetchFn(url, {
+              method: httpMethod,
+              headers,
+              body: body !== undefined ? JSON.stringify(body) : undefined,
+              signal: callOpts?.signal
+            });
+
+            const contentType = res.headers.get("Content-Type") || "";
+            if (contentType.includes("application/json")) {
+              const resBody = await res.json();
+              if (resBody && typeof resBody === "object" && "ok" in resBody) {
+                if (!resBody.ok) {
+                  devtools?.updateRpcCall(logId, { status: "error", error: resBody.error });
+                  throw new RPCError({
+                    code: resBody.error?.code || "INTERNAL_SERVER_ERROR",
+                    message: resBody.error?.message || "Request failed",
+                    issues: resBody.error?.issues
+                  });
+                }
+                devtools?.updateRpcCall(logId, { status: "success", response: resBody.data });
+                return resBody.data;
+              }
+              if (!res.ok) {
+                throw new Error(`Request failed with status ${res.status}`);
+              }
+              devtools?.updateRpcCall(logId, { status: "success", response: resBody });
+              return resBody;
+            }
+
+            if (!res.ok) {
+              throw new Error(`Request failed with status ${res.status}`);
+            }
+            const text = await res.text();
+            devtools?.updateRpcCall(logId, { status: "success", response: text });
+            return text;
+          } catch (err) {
+            devtools?.updateRpcCall(logId, { status: "error", error: err });
+            throw err;
+          }
+        };
+      }
+
+      // 3. SSE Subscriptions
+      if (prop === "subscribe") {
+        return (input: unknown, callbacks: ApiSubscriptionCallbacks): ApiSubscriptionHandle => {
+          const fetchFn = options.fetch ?? globalThis.fetch;
+          const url = buildUrl(options.baseUrl, path, input);
+          const controller = new AbortController();
+
+          const devtools =
+            typeof window !== "undefined" ? (window as any).__VISAGE_DEVTOOLS__ : null;
+          const logId = devtools?.logRpcCall({
+            id: `api_sse_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+            path: fullPath,
+            type: "subscription",
+            input
+          });
+
+          (async () => {
+            try {
+              const dynamicHeaders = await resolveHeaders(options.headers, fullPath);
+              const headers = {
+                Accept: "text/event-stream",
+                ...dynamicHeaders
+              };
+
+              const res = await fetchFn(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal
+              });
+
+              if (!res.ok || !res.body) {
+                throw new Error(`SSE stream failed with status ${res.status}`);
+              }
+
+              const reader = res.body.getReader();
+              const decoder = new TextDecoder();
+              let buffer = "";
+
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n\n");
+                buffer = lines.pop() ?? "";
+
+                for (const line of lines) {
+                  const trimmed = line.trim();
+                  if (trimmed.startsWith("data:")) {
+                    const jsonStr = trimmed.slice(5).trim();
+                    try {
+                      const parsed = JSON.parse(jsonStr);
+                      devtools?.logRpcEvent(logId, parsed);
+                      callbacks.onData(parsed);
+                    } catch (parseErr) {
+                      devtools?.updateRpcCall(logId, { status: "error", error: parseErr });
+                      callbacks.onError?.(parseErr);
+                    }
+                  } else if (trimmed.startsWith("event: error")) {
+                    devtools?.updateRpcCall(logId, { status: "error" });
+                    callbacks.onError?.(new Error("Server SSE error"));
+                  }
+                }
+              }
+
+              callbacks.onComplete?.();
+            } catch (err: any) {
+              if (!controller.signal.aborted) {
+                callbacks.onError?.(err);
+              }
+            }
+          })();
+
+          return {
+            unsubscribe: () => {
+              controller.abort();
+            }
+          };
+        };
+      }
+
+      // 4. Query Signals Integration
+      if (prop === "queryKey") {
+        return (input?: unknown) => {
+          const resolved = typeof input === "function" ? (input as () => unknown)() : input;
+          const key: unknown[] = [...path];
+          if (resolved !== undefined) key.push(resolved);
+          return key;
+        };
+      }
+
+      if (prop === "queryOptions") {
+        return (input?: unknown, extra?: Record<string, unknown>) => {
+          const resolved = typeof input === "function" ? (input as () => unknown)() : input;
+          const key: unknown[] = [...path];
+          if (resolved !== undefined) key.push(resolved);
+          return {
+            queryKey: key,
+            queryFn: ({ signal }: { signal: AbortSignal }) => {
+              const proxy = createApiProxy(options, path);
+              return proxy.get(resolved, { signal });
+            },
+            ...extra
+          };
+        };
+      }
+
+      if (prop === "createQuery" || prop === "useQuery") {
+        return (input?: unknown, extra?: Record<string, unknown>) => {
+          const proxy = createApiProxy(options, path);
+          return createQuery(() => proxy.queryOptions(input, extra));
+        };
+      }
+
+      // 5. Mutation Signals Integration
+      if (prop === "mutationKey") {
+        return () => [...path];
+      }
+
+      if (prop === "mutationOptions") {
+        return (extra?: Record<string, unknown>) => {
+          return {
+            mutationKey: [...path],
+            mutationFn: (body: unknown) => {
+              const proxy = createApiProxy(options, path);
+              return proxy.post(body);
+            },
+            ...extra
+          };
+        };
+      }
+
+      if (prop === "createMutation" || prop === "useMutation") {
+        return (extra?: Record<string, unknown>) => {
+          const proxy = createApiProxy(options, path);
+          return createMutation(proxy.mutationOptions(extra));
+        };
+      }
+
+      // 6. Nested Route Segment
+      return createApiProxy(options, [...path, prop]);
+    }
+  });
+}
+
+/**
+ * Create a type-safe API client for file-based API routes
+ */
+export function createApiClient<TRoutes = any>(options: ApiClientOptions): ApiClient<TRoutes> {
+  return createApiProxy(options, []) as ApiClient<TRoutes>;
+}

package/src/api/file-router.ts

@@ -0,0 +1,183 @@
+/**
+ * Visage File-Based Router & Middleware Discovery
+ */
+import { parsePragma, shouldApplyMiddleware } from "./pragma";
+import type { ApiProcedure, FileRouteModule, MiddlewareDefinition, RouteMatch } from "./types";
+
+export interface FileRouteEntry {
+  filePath: string;
+  module: FileRouteModule;
+  sourceCode?: string;
+}
+
+/**
+ * Compile a route path pattern into a regex and parameter list
+ * e.g. `/admin/users/:id` or `/admin/files/*slug`
+ */
+export function compileRoutePattern(path: string): { pattern: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  const normalized = path.replace(/\/+$/, "") || "/";
+
+  const regexStr = normalized
+    .replace(/:([a-zA-Z0-9_]+)/g, (_, name) => {
+      paramNames.push(name);
+      return "([^/]+)";
+    })
+    .replace(/\*([a-zA-Z0-9_]+)/g, (_, name) => {
+      paramNames.push(name);
+      return "(.*)";
+    });
+
+  const pattern = new RegExp(`^${regexStr}(?:/)?$`);
+  return { pattern, paramNames };
+}
+
+/**
+ * Normalize a file path to an API URL route path and directory
+ */
+export function normalizeFilePath(rawPath: string): {
+  isMiddleware: boolean;
+  routePath: string;
+  directory: string;
+} {
+  // Strip relative dots and common root folder prefixes
+  const cleaned = rawPath
+    .replace(/^\.\//, "")
+    .replace(/\.(ts|tsx|js|jsx)$/, "")
+    .replace(/^(src\/)?(routes|api)\//, "");
+
+  const parts = cleaned.split("/").filter(Boolean);
+  const fileName = parts.pop() || "";
+  const isMiddleware = fileName === "_middleware";
+
+  const dirParts = [...parts];
+  const directory = `/${dirParts.join("/")}`.replace(/\/+$/, "") || "/";
+
+  if (isMiddleware) {
+    return {
+      isMiddleware: true,
+      routePath: directory,
+      directory
+    };
+  }
+
+  // Handle index files
+  if (fileName !== "index") {
+    // Transform [id] -> :id and [...slug] -> *slug
+    const transformedFile = fileName
+      .replace(/\[\.\.\.([a-zA-Z0-9_]+)\]/g, "*$1")
+      .replace(/\[([a-zA-Z0-9_]+)\]/g, ":$1");
+    parts.push(transformedFile);
+  }
+
+  const routePath = `/${parts.join("/")}`.replace(/\/+$/, "") || "/";
+
+  return {
+    isMiddleware: false,
+    routePath,
+    directory
+  };
+}
+
+/**
+ * Build a file-based routing manifest with hierarchical middleware cascades
+ */
+export function buildFileRouter(
+  files: Record<string, FileRouteModule | { default?: any; [key: string]: any }>,
+  sourceMap: Record<string, string> = {}
+): RouteMatch[] {
+  const middlewaresByDir: MiddlewareDefinition[] = [];
+  const rawRoutes: Array<{
+    filePath: string;
+    routePath: string;
+    directory: string;
+    module: FileRouteModule;
+  }> = [];
+
+  // 1. Separate middlewares and route handlers
+  for (const [filePath, mod] of Object.entries(files)) {
+    const { isMiddleware, routePath, directory } = normalizeFilePath(filePath);
+    const sourceCode = sourceMap[filePath] || "";
+    const pragma = mod.pragma || parsePragma(sourceCode);
+
+    if (isMiddleware) {
+      const mwFn = typeof mod === "function" ? (mod as any) : mod.middleware || mod.default;
+
+      if (typeof mwFn === "function") {
+        middlewaresByDir.push({
+          fn: mwFn,
+          pragma,
+          filePath,
+          directory
+        });
+      }
+    } else {
+      rawRoutes.push({
+        filePath,
+        routePath,
+        directory,
+        module: mod as FileRouteModule
+      });
+    }
+  }
+
+  // 2. Sort middlewares by directory depth & priority
+  middlewaresByDir.sort((a, b) => {
+    const dirA = a.directory || "/";
+    const dirB = b.directory || "/";
+    const depthA = dirA.split("/").filter(Boolean).length;
+    const depthB = dirB.split("/").filter(Boolean).length;
+    if (depthA !== depthB) return depthA - depthB;
+    return (b.pragma.priority ?? 0) - (a.pragma.priority ?? 0);
+  });
+
+  // 3. Assemble routes with applicable cascading middlewares
+  const routes: RouteMatch[] = [];
+
+  for (const raw of rawRoutes) {
+    const applicableMiddlewares = middlewaresByDir.filter((mw) =>
+      shouldApplyMiddleware(mw.pragma, raw.routePath, raw.directory, mw.directory || "/")
+    );
+
+    const { pattern, paramNames } = compileRoutePattern(raw.routePath);
+    const procedures: Record<string, ApiProcedure> = {};
+
+    // Extract procedures or standard export
+    const mod = raw.module;
+    if (mod.default && typeof mod.default === "object" && "type" in mod.default) {
+      procedures.default = mod.default as ApiProcedure;
+    }
+
+    for (const [key, val] of Object.entries(mod)) {
+      if (val && typeof val === "object" && "type" in val && "options" in val) {
+        procedures[key] = val as ApiProcedure;
+      }
+    }
+
+    const handler =
+      typeof mod.default === "function" && !("type" in mod.default)
+        ? (mod.default as (req: Request, ctx: any) => Promise<Response> | Response)
+        : undefined;
+
+    routes.push({
+      pattern,
+      paramNames,
+      routePath: raw.routePath,
+      filePath: raw.filePath,
+      directory: raw.directory,
+      procedures,
+      middlewares: applicableMiddlewares,
+      handler
+    });
+  }
+
+  // 4. Sort routes: static paths before parameterized paths
+  routes.sort((a, b) => {
+    const isParamA = a.routePath.includes(":") || a.routePath.includes("*");
+    const isParamB = b.routePath.includes(":") || b.routePath.includes("*");
+    if (isParamA !== isParamB) return isParamA ? 1 : -1;
+    return b.routePath.length - a.routePath.length;
+  });
+
+  return routes;
+}