@octanejs/app-core 0.0.1

package/src/config-loader.js

@@ -0,0 +1,307 @@
+// @ts-check
+
+/**
+ * Bundler-neutral loading for `octane.config.ts`.
+ *
+ * Development integrations can inject their own module runner so config
+ * modules participate in the integration's native graph and invalidation.
+ * Build tools and CLIs use the esbuild evaluator, which bundles local config
+ * helpers, compiles imported `.tsrx` files for the server, and reports every
+ * file consulted for watch/cache invalidation.
+ */
+
+/** @import { OctaneConfigOptions, ResolvedOctaneConfig } from '@octanejs/app-core' */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { builtinModules, createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+import { build } from 'esbuild';
+import { compile } from 'octane/compiler';
+
+import { resolveOctaneConfig } from './resolve-config.js';
+
+const DEFAULT_CONFIG_FILE = 'octane.config.ts';
+const OCTANE_EXTENSION_PATTERN = /\.tsrx$/;
+const BUILTINS = new Set([...builtinModules, ...builtinModules.map((id) => `node:${id}`)]);
+
+// Validation + defaults have no compiler/esbuild imports and remain safe to
+// include in production server bundles.
+export { resolveOctaneConfig } from './resolve-config.js';
+
+/**
+ * @typedef {Object} ConfigModuleRunner
+ * @property {(id: string) => Promise<Record<string, unknown>>} loadModule
+ * @property {((id: string) => string[] | Promise<string[]>)} [getDependencies]
+ * @property {((id: string) => string[] | Promise<string[]>)} [getMissingDependencies]
+ */
+
+/**
+ * @typedef {Object} LoadConfigOptions
+ * @property {string} [configFile] Relative to `projectRoot`, or absolute
+ * @property {boolean} [requireAdapter]
+ * @property {ConfigModuleRunner | ((id: string) => Promise<Record<string, unknown>>)} [moduleRunner]
+ * @property {string} [cacheDir] Directory for the evaluated ESM module
+ */
+
+/**
+ * @typedef {Object} LoadedOctaneConfig
+ * @property {ResolvedOctaneConfig} config
+ * @property {string} configPath
+ * @property {string[]} dependencies Existing files that affect the config
+ * @property {string[]} missingDependencies Unresolved files/specifiers consulted while loading
+ */
+
+/**
+ * Return the absolute config path for a project.
+ *
+ * @param {string} projectRoot
+ * @param {string} [configFile]
+ * @returns {string}
+ */
+export function getOctaneConfigPath(projectRoot, configFile = DEFAULT_CONFIG_FILE) {
+	return path.resolve(projectRoot, configFile);
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} [configFile]
+ * @returns {boolean}
+ */
+export function octaneConfigExists(projectRoot, configFile = DEFAULT_CONFIG_FILE) {
+	return fs.existsSync(getOctaneConfigPath(projectRoot, configFile));
+}
+
+/**
+ * Load, validate, and resolve `octane.config.ts`.
+ *
+ * @param {string} projectRoot
+ * @param {LoadConfigOptions} [options]
+ * @returns {Promise<ResolvedOctaneConfig>}
+ */
+export async function loadOctaneConfig(projectRoot, options = {}) {
+	return (await loadOctaneConfigWithMetadata(projectRoot, options)).config;
+}
+
+/**
+ * Load a config and return the dependency metadata an integration needs to
+ * invalidate its cache and register watch dependencies.
+ *
+ * @param {string} projectRoot
+ * @param {LoadConfigOptions} [options]
+ * @returns {Promise<LoadedOctaneConfig>}
+ */
+export async function loadOctaneConfigWithMetadata(projectRoot, options = {}) {
+	const root = path.resolve(projectRoot);
+	const configPath = getOctaneConfigPath(root, options.configFile);
+	if (!fs.existsSync(configPath)) {
+		throw new Error(`[octane] ${path.basename(configPath)} not found in ${root}`);
+	}
+
+	if (options.moduleRunner) {
+		const runner = options.moduleRunner;
+		const loadModule = typeof runner === 'function' ? runner : runner.loadModule.bind(runner);
+		const configModule = await loadModule(configPath);
+		const runnerDependencies =
+			typeof runner === 'object' && runner.getDependencies
+				? await runner.getDependencies(configPath)
+				: [];
+		const runnerMissingDependencies =
+			typeof runner === 'object' && runner.getMissingDependencies
+				? await runner.getMissingDependencies(configPath)
+				: [];
+		return {
+			config: resolveOctaneConfig(/** @type {OctaneConfigOptions} */ (configModule.default), {
+				requireAdapter: options.requireAdapter,
+			}),
+			configPath,
+			dependencies: sortUnique([configPath, ...runnerDependencies]),
+			missingDependencies: sortUnique(runnerMissingDependencies),
+		};
+	}
+
+	const evaluated = await evaluateConfigModule(root, configPath, options.cacheDir);
+	return {
+		config: resolveOctaneConfig(/** @type {OctaneConfigOptions} */ (evaluated.module.default), {
+			requireAdapter: options.requireAdapter,
+		}),
+		configPath,
+		dependencies: evaluated.dependencies,
+		missingDependencies: evaluated.missingDependencies,
+	};
+}
+
+/**
+ * @param {string} root
+ * @param {string} configPath
+ * @param {string | undefined} configuredCacheDir
+ */
+async function evaluateConfigModule(root, configPath, configuredCacheDir) {
+	const dependencies = new Set([configPath]);
+	const missingDependencies = new Set();
+	const packageRequire = createRequire(configPath);
+
+	/** @type {import('esbuild').Plugin} */
+	const dependencyPlugin = {
+		name: 'octane-config-dependencies',
+		setup(buildApi) {
+			buildApi.onResolve({ filter: /.*/ }, (args) => {
+				if (BUILTINS.has(args.path)) return null;
+				// Preserve lazy config imports instead of traversing an application's
+				// renderer graph during config evaluation. Dev integrations execute
+				// these through their native module runner; the neutral evaluator only
+				// needs the declarative config object now. Absolute file URLs keep the
+				// lazy reference stable when the evaluated module lives in a cache dir.
+				if (args.kind === 'dynamic-import' && !isBareSpecifier(args.path)) {
+					const candidate = path.resolve(args.resolveDir, args.path);
+					const resolved = resolveLocalCandidate(candidate);
+					if (resolved) {
+						dependencies.add(resolved);
+						return { path: pathToFileURL(resolved).href, external: true };
+					}
+					missingDependencies.add(candidate);
+					return { path: args.path, external: true };
+				}
+				if (isBareSpecifier(args.path)) {
+					try {
+						const resolved = packageRequire.resolve(args.path);
+						dependencies.add(resolved);
+						const packageJson = findPackageJson(resolved);
+						if (packageJson) dependencies.add(packageJson);
+					} catch {
+						missingDependencies.add(args.path);
+					}
+					return null;
+				}
+
+				if (args.kind === 'entry-point') return null;
+				const candidate = path.resolve(args.resolveDir, args.path);
+				if (!resolveLocalCandidate(candidate)) missingDependencies.add(candidate);
+				return null;
+			});
+
+			buildApi.onLoad({ filter: OCTANE_EXTENSION_PATTERN }, async (args) => {
+				dependencies.add(args.path);
+				const source = await fs.promises.readFile(args.path, 'utf8');
+				const filename = path.relative(root, args.path).split(path.sep).join('/');
+				const result = compile(source, filename, { mode: 'server', hmr: false });
+				return {
+					contents: typeof result === 'string' ? result : result.code,
+					loader: 'js',
+					resolveDir: path.dirname(args.path),
+				};
+			});
+		},
+	};
+
+	let result;
+	try {
+		result = await build({
+			absWorkingDir: root,
+			entryPoints: [configPath],
+			bundle: true,
+			format: 'esm',
+			platform: 'node',
+			target: 'node22',
+			packages: 'external',
+			metafile: true,
+			sourcemap: 'inline',
+			write: false,
+			plugins: [dependencyPlugin],
+			logLevel: 'silent',
+		});
+	} catch (error) {
+		attachDependencyMetadata(error, dependencies, missingDependencies);
+		throw error;
+	}
+
+	for (const input of Object.keys(result.metafile.inputs)) {
+		const filename = path.isAbsolute(input) ? input : path.resolve(root, input);
+		if (fs.existsSync(filename)) dependencies.add(filename);
+	}
+
+	const output = result.outputFiles[0]?.text;
+	if (!output) throw new Error('[octane] Config evaluation produced no JavaScript output.');
+
+	const cacheDir = configuredCacheDir
+		? path.resolve(root, configuredCacheDir)
+		: path.join(root, 'node_modules/.cache/octane/config');
+	const outputPath = path.join(cacheDir, 'octane.config.mjs');
+	fs.mkdirSync(cacheDir, { recursive: true });
+	if (!fs.existsSync(outputPath) || fs.readFileSync(outputPath, 'utf8') !== output) {
+		fs.writeFileSync(outputPath, output);
+	}
+	const contentHash = createHash('sha256').update(output).digest('hex').slice(0, 16);
+	let configModule;
+	try {
+		configModule = await import(`${pathToFileURL(outputPath).href}?v=${contentHash}`);
+	} catch (error) {
+		attachDependencyMetadata(error, dependencies, missingDependencies);
+		throw error;
+	}
+
+	return {
+		module: configModule,
+		dependencies: sortUnique(dependencies),
+		missingDependencies: sortUnique(missingDependencies),
+	};
+}
+
+/** @param {string} specifier */
+function isBareSpecifier(specifier) {
+	return (
+		!specifier.startsWith('.') && !path.isAbsolute(specifier) && !specifier.startsWith('file:')
+	);
+}
+
+/** @param {string} candidate */
+function resolveLocalCandidate(candidate) {
+	for (const filename of [
+		candidate,
+		`${candidate}.ts`,
+		`${candidate}.tsx`,
+		`${candidate}.tsrx`,
+		`${candidate}.js`,
+		`${candidate}.mjs`,
+		`${candidate}.cjs`,
+		path.join(candidate, 'index.ts'),
+		path.join(candidate, 'index.tsx'),
+		path.join(candidate, 'index.tsrx'),
+		path.join(candidate, 'index.js'),
+	]) {
+		if (fs.existsSync(filename)) return filename;
+	}
+	return null;
+}
+
+/** @param {string} filename */
+function findPackageJson(filename) {
+	let current = path.dirname(filename);
+	for (;;) {
+		const candidate = path.join(current, 'package.json');
+		if (fs.existsSync(candidate)) return candidate;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+
+/** @param {Iterable<string>} values */
+function sortUnique(values) {
+	return [...new Set(values)].sort();
+}
+
+/**
+ * @param {unknown} error
+ * @param {Set<string>} dependencies
+ * @param {Set<string>} missingDependencies
+ */
+function attachDependencyMetadata(error, dependencies, missingDependencies) {
+	if (!error || typeof error !== 'object') return;
+	Object.assign(error, {
+		dependencies: sortUnique(dependencies),
+		missingDependencies: sortUnique(missingDependencies),
+	});
+}

package/src/config.js

@@ -0,0 +1,14 @@
+export { DEFAULT_OUTDIR, ENTRY_FILENAME, OCTANE_NONCE_STATE_KEY } from './constants.js';
+export { resolveOctaneConfig } from './resolve-config.js';
+export { RenderRoute, ServerRoute } from './routes.js';
+
+/**
+ * Type-safe identity helper for `octane.config.ts`.
+ *
+ * @template {import('@octanejs/app-core').OctaneConfigOptions} T
+ * @param {T} options
+ * @returns {T}
+ */
+export function defineConfig(options) {
+	return options;
+}

package/src/constants.js

@@ -0,0 +1,5 @@
+// @ts-check
+export const DEFAULT_OUTDIR = 'dist';
+export const ENTRY_FILENAME = 'entry.js';
+/** Context.state key a middleware sets to apply a per-request CSP nonce. */
+export const OCTANE_NONCE_STATE_KEY = 'octane.nonce';

package/src/html.js

@@ -0,0 +1,10 @@
+export { composeHtmlStream } from './server/html-stream.js';
+export {
+	HYDRATION_NONCE_PLACEHOLDER,
+	applyHydrationNonce,
+	getContextNonce,
+	injectHydrationEntry,
+	nonceAttribute,
+	splitSsrTemplate,
+	validateSsrTemplate,
+} from './server/html-template.js';

package/src/index.js

@@ -0,0 +1,18 @@
+export { DEFAULT_OUTDIR, ENTRY_FILENAME, OCTANE_NONCE_STATE_KEY } from './constants.js';
+export { defineConfig, resolveOctaneConfig } from './config.js';
+export {
+	RenderRoute,
+	ServerRoute,
+	createRouter,
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_id,
+	get_route_entry_path,
+} from './routes.js';
+export {
+	compose,
+	createContext,
+	handleServerRoute,
+	is_rpc_request,
+	runMiddlewareChain,
+} from './middleware.js';

package/src/middleware.js

@@ -0,0 +1,3 @@
+export { compose, createContext, runMiddlewareChain } from './server/middleware.js';
+export { handleServerRoute } from './server/server-route.js';
+export { is_rpc_request } from '@ripple-ts/adapter/rpc';

package/src/resolve-config.js

@@ -0,0 +1,177 @@
+// @ts-check
+/**
+ * Config validation + defaults — `resolveOctaneConfig` and its validators.
+ *
+ * Kept in a module with NO heavy imports (no bundler or octane/compiler) because
+ * it is part of the PRODUCTION server bundle's graph: the generated server
+ * entry re-resolves octane.config.ts through it at boot, and the whole
+ * `@octanejs/app-core/production` graph is bundled into dist/server/entry.js.
+ * The file-loading half (`loadOctaneConfig`) lives in
+ * `load-config.js` and re-exports everything here.
+ */
+
+/** @import { OctaneConfigOptions, ResolvedOctaneConfig } from '@octanejs/app-core' */
+
+import { DEFAULT_OUTDIR } from './constants.js';
+
+/**
+ * @param {unknown} route
+ * @returns {void}
+ */
+function validate_render_route(route) {
+	if (
+		!route ||
+		typeof route !== 'object' ||
+		/** @type {{ type?: unknown }} */ (route).type !== 'render'
+	) {
+		return;
+	}
+
+	const render_route = /** @type {{ entry?: unknown, layout?: unknown }} */ (route);
+	const has_entry =
+		typeof render_route.entry === 'string' ||
+		(Array.isArray(render_route.entry) &&
+			render_route.entry.length === 2 &&
+			typeof render_route.entry[0] === 'string' &&
+			typeof render_route.entry[1] === 'string');
+
+	if (!has_entry) {
+		throw new Error('[octane] RenderRoute requires a string/tuple `entry`.');
+	}
+
+	if (render_route.layout !== undefined && typeof render_route.layout !== 'string') {
+		throw new Error('[octane] RenderRoute `layout` must be a string path.');
+	}
+
+	const status = /** @type {{ status?: unknown }} */ (route).status;
+	if (status !== undefined && (typeof status !== 'number' || !Number.isInteger(status))) {
+		throw new Error('[octane] RenderRoute `status` must be an integer.');
+	}
+}
+
+/**
+ * @param {unknown} rootBoundary
+ * @returns {void}
+ */
+function validate_root_boundary(rootBoundary) {
+	if (rootBoundary === undefined) {
+		return;
+	}
+	if (!rootBoundary || typeof rootBoundary !== 'object') {
+		throw new Error('[octane] rootBoundary must be an object when provided.');
+	}
+
+	const boundary = /** @type {{ pending?: unknown, catch?: unknown }} */ (rootBoundary);
+	for (const name of ['pending', 'catch']) {
+		const entry = boundary[/** @type {'pending' | 'catch'} */ (name)];
+		if (entry === undefined) continue;
+		const valid =
+			(typeof entry === 'string' && entry.startsWith('/')) ||
+			(Array.isArray(entry) &&
+				entry.length === 2 &&
+				typeof entry[0] === 'string' &&
+				typeof entry[1] === 'string' &&
+				entry[1].startsWith('/'));
+		if (!valid) {
+			throw new Error(
+				`[octane] rootBoundary.${name} must be a project-root component module ID or [exportName, moduleId] tuple.`,
+			);
+		}
+	}
+}
+
+/**
+ * Validate a raw octane config and apply all defaults.
+ *
+ * After this function returns every optional field carries its default
+ * value so callers never need to use `??` / `||` fallbacks.
+ *
+ * The function is idempotent — passing an already-resolved config
+ * through it again is safe and produces the same result.
+ *
+ * @param {OctaneConfigOptions} raw - The user-provided config (from octane.config.ts)
+ * @param {{ requireAdapter?: boolean }} [options]
+ * @returns {ResolvedOctaneConfig}
+ */
+export function resolveOctaneConfig(raw, options = {}) {
+	const { requireAdapter = false } = options;
+
+	// ------------------------------------------------------------------
+	// Validate
+	// ------------------------------------------------------------------
+	if (!raw) {
+		throw new Error('[octane] octane.config.ts must export a default config object.');
+	}
+
+	if (requireAdapter && !raw.adapter) {
+		throw new Error(
+			'[octane] This build requires an `adapter` in octane.config.ts. ' +
+				'Install an adapter package (e.g. @octanejs/adapter-vercel) and set the `adapter` property.',
+		);
+	}
+
+	if (raw.adapter !== undefined) {
+		if (typeof raw.adapter !== 'object' || raw.adapter === null) {
+			throw new Error('[octane] adapter must be an adapter object (e.g. `adapter: vercel()`).');
+		}
+		if (raw.adapter.adapt !== undefined && typeof raw.adapter.adapt !== 'function') {
+			throw new Error('[octane] adapter.adapt must be a function.');
+		}
+		if (raw.adapter.serve !== undefined && typeof raw.adapter.serve !== 'function') {
+			throw new Error('[octane] adapter.serve must be a function.');
+		}
+	}
+
+	if (raw.router?.routes !== undefined && !Array.isArray(raw.router.routes)) {
+		throw new Error('[octane] router.routes must be an array.');
+	}
+
+	if (raw.router?.preHydrate !== undefined) {
+		// A project-root module ID: the client hydrate entry dynamic-imports it in
+		// the browser, so it must be root-absolute ('/src/…'), not relative or fs.
+		if (typeof raw.router.preHydrate !== 'string' || !raw.router.preHydrate.startsWith('/')) {
+			throw new Error(
+				"[octane] router.preHydrate must be a project-root module ID (e.g. '/src/pre-hydrate.ts').",
+			);
+		}
+	}
+
+	for (const route of raw.router?.routes ?? []) {
+		validate_render_route(route);
+	}
+
+	validate_root_boundary(raw.rootBoundary);
+
+	if (
+		raw.server?.render !== undefined &&
+		raw.server.render !== 'streaming' &&
+		raw.server.render !== 'buffered'
+	) {
+		throw new Error("[octane] server.render must be 'streaming' or 'buffered'.");
+	}
+
+	// ------------------------------------------------------------------
+	// Apply defaults
+	// ------------------------------------------------------------------
+	return {
+		build: {
+			outDir: raw.build?.outDir ?? DEFAULT_OUTDIR,
+			minify: raw.build?.minify,
+			target: raw.build?.target,
+		},
+		adapter: raw.adapter,
+		router: {
+			routes: raw.router?.routes ?? [],
+			preHydrate: raw.router?.preHydrate,
+		},
+		rootBoundary: raw.rootBoundary ?? {},
+		middlewares: raw.middlewares ?? [],
+		platform: {
+			env: raw.platform?.env ?? {},
+		},
+		server: {
+			trustProxy: raw.server?.trustProxy ?? false,
+			render: raw.server?.render ?? 'streaming',
+		},
+	};
+}

package/src/routes.js

@@ -0,0 +1,135 @@
+// @ts-check
+/**
+ * @typedef {import('@octanejs/app-core').Context} Context
+ * @typedef {import('@octanejs/app-core').Middleware} Middleware
+ * @typedef {import('@octanejs/app-core').RenderRouteOptions} RenderRouteOptions
+ * @typedef {import('@octanejs/app-core').ServerRouteOptions} ServerRouteOptions
+ */
+
+/**
+ * @typedef {string | readonly [string, string]} RenderRouteEntry
+ */
+
+/**
+ * @param {RenderRouteEntry | undefined} entry
+ * @returns {string | undefined}
+ */
+export function get_route_entry_path(entry) {
+	return typeof entry === 'string' ? entry : entry?.[1];
+}
+
+/**
+ * @param {RenderRouteEntry | undefined} entry
+ * @returns {string | undefined}
+ */
+export function get_route_entry_export_name(entry) {
+	return typeof entry === 'string' ? undefined : entry?.[0];
+}
+
+/**
+ * @param {RenderRouteEntry | undefined} entry
+ * @returns {string | undefined}
+ */
+export function get_route_entry_id(entry) {
+	const path = get_route_entry_path(entry);
+	const export_name = get_route_entry_export_name(entry);
+	return path && export_name ? `${path}#${export_name}` : path;
+}
+
+/**
+ * @param {Record<string, unknown>} module
+ * @param {string | undefined} export_name
+ * @returns {Function | null}
+ */
+export function get_component_export(module, export_name) {
+	// When an explicit export name is given, require an exact match. Do NOT fall
+	// back to default/first-PascalCase — a typo'd route tuple should fail loudly
+	// rather than silently render the wrong component.
+	if (export_name) {
+		return typeof module[export_name] === 'function' ? module[export_name] : null;
+	}
+	if (typeof module.default === 'function') {
+		return module.default;
+	}
+	for (const [key, value] of Object.entries(module)) {
+		if (typeof value === 'function' && /^[A-Z]/.test(key)) {
+			return value;
+		}
+	}
+	return null;
+}
+
+/**
+ * Route for rendering octane components with SSR
+ */
+export class RenderRoute {
+	/** @type {'render'} */
+	type = 'render';
+
+	/** @type {string} */
+	path;
+
+	// Non-optional: the constructor throws without one (matches types/index.d.ts).
+	/** @type {RenderRouteEntry} */
+	entry;
+
+	/** @type {string | undefined} */
+	layout;
+
+	/** @type {Middleware[]} */
+	before;
+
+	/** @type {number | undefined} */
+	status;
+
+	/**
+	 * @param {RenderRouteOptions} options
+	 */
+	constructor(options) {
+		if (!options.entry) {
+			throw new Error('RenderRoute requires an `entry`.');
+		}
+
+		this.path = options.path;
+		this.entry = options.entry;
+		this.layout = options.layout;
+		this.before = options.before ?? [];
+		this.status = options.status;
+	}
+}
+
+/**
+ * Route for API endpoints (returns Response directly)
+ */
+export class ServerRoute {
+	/** @type {'server'} */
+	type = 'server';
+
+	/** @type {string} */
+	path;
+
+	/** @type {string[]} */
+	methods;
+
+	/** @type {(context: Context) => Response | Promise<Response>} */
+	handler;
+
+	/** @type {Middleware[]} */
+	before;
+
+	/** @type {Middleware[]} */
+	after;
+
+	/**
+	 * @param {ServerRouteOptions} options
+	 */
+	constructor(options) {
+		this.path = options.path;
+		this.methods = options.methods ?? ['GET'];
+		this.handler = options.handler;
+		this.before = options.before ?? [];
+		this.after = options.after ?? [];
+	}
+}
+
+export { createRouter } from './server/router.js';