@octanejs/app-core 0.0.1

package/types/index.d.ts

@@ -0,0 +1,319 @@
+import type { RuntimePrimitives } from '@ripple-ts/adapter';
+
+// ============================================================================
+// Shared app/config exports
+// ============================================================================
+
+export function defineConfig(options: OctaneConfigOptions): OctaneConfigOptions;
+/** Context.state key for a per-request CSP nonce set by middleware. */
+export const OCTANE_NONCE_STATE_KEY: 'octane.nonce';
+export const DEFAULT_OUTDIR: 'dist';
+export const ENTRY_FILENAME: 'entry.js';
+export function resolveOctaneConfig(
+	raw: OctaneConfigOptions,
+	options?: { requireAdapter?: boolean },
+): ResolvedOctaneConfig;
+
+// ============================================================================
+// Route classes
+// ============================================================================
+
+export class RenderRoute {
+	readonly type: 'render';
+	path: string;
+	entry: RenderRouteEntry;
+	layout?: string;
+	before: Middleware[];
+	status?: number;
+	constructor(options: RenderRouteOptions);
+}
+
+export class ServerRoute {
+	readonly type: 'server';
+	path: string;
+	methods: string[];
+	handler: RouteHandler;
+	before: Middleware[];
+	after: Middleware[];
+	constructor(options: ServerRouteOptions);
+}
+
+export type Route = RenderRoute | ServerRoute;
+
+export interface RouteMatch {
+	route: Route;
+	params: Record<string, string>;
+}
+
+export interface Router {
+	match(method: string, pathname: string): RouteMatch | null;
+}
+
+export function createRouter(routes: Route[]): Router;
+export function get_route_entry_path(entry?: RenderRouteEntry): string | undefined;
+export function get_route_entry_export_name(entry?: RenderRouteEntry): string | undefined;
+export function get_route_entry_id(entry?: RenderRouteEntry): string | undefined;
+export function get_component_export(
+	module: Record<string, unknown>,
+	exportName?: string,
+): Function | null;
+
+// ============================================================================
+// Route options
+// ============================================================================
+
+export interface RenderRouteOptions {
+	/** URL path pattern (e.g., '/', '/posts/:id', '/docs/*slug') */
+	path: string;
+	/** Path to the component entry file, optionally with a preferred named export */
+	entry: RenderRouteEntry;
+	/** Path to the layout component (wraps the entry) */
+	layout?: string;
+	/** Middleware to run before rendering */
+	before?: Middleware[];
+	/**
+	 * HTTP status for the rendered response (default 200). Set 404 on a
+	 * catch-all route so the SSR'd not-found page reports its real status.
+	 */
+	status?: number;
+}
+
+export interface ServerRouteOptions {
+	/** URL path pattern (e.g., '/api/hello', '/api/posts/:id') */
+	path: string;
+	/** HTTP methods to handle (default: ['GET']) */
+	methods?: string[];
+	/** Request handler that returns a Response */
+	handler: RouteHandler;
+	/** Middleware to run before the handler */
+	before?: Middleware[];
+	/** Middleware to run after the handler */
+	after?: Middleware[];
+}
+
+// ============================================================================
+// Context and middleware
+// ============================================================================
+
+export interface Context {
+	/** The incoming Request object */
+	request: Request;
+	/** URL parameters extracted from the route pattern */
+	params: Record<string, string>;
+	/** Parsed URL object */
+	url: URL;
+	/**
+	 * Shared state for passing data between middlewares. Set
+	 * `OCTANE_NONCE_STATE_KEY` (`'octane.nonce'`) to a non-empty string to nonce
+	 * renderer inline scripts, hydration data, and the hydrate module script.
+	 */
+	state: Map<string, unknown>;
+}
+
+export type NextFunction = () => Promise<Response>;
+export type Middleware = (context: Context, next: NextFunction) => Response | Promise<Response>;
+export type RouteHandler = (context: Context) => Response | Promise<Response>;
+
+export function compose(
+	middlewares: Middleware[],
+): (context: Context, finalHandler: () => Promise<Response>) => Promise<Response>;
+export function createContext(request: Request, params: Record<string, string>): Context;
+export function runMiddlewareChain(
+	context: Context,
+	globalMiddlewares: Middleware[],
+	beforeMiddlewares: Middleware[],
+	handler: () => Promise<Response>,
+	afterMiddlewares?: Middleware[],
+): Promise<Response>;
+export function handleServerRoute(
+	route: ServerRoute,
+	context: Context,
+	globalMiddlewares: Middleware[],
+): Promise<Response>;
+export function is_rpc_request(pathname: string): boolean;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export type Component<T = Record<string, any>> = (
+	props: T,
+	scope: any,
+	extra?: any,
+) => string | void;
+
+export type RenderRouteEntry = string | readonly [exportName: string, path: string];
+
+/**
+ * Props every RenderRoute component (and layout) receives: the route params
+ * and the request `url` (pathname + search, origin-free — the client hydrate
+ * entry re-renders with the identical string).
+ */
+export interface RenderRouteProps {
+	params: Record<string, string>;
+	url: string;
+	/**
+	 * Request-scoped middleware state on the server. This Map is intentionally
+	 * absent during browser hydration and is never serialized.
+	 */
+	state?: Map<string, unknown>;
+}
+
+/**
+ * The app hook run by the client hydrate entry BEFORE `hydrateRoot` (config
+ * `router.preHydrate`): commit client-side state the server already resolved —
+ * typically a client router loading its match tree — so the first hydration
+ * pass adopts the same tree the server rendered.
+ */
+export type PreHydrateHook = (info: {
+	url: string;
+	params: Record<string, string>;
+}) => void | Promise<void>;
+
+export interface RootBoundaryOptions {
+	/** Component entry rendered while the root route tree is suspended. */
+	pending?: RenderRouteEntry;
+	/** Component entry rendered when an uncaught root render/effect error reaches the boundary. */
+	catch?: RenderRouteEntry;
+}
+
+export interface OctaneConfigOptions {
+	build?: {
+		/** Output directory for the production build. @default 'dist' */
+		outDir?: string;
+		minify?: boolean;
+		target?: BuildTarget;
+	};
+	adapter?: OctaneAdapter;
+	router?: {
+		routes: Route[];
+		/**
+		 * Project-root module ID (e.g. '/src/pre-hydrate.ts') whose default
+		 * export is a {@link PreHydrateHook}. The client hydrate entry imports it
+		 * and awaits the hook before calling `hydrateRoot`.
+		 */
+		preHydrate?: string;
+	};
+	/**
+	 * Global root pending/catch component entries used by client and SSR roots.
+	 * Paths use project-root module IDs (for example `/src/Pending.tsrx`); a tuple
+	 * selects a named export.
+	 */
+	rootBoundary?: RootBoundaryOptions;
+	/** Global middlewares applied to all routes */
+	middlewares?: Middleware[];
+	platform?: {
+		env: Record<string, string>;
+	};
+	server?: {
+		/**
+		 * Trust `X-Forwarded-Proto` / `X-Forwarded-Host` when deriving the
+		 * request origin. Enable only behind a trusted reverse proxy.
+		 * @default false
+		 */
+		trustProxy?: boolean;
+		/**
+		 * Production SSR mode: 'streaming' (default) flushes the shell at
+		 * first await and streams suspense segments out-of-order (same engine
+		 * as dev SSR); 'buffered' awaits everything (`prerender`) and sends
+		 * one document — for hosts that break streamed responses.
+		 * @default 'streaming'
+		 */
+		render?: 'streaming' | 'buffered';
+	};
+}
+
+/**
+ * Resolved configuration with all defaults applied.
+ */
+export interface ResolvedOctaneConfig {
+	build: {
+		/** @default 'dist' */
+		outDir: string;
+		minify?: boolean;
+		target?: BuildTarget;
+	};
+	adapter?: OctaneAdapter;
+	router: {
+		routes: Route[];
+		preHydrate?: string;
+	};
+	rootBoundary: RootBoundaryOptions;
+	/** @default [] */
+	middlewares: Middleware[];
+	platform: {
+		/** @default {} */
+		env: Record<string, string>;
+	};
+	server: {
+		/** @default false */
+		trustProxy: boolean;
+		/** @default 'streaming' */
+		render: 'streaming' | 'buffered';
+	};
+}
+
+/**
+ * The build context an Octane app integration passes to an adapter after it
+ * produced the client and server bundles.
+ */
+export interface AdaptContext {
+	/** Absolute project root. */
+	root: string;
+	/** The config `build.outDir` (relative to root, e.g. 'dist'). */
+	outDir: string;
+	/** Absolute path of the static client bundle ({outDir}/client). */
+	clientDir: string;
+	/** Absolute path of the server bundle ({outDir}/server, contains entry.js). */
+	serverDir: string;
+	/** Prefixed build logger. */
+	log: (message: string) => void;
+}
+
+/**
+ * The octane.config.ts `adapter` contract. All parts are optional and
+ * independent:
+ *
+ * - `adapt(ctx)` — post-build hook: restructure dist/client + dist/server for
+ *   a deployment target (e.g. @octanejs/adapter-vercel emits `.vercel/output`).
+ * - `serve(handler, opts)` — replaces the generated server entry's built-in
+ *   Node boot when running `node dist/server/entry.js` / `octane-preview`.
+ * - `runtime` — platform primitives (hashing, async context) replacing the
+ *   entry's Node defaults; needed on non-Node runtimes.
+ */
+export interface OctaneAdapter {
+	name?: string;
+	adapt?: (ctx: AdaptContext) => void | Promise<void>;
+	serve?: AdapterServeFunction;
+	runtime?: RuntimePrimitives;
+}
+
+export type AdapterServeFunction = (
+	handler: (request: Request, platform?: unknown) => Response | Promise<Response>,
+	options?: Record<string, unknown>,
+) => { listen: (port?: number) => unknown; close: () => void };
+
+/** A shared syntax accepted by current app integrations and their transpilers. */
+export type BuildTarget = string | string[] | false;
+
+export interface ConfigModuleRunner {
+	loadModule(id: string): Promise<Record<string, unknown>>;
+	getDependencies?(id: string): string[] | Promise<string[]>;
+	getMissingDependencies?(id: string): string[] | Promise<string[]>;
+}
+
+export interface LoadConfigOptions {
+	/** Config filename relative to the project root, or an absolute path. */
+	configFile?: string;
+	requireAdapter?: boolean;
+	moduleRunner?: ConfigModuleRunner | ConfigModuleRunner['loadModule'];
+	/** Directory used for the neutral evaluator's generated ESM module. */
+	cacheDir?: string;
+}
+
+export interface LoadedOctaneConfig {
+	config: ResolvedOctaneConfig;
+	configPath: string;
+	dependencies: string[];
+	missingDependencies: string[];
+}

package/types/middleware.d.ts

@@ -0,0 +1,3 @@
+export { compose, createContext, handleServerRoute, runMiddlewareChain } from '@octanejs/app-core';
+export function is_rpc_request(pathname: string): boolean;
+export type { Context, Middleware, NextFunction, RouteHandler } from '@octanejs/app-core';

package/types/node.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage, ServerResponse, Server } from 'node:http';
+
+/** Convert a Node.js IncomingMessage to a Web Request. */
+export function nodeRequestToWebRequest(nodeRequest: IncomingMessage): Request;
+
+/**
+ * Pipe a Web Response to a Node.js ServerResponse, streaming chunk-by-chunk
+ * (a streaming SSR body flushes as it renders).
+ */
+export function sendWebResponse(nodeResponse: ServerResponse, webResponse: Response): Promise<void>;
+
+/**
+ * Serve a static file from `staticDir` when the request path maps to one.
+ * Vite's `/assets/*` and Rsbuild's `/static/*` hash-named output get immutable
+ * caching; other files revalidate. Returns true when the request was handled.
+ */
+export function serveStaticFile(
+	req: IncomingMessage,
+	res: ServerResponse,
+	staticDir: string,
+): boolean;
+
+/**
+ * Minimal production HTTP server: static files from `staticDir` first (the
+ * built client assets), then the fetch-style SSR handler. The default boot for
+ * `node dist/server/entry.js` when octane.config.ts has no adapter.
+ */
+export function createNodeServer(
+	handler: (request: Request) => Response | Promise<Response>,
+	options?: { staticDir?: string },
+): { listen: (port?: number) => Server; close: () => void };

package/types/production.d.ts

@@ -0,0 +1,98 @@
+import type { RuntimePrimitives } from '@ripple-ts/adapter';
+import type {
+	Route,
+	Middleware,
+	OctaneConfigOptions,
+	ResolvedOctaneConfig,
+	Component,
+} from '@octanejs/app-core';
+import type { RenderResult, StreamOptions, RenderOptions } from 'octane/server';
+
+export function resolveOctaneConfig(
+	raw: OctaneConfigOptions,
+	options?: { requireAdapter?: boolean },
+): ResolvedOctaneConfig;
+
+export interface ClientAssetEntry {
+	/** Path to the built JS file (relative to the client output dir) */
+	js: string;
+	/** Paths to the built CSS files (relative to the client output dir) */
+	css: string[];
+}
+
+export interface ServerManifest {
+	routes: Route[];
+	/** RenderRoute entry module path → module namespace (export picked per-route) */
+	components: Record<string, Record<string, unknown>>;
+	/** Layout module path → module namespace */
+	layouts: Record<string, Record<string, unknown>>;
+	middlewares: Middleware[];
+	/** Trust X-Forwarded-* headers when deriving origin for RPC fetch */
+	trustProxy?: boolean;
+	/** 'streaming' (default) renders via renderToReadableStream; 'buffered' awaits everything via prerender */
+	render?: 'streaming' | 'buffered';
+	/** Resolved server-compiled global boundary components. */
+	rootBoundary?: {
+		pending?: Component | null;
+		catch?: Component<{ error: unknown; reset: () => void }> | null;
+	};
+	/** Import descriptors serialized to the client hydration payload. */
+	rootBoundaryEntries?: {
+		pending: { path: string; exportName: string | null } | null;
+		catch: { path: string; exportName: string | null } | null;
+	};
+	/** config `router.preHydrate`, serialized into #__octane_data for the client entry */
+	preHydrate?: string | null;
+	/** Map of entry path → `module server` namespace for RPC support */
+	rpcModules?: Record<string, Record<string, Function>>;
+	/** Platform primitives (adapter's, or the generated entry's Node defaults) */
+	runtime?: RuntimePrimitives;
+	/** Route entry module path → built client asset paths (preload tags) */
+	clientAssets?: Record<string, ClientAssetEntry>;
+}
+
+export interface HandlerOptions {
+	/** `renderToReadableStream` from 'octane/server' (the streaming engine dev SSR uses) */
+	renderToReadableStream: (
+		component: Function,
+		props?: unknown,
+		options?: StreamOptions,
+	) => Promise<ReadableStream<Uint8Array>>;
+	/** `prerender` from 'octane/static' (the buffered await-everything fallback) */
+	prerender: (
+		component: Function,
+		props?: unknown,
+		options?: RenderOptions,
+	) => Promise<RenderResult>;
+	/** The BUILT dist client index.html (moved to dist/server by the build) */
+	htmlTemplate: string;
+	/** RPC executor from 'octane/server' */
+	executeServerFunction: (fn: Function, body: string) => Promise<string>;
+	/** Boundary primitives from 'octane/server'. */
+	Suspense: Component;
+	ErrorBoundary: Component;
+	createElement: Function;
+}
+
+/**
+ * Production fetch-handler factory. Mirrors the dev middleware's render path
+ * byte-for-byte in everything hydration can see. Repeated calls in one process
+ * refresh the same-origin fetch dispatcher, so a dev server can replace a
+ * hot-reloaded manifest without retaining the first handler.
+ */
+export function createHandler(
+	manifest: ServerManifest,
+	options: HandlerOptions,
+): (request: Request) => Promise<Response>;
+
+export function createPropsWrapper(Page: Component, pageProps: Record<string, unknown>): Component;
+export function createLayoutWrapper(
+	Layout: Component,
+	Page: Component,
+	pageProps: Record<string, unknown>,
+): Component;
+export function createRootBoundaryWrapper(
+	Content: Component,
+	boundary: { pending?: Component | null; catch?: Component | null },
+	runtime: { Suspense: Component; ErrorBoundary: Component; createElement: Function },
+): Component;

package/types/routes.d.ts

@@ -0,0 +1,17 @@
+export {
+	RenderRoute,
+	ServerRoute,
+	createRouter,
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_id,
+	get_route_entry_path,
+} from '@octanejs/app-core';
+export type {
+	RenderRouteEntry,
+	RenderRouteOptions,
+	Route,
+	RouteMatch,
+	Router,
+	ServerRouteOptions,
+} from '@octanejs/app-core';