@fiyuu/core 0.1.0 → 0.2.0

package/src/contracts.ts

@@ -0,0 +1,247 @@
+import { z } from "zod";
+
+export type AnyZodSchema = z.ZodTypeAny;
+
+export interface SchemaContract<TInput extends AnyZodSchema = AnyZodSchema, TOutput extends AnyZodSchema = AnyZodSchema> {
+  input: TInput;
+  output: TOutput;
+  description: string;
+}
+
+export interface ActionDefinition<TInput extends AnyZodSchema = AnyZodSchema, TOutput extends AnyZodSchema = AnyZodSchema>
+  extends SchemaContract<TInput, TOutput> {
+  kind: "action";
+}
+
+export interface QueryDefinition<TInput extends AnyZodSchema = AnyZodSchema, TOutput extends AnyZodSchema = AnyZodSchema>
+  extends SchemaContract<TInput, TOutput> {
+  kind: "query";
+}
+
+export interface QueryCacheConfig {
+  /** Cache TTL in seconds. Set to 0 to disable. */
+  ttl: number;
+  /** Cache key varies by these URL query string parameters. */
+  vary?: string[];
+}
+
+export interface MetaDefinition {
+  intent: string;
+  title?: string;
+  render?: RenderMode;
+  /**
+   * Mark this page as zero-JS.
+   * `fiyuu doctor` will warn if <script> tags are detected in page.tsx.
+   */
+  noJs?: boolean;
+  /**
+   * Revalidate interval in seconds for `render: "ssg"` pages.
+   * Works like ISR: stale HTML is served immediately and refreshed in background.
+   */
+  revalidate?: number;
+  seo?: {
+    title?: string;
+    description?: string;
+  };
+}
+
+export interface PageDefinition {
+  kind: "page";
+  intent: string;
+}
+
+export interface LayoutDefinition {
+  kind: "layout";
+  name?: string;
+}
+
+export type RenderMode = "ssr" | "csr" | "ssg";
+
+export interface PageProps<TData = unknown> {
+  data: TData | null;
+  route: string;
+  intent: string;
+  render: RenderMode;
+  /** Dynamic route parameters extracted from the URL, e.g. { id: "42" } for /blog/[id] */
+  params: Record<string, string>;
+}
+
+export interface LayoutProps {
+  children: string;
+  route: string;
+}
+
+export function defineAction<TInput extends AnyZodSchema, TOutput extends AnyZodSchema>(config: SchemaContract<TInput, TOutput>): ActionDefinition<TInput, TOutput> {
+  return {
+    kind: "action",
+    ...config,
+  };
+}
+
+export function defineQuery<TInput extends AnyZodSchema, TOutput extends AnyZodSchema>(config: SchemaContract<TInput, TOutput>): QueryDefinition<TInput, TOutput> {
+  return {
+    kind: "query",
+    ...config,
+  };
+}
+
+export function definePage(config: { intent: string }): PageDefinition {
+  return {
+    kind: "page",
+    ...config,
+  };
+}
+
+export function defineLayout(config: { name?: string } = {}): LayoutDefinition {
+  return {
+    kind: "layout",
+    ...config,
+  };
+}
+
+export function defineMeta(config: MetaDefinition): MetaDefinition {
+  return config;
+}
+
+// ── Type inference helpers ─────────────────────────────────────────────────
+//
+// Eliminate type duplication between Zod schemas and TypeScript code.
+// Define your schema once in query.ts / action.ts — infer everywhere else.
+//
+// @example  page.tsx
+//   import { query } from "./query.js";
+//   type PageData = InferQueryOutput<typeof query>;  // no manual type needed
+//
+// @example  action.ts execute()
+//   export async function execute({ input, request }: ActionContext<typeof action>) { ... }
+//   // input is fully typed from the action's Zod input schema
+
+/** TypeScript output type inferred from a QueryDefinition's output Zod schema. */
+export type InferQueryOutput<T extends QueryDefinition> = z.infer<T["output"]>;
+
+/** TypeScript input type inferred from a QueryDefinition's input Zod schema. */
+export type InferQueryInput<T extends QueryDefinition> = z.infer<T["input"]>;
+
+/** TypeScript input type inferred from an ActionDefinition's input Zod schema. */
+export type InferActionInput<T extends ActionDefinition> = z.infer<T["input"]>;
+
+/** TypeScript output type inferred from an ActionDefinition's output Zod schema. */
+export type InferActionOutput<T extends ActionDefinition> = z.infer<T["output"]>;
+
+/**
+ * Context passed to query `execute()` functions.
+ *
+ * @example
+ * export async function execute({ request, params }: QueryContext) {
+ *   const sessionId = getSessionIdFromRequest(request as any);
+ *   ...
+ * }
+ */
+export interface QueryContext {
+  /** Incoming HTTP request (Node.js IncomingMessage). Cast to `any` if you need raw access. */
+  request: unknown;
+  /** Dynamic URL parameters, e.g. { id: "42" } for route /blog/[id] */
+  params: Record<string, string>;
+}
+
+/**
+ * Context passed to action `execute()` functions.
+ * Pass `typeof action` as the generic to get fully typed `input`.
+ *
+ * @example
+ * export const action = defineAction({ input: z.object({ title: z.string() }), ... });
+ *
+ * export async function execute({ input, request }: ActionContext<typeof action>) {
+ *   // input.title is typed as string — no manual type annotation needed
+ * }
+ */
+export interface ActionContext<T extends ActionDefinition = ActionDefinition> {
+  /** Action input, typed from the action's Zod input schema. */
+  input: z.infer<T["input"]>;
+  /** Incoming HTTP request (Node.js IncomingMessage). Cast to `any` if you need raw access. */
+  request: unknown;
+  /** Dynamic URL parameters, e.g. { id: "42" } for route /blog/[id] */
+  params: Record<string, string>;
+}
+
+// ── Middleware ─────────────────────────────────────────────────────────────
+//
+// Use `defineMiddleware` to get full type inference without importing from
+// @fiyuu/runtime. All types use `unknown` for Node.js primitives so that
+// @fiyuu/core stays free of @types/node as a required peer dependency.
+
+/**
+ * Context object passed to every middleware handler.
+ *
+ * @example
+ * export const middleware = defineMiddleware(async ({ url, request }, next) => {
+ *   if (url.pathname === "/secret") { ... }
+ *   await next();
+ * });
+ */
+export interface FiyuuMiddlewareContext {
+  /** Incoming HTTP request — Node.js `IncomingMessage`. */
+  request: unknown;
+  /** Parsed request URL. */
+  url: URL;
+  /** Mutable response headers that will be sent with the final response. */
+  responseHeaders: Record<string, string>;
+  /** Unique ID for this request (useful for logging). */
+  requestId: string;
+  /** Non-fatal warnings accumulated during request handling. */
+  warnings: string[];
+}
+
+/**
+ * Return this from a middleware to short-circuit the request.
+ *
+ * @example
+ * // Redirect to login
+ * return {
+ *   headers: { Location: "/auth" },
+ *   response: { status: 302, body: "" },
+ * };
+ */
+export interface FiyuuMiddlewareResult {
+  /** Extra response headers to send (e.g. `Location` for redirects). */
+  headers?: Record<string, string>;
+  response?: {
+    /** HTTP status code. */
+    status?: number;
+    /** JSON body — serialised automatically. */
+    json?: unknown;
+    /** Raw string body. */
+    body?: string;
+  };
+}
+
+/** Call this to continue to the next middleware or the route handler. */
+export type FiyuuMiddlewareNext = () => Promise<void>;
+
+/**
+ * A single middleware function.
+ * Return `FiyuuMiddlewareResult` to short-circuit, or call `next()` to continue.
+ */
+export type FiyuuMiddlewareHandler = (
+  context: FiyuuMiddlewareContext,
+  next: FiyuuMiddlewareNext,
+) => Promise<FiyuuMiddlewareResult | void> | FiyuuMiddlewareResult | void;
+
+/**
+ * Wraps your middleware function and gives it full type inference.
+ * Import from `@fiyuu/core` — no need to touch `@fiyuu/runtime`.
+ *
+ * @example  app/middleware.ts
+ * import { defineMiddleware } from "@fiyuu/core";
+ *
+ * export const middleware = defineMiddleware(async ({ url, request }, next) => {
+ *   if (url.pathname.startsWith("/dashboard")) {
+ *     const user = await getSessionUser(request);
+ *     if (!user) return { headers: { Location: "/auth" }, response: { status: 302, body: "" } };
+ *   }
+ *   await next();
+ * });
+ */
+export function defineMiddleware(handler: FiyuuMiddlewareHandler): FiyuuMiddlewareHandler {
+  return handler;
+}

package/src/{generator.js → generator.ts}

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+
 const PAGE_TEMPLATE = `import { Component } from "@geajs/core";
 import { definePage, html, optimizedImage, responsiveStyle, fluid, type PageProps } from "fiyuu/client";
 
@@ -28,6 +29,7 @@ export default class {{Title}}Page extends Component<PageProps<{{Title}}Data>> {
   }
 }
 `;
+
 const ACTION_TEMPLATE = `import { z } from "zod";
 import { defineAction } from "fiyuu/client";
 
@@ -41,6 +43,7 @@ export async function execute(input: Record<string, unknown>) {
   return { success: true };
 }
 `;
+
 const QUERY_TEMPLATE = `import { z } from "zod";
 import { defineQuery } from "fiyuu/client";
 
@@ -54,6 +57,7 @@ export async function execute() {
   return {};
 }
 `;
+
 const SCHEMA_TEMPLATE = `import { z } from "zod";
 
 export const input = z.object({});
@@ -64,6 +68,7 @@ export const output = z.object({
 
 export const description = "{{description}}";
 `;
+
 const META_TEMPLATE = `import { defineMeta } from "fiyuu/client";
 
 export default defineMeta({
@@ -76,49 +81,71 @@ export default defineMeta({
   },
 });
 `;
-export async function generatePageFeature(appDirectory, featureName) {
-    const featureDirectory = path.join(appDirectory, featureName);
-    await fs.mkdir(featureDirectory, { recursive: true });
-    const title = titleCase(featureName);
-    const intent = `${title} page for user-facing interactions`;
-    const description = `Fetches data for ${title}`;
-    const files = [
-        ["page.tsx", PAGE_TEMPLATE],
-        ["query.ts", QUERY_TEMPLATE],
-        ["schema.ts", SCHEMA_TEMPLATE],
-        ["meta.ts", META_TEMPLATE],
-    ];
-    await Promise.all(files.map(([fileName, template]) => fs.writeFile(path.join(featureDirectory, fileName), hydrate(template, { title, intent, description, Title: pascalCase(featureName) }))));
-    return files.map(([fileName]) => path.join(featureDirectory, fileName));
+
+export async function generatePageFeature(appDirectory: string, featureName: string): Promise<string[]> {
+  const featureDirectory = path.join(appDirectory, featureName);
+  await fs.mkdir(featureDirectory, { recursive: true });
+
+  const title = titleCase(featureName);
+  const intent = `${title} page for user-facing interactions`;
+  const description = `Fetches data for ${title}`;
+  const files = [
+    ["page.tsx", PAGE_TEMPLATE],
+    ["query.ts", QUERY_TEMPLATE],
+    ["schema.ts", SCHEMA_TEMPLATE],
+    ["meta.ts", META_TEMPLATE],
+  ] as const;
+
+  await Promise.all(
+    files.map(([fileName, template]) =>
+      fs.writeFile(path.join(featureDirectory, fileName), hydrate(template, { title, intent, description, Title: pascalCase(featureName) })),
+    ),
+  );
+
+  return files.map(([fileName]) => path.join(featureDirectory, fileName));
 }
-export async function generateActionFeature(appDirectory, featureName) {
-    const featureDirectory = path.join(appDirectory, featureName);
-    await fs.mkdir(featureDirectory, { recursive: true });
-    const title = titleCase(featureName);
-    const intent = `${title} workflow for server-side mutations`;
-    const description = `Performs ${title} mutation`;
-    const files = [
-        ["action.ts", ACTION_TEMPLATE],
-        ["schema.ts", SCHEMA_TEMPLATE],
-        ["meta.ts", META_TEMPLATE],
-    ];
-    await Promise.all(files.map(([fileName, template]) => fs.writeFile(path.join(featureDirectory, fileName), hydrate(template, { title, intent, description, Title: pascalCase(featureName) }))));
-    return files.map(([fileName]) => path.join(featureDirectory, fileName));
+
+export async function generateActionFeature(appDirectory: string, featureName: string): Promise<string[]> {
+  const featureDirectory = path.join(appDirectory, featureName);
+  await fs.mkdir(featureDirectory, { recursive: true });
+
+  const title = titleCase(featureName);
+  const intent = `${title} workflow for server-side mutations`;
+  const description = `Performs ${title} mutation`;
+  const files = [
+    ["action.ts", ACTION_TEMPLATE],
+    ["schema.ts", SCHEMA_TEMPLATE],
+    ["meta.ts", META_TEMPLATE],
+  ] as const;
+
+  await Promise.all(
+    files.map(([fileName, template]) =>
+      fs.writeFile(path.join(featureDirectory, fileName), hydrate(template, { title, intent, description, Title: pascalCase(featureName) })),
+    ),
+  );
+
+  return files.map(([fileName]) => path.join(featureDirectory, fileName));
 }
-function hydrate(template, replacements) {
-    return Object.entries(replacements).reduce((content, [key, value]) => content.replaceAll(`{{${key}}}`, value), template);
+
+function hydrate(template: string, replacements: Record<string, string>): string {
+  return Object.entries(replacements).reduce(
+    (content, [key, value]) => content.replaceAll(`{{${key}}}`, value),
+    template,
+  );
 }
-function titleCase(value) {
-    return value
-        .split(/[\/-]/)
-        .filter(Boolean)
-        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-        .join(" ");
+
+function titleCase(value: string): string {
+  return value
+    .split(/[\/-]/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(" ");
 }
-function pascalCase(value) {
-    return value
-        .split(/[\/-_]/)
-        .filter(Boolean)
-        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-        .join("");
+
+function pascalCase(value: string): string {
+  return value
+    .split(/[\/-_]/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join("");
 }

package/src/media.ts

@@ -0,0 +1,143 @@
+import { escapeHtml } from "./template.js";
+
+export interface OptimizedImageSource {
+  srcSet: string;
+  media?: string;
+  type?: string;
+  sizes?: string;
+}
+
+export interface OptimizedImageProps {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+  sizes?: string;
+  srcSet?: string;
+  sources?: OptimizedImageSource[];
+  loading?: "lazy" | "eager";
+  decoding?: "async" | "sync" | "auto";
+  fetchPriority?: "high" | "low" | "auto";
+  class?: string;
+  style?: string;
+  id?: string;
+}
+
+export interface OptimizedVideoSource {
+  src: string;
+  type?: string;
+  media?: string;
+}
+
+export interface OptimizedVideoProps {
+  src?: string;
+  sources?: OptimizedVideoSource[];
+  poster?: string;
+  preload?: "none" | "metadata" | "auto";
+  controls?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  autoPlay?: boolean;
+  playsInline?: boolean;
+  width?: number;
+  height?: number;
+  class?: string;
+  style?: string;
+  id?: string;
+}
+
+export function optimizedImage(props: OptimizedImageProps): string {
+  const loading = props.loading ?? "lazy";
+  const decoding = props.decoding ?? "async";
+  const fetchPriority = props.fetchPriority ?? "auto";
+  const imageAttributes = [
+    createAttribute("src", props.src),
+    createAttribute("alt", props.alt),
+    createAttribute("loading", loading),
+    createAttribute("decoding", decoding),
+    createAttribute("fetchpriority", fetchPriority),
+    createAttribute("sizes", props.sizes),
+    createAttribute("srcset", props.srcSet),
+    createAttribute("width", props.width),
+    createAttribute("height", props.height),
+    createAttribute("class", props.class),
+    createAttribute("style", props.style),
+    createAttribute("id", props.id),
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const sourceTags = (props.sources ?? [])
+    .map((source) => {
+      const attributes = [
+        createAttribute("srcset", source.srcSet),
+        createAttribute("media", source.media),
+        createAttribute("type", source.type),
+        createAttribute("sizes", source.sizes),
+      ]
+        .filter(Boolean)
+        .join(" ");
+      return `<source ${attributes}>`;
+    })
+    .join("");
+
+  if (sourceTags.length > 0) {
+    return `<picture>${sourceTags}<img ${imageAttributes}></picture>`;
+  }
+
+  return `<img ${imageAttributes}>`;
+}
+
+export function optimizedVideo(props: OptimizedVideoProps): string {
+  const preload = props.preload ?? "metadata";
+  const controls = props.controls ?? true;
+  const playsInline = props.playsInline ?? true;
+  const sources = props.sources && props.sources.length > 0
+    ? props.sources
+    : props.src
+      ? [{ src: props.src }]
+      : [];
+
+  if (sources.length === 0) {
+    throw new Error("optimizedVideo requires either `src` or `sources`.");
+  }
+
+  const videoAttributes = [
+    createAttribute("poster", props.poster),
+    createAttribute("preload", preload),
+    createAttribute("width", props.width),
+    createAttribute("height", props.height),
+    createAttribute("class", props.class),
+    createAttribute("style", props.style),
+    createAttribute("id", props.id),
+    controls ? "controls" : "",
+    props.muted ? "muted" : "",
+    props.loop ? "loop" : "",
+    props.autoPlay ? "autoplay" : "",
+    playsInline ? "playsinline" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const sourceTags = sources
+    .map((source) => {
+      const attributes = [
+        createAttribute("src", source.src),
+        createAttribute("type", source.type),
+        createAttribute("media", source.media),
+      ]
+        .filter(Boolean)
+        .join(" ");
+      return `<source ${attributes}>`;
+    })
+    .join("");
+
+  return `<video ${videoAttributes}>${sourceTags}</video>`;
+}
+
+function createAttribute(name: string, value: string | number | undefined): string {
+  if (value === undefined || value === null || value === "") {
+    return "";
+  }
+  return `${name}="${escapeHtml(value)}"`;
+}