Module Format Schema

A technology-agnostic module format standard that defines the structure and types for web application modules. This schema provides a foundation for building modular web applications with clear separation of concerns and consistent interfaces.

Overview

This package defines TypeScript type definitions for a standardized module format that enables:

- Route Modules: Handle HTTP requests and render pages
- Widget Modules: Reusable components that work on both server and client
- Action Modules: Server-side functions callable from the client
- Middleware Modules: Request processing and context modification
- HTTP Types: Standard HTTP request/response handling
- Metadata Types: HTML document metadata management
- Rendering Types: Server-side and client-side rendering interfaces

Module Types

$3

Route modules handle HTTP requests and define page endpoints. They can contain components, handlers, metadata, and rendering logic.

📁 Type Definitions: types/route.d.ts

``typescript
interface RouteModule {
config?: RouteConfig;
default?: RouteComponent;
fallback?: RouteFallbackComponent;
handler?: RouteHandler | RouteHandlers;
meta?: Meta;
render?: ServerRender;
}
`

Key Features:

- HTTP method handlers for different request types
- Server-side rendering with streaming support
- Error handling with fallback components
- Metadata management for HTML head elements
- Type-safe context with request parameters and state

$3

Widget modules are reusable components that can be embedded in different contexts. They support both server-side and client-side rendering.

📁 Type Definitions: types/widget.d.ts

`typescript
type WidgetModule = ServerWidgetModule | ClientWidgetModule;

interface ServerWidgetModule {
default?: unknown;
meta?: Meta;
render?: ServerRender;
}

interface ClientWidgetModule {
default?: unknown;
meta?: Meta;
render?: ClientRender;
}
`

Key Features:

- Isomorphic components that work on server and client
- Progressive hydration support
- Lifecycle management for client-side rendering
- Metadata integration for dynamic head elements

$3

Action modules contain server-side functions that can be called from the client to perform operations.

📁 Type Definitions: types/action.d.ts

`typescript
interface ActionModule {
[method: string]: ActionHandler;
}

interface ActionHandler {
(...args: A[]): Promise;
}
`

Key Features:

- Type-safe serializable arguments and return values
- Promise-based async operations
- Method-based organization for multiple actions

$3

Middleware modules provide request processing and context modification capabilities.

📁 Type Definitions: types/middleware.d.ts

`typescript
interface MiddlewareModule {
handler?: MiddlewareHandler | MiddlewareHandlers;
}

interface MiddlewareHandler {
(
context: MiddlewareContext,
next: MiddlewareNext
): MiddlewareResult | Promise;
}
`

Key Features:

- HTTP method-specific middleware handlers
- Context modification and state management
- Chainable middleware execution
- Type-safe context and response handling

Core Types

$3

Standard HTTP request/response handling with error management and state management.

📁 Type Definitions: types/http.d.ts

`typescript
interface FetchContext> {
request: Request;
params: Readonly;
state: State;
error?: HTTPException;
}

interface HTTPException extends Error {
expose?: boolean;
status?: number;
statusText?: string;
}
`

$3

Comprehensive HTML document metadata management for dynamic head elements.

📁 Type Definitions: types/meta.d.ts

`typescript
interface Meta {
title?: string;
description?: string;
link?: LinkDescriptor[];
meta?: MetaDescriptor[];
script?: ScriptDescriptor[];
style?: StyleDescriptor[];
base?: BaseDescriptor;
}
`

$3

Server-side and client-side rendering interfaces with streaming support.

📁 Type Definitions: types/render.d.ts

`typescript
interface ServerRender {
(
component: Component,
data: Data,
options: Options
): Result | Promise;
}

interface ClientRender {
(
component: Component,
data: Data,
options: Options
): Result | Promise;
}
``

Design Principles

$3

The schema is designed to be framework-agnostic, allowing different frontend technologies to implement the same module format while maintaining their unique characteristics.

$3

Comprehensive TypeScript definitions ensure type safety across the entire application stack, from server to client.

$3

Built on web standards like Fetch API, ReadableStream, and standard HTTP methods, ensuring long-term compatibility.

$3

Clear separation of concerns with distinct module types for different responsibilities, enabling better code organization and reusability.

Type Definitions Entry Point

📁 Main Entry: types/index.d.ts - Exports all type definitions

Usage

This schema serves as a foundation for implementing module-based web applications. Framework implementations can use these types to ensure consistency and interoperability across different technology stacks.

The type definitions provide detailed JSDoc comments for each interface and method, making them self-documenting for developers implementing this standard.