@epoch32/visage 0.0.0-stage → 1.0.0

package/src/rpc/types.ts

@@ -0,0 +1,328 @@
+import type { InferSchemaType, SchemaLike, ValidationIssue } from "../form/schema";
+import type {
+  CreateQueryOptions,
+  MutationOptions,
+  MutationResult,
+  QueryResult
+} from "../query/types";
+
+export type RPCErrorCode =
+  | "BAD_REQUEST"
+  | "UNAUTHORIZED"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "METHOD_NOT_ALLOWED"
+  | "TIMEOUT"
+  | "CONFLICT"
+  | "UNPROCESSABLE_CONTENT"
+  | "INTERNAL_SERVER_ERROR";
+
+export type ProcedureType = "query" | "mutation" | "subscription";
+
+export type MiddlewareFn<TContext = any, TNewContext = TContext> = (opts: {
+  ctx: TContext;
+  req: Request;
+  signal: AbortSignal;
+  next: (opts?: { ctx?: TNewContext }) => Promise<any>;
+}) => Promise<any>;
+
+export interface ProcedureOptionsWithInput<
+  TSchema extends SchemaLike<any>,
+  TOutput = any,
+  TContext = any
+> {
+  input: TSchema;
+  output?: SchemaLike<TOutput>;
+  resolve: (opts: {
+    input: InferSchemaType<TSchema>;
+    ctx: TContext;
+    req: Request;
+    signal: AbortSignal;
+  }) => Promise<TOutput> | TOutput | AsyncIterable<TOutput>;
+}
+
+export interface ProcedureOptionsWithoutInput<TOutput = any, TContext = any> {
+  input?: undefined;
+  output?: SchemaLike<TOutput>;
+  resolve: (opts: {
+    input: void;
+    ctx: TContext;
+    req: Request;
+    signal: AbortSignal;
+  }) => Promise<TOutput> | TOutput | AsyncIterable<TOutput>;
+}
+
+export type ProcedureOptions<TInput = any, TOutput = any, TContext = any> = {
+  input?: SchemaLike<TInput>;
+  output?: SchemaLike<TOutput>;
+  resolve: (opts: {
+    input: TInput;
+    ctx: TContext;
+    req: Request;
+    signal: AbortSignal;
+  }) => Promise<TOutput> | TOutput | AsyncIterable<TOutput>;
+};
+
+export interface Procedure<
+  TType extends ProcedureType = ProcedureType,
+  TInput = any,
+  TOutput = any,
+  TContext = any
+> {
+  type: TType;
+  inputSchema?: SchemaLike<TInput>;
+  outputSchema?: SchemaLike<TOutput>;
+  middlewares: MiddlewareFn<any, any>[];
+  resolve: (opts: {
+    input: TInput;
+    ctx: TContext;
+    req: Request;
+    signal: AbortSignal;
+  }) => Promise<TOutput> | TOutput | AsyncIterable<TOutput>;
+}
+
+export type ProcedureRecord = Record<string, Procedure<any, any, any, any> | Router<any, any>>;
+
+export interface Router<TRecord extends ProcedureRecord = ProcedureRecord, TContext = any> {
+  _def: {
+    record: TRecord;
+    middlewares: MiddlewareFn<any, any>[];
+  };
+  query<TName extends string, TSchema extends SchemaLike<any>, TOutput = any>(
+    name: TName,
+    options: ProcedureOptionsWithInput<TSchema, TOutput, TContext>
+  ): Router<
+    TRecord & { [K in TName]: Procedure<"query", InferSchemaType<TSchema>, TOutput, TContext> },
+    TContext
+  >;
+  query<TName extends string, TOutput = any>(
+    name: TName,
+    options: ProcedureOptionsWithoutInput<TOutput, TContext>
+  ): Router<TRecord & { [K in TName]: Procedure<"query", void, TOutput, TContext> }, TContext>;
+
+  mutation<TName extends string, TSchema extends SchemaLike<any>, TOutput = any>(
+    name: TName,
+    options: ProcedureOptionsWithInput<TSchema, TOutput, TContext>
+  ): Router<
+    TRecord & { [K in TName]: Procedure<"mutation", InferSchemaType<TSchema>, TOutput, TContext> },
+    TContext
+  >;
+  mutation<TName extends string, TOutput = any>(
+    name: TName,
+    options: ProcedureOptionsWithoutInput<TOutput, TContext>
+  ): Router<TRecord & { [K in TName]: Procedure<"mutation", void, TOutput, TContext> }, TContext>;
+
+  subscription<TName extends string, TSchema extends SchemaLike<any>, TOutput = any>(
+    name: TName,
+    options: ProcedureOptionsWithInput<TSchema, TOutput, TContext>
+  ): Router<
+    TRecord & {
+      [K in TName]: Procedure<"subscription", InferSchemaType<TSchema>, TOutput, TContext>;
+    },
+    TContext
+  >;
+  subscription<TName extends string, TOutput = any>(
+    name: TName,
+    options: ProcedureOptionsWithoutInput<TOutput, TContext>
+  ): Router<
+    TRecord & { [K in TName]: Procedure<"subscription", void, TOutput, TContext> },
+    TContext
+  >;
+
+  use<TNewContext = TContext>(
+    middleware: MiddlewareFn<TContext, TNewContext>
+  ): Router<TRecord, TNewContext>;
+
+  merge<TPrefix extends string, TSubRecord extends ProcedureRecord>(
+    prefix: TPrefix,
+    router: Router<TSubRecord, TContext>
+  ): Router<TRecord & { [K in TPrefix]: Router<TSubRecord, TContext> }, TContext>;
+}
+
+export interface CORSOptions {
+  origin?: string | string[] | ((origin: string) => boolean | string);
+  methods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+
+export type DynamicHeadersFn = (
+  req: Request,
+  ctx: any
+) => Promise<Record<string, string>> | Record<string, string>;
+
+export type HeadersConfig = Record<string, string> | DynamicHeadersFn;
+
+export interface RouteRule {
+  /**
+   * Response headers to attach to all matching requests.
+   */
+  headers?: HeadersConfig;
+
+  /**
+   * Required request headers. If any are missing, automatically rejects with HTTP 401 Unauthorized.
+   */
+  requireHeaders?: string[];
+
+  /**
+   * Required query parameters. If missing on GET requests, rejects with HTTP 400 Bad Request.
+   */
+  requireParams?: string[];
+
+  /**
+   * Custom guard function for matching requests. Return false or throw RPCError to reject.
+   */
+  guard?: (opts: {
+    req: Request;
+    ctx: any;
+    path: string;
+  }) => Promise<boolean | void> | boolean | void;
+}
+
+export interface FetchHandlerOptions<
+  TRouter extends Router<any, any> = Router<any, any>,
+  TContext = any
+> {
+  router: TRouter;
+  endpoint?: string;
+  createContext?: (opts: { req: Request; extra: any[] }) => Promise<TContext> | TContext;
+  onError?: (opts: { error: any; path?: string; req: Request }) => void;
+  cors?: boolean | CORSOptions;
+  securityHeaders?: boolean | Record<string, string>;
+
+  /**
+   * Declarative pattern rules matching URL paths or procedure names (e.g. "*", "/api/*", "admin.*").
+   * Supports wildcard matching with '*'.
+   */
+  rules?: Record<string, RouteRule> | Array<{ match: string } & RouteRule>;
+}
+
+export type ClientHeadersRule =
+  | Record<string, string>
+  | (() => Promise<Record<string, string>> | Record<string, string>);
+
+export interface ClientOptions {
+  baseUrl: string;
+  fetch?: typeof fetch;
+  headers?:
+    | Record<string, string>
+    | Record<string, ClientHeadersRule>
+    | (() => Promise<Record<string, string>> | Record<string, string>);
+}
+
+export interface SubscriptionCallbacks<TData = any> {
+  onData: (data: TData) => void;
+  onError?: (error: any) => void;
+  onComplete?: () => void;
+}
+
+export interface SubscriptionHandle {
+  unsubscribe: () => void;
+}
+
+export type InferProcedureInput<P> =
+  P extends Procedure<any, infer TInput, any, any> ? TInput : void;
+
+export type InferProcedureOutput<P> =
+  P extends Procedure<any, any, infer TOutput, any> ? TOutput : unknown;
+
+export type ClientQueryMethod<P> =
+  InferProcedureInput<P> extends void | undefined
+    ? (
+        input?: void,
+        options?: { signal?: AbortSignal; headers?: Record<string, string> }
+      ) => Promise<InferProcedureOutput<P>>
+    : (
+        input: InferProcedureInput<P>,
+        options?: { signal?: AbortSignal; headers?: Record<string, string> }
+      ) => Promise<InferProcedureOutput<P>>;
+
+export type ClientMutationMethod<P> =
+  InferProcedureInput<P> extends void | undefined
+    ? (
+        input?: void,
+        options?: { signal?: AbortSignal; headers?: Record<string, string> }
+      ) => Promise<InferProcedureOutput<P>>
+    : (
+        input: InferProcedureInput<P>,
+        options?: { signal?: AbortSignal; headers?: Record<string, string> }
+      ) => Promise<InferProcedureOutput<P>>;
+
+export type ClientSubscriptionMethod<P> =
+  InferProcedureInput<P> extends void | undefined
+    ? (
+        input: void | undefined,
+        callbacks: SubscriptionCallbacks<InferProcedureOutput<P>>
+      ) => SubscriptionHandle
+    : (
+        input: InferProcedureInput<P>,
+        callbacks: SubscriptionCallbacks<InferProcedureOutput<P>>
+      ) => SubscriptionHandle;
+
+export type ClientProcedure<P> =
+  P extends Procedure<"query", infer TInput, infer TOutput, any>
+    ? {
+        query: ClientQueryMethod<P>;
+        createQuery: (
+          input?: TInput | (() => TInput),
+          extra?: Partial<CreateQueryOptions<TOutput, any, TOutput, any>>
+        ) => QueryResult<TOutput, any>;
+        useQuery: (
+          input?: TInput | (() => TInput),
+          extra?: Partial<CreateQueryOptions<TOutput, any, TOutput, any>>
+        ) => QueryResult<TOutput, any>;
+        queryKey: (input?: TInput) => unknown[];
+        queryOptions: (
+          input?: TInput,
+          extra?: Partial<CreateQueryOptions<TOutput, any, TOutput, any>>
+        ) => CreateQueryOptions<TOutput, any, TOutput, any>;
+      }
+    : P extends Procedure<"mutation", infer TInput, infer TOutput, any>
+      ? {
+          mutate: ClientMutationMethod<P>;
+          createMutation: (
+            extra?: Partial<MutationOptions<TOutput, any, TInput, any>>
+          ) => MutationResult<TOutput, any, TInput, any>;
+          useMutation: (
+            extra?: Partial<MutationOptions<TOutput, any, TInput, any>>
+          ) => MutationResult<TOutput, any, TInput, any>;
+          mutationKey: () => unknown[];
+          mutationOptions: (
+            extra?: Partial<MutationOptions<TOutput, any, TInput, any>>
+          ) => MutationOptions<TOutput, any, TInput, any>;
+        }
+      : P extends Procedure<"subscription", any, any, any>
+        ? {
+            subscribe: ClientSubscriptionMethod<P>;
+          }
+        : never;
+
+export type ClientRouter<R> =
+  R extends Router<infer TRecord, any>
+    ? {
+        [K in keyof TRecord]: TRecord[K] extends Procedure<any, any, any, any>
+          ? ClientProcedure<TRecord[K]>
+          : TRecord[K] extends Router<any, any>
+            ? ClientRouter<TRecord[K]>
+            : never;
+      }
+    : never;
+
+export interface RPCResponseSuccess<T = any> {
+  result: {
+    data: T;
+  };
+}
+
+export interface RPCResponseError {
+  error: {
+    code: RPCErrorCode;
+    message: string;
+    issues?: ValidationIssue[];
+    data?: any;
+  };
+}
+
+export type RPCResponse<T = any> = RPCResponseSuccess<T> | RPCResponseError;

package/src/server/hydrate.ts

@@ -0,0 +1,21 @@
+import { type Child, insertChild } from "../dom/render";
+import { createRoot, onCleanup } from "../signals";
+
+/**
+ * Hydrate server-rendered HTML by attaching fine-grained signal subscriptions and event listeners
+ */
+export function hydrate(fn: () => Child, container: HTMLElement | DocumentFragment): () => void {
+  return createRoot((dispose) => {
+    // Adopt / mount fine-grained reactive tree into container
+    container.textContent = "";
+    const node = insertChild(container, fn());
+
+    onCleanup(() => {
+      if (node && node instanceof Node && node.parentNode === container) {
+        container.removeChild(node);
+      }
+    });
+
+    return dispose;
+  });
+}

package/src/server/index.ts

@@ -0,0 +1,10 @@
+export { hydrate } from "./hydrate";
+
+export {
+  renderToStream,
+  type StreamOptions
+} from "./render-to-stream";
+export {
+  renderChildToString,
+  renderToString
+} from "./render-to-string";

package/src/server/render-to-stream.ts

@@ -0,0 +1,31 @@
+import type { Child } from "../dom/render";
+import { renderToString } from "./render-to-string";
+
+export interface StreamOptions {
+  onChunk?: (chunk: string) => void;
+  onError?: (error: any) => void;
+}
+
+/**
+ * Stream HTML chunks progressively using standard Web Streams (ReadableStream)
+ */
+export function renderToStream(
+  fn: () => Child,
+  options?: StreamOptions
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      try {
+        const initialHtml = renderToString(fn);
+        options?.onChunk?.(initialHtml);
+        controller.enqueue(encoder.encode(initialHtml));
+        controller.close();
+      } catch (err) {
+        options?.onError?.(err);
+        controller.error(err);
+      }
+    }
+  });
+}

package/src/server/render-to-string.ts

@@ -0,0 +1,125 @@
+import type { Child } from "../dom/render";
+import { createRoot } from "../signals";
+
+const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function renderChildToString(child: Child): string {
+  if (child === null || child === undefined || child === false || child === true) {
+    return "";
+  }
+
+  if (typeof child === "function") {
+    return renderChildToString((child as () => any)());
+  }
+
+  if (Array.isArray(child)) {
+    return child.map((c) => renderChildToString(c)).join("");
+  }
+
+  if (typeof child === "object" && "nodeType" in child) {
+    if ((child as any).nodeType === 11 && (child as any).childNodes) {
+      return (child as any).childNodes.map((c: any) => renderChildToString(c)).join("");
+    }
+    return (child as any).outerHTML || (child as any).textContent || "";
+  }
+
+  return escapeHtml(String(child));
+}
+
+/**
+ * Synchronously render a Visage component tree to an HTML string
+ */
+export function renderToString(fn: () => Child): string {
+  return createRoot(() => {
+    const result = fn();
+    return renderNodeToString(result);
+  });
+}
+
+function renderNodeToString(node: any): string {
+  if (node === null || node === undefined || node === false || node === true) {
+    return "";
+  }
+
+  if (typeof node === "function") {
+    return renderNodeToString(node());
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((n) => renderNodeToString(n)).join("");
+  }
+
+  if (typeof node === "object" && node !== null) {
+    if (node.nodeType === 11) {
+      return (node.childNodes || []).map((c: any) => renderNodeToString(c)).join("");
+    }
+
+    if ("tagName" in node) {
+      const tag = String(node.tagName).toLowerCase();
+      const isVoid = VOID_ELEMENTS.has(tag);
+
+      let attrStr = "";
+      if (node.attributes instanceof Map) {
+        for (const [k, v] of node.attributes) {
+          attrStr += ` ${k}="${escapeHtml(String(v))}"`;
+        }
+      }
+
+      if (
+        node.style &&
+        typeof node.style === "object" &&
+        !(node.attributes instanceof Map && node.attributes.has("style"))
+      ) {
+        const styleEntries = Object.entries(node.style).filter(
+          ([_, v]) => typeof v === "string" && v.length > 0
+        );
+        if (styleEntries.length > 0) {
+          const styleStr = styleEntries
+            .map(
+              ([k, v]) =>
+                `${k.startsWith("--") ? k : k.replace(/([A-Z])/g, "-$1").toLowerCase()}: ${v}`
+            )
+            .join("; ");
+          attrStr += ` style="${escapeHtml(styleStr)}"`;
+        }
+      }
+
+      if (isVoid) {
+        return `<${tag}${attrStr} />`;
+      }
+
+      const inner = (node.childNodes || []).map((c: any) => renderNodeToString(c)).join("");
+      return `<${tag}${attrStr}>${inner}</${tag}>`;
+    }
+
+    if ("textContent" in node) {
+      return escapeHtml(node.textContent || "");
+    }
+  }
+
+  return escapeHtml(String(node));
+}